금 API 참조: 엔드포인트와 예제

모든 엔드포인트에 API 키가 필요합니다. 키가 없거나 틀리면 401, 제한을 넘으면 429를 반환합니다. 각 엔드포인트의 코드는 아래에 있으며, 전체 설명은 다음에 있습니다: 오류

GETFree /api/v1/price/{symbol}/{currency}/{karat} 통화별 금속 가격, 단위당과 그램당. GETFree /api/v1/karat 모든 금 캐럿의 그램 가격을 한 번의 요청으로. GETFree /api/v1/convert 금속, 통화, 무게 단위 간 변환. GETFree /api/v1/symbols 요청할 수 있는 금속. GETFree /api/v1/rates 미국 달러 대비 오늘 환율. GETBasic /api/v1/history/{symbol} 기간별 금속의 일별 종가. GETPro /api/v1/ohlc/{symbol} 각 날의 시가, 고가, 저가, 종가.

인증

모든 요청에 이 헤더로 키가 필요합니다. 간단한 테스트에는 ?api_key=로 보낼 수도 있습니다. 키는 계정을 가입한 사이트에서만 작동합니다. 브라우저에서 직접 호출할 수 있지만 키가 방문자에게 보입니다.

Header

X-API-Key: YOUR_API_KEY

제한에 도달하면

Free는 시간당 100건, Basic은 2,000건이며 Pro는 제한이 없습니다. 계정의 모든 키를 합산하고 플랜 때문에 거부된 요청도 포함하며, 매시 정각에 초기화됩니다. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset(Unix 시간) 헤더로 현황을 알 수 있으며, Pro는 X-RateLimit-Limit: unlimited만 받습니다. 제한을 넘으면 429와 초 단위 Retry-After 헤더를 받습니다. 무료 요금제 제한

실시간 가격

GET/api/v1/price/{symbol}/{currency}/{karat}API 키 · Free 이상

모든 통화의 금속 실시간 가격을 단위당과 그램당으로 반환합니다. 금은 순도를 고를 수 있습니다.

경로 매개변수

symbolstring필수: 금속: XAU, XAG, XPT, XPD, HG.
currencystring: 통화 코드, 기본값 USD. /rates에 있는 코드를 사용할 수 있습니다.
karatint: 금 전용: 24, 22, 21, 18, 14, 기본값 24. 그램 가격이 바뀝니다.

쿼리 매개변수

currencystring: 쿼리 매개변수로도 같은 값을 보낼 수 있습니다. 둘 다 보내면 경로가 우선합니다.
karatint: 쿼리 매개변수로도 같은 값을 보낼 수 있습니다. 둘 다 보내면 경로가 우선합니다.

응답 필드

price: 단위당 가격. 순도로 바뀌지 않습니다. EGP 금은 이집트 현지 시장을 따릅니다.
gram: 1그램 가격으로, 금은 응답의 순도 기준입니다. EGP에서는 10파운드 미만이 아니면 정수입니다.
gramBuy, gramSell: EGP 금 전용: 그램의 예상 매수·매도 가격.
karat: 금 전용: 그램 가격의 순도.
prevClose, chPercent: Pro 전용: 요청한 통화의 최근 종가와 그 대비 변동률(%). 종가가 없으면 null입니다.
updatedAt: 이 응답의 시각.

응답 코드

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

응답 스키마

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

응답예시

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

캐럿별 가격

GET/api/v1/karatAPI 키 · Free 이상

모든 캐럿(24, 22, 21, 18, 14)의 금 그램 실시간 가격을 한 번의 요청으로 반환합니다. 한 캐럿만 필요하면 /price를 사용하세요.

쿼리 매개변수

currencystring: 통화 코드, 기본값 USD. /rates에 있는 코드를 사용할 수 있습니다.

응답 필드

karats[].karat: 캐럿과 순도: 24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%.
karats[].gram: 1그램 가격으로, 금은 응답의 순도 기준입니다. EGP에서는 10파운드 미만이 아니면 정수입니다.
karats[].gramBuy, gramSell: EGP 금 전용: 그램의 예상 매수·매도 가격.
updatedAt: 이 응답의 시각.

응답 코드

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

응답 스키마

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

응답예시

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

변환

GET/api/v1/convertAPI 키 · Free 이상

금속과 통화, 두 금속, 두 통화 사이를 실시간 가격으로 변환합니다. 금은 캐럿을 선택할 수 있습니다.

쿼리 매개변수

fromstring필수: 변환할 대상: 금속(XAU, XAG, XPT, XPD, HG) 또는 /rates의 통화 코드.
tostring필수: 변환 결과의 대상. from과 선택지가 같습니다.
amountnumber: 수량이며 기본값은 1입니다. 0보다 커야 합니다.
unitstring: 금속 쪽 단위: gram, tola, oz, tael, kilo, lb. 기본값은 금속 자체의 단위입니다(oz, 구리는 lb).
karatint: 한쪽이 금일 때: 24, 22, 21, 18, 14. 기본값은 24.

응답 필드

unit: 금속 쪽 단위. 양쪽이 모두 통화이면 포함되지 않습니다.
karat: 사용된 캐럿. 한쪽이 금일 때만.
rate: from 1단위의 to 기준 값.
result: 수량에 rate를 곱한 값.
updatedAt: 이 응답의 시각.

