선물 API 레퍼런스

개요

29개 선물의 가격과 가격 이력입니다. 원자재, 주가지수, 국채, 통화가 포함됩니다. 모든 요청에 Bearer 키가 필요하며 REST와 MCP는 하나의 크레딧 잔액을 함께 사용합니다.

id는 거래소의 루트 코드입니다. CL은 WTI 원유, GC는 금, ES는 E-mini S&P 500, 6E는 유로를 뜻합니다. 대소문자는 구분하지 않습니다. 목록 경로는 모든 id를 이름, 카테고리, 거래소, 통화, 단위와 함께 반환합니다.

각 시리즈는 근월물 계약을 이어 붙인 것이며 조정하지 않습니다. 근월물이 바뀌는 날에는 가격이 한 계약에서 다음 계약으로 단계적으로 바뀝니다. 이 차이는 거래된 그대로 데이터에 들어 있습니다.

기본 URL: https://api.narwhalapi.com. MCP 도구: futures, with one action 를 아래 각 라우트에 대응해 둡니다.

모든 계정에 제공되는 것

확인 요금 페이지에서 호출당 비용을 확인할 수 있습니다. 라우트에 별도 안내가 없으면 요청은 해당 API의 가격으로 청구됩니다.

• 선물 가격에는 전일 종가, 변동, 거래량이 없습니다. 만기 교체를 가로지르는 변동은 잘못된 값이 되므로 API는 이를 계산하지 않습니다.
• 가격과 봉은 거래된 그대로의 근월물입니다. 교체일마다 값이 단계적으로 바뀌며, CL은 2026년 10월 19일에 약 4달러 달라졌습니다. 이 차이를 하루 동안의 변동으로 읽지 마십시오.
• market_session은 계약의 공시된 거래 시간에 따라 open 또는 closed가 됩니다. closed 시리즈는 최종 가격으로 응답하며 stale이 아닙니다. open 시리즈는 가격이 15분을 넘으면 stale입니다.
• 일봉은 거래일 하루이며 00:00 UTC에 나타납니다. 오늘의 미완성 봉은 표시되지 않습니다.
• 1분봉은 12개월 동안 보관되며 요청 한 번으로 최대 5일까지 조회할 수 있습니다.
• 배치에는 최대 50개의 id를 담을 수 있으며 가격이 반환된 id마다 호출 1회로 계산됩니다. 알 수 없는 id는 errors에 나열되고 계산되지 않습니다.

엔드포인트

모든 경로는 GET이며, 키를 다음 헤더에 담아 보내야 합니다: Authorization: Bearer 헤더입니다. 예시는 응답의 형태를 보여 줄 뿐이며 실시간 데이터가 아닙니다.

가격을 제공하는 선물

GET /v1/futures

가격을 제공하는 모든 선물 시리즈를 id별로 이름, 단위와 함께 반환합니다. 자체 목록에서 읽으므로 모든 계정에서 사용할 수 있고 호출 1회로 계산됩니다.

MCP: 도구 futures, action list.

매개변수

이 라우트는 파라미터가 없습니다.

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures"

{
  "futures": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "category": "energy",
      "exchange": "NYMEX",
      "currency": "USD",
      "unit": "usd_per_barrel"
    },
    {
      "id": "GC",
      "name": "Gold",
      "category": "metals",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce"
    }
  ]
}

선물 시리즈 하나의 최신 가격

GET /v1/futures/{id}/price

최신 가격입니다. market_session은 시리즈의 거래 시간에 따라 open 또는 closed가 됩니다. closed 시리즈는 최종 가격으로 응답하며, stale은 open 시리즈에 최근 15분 이내의 가격이 없을 때만 true입니다. 선물 가격에는 전일 종가, 변동, 거래량이 없습니다. 시리즈는 근월물을 이어 붙인 것이며 조정하지 않으므로 교체일마다 가격 차이가 생깁니다.

MCP: 도구 futures, action price.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/CL/price"

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

최대 50개 선물 시리즈의 최신 가격

GET /v1/futures/prices

나열된 각 id의 최신 가격입니다. 가격이 반환된 id마다 호출 1회로 계산하며 한 번에 차감합니다. 조회에 성공한 id의 비용을 잔액으로 감당할 수 없으면 요청 전체가 402 insufficient_credits로 거부됩니다. 가격이 반환되지 않은 id는 errors에 (id로) 나열되며 비용이 들지 않습니다. 조회에 성공한 id가 하나도 없어도 응답은 200이며 prices가 비어 있습니다. 선물 가격에는 전일 종가, 변동, 거래량이 없습니다. 시리즈는 근월물을 이어 붙인 것이며 조정하지 않으므로 교체일마다 가격 차이가 생깁니다.

최대 50개의 ID를 보낼 수 있습니다. 배치는 한 번에 과금됩니다. 확인된 ID의 비용을 잔액으로 감당할 수 없으면 전체 요청이 402 insufficient_credits를 반환합니다.

MCP: 도구 futures, action prices.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/prices?ids=CL,GC,ES"

{
  "prices": [
    {
      "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
    },
    {
      "id": "GC",
      "name": "Gold",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce",
      "price": "4021.3",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

선물 시리즈 하나의 가격 봉

GET /v1/futures/{id}/bars

일봉(1d, 거래일당 봉 1개) 또는 1분봉(1m)을 오래된 순으로 반환합니다. 하루치 봉은 그날 이후 00:00 UTC에 나오며 오늘의 미완성 봉은 표시되지 않습니다. 1분봉은 12개월 동안 보관됩니다. 이력은 모든 계정에 전체 기간이 제공됩니다. 한 페이지에 최대 5,000개의 봉이 담기며 next_cursor가 함께 반환됩니다. 페이지당 호출 1회입니다.

봉은 조정하지 않은 근월물 가격이므로 교체일에는 봉의 시가가 직전 봉의 종가와 다를 수 있습니다.

MCP: 도구 futures, action bars.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/ES/bars?interval=1d&start=2017-04-03&end=2017-04-05"

{
  "id": "ES",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2017-04-03T00:00:00Z",
      "open": "2357.5",
      "high": "2363.25",
      "low": "2340",
      "close": "2354.5"
    }
  ],
  "next_cursor": null
}

오류

오류는 공통 문제 형식을 사용하며, 다음 필드를 포함합니다: request_id. 확인 API 오류 코드와 크레딧 형식과 크레딧 헤더에 대한 설명이 있습니다. 실패한 요청에는 요금이 부과되지 않습니다.