Gold API Reference: Endpoints and Examples

Every endpoint needs an API key: a missing or wrong key returns 401, and over the limit returns 429. Each endpoint lists its own codes below, and all of them are explained in Errors

GETFree /api/v1/price/{symbol}/{currency}/{karat} A metal's price in a currency, per unit and per gram. GETFree /api/v1/karat The gram's price at every gold karat, in one request. GETFree /api/v1/convert Between metals, currencies and weight units. GETFree /api/v1/symbols The metals you can ask for. GETFree /api/v1/rates Today's rates against the US dollar. GETBasic /api/v1/history/{symbol} A metal's daily closes over a period. GETPro /api/v1/ohlc/{symbol} Open, high, low and close for each day.

Authentication

Every request needs your key in this header. For a quick test you can also send it as ?api_key=. A key works only on the site where its account signed up. Browsers can call the API directly, but the key is then visible to visitors.

Header

X-API-Key: YOUR_API_KEY

When you reach a limit

Free includes 100 requests an hour, Basic 2,000, and Pro has no limit. The count covers all your account's keys together, also requests refused because of the plan, and restarts at each clock hour. The X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time) headers show where you are; Pro gets only X-RateLimit-Limit: unlimited. Over the limit you get 429 with a Retry-After header in seconds. Free plan limits

Live price

GET/api/v1/price/{symbol}/{currency}/{karat}API key · Free and above

The live price of a metal in any currency, per its unit and per gram. For gold you can choose the karat.

Path parameters

symbolstringrequired: The metal: XAU, XAG, XPT, XPD or HG.
currencystring: Currency code, USD by default. Any code in /rates.
karatint: Gold only: 24, 22, 21, 18 or 14, 24 by default. It changes the gram price.

Query parameters

currencystring: The same value as a query parameter. If both are sent, the path wins.
karatint: The same value as a query parameter. If both are sent, the path wins.

Response fields

price: The price per unit. The karat doesn't change it. Gold in EGP follows Egypt's local market.
gram: The price of one gram, at the karat in the answer for gold. Whole pounds in EGP, unless under 10 pounds.
gramBuy, gramSell: Gold in EGP only: the gram's estimated buy and sell prices.
karat: Gold only: the karat of the gram price.
prevClose, chPercent: Pro only: the last close in the requested currency and the change from it in %. null when there is no close.
updatedAt: The time of this answer.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable400 unknown_karat400 karat_only_for_gold404 unknown_symbol429 rate_limit_exceeded

Response schema

{
  "symbol": string,
  "name": string,
  "currency": string,
  "unit": string,        // "oz" | "lb"
  "price": number,
  "gram": number,
  "gramBuy"?: number,    // gold in EGP
  "gramSell"?: number,   // gold in EGP
  "karat"?: number,      // gold
  "prevClose"?: number | null,  // Pro
  "chPercent"?: number | null,  // Pro
  "updatedAt": string    // ISO-8601
}

ResponseExample

{
    "symbol": "XAU",
    "name": "Gold",
    "currency": "USD",
    "unit": "oz",
    "price": 4072.1,
    "gram": 130.921,
    "karat": 24,
    "updatedAt": "2026-11-07T01:59:05+02:00"
}

Karat prices

GET/api/v1/karatAPI key · Free and above

The live gold gram price at every karat (24, 22, 21, 18 and 14) in one request. For one karat only, use /price.

Query parameters

currencystring: Currency code, USD by default. Any code in /rates.

Response fields

karats[].karat: The karat and its purity: 24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%.
karats[].gram: The price of one gram, at the karat in the answer for gold. Whole pounds in EGP, unless under 10 pounds.
karats[].gramBuy, gramSell: Gold in EGP only: the gram's estimated buy and sell prices.
updatedAt: The time of this answer.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

Response schema

{
  "currency": string,
  "karats": [
    {
      "karat": number,
      "gram": number,
      "gramBuy"?: number,   // EGP
      "gramSell"?: number   // EGP
    }
  ],
  "updatedAt": string    // ISO-8601
}

ResponseExample