응답 코드

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

응답 스키마

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

응답예시

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

심볼

GET/api/v1/symbolsAPI 키 · Free 이상

API가 아는 금속과 이름, 단위를 반환합니다.

응답 필드

symbol: 금속 심볼.
name: 금속 이름.
unit: 가격 단위: oz 또는 lb.

응답 코드

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

응답 스키마

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

응답예시

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

환율

GET/api/v1/ratesAPI 키 · Free 이상

미국 달러 대비 오늘의 환율을 많이 쓰는 통화부터 반환합니다.

응답 필드

base: 기준 통화: USD.
rates: 1달러 대비 각 통화의 환율.

응답 코드

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

응답 스키마

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

응답예시

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

일별 내역

GET/api/v1/history/{symbol}API 키 · Basic 이상

금속의 일별 종가를 오래된 순으로 아카이브 범위까지 제공하며, 마지막은 진행 중인 오늘이라 days보다 한 행 많을 수 있습니다. 각 날은 그날의 환율을 쓰고, EGP 금은 그날의 현지 시장 프리미엄도 씁니다. 저장된 환율이 없는 날은 제외됩니다.

경로 매개변수

symbolstring필수: 금속: XAU, XAG, XPT, XPD, HG.

쿼리 매개변수

currencystring: 통화 코드, 기본값 USD. 일별 데이터가 있는 통화만 가능하며 통화 항목에 나와 있습니다.
rangestring: 1W, 1M, 3M, 6M, 1Y 또는 ALL(10년). days보다 우선하며 다른 값은 무시됩니다.
daysint: 일수, 기본값 365. 1에서 3650 사이로 유지됩니다.

응답 필드

days: range와 1~3650 제한을 적용한 뒤의 일수입니다.
count: 반환된 행 수.
history[].date, close: 날짜와 단위당 종가. 오늘 종가는 하루가 끝날 때까지 바뀝니다.

응답 코드

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

응답 스키마

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

응답예시

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

일별 캔들

GET/api/v1/ohlc/{symbol}API 키 · Pro 이상

하루 하나의 캔들을 오래된 순으로 제공하며, 마지막은 진행 중인 오늘입니다. 각 날은 그날의 환율을 쓰고, EGP 금은 그날의 현지 시장 프리미엄도 씁니다. 저장된 환율이 없는 날은 제외됩니다.

경로 매개변수

symbolstring필수: 금속: XAU, XAG, XPT, XPD, HG.

쿼리 매개변수

currencystring: 통화 코드, 기본값 USD. 일별 데이터가 있는 통화만 가능하며 통화 항목에 나와 있습니다.
startunix: 첫날, 초 단위 Unix 시간. 기본값은 저장된 첫날입니다.
endunix: 마지막 날, 초 단위 Unix 시간. 기본값은 오늘까지입니다.

응답 필드

count: 반환된 행 수.
candles[].date, open, high, low, close: 날짜와 단위당 가격.
candles[].sealed: 확정된 날은 true, 아직 바뀔 수 있으면 false.

응답 코드

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

응답 스키마

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

응답예시

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

통화

/price, /karat, /convert, /rates는 166개 통화를 지원하며 /rates에 목록이 있습니다. /history와 /ohlc는 각 날의 환율을 저장하므로 아래 47개 통화를 지원합니다. 이 둘에서 다른 코드는 400 unknown_currency를 반환합니다.

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

오류

오류는 error 필드가 있는 JSON이며, 일부는 표의 필드를 추가합니다. 요청은 키, 시간당 제한, 플랜, 매개변수 순으로 확인됩니다.

상태	오류	발생 조건	함께 반환
400	`unknown_currency_or_unavailable`	알 수 없는 통화이거나 지금 가격을 받을 수 없음	`symbol, currency`
400	`unknown_currency`	/history 또는 /ohlc에서 일별 데이터가 없는 통화	`currency, allowed`
400	`unknown_karat`	24, 22, 21, 18, 14 이외의 순도	`karat, allowed`
400	`karat_only_for_gold`	금이 아닌 금속에 순도 지정	`symbol`
400	`from_and_to_required`	from 또는 to가 없음
400	`invalid_amount`	amount가 0보다 큰 숫자가 아님	`amount`
400	`unknown_unit`	gram, tola, oz, tael, kilo, lb 이외의 단위	`unit, allowed`
401	`api_key_required`	요청에 키가 없음
401	`invalid_api_key`	키가 유효하지 않음
403	`feature_requires_basic`	요금제에 이 엔드포인트가 없음
403	`feature_requires_pro`	요금제에 이 엔드포인트가 없음
403	`key_disabled`	키가 비활성화됨
403	`account_suspended`	계정이 정지됨
403	`email_not_verified`	계정 이메일이 아직 확인되지 않음
403	`Forbidden`	/api 또는 /api/v1 주소만 호출한 경우. 응답에는 error 대신 status와 message가 있습니다.
404	`unknown_symbol`	알 수 없는 금속	`symbol`
404	`not_found`	해당 엔드포인트가 없거나 경로에 불필요한 부분이 있습니다. 내역과 캔들은 currency를 쿼리 매개변수로만 받습니다.
429	`rate_limit_exceeded`	요금제의 시간당 요청 초과
503	`prices_unavailable`	금속 가격을 지금 사용할 수 없음