모든 API

원유, 금속, 곡물, 가축 원자재 선물 가격 API

REST 또는 MCP로 13개 상품 선물의 최신 가격과 일봉 또는 1분봉 이력을 가져옵니다. 각 시리즈는 근월물 계약이므로 롤오버일에 가격에 단차가 생깁니다.

무료 API 키 받기
문서 읽기 →

첫 요청

WTI 원유의 최신 가격 조회

curl --request GET \
  --url "https://api.narwhalapi.com/v1/futures/CL/price" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
응답 예시
{
  "id": "CL",
  "name": "WTI Crude Oil",
  "commodity_key": "crude-oil",
  "benchmark": "wti",
  "exchange": "NYMEX",
  "exchange_mic": "XNYM",
  "currency": "USD",
  "unit": "usd_per_barrel",
  "unit_key": "barrel",
  "price": "102.11",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

엔드포인트

GET선물 목록/v1/futures

Narwhal이 가격을 제공하는 모든 선물 계약을 이름, 카테고리, 거래소, 통화, 단위와 함께 나열합니다.

응답 필드

  • futures객체 목록

    Narwhal이 가격을 제공하는 모든 계약이며, 각각 id, 이름, 카테고리, 거래소, 통화, 단위를 포함합니다.

전체 레퍼런스 →
GET선물 가격 조회/v1/futures/{id}/price

한 계약의 최신 가격을 가져옵니다.

매개변수

  • id필수

    선물 id로, 거래소의 루트 코드입니다. 예: CL, GC, ES, 6E. 대소문자는 구분하지 않습니다. 시리즈는 조정하지 않은 연속 근월물이며 교체일마다 가격 차이가 있습니다.

주요 응답 필드

  • id문자열

    CL과 같은 루트 코드입니다.

  • name문자열

    계약의 공식 명칭입니다.

  • commodity_key문자열

    원자재의 고정 키이며 현물, 선물, 예측, 실물 가격에서 모두 같습니다. 예: gold, crude-oil. 이 키로 서로 연결할 수 있습니다. 주가지수, 금리, 통화 선물에서는 생략됩니다.

  • benchmarkwti, brent, urals, dubai 중 하나

    원유 기준물이며 wti, brent, urals, dubai 중 하나입니다. 원유에만 전달되며, 이 값이 없는 원유 행은 원유 전체를 뜻합니다.

  • exchange문자열

    계약이 거래되는 거래소입니다.

  • exchange_mic문자열

    거래소의 ISO 10383 시장 식별 코드입니다. 예: XNYM.

  • currency문자열

    가격의 통화입니다.

  • unit문자열

    가격의 기준 단위입니다. 예: usd_per_barrel, index_point.

  • unit_key문자열

    단위의 표준 소문자 이름이며, 이 단위를 사용하는 모든 화면에서 동일합니다. 예: barrel, troy_ounce, mmbtu, tonne. unit은 출처의 표기를 그대로 유지합니다.

  • price_scale문자열

    가격이 보조 단위로 표시될 때만 전송됩니다. price에 이 값을 곱하면 currency 기준 가격이 됩니다. 0.01은 price가 센트 단위라는 뜻이므로, unit이 cent_per_bushel인 price 450은 부셸당 4.50 USD입니다.

전체 레퍼런스 →
GET여러 선물 가격 조회/v1/futures/prices

한 번의 호출로 최대 50개 계약의 최신 가격을 가져옵니다.

매개변수

  • ids필수

    쉼표로 구분한 id이며 중복을 제거한 뒤 최대 50개입니다. 각 id는 단건 가격 경로와 같은 규칙을 따릅니다. 가격이 반환된 id마다 호출 1회로 계산됩니다.

응답 필드

  • prices객체 목록

    가격이 반환된 id마다 하나의 항목이 있으며, 단일 가격의 필드를 그대로 갖습니다.

  • errors객체 목록

    가격을 반환하지 않은 ID로, 각각 not_found 코드가 붙습니다. 비용은 들지 않습니다.

전체 레퍼런스 →
GET선물 바 조회/v1/futures/{id}/bars

한 계약의 일봉 또는 1분봉을 오래된 순으로 가져옵니다. 가격은 가공하지 않은 근월물 가격이므로 롤오버일에 단차가 생깁니다.

매개변수

  • id필수

    선물 id로, 거래소의 루트 코드입니다. 예: CL, GC, ES, 6E. 대소문자는 구분하지 않습니다. 시리즈는 조정하지 않은 연속 근월물이며 교체일마다 가격 차이가 있습니다.

  • interval선택

    1d(거래일당 막대 1개, 해당 거래일 날짜 기준) 또는 1m(1분 막대, 12개월간 보관). 그 외의 값은 400 invalid_interval입니다.

  • start선택

    첫 번째 막대입니다. 1d: 날짜(YYYY-MM-DD), 해당 날짜 포함이며, 생략하면 가장 오래된 막대부터입니다. 1m: UTC 시각(YYYY-MM-DDTHH:MM:SSZ, 또는 00:00 UTC를 뜻하는 날짜), 해당 시각 포함이며, 생략하면 end의 하루 전입니다.

  • end선택

    마지막 막대입니다. 1d: 날짜, 해당 날짜 포함이며, 생략하면 마감된 가장 최근 거래일입니다. 1m: UTC 시각, 해당 시각 미포함이며, 생략하면 현재 시각 또는 start로부터 5일 뒤입니다. 1m에서 start와 end의 간격은 최대 5일입니다(400 range_too_large).

  • cursor선택

    이전 페이지의 next_cursor이며, 매개변수는 동일하게 사용합니다.

응답 필드

  • id문자열

    CL과 같은 루트 코드입니다.

  • commodity_key문자열

    원자재의 고정 키이며 현물, 선물, 예측, 실물 가격에서 모두 같습니다. 예: gold, crude-oil. 이 키로 서로 연결할 수 있습니다. 주가지수, 금리, 통화 선물에서는 생략됩니다.

  • benchmarkwti, brent, urals, dubai 중 하나

    원유 기준물이며 wti, brent, urals, dubai 중 하나입니다. 원유에만 전달되며, 이 값이 없는 원유 행은 원유 전체를 뜻합니다.

  • currency문자열

    가격의 통화입니다.

  • price_scale문자열

    가격이 보조 단위로 표시될 때만 전송됩니다. price에 이 값을 곱하면 currency 기준 가격이 됩니다. 0.01은 price가 센트 단위라는 뜻이므로, unit이 cent_per_bushel인 price 450은 부셸당 4.50 USD입니다.

  • start문자열

    범위의 시작이 뒤로 옮겨졌을 때만 전송됩니다.

  • end문자열

    전송되지 않습니다. 가격이 모든 계정에서 실시간이기 때문입니다.

  • bars객체 목록

    오래된 순으로 정렬된 바입니다. 각 바에는 timestamp, open, high, low, close가 있으며 거래량은 없습니다.

  • next_cursor문자열

    다음 페이지를 읽으려면 이 값을 다시 전달합니다. 마지막 페이지에서는 null입니다.

전체 레퍼런스 →

활용 사례

전체 이력 백필

이력 전체를 페이지 단위로 가져와 파일에 저장하고, 중단되면 이어서 받습니다.

가이드 읽기 →

매일 데이터 가져오기

작은 스크립트를 하루에 한 번 실행하고 결과를 CSV에 추가합니다.

가이드 읽기 →

캐싱과 429 오류

Cache responses by data type and tell a rate limit (429) from an empty credit balance (402).

가이드 읽기 →

데이터 범위

에너지

  • WTI 원유CL · NYMEX · 배럴당 USD
  • 헨리 허브 천연가스NG · NYMEX · MMBtu당 USD
  • RBOB 가솔린RB · NYMEX · 갤런당 USD
  • 뉴욕항 초저유황 디젤HO · NYMEX · 갤런당 USD

금속

  • 금GC · COMEX · 트로이온스당 USD
  • 은SI · COMEX · 트로이온스당 USD
  • 백금PL · NYMEX · 트로이온스당 USD
  • 구리HG · COMEX · 파운드당 USD

곡물

  • 옥수수ZC · CBOT · 부셸당 센트
  • 시카고 연질 적색 겨울밀ZW · CBOT · 부셸당 센트
  • 대두ZS · CBOT · 부셸당 센트

Livestock

  • 생우(Live Cattle)LE · CME · 파운드당 센트
  • 설 호그(Lean Hog)HE · CME · 파운드당 센트

관련 API

선물 API 데이터

REST와 MCP로 제공하는 29개 선물의 가격과 이력

API 탐색 →

현물 금속 가격 API

금, 은, 백금, 팔라듐의 현물 가격과 WTI, 브렌트유, 구리의 기준 가격입니다.

API 탐색 →

지수 데이터를 위한 주가지수 API

REST와 MCP로 제공하는 18개 지수의 수준과 이력

API 탐색 →

요금

매달 10달러의 무료 크레딧, 이후 1,000회당 2달러부터.

요금 보기 →

자주 묻는 질문

어떤 상품 선물을 가져올 수 있나요?

13개 계약입니다. 에너지: WTI 원유, 헨리 허브 천연가스, RBOB 가솔린, NY Harbor ULSD. 금속: 금, 은, 백금, 구리. 곡물: 옥수수, 밀, 대두. 축산: 생우와 설 호그.

현물 가격 API와는 무엇이 다른가요?

현물 API는 금을 여러 통화로, 은, 백금, 팔라듐을 미국 달러로 제공합니다. 상품 선물은 미국 달러 기준의 근월물 계약이며 계약 고유의 단위를 사용합니다. 금 선물(GC)과 금 현물(XAU)은 서로 다른 가격입니다.

왜 어떤 날은 가격이 갑자기 뛰나요?

각 시리즈는 근월물 계약을 조정 없이 이어 붙인 것입니다. 근월물이 바뀌면 시리즈는 다음 계약으로 넘어가며 가격은 그 계약의 가격으로 바뀝니다. CL은 2026년 10월 19일에 약 4달러 달라졌습니다. 가격과 바는 거래된 그대로 이 변화를 보여 주므로 하루 동안의 움직임으로 읽지 마세요. 그래서 선물 가격에는 전일 종가나 변동폭이 없습니다. 롤오버 구간에서는 변동폭이 사실과 다르기 때문입니다.

가격은 어떤 단위인가요?

각 응답에는 단위가 포함됩니다. CL은 usd_per_barrel, NG는 usd_per_mmbtu, RB와 HO는 usd_per_gallon, GC, SI, PL은 usd_per_troy_ounce, HG는 usd_per_pound입니다. 곡물은 cent_per_bushel, 축산은 cent_per_pound이므로 달러가 아닌 센트 단위입니다.

가격은 실시간인가요, 지연되나요?

가격은 모든 계정에서 실시간입니다. 일봉은 2017년 4월까지 거슬러 올라가며 모든 계정이 전체 이력을 받습니다.

비용은 얼마인가요?

호출은 1,000건당 $2이며 선불 크레딧에서 차감됩니다. 모든 계정은 가입 후 첫 12개월 동안 매월 $10의 무료 크레딧을 받습니다.