Tham chiếu API vàng: endpoint và ví dụ

Mọi endpoint đều cần khóa API: thiếu hoặc sai khóa trả về 401, và vượt giới hạn trả về 429. Mỗi endpoint liệt kê mã của nó bên dưới, và tất cả được giải thích tại Lỗi

GETFree /api/v1/price/{symbol}/{currency}/{karat} Giá kim loại bằng một tiền tệ, theo đơn vị và theo gam. GETFree /api/v1/karat Giá mỗi gram của mọi loại karat vàng, trong một yêu cầu. GETFree /api/v1/convert Giữa kim loại, tiền tệ và đơn vị khối lượng. GETFree /api/v1/symbols Các kim loại có thể yêu cầu. GETFree /api/v1/rates Tỷ giá hôm nay so với đô la Mỹ. GETBasic /api/v1/history/{symbol} Giá đóng cửa theo ngày của kim loại trong một khoảng. GETPro /api/v1/ohlc/{symbol} Giá mở, cao, thấp và đóng mỗi ngày.

Xác thực

Mọi yêu cầu cần khóa của bạn trong header này. Để thử nhanh, bạn cũng có thể gửi bằng ?api_key=. Khóa chỉ hoạt động trên trang nơi tài khoản đăng ký. Trình duyệt có thể gọi API trực tiếp, nhưng khi đó khách truy cập sẽ thấy khóa.

Header

X-API-Key: YOUR_API_KEY

Khi đạt giới hạn

Free có 100 yêu cầu mỗi giờ, Basic 2,000, và Pro không giới hạn. Số đếm gồm mọi khóa của tài khoản, cả yêu cầu bị từ chối do gói, và đặt lại vào đầu mỗi giờ. Các header X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset (thời gian Unix) cho biết tình trạng; Pro chỉ nhận X-RateLimit-Limit: unlimited. Vượt giới hạn sẽ nhận 429 kèm header Retry-After tính bằng giây. Giới hạn gói miễn phí

Giá trực tiếp

GET/api/v1/price/{symbol}/{currency}/{karat}Khóa API · Free trở lên

Giá trực tiếp của kim loại bằng bất kỳ tiền tệ nào, theo đơn vị và theo gam. Với vàng bạn có thể chọn tuổi vàng.

Tham số đường dẫn

symbolstringbắt buộc: Kim loại: XAU, XAG, XPT, XPD hoặc HG.
currencystring: Mã tiền tệ, mặc định USD. Bất kỳ mã nào trong /rates.
karatint: Chỉ vàng: 24, 22, 21, 18 hoặc 14, mặc định 24. Thay đổi giá theo gam.

Tham số truy vấn

currencystring: Cùng giá trị dưới dạng tham số truy vấn. Nếu gửi cả hai, đường dẫn được ưu tiên.
karatint: Cùng giá trị dưới dạng tham số truy vấn. Nếu gửi cả hai, đường dẫn được ưu tiên.

Trường phản hồi

price: Giá mỗi đơn vị. Tuổi vàng không làm thay đổi giá này. Vàng theo EGP đi theo thị trường nội địa Ai Cập.
gram: Giá một gram, với vàng là theo tuổi trong phản hồi. Theo EGP là số nguyên bảng, trừ khi dưới 10 bảng.
gramBuy, gramSell: Chỉ vàng bằng EGP: giá mua và bán ước tính mỗi gam.
karat: Chỉ vàng: tuổi vàng của giá theo gam.
prevClose, chPercent: Chỉ Pro: giá đóng gần nhất theo tiền tệ yêu cầu và mức thay đổi tính bằng %. null khi không có giá đóng.
updatedAt: Thời điểm của phản hồi này.

Mã phản hồi

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

Cấu trúc phản hồi

{
  "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
}

Phản hồiVí dụ

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

Giá theo karat

GET/api/v1/karatKhóa API · Free trở lên

Giá trực tiếp mỗi gram vàng ở mọi karat (24, 22, 21, 18 và 14) trong một yêu cầu. Nếu chỉ cần một karat, hãy dùng /price.

