Reddit의 금 가격 API: 개발자 질문에 답한다

Reddit에서 금 가격 API를 검색하면 스레드는 거의 항상 같은 모양이다. 누군가 대시보드나 가격 알림, 트레이딩 봇, 또는 지금(地金) 가격을 표시하는 스토어프론트를 만들고 있고, 코드에서 바로 가져다 쓸 수 있는 실시간 금 가격을 원한다. 무엇이든 연결하기 전에, 이들은 r/algotrading, r/webdev, r/golang에서 매번 같은 몇 가지 질문을 던진다. 무료 등급이 있는가, 숫자는 얼마나 최신인가, 한도는 얼마인가, 상업적으로 써도 되는가, 그 데이터를 신뢰할 수 있는가.

이 글은 goldprice.dev를 실제 예시로 삼아 그 질문들에 직접 답한다. 읽는 데 가입은 필요 없고, 아래 첫 번째 API 호출도 키 없이 실행된다.

goldprice.dev는 무엇이고, 무엇이 아닌가

개발자를 위한 원자재 가격 API다. https://api.goldprice.dev의 단일 인증 REST 엔드포인트로 금, 은, 구리를 제공한다. 모든 응답에는 교차 검증된 데이터 신선도 플래그가 실려 있고, ?include=로 소스별 가격과 타임스탬프, 혹은 괴리 수치를 요청할 수 있으므로, 코드가 조용히 실패하는 대신 특정 업스트림이 지연되고 있음을 알아챌 수 있다. MCP 서버는 무료 등급을 포함한 모든 플랜에 포함되어 있다.

이것은 증권사도, 결제 피드도 아니다. 여기 나오는 가격은 표시, 분석, 알림을 위해 공개되는 참고용 지표다. 거래를 결제할 실행 가능한 딜링 호가가 필요하다면, 공개된 금 가격 API 중 그 어느 것도(이 API를 포함해) 맞는 도구가 아니다.

무료 등급이 있는가

있고, 카드 등록도 필요 없다. 무료 플랜은 15분 지연된 금(XAU) 현물 가격을 대상으로 월 1,000회 호출, 분당 30회 요청을 제공한다. 유료 플랜은 은과 구리, 선물 결제 데이터, 더 높은 한도, 상업적 권리를 추가한다.

가격은 얼마나 자주 갱신되는가

실시간 현물 가격은 정식 이용 허가를 받은 시장 원천 데이터에 기반하며, Free 플랜·익명 호출·이 웹사이트에는 15분 늦게 제공된다. 선물 결제값은 거래소의 결제 스케줄에 맞춰 갱신된다. 이 API의 핵심은 지금 보고 있는 값이 어느 쪽인지 절대 추측할 필요가 없다는 데 있다. 모든 응답에는 computed_at이 실리고, 값이 예상 갱신 주기보다 오래되면 is_stale이 설정되며, 필요하면 ?include=sources로 소스별 타임스탬프까지 분해해 볼 수 있다. 신선도는 뭉뚱그린 "실시간" 라벨을 믿는 대신 페이로드에서 직접 읽는다.

속도 제한은 얼마인가

Free는 분당 30회 요청이고, 유료 플랜은 각각 120회와 500회다. 모든 응답은 표준 X-RateLimit-Remaining 헤더를 함께 반환하므로, 올바른 패턴은 무작정 폴링하다 429를 맞는 것이 아니라 이 헤더를 읽고 잔여량이 적을 때 속도를 늦추는 것이다. 대부분의 앱에서는 실제로 값이 움직이는 빈도에 맞춘 짧은 클라이언트 캐시만으로도 무료 등급 안에 넉넉히 머물 수 있다.

인증은 어떻게 하는가

베어러 토큰이다. 키는 ga_live_로 시작하며 Authorization 헤더에 넣는다. IP당 분당 30회, 시간당 100회, 월 1,000회로 제한된 익명 접근도 있는데, 가격, 타임스탬프, 신선도 필드를 반환한다. bid/ask는 유료 전용 선택 필드이며 일관된 양방향 호가가 필요하다. 인증하면 시가·고가·저가·전일 종가·변동폭·소스 간 괴리 필드를 담은 ?include=stats가 열린다. ?include=sources와 ?include=karat는 인증 여부와 관계없이 사용할 수 있다.

이 숫자가 어디서 오는지 볼 수 있는가

볼 수 있고, 이 부분이야말로 대부분의 API가 감추는 지점이다. ?include=sources를 붙이면 응답에 sources[] 배열이 포함되는데, 업스트림마다 한 행씩, 각각 자체 가격과 타임스탬프를 갖는다. 소스 간에 의견이 갈릴 때는 ?include=stats(인증 필요)에 divergence_bps와 divergence_flag가 실리므로, 출처를 알 수 없는 단일 혼합값을 그냥 믿는 대신 스스로 허용 오차를 정할 수 있다. 잘못된 가격에 비용이 따르는 무언가를 만들고 있다면, 이 가시성이야말로 웹페이지를 스크래핑하는 대신 구조화된 API를 쓰는 이유다.

상업적으로 써도 되는가

무료와 Physical 등급은 개인 사용 및 평가용이다. 상업적 이용, 즉 자신이 출시하는 제품에 가격을 다시 표시하는 것은 Pro 플랜부터 가능하며 출처 표기가 필요하다. 자신의 사용자에게 금 가격을 보여줄 생각이라면 Pro가 최소 기준이다.

내 LLM 에이전트가 이걸 쓸 수 있는가

쓸 수 있다. MCP 서버는 무료 등급을 포함한 모든 플랜에 들어 있다. Claude, Cursor, 또는 MCP를 지원하는 어떤 런타임에든 설정 블록 하나만 추가하면 에이전트가 도구 코드를 손으로 짜지 않고도 실시간 가격을 바로 가져온다. 데이터는 REST API가 제공하는 것과 동일하다. 설정 세부사항이 필요하면 전체 MCP 안내를 참고하라.

가장 짧은 호출

키도, 의존성도 없이:

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT

가격과 신선도 플래그가 담긴 JSON을 15분 지연으로 받는다. bid/ask는 유료 전용 선택 필드이며 일관된 양방향 호가가 있을 때만 제공된다. 캐럿별 그램당 내역이 필요하면 ?include=karat을, 기여한 소스가 필요하면 ?include=sources를 붙인다. 전체 응답 구조와 더 높은 한도가 필요할 때는 무료 키 발급이 1분이면 끝난다.

언어별 안내가 필요하다면, JavaScript로 실시간 금 가격 가져오기에서 REST 경로를 처음부터 끝까지 다루고, 금 가격 캐싱과 속도 제한 안에 머물기에서 대량 트래픽에서 그렇게 하는 방법을 다룬다.