---
title: "Gold price per gram and ounce API by country · goldprice.dev"
description: "Gold price per gram by country API: GET /v1/physical/{country} returns dealer sell and buyback prices, local spot per gram and nullable premium over spot."
canonical: "https://goldprice.dev/docs/physical"
---

# Physical dealer prices

For spot gold per troy ounce, use GET /v1/spot/XAU-USD-SPOT. For dealer gold prices by country per gram, bar, tola or tael, use GET /v1/physical/{country}, which also returns the spot value per gram in local currency. Product overview at /physical.

Basic+ · 22 countries live · MCP tool parity

## Country index

`GET /v1/physical` · Bearer · Basic+

Which countries are live, how many sources each has, and the freshest fetch time. Use it to discover coverage before calling the per-country endpoint.

### Sample response

```json
{
  "result": "success",
  "countries": [
    {"country": "ID", "sources": 4, "products": ["digital_gram", "bar"],
     "currency": "IDR", "latest_fetched_at": "2026-10-23T07:15:09Z"},
    {"country": "MY", "sources": 1, "products": ["bar"],
     "currency": "MYR", "latest_fetched_at": "2026-10-23T07:15:11Z"}
  ]
}
```

## Dealer quotes for one country

`GET /v1/physical/{country}` · Bearer · Basic+

Latest quote per (source, metal, brand, product, product name, denomination). `country` is an ISO 3166-1 alpha-2 code (ID, MY, VN, PK, AE, JP, NP, EG, SA, HK, DE, AT, CH, PL, SE, FI, NO, LT, HU, GB, US, SG). Unknown codes return `404 unknown_country` on every plan, with the list of covered countries. Responses are cached for 60 seconds.

### Sample response

```json
{
  "result": "success",
  "country": "ID",
  "currency": "IDR",
  "spot_reference": {
    "xau_usd": "4016.55",
    "fx_usd_local": "18082.43",
    "spot_per_gram_local": "2335076.00"
  },
  "quotes": [
    {"source": "pegadaian", "brand": null, "product": "digital_gram",
     "denomination_grams": null, "price_basis": "per_gram",
     "sell": "2497154", "buyback": "2414599",
     "premium_over_spot_bps": 694,
     "data_updated_at": "2026-10-23T07:14:02Z",
     "fetched_at": "2026-10-23T07:15:09Z"},
    {"source": "indogold", "brand": "Antam", "product": "bar",
     "denomination_grams": "1", "price_basis": "per_bar",
     "sell": "2719000", "buyback": "2520000",
     "premium_over_spot_bps": 1644,
     "data_updated_at": null,
     "fetched_at": "2026-10-23T07:15:10Z"}
  ]
}
```

### Reading the quote rows

`price_basis` tells you what the price is per: `per_gram`, `per_bar` (with `denomination_grams` carrying the bar weight), `per_tola`, `per_tael`, or `per_sku` (per named coin or bar). `premium_over_spot_bps` compares the per-gram equivalent against purity-adjusted international spot converted at the live FX cross: 18-karat rows compare against 18k-equivalent spot, never against pure spot. Products whose purity is not in the label carry `premium: null`. Stale spot or FX inputs also yield `null`, never a fabricated number.

## Silver and coin or bar quotes

Both endpoints accept optional `metal=gold` or `metal=silver`; other values return `400 invalid_metal`. Omit `metal` for unchanged gold-only responses. Filtering keeps only matching quotes, adding top-level `metal`, quote `metal` and `sku_label`, and `spot_reference.xag_usd`. `spot_per_gram_local` and `premium_over_spot_bps` use XAU for gold, XAG for silver. The filtered index lists countries quoting that metal, adding `metal` and `products_by_metal` (`{"gold": [...], "silver": [...]}`) per country. Products `coin`, `minted_bar`, `cast_bar` can use `price_basis=per_sku`; `sku_label` names the product, e.g. "Krugerrand 1 oz". `denomination_grams` is fine metal weight; premiums are per gram of pure metal. Unfiltered quotes include `sku_label` for these products, omit it for weight and karat quotes. `fetched_at` records the quote's latest successful check.

```http
GET /v1/physical/JP?metal=silver
```

## MCP tool + WebSocket channel

The `get_physical_price(country)` MCP tool returns the same shape as the per-country endpoint, gated identically. On [Pro](https://goldprice.dev/pricing), the `physical:{country}` WebSocket channel pushes this payload whenever a country's quotes change; see [the stream reference](https://goldprice.dev/docs/stream).

## FAQ

### What does /v1/physical/{country} return?

The latest dealer quote per (source, metal, brand, product, product name, denomination) for one country: sell and buyback prices, the pricing basis (per gram, per bar, per tola, per tael), and nullable premium_over_spot_bps. The premium is computed against live international spot times live FX and purity-adjusted per product when those inputs are available.

### When is premium_over_spot_bps null?

Whenever an input would make it dishonest: the spot or FX reading is stale (spot: older than 15 minutes of open-market time, so a Friday-close price still serves the weekend; FX: older than 15 minutes), or the product's purity is not stated in its label. A null premium is deliberate. The API never fabricates a number.

### Which tier do I need?

Basic, Plus, or Pro. Free keys receive 403 plan_gated. The MCP tool get_physical_price follows the same gate. Countries we don't cover return 404 unknown_country on every plan, so you won't be asked to upgrade for a country we don't serve.

### Which countries have sell-only quotes?

GB, US and SG quotes are sell-only. Their buyback field is always null.

### What happens to out-of-stock items?

Out-of-stock items drop out. A quote appears only if the dealer listed it in its latest successful check.

Source: https://goldprice.dev/docs/physical