Tham số truy vấn

currencystring: Mã tiền tệ, mặc định USD. Bất kỳ mã nào trong /rates.

Trường phản hồi

karats[].karat: Karat và độ tinh khiết: 24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%.
karats[].gram: Giá một gram, với vàng là theo tuổi trong phản hồi. Theo EGP là số nguyên bảng, trừ khi dưới 10 bảng.
karats[].gramBuy, gramSell: Chỉ vàng bằng EGP: giá mua và bán ước tính mỗi gam.
updatedAt: Thời điểm của phản hồi này.

Mã phản hồi

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

Cấu trúc phản hồi

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

Phản hồiVí dụ

{
    "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-07T02:40:24+02:00"
}

Chuyển đổi

GET/api/v1/convertKhóa API · Free trở lên

Chuyển đổi giữa kim loại và tiền tệ, hai kim loại hoặc hai tiền tệ theo giá trực tiếp. Với vàng, bạn có thể chọn karat.

Tham số truy vấn

fromstringbắt buộc: Giá trị cần chuyển: kim loại (XAU, XAG, XPT, XPD, HG) hoặc mã tiền tệ trong /rates.
tostringbắt buộc: Giá trị đích, với các lựa chọn giống from.
amountnumber: Số lượng, mặc định là 1. Phải lớn hơn 0.
unitstring: Đơn vị của phía kim loại: gram, tola, oz, tael, kilo, lb. Mặc định là đơn vị của chính kim loại đó (oz, hoặc lb với đồng).
karatint: Khi một phía là vàng: 24, 22, 21, 18, 14. Mặc định là 24.

Trường phản hồi

unit: Đơn vị của phía kim loại. Không có khi cả hai phía là tiền tệ.
karat: Karat đã dùng. Chỉ khi một phía là vàng.
rate: Giá trị của một đơn vị from tính theo to.
result: Số lượng nhân với rate.
updatedAt: Thời điểm của phản hồi này.

Mã phản hồi

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

Cấu trúc phản hồi

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

Phản hồiVí dụ

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

Ký hiệu

GET/api/v1/symbolsKhóa API · Free trở lên

Các kim loại API hỗ trợ, cùng tên và đơn vị.

Trường phản hồi

symbol: Ký hiệu kim loại.
name: Tên kim loại.
unit: Đơn vị giá: oz hoặc lb.

Mã phản hồi

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Cấu trúc phản hồi

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

Phản hồiVí dụ

{
    "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-07T02:40:24+02:00"
}

Tỷ giá

GET/api/v1/ratesKhóa API · Free trở lên

Tỷ giá hôm nay so với đô la Mỹ, các tiền tệ phổ biến nhất trước.

Trường phản hồi

base: Tiền tệ gốc: USD.
rates: Tỷ giá mỗi tiền tệ so với một đô la.

Mã phản hồi

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Cấu trúc phản hồi

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

Phản hồiVí dụ

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

Lịch sử theo ngày

GET/api/v1/history/{symbol}Khóa API · Basic trở lên

Giá đóng hằng ngày của kim loại, từ cũ nhất, trong phạm vi kho lưu trữ và kết thúc bằng ngày đang chạy, nên có thể nhiều hơn days một dòng. Mỗi ngày dùng tỷ giá riêng, và vàng theo EGP dùng thêm phần bù thị trường nội địa của ngày đó. Ngày không có tỷ giá đã lưu sẽ bị bỏ qua.

Tham số đường dẫn

symbolstringbắt buộc: Kim loại: XAU, XAG, XPT, XPD hoặc HG.

Tham số truy vấn

currencystring: Mã tiền tệ, mặc định USD. Chỉ các tiền tệ có dữ liệu ngày, liệt kê ở mục Tiền tệ.
rangestring: 1W, 1M, 3M, 6M, 1Y hoặc ALL (10 năm). Được ưu tiên hơn days, giá trị khác bị bỏ qua.
daysint: Số ngày, mặc định 365. Giữ trong khoảng 1 đến 3650.

Trường phản hồi