{
    "currency": "USD",
    "karats": [
        {
            "karat": 24,
            "gram": 130.921
        },
        {
            "karat": 22,
            "gram": 120.0022
        },
        {
            "karat": 21,
            "gram": 114.5558
        },
        {
            "karat": 18,
            "gram": 98.1907
        },
        {
            "karat": 14,
            "gram": 76.3662
        }
    ],
    "updatedAt": "2026-11-07T01:59:05+02:00"
}

Convert

GET/api/v1/convertAPI key · Free and above

Converts between a metal and a currency, two metals or two currencies, at the live price. For gold you can choose the karat.

Query parameters

fromstringrequired: What you convert from: a metal (XAU, XAG, XPT, XPD, HG) or a currency code in /rates.
tostringrequired: What you convert to, with the same choices as from.
amountnumber: The amount, 1 by default. It must be greater than 0.
unitstring: The metal side's unit: gram, tola, oz, tael, kilo, lb. The metal's own unit by default (oz, or lb for copper).
karatint: When one side is gold: 24, 22, 21, 18, 14. 24 by default.

Response fields

unit: The metal side's unit. Left out when both sides are currencies.
karat: The karat used. Only when one side is gold.
rate: The value of one unit of from, in to.
result: The amount multiplied by the rate.
updatedAt: The time of this answer.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 from_and_to_required400 invalid_amount400 unknown_unit400 unknown_karat400 karat_only_for_gold400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

Response schema

{
  "from": string,
  "to": string,
  "amount": number,
  "unit"?: string,     // metal side
  "karat"?: number,    // gold side
  "rate": number,
  "result": number,
  "updatedAt": string  // ISO-8601
}

ResponseExample

{
    "from": "XAU",
    "to": "USD",
    "amount": 1,
    "unit": "gram",
    "karat": 24,
    "rate": 130.921,
    "result": 130.92,
    "updatedAt": "2026-11-07T01:59:05+02:00"
}

Symbols

GET/api/v1/symbolsAPI key · Free and above

The metals the API knows, with their names and units.

Response fields

symbol: The metal's symbol.
name: The metal's name.
unit: The unit of its price: oz or lb.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Response schema

{
  "symbols": [
    { "symbol": string, "name": string, "unit": string }
  ],
  "_server_time": string  // ISO-8601
}

ResponseExample

{
    "symbols": [
        {
            "symbol": "XAU",
            "name": "Gold",
            "unit": "oz"
        },
        {
            "symbol": "XAG",
            "name": "Silver",
            "unit": "oz"
        },
        {
            "symbol": "XPT",
            "name": "Platinum",
            "unit": "oz"
        },
        {
            "symbol": "XPD",
            "name": "Palladium",
            "unit": "oz"
        },
        {
            "symbol": "HG",
            "name": "Copper",
            "unit": "lb"
        }
    ],
    "_server_time": "2026-11-07T01:59:05+02:00"
}

Exchange rates

GET/api/v1/ratesAPI key · Free and above

Today's exchange rates against the US dollar, the most used currencies first.

Response fields

base: The base currency: USD.
rates: Each currency's rate against one US dollar.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Response schema

{
  "base": "USD",
  "rates": { [currency: string]: number },
  "_server_time": string  // ISO-8601
}

ResponseExample

{
    "base": "USD",
    "rates": {
        "USD": 1,
        "EUR": 0.89048,
        "GBP": 0.742915,
        "INR": 94.537031,
        "CNY": 6.682525,
        "JPY": 157.835475
    },
    "_server_time": "2026-11-07T01:59:05+02:00"
}

Daily history

GET/api/v1/history/{symbol}API key · Basic and above

A metal's daily closes, oldest first, as far back as the archive goes, ending with today's running day, so you can get one row more than days. Each day uses its own exchange rate, and gold in EGP also uses that day's local market premium. A day without a saved rate is left out.

Path parameters

symbolstringrequired: The metal: XAU, XAG, XPT, XPD or HG.

Query parameters

currencystring: Currency code, USD by default. Only the currencies with daily data, listed under Currencies.
rangestring: 1W, 1M, 3M, 6M, 1Y or ALL (10 years). It wins over days, and any other value is ignored.
daysint: Number of days, 365 by default. Kept between 1 and 3650.

Response fields

