주가지수 API 레퍼런스

개요

주가지수와 변동성 지수 18개의 지수 수준과 수준 이력입니다. 모든 요청에 Bearer 키가 필요하며 REST와 MCP는 하나의 크레딧 잔액을 함께 사용합니다.

id는 지수의 표준 코드입니다. SPX는 S&P 500, NDX는 Nasdaq-100, DJI는 Dow Jones Industrial Average를 뜻합니다. 대소문자는 구분하지 않습니다. 목록 경로는 모든 id를 이름, 지역, 통화와 함께 반환합니다.

지수의 일별 이력이 들어오면 가격에 전일 종가, 변동, 퍼센트 단위의 변동이 함께 담깁니다.

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

모든 계정에 제공되는 것

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

• 이력은 보유하고 있는 시점부터 시작됩니다. S&P 500은 2023년 2월부터입니다.
• 변동성 지수(VIX, OVX, GVZ)는 금액이 아니므로 응답에 통화가 없습니다.
• 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/indices

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

MCP: 도구 indices, action list.

매개변수

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

응답 필드

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

{
  "indices": [
    {
      "id": "SPX",
      "name": "S&P 500",
      "region": "us",
      "currency": "USD"
    },
    {
      "id": "VIX",
      "name": "Cboe Volatility Index",
      "region": "us"
    }
  ]
}

지수 시리즈 하나의 최신 가격

GET /v1/indices/{id}/price

최신 가격입니다. market_session은 시리즈의 거래 시간에 따라 open 또는 closed가 됩니다. closed 시리즈는 최종 가격으로 응답하며, stale은 open 시리즈에 최근 15분 이내의 가격이 없을 때만 true입니다. previous_close는 직전 거래일의 종가이고 change_percent는 퍼센트 단위입니다.

MCP: 도구 indices, action price.

매개변수

응답 필드

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

{
  "id": "SPX",
  "name": "S&P 500",
  "currency": "USD",
  "price": "7696.46",
  "previous_close": "7681.2",
  "change": "15.26",
  "change_percent": "0.2",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

최대 50개 지수 시리즈의 최신 가격

GET /v1/indices/prices

나열된 각 id의 최신 가격입니다. 가격이 반환된 id마다 호출 1회로 계산하며 한 번에 차감합니다. 조회에 성공한 id의 비용을 잔액으로 감당할 수 없으면 요청 전체가 402 insufficient_credits로 거부됩니다. 가격이 반환되지 않은 id는 errors에 (id로) 나열되며 비용이 들지 않습니다. 조회에 성공한 id가 하나도 없어도 응답은 200이며 prices가 비어 있습니다. previous_close는 직전 거래일의 종가이고 change_percent는 퍼센트 단위입니다.

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

MCP: 도구 indices, action prices.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices/prices?ids=SPX,NDX,DJI"

{
  "prices": [
    {
      "id": "SPX",
      "name": "S&P 500",
      "currency": "USD",
      "price": "7696.46",
      "previous_close": "7681.2",
      "change": "15.26",
      "change_percent": "0.2",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    },
    {
      "id": "NDX",
      "name": "Nasdaq-100",
      "currency": "USD",
      "price": "27310.5",
      "previous_close": "27264.9",
      "change": "45.6",
      "change_percent": "0.17",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

지수 시리즈 하나의 가격 봉

GET /v1/indices/{id}/bars

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

MCP: 도구 indices, action bars.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices/SPX/bars?interval=1d&start=2026-10-01"

{
  "id": "SPX",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2026-10-28T00:00:00Z",
      "open": "7655.1",
      "high": "7702.4",
      "low": "7640.8",
      "close": "7681.2"
    }
  ],
  "next_cursor": null
}

오류

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