days: Số ngày được dùng, sau khi áp dụng range và giới hạn 1 đến 3650.
count: Số dòng trả về.
history[].date, close: Ngày và giá đóng mỗi đơn vị. Giá đóng của hôm nay còn thay đổi đến hết ngày.

Mã phản hồi

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

Cấu trúc phản hồi

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

Phản hồiVí dụ

{
    "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-07T02:40:24+02:00"
}

Nến theo ngày

GET/api/v1/ohlc/{symbol}Khóa API · Pro trở lên

Mỗi ngày một nến, từ cũ nhất và kết thúc bằng ngày đang chạy. Mỗi ngày dùng tỷ giá riêng, và vàng theo EGP dùng thêm phần bù thị trường nội địa của ngày đó. Ngày không có tỷ giá đã lưu sẽ bị bỏ qua.

Tham số đường dẫn

symbolstringbắt buộc: Kim loại: XAU, XAG, XPT, XPD hoặc HG.

Tham số truy vấn

currencystring: Mã tiền tệ, mặc định USD. Chỉ các tiền tệ có dữ liệu ngày, liệt kê ở mục Tiền tệ.
startunix: Ngày đầu, theo thời gian Unix tính bằng giây. Mặc định từ ngày đầu tiên đã lưu.
endunix: Ngày cuối, theo thời gian Unix tính bằng giây. Mặc định đến hôm nay.

Trường phản hồi

count: Số dòng trả về.
candles[].date, open, high, low, close: Ngày và các mức giá mỗi đơn vị.
candles[].sealed: true khi ngày đã chốt, false khi còn có thể thay đổi.

Mã phản hồi

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

Cấu trúc phản hồi

{
  "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
}

Phản hồiVí dụ

{
    "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-07T02:40:24+02:00"
}

Tiền tệ

/price, /karat, /convert và /rates hoạt động với 166 tiền tệ, và /rates liệt kê chúng. /history và /ohlc hoạt động với 47 tiền tệ bên dưới, vì mỗi ngày lưu tỷ giá riêng. Mã khác trên hai endpoint này trả về 400 unknown_currency.

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

Lỗi

Lỗi là JSON có trường error, một số thêm các trường trong bảng. Yêu cầu được kiểm tra theo thứ tự: khóa, giới hạn giờ, gói, rồi tham số.

Trạng thái	lỗi	Khi nào	Trả về thêm
400	`unknown_currency_or_unavailable`	Tiền tệ không xác định, hoặc hiện chưa có giá	`symbol, currency`
400	`unknown_currency`	Trên /history hoặc /ohlc: tiền tệ không có dữ liệu ngày	`currency, allowed`
400	`unknown_karat`	Tuổi vàng khác 24, 22, 21, 18 hoặc 14	`karat, allowed`
400	`karat_only_for_gold`	Tuổi vàng với kim loại không phải vàng	`symbol`
400	`from_and_to_required`	Thiếu from hoặc to
400	`invalid_amount`	amount không phải số lớn hơn 0	`amount`
400	`unknown_unit`	Đơn vị khác gram, tola, oz, tael, kilo, lb	`unit, allowed`
401	`api_key_required`	Yêu cầu không có khóa
401	`invalid_api_key`	Khóa không hợp lệ
403	`feature_requires_basic`	Gói không bao gồm endpoint này
403	`feature_requires_pro`	Gói không bao gồm endpoint này
403	`key_disabled`	Khóa đã tắt
403	`account_suspended`	Tài khoản bị tạm ngưng
403	`email_not_verified`	Email tài khoản chưa được xác nhận
403	`Forbidden`	Chỉ địa chỉ /api hoặc /api/v1. Phản hồi có trường status và message thay vì error.
404	`unknown_symbol`	Kim loại không xác định	`symbol`
404	`not_found`	Không có endpoint này, hoặc đường dẫn có phần thừa. Lịch sử và nến chỉ nhận currency dưới dạng tham số truy vấn.
429	`rate_limit_exceeded`	Vượt số yêu cầu mỗi giờ của gói
503	`prices_unavailable`	Giá kim loại hiện không có sẵn