days: The days used, after range and the 1 to 3650 limit.
count: How many rows came back.
history[].date, close: The day and its closing price per unit. Today's close keeps changing until the day ends.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_basic404 unknown_symbol429 rate_limit_exceeded

Response schema

{
  "symbol": string,
  "currency": string,
  "days": number,
  "count": number,
  "history": [
    { "date": string, "close": number }  // YYYY-MM-DD, oldest first
  ],
  "_server_time": string  // ISO-8601
}

ResponseExample

{
    "symbol": "XAU",
    "currency": "USD",
    "days": 1,
    "count": 2,
    "history": [
        {
            "date": "2026-11-06",
            "close": 4072
        },
        {
            "date": "2026-11-07",
            "close": 4072.1001
        }
    ],
    "_server_time": "2026-11-07T01:59:05+02:00"
}

Daily candles

GET/api/v1/ohlc/{symbol}API key · Pro and above

A candle for each day, oldest first, ending with today's running day. Each day uses its own exchange rate, and gold in EGP also uses that day's local market premium. A day without a saved rate is left out.

Path parameters

symbolstringrequired: The metal: XAU, XAG, XPT, XPD or HG.

Query parameters

currencystring: Currency code, USD by default. Only the currencies with daily data, listed under Currencies.
startunix: First day, as Unix time in seconds. From the first saved day by default.
endunix: Last day, as Unix time in seconds. Up to today by default.

Response fields

count: How many rows came back.
candles[].date, open, high, low, close: The day and its prices per unit.
candles[].sealed: true when the day is final, false while it can still change.

Response codes

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_pro404 unknown_symbol429 rate_limit_exceeded

Response schema

{
  "symbol": string,
  "currency": string,
  "count": number,
  "candles": [
    {
      "date": string,  // YYYY-MM-DD
      "open": number,
      "high": number,
      "low": number,
      "close": number,
      "sealed": boolean
    }
  ],
  "_server_time": string  // ISO-8601
}

ResponseExample

{
    "symbol": "XAU",
    "currency": "USD",
    "count": 2,
    "candles": [
        {
            "date": "2026-11-06",
            "open": 4090.3,
            "high": 4106.7998,
            "low": 4032.5,
            "close": 4072,
            "sealed": true
        },
        {
            "date": "2026-11-07",
            "open": 4072.3999,
            "high": 4072.3999,
            "low": 4072.1001,
            "close": 4072.1001,
            "sealed": false
        }
    ],
    "_server_time": "2026-11-07T01:59:05+02:00"
}

Currencies

/price, /karat, /convert and /rates work with 166 currencies, and /rates lists them. /history and /ohlc work with the 47 below, because each day keeps its own rates. Any other code on these two returns 400 unknown_currency.

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

Errors

Errors are JSON with an error field, and some add the fields shown in the table. A request is checked in this order: key, hourly limit, plan, then parameters.

Status	error	When	Also returns
400	`unknown_currency_or_unavailable`	Unknown currency, or the price isn't available right now	`symbol, currency`
400	`unknown_currency`	On /history or /ohlc: a currency without daily data	`currency, allowed`
400	`unknown_karat`	A karat other than 24, 22, 21, 18 or 14	`karat, allowed`
400	`karat_only_for_gold`	A karat with a metal other than gold	`symbol`
400	`from_and_to_required`	from or to is missing
400	`invalid_amount`	amount isn't a number greater than 0	`amount`
400	`unknown_unit`	A unit other than gram, tola, oz, tael, kilo, lb	`unit, allowed`
401	`api_key_required`	The request has no key
401	`invalid_api_key`	The key is not valid
403	`feature_requires_basic`	The plan doesn't include this endpoint
403	`feature_requires_pro`	The plan doesn't include this endpoint
403	`key_disabled`	The key is turned off
403	`account_suspended`	The account is suspended
403	`email_not_verified`	The account's email isn't confirmed yet
403	`Forbidden`	The bare /api or /api/v1 address. Its answer has status and message fields instead of error.
404	`unknown_symbol`	Unknown metal	`symbol`
404	`not_found`	No such endpoint, or extra parts in the path. History and candles take currency only as a query parameter.
429	`rate_limit_exceeded`	Over the plan's requests an hour
503	`prices_unavailable`	A metal's price isn't available right now