첫 Narwhal API 요청 보내기

하나의 API 키로 경제, 외환, 상품 현물 가격(금, 은, 백금, 팔라듐, 구리, WTI 원유 및 브렌트유), 팜유, 미국 주간 휘발유 가격(EIA), 미국 주간 경유 가격(EIA), 월간 상품 기준가격(World Bank), 일별 현물 가격(WTI 원유, 브렌트유 및 천연가스), 미국, 영국, 독일, 일본, 캐나다 수익률 곡선, 예측시장 확률(Kalshi 및 Polymarket), 경제지표 발표 일정 및 공휴일 사용을 시작하세요. Bearer 키로 인증하고 응답과 오류를 처리하는 방법을 알아보세요.

이 가이드는 CPI부터 시작하며, 다음 주소에서 제공 중인 API의 참조 문서로 안내합니다: api.narwhalapi.com.

경제 데이터 지원 범위

36 국가: AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA. 범위는 작업과 국가에 따라 다릅니다. 각 작업에 지원 국가가 표시됩니다. 모든 데이터 요청에는 Bearer 키가 필요합니다.

Free 베타 한도: 5,000 건의 성공 요청(UTC 기준 월간)과 분당 30건의 요청. REST와 MCP는 동일한 한도를 공유합니다.

API 키 설정

키를 Bearer 토큰으로 보낼 위치: Authorization 헤더입니다. URL에는 절대 넣지 마세요. 계정을 만들어 무료 키를 받으세요, 그런 다음 참고할 문서: 인증 가이드 —키를 저장하기 전에 읽으세요.

터미널

export NARWHAL_API_KEY="nw_live_..."

공식 CPI 요청

경로에 ISO 영문 3자리 국가 코드를 전달하세요. 생략 가능한 매개변수: period 매개변수를 생략하면 승인 완료 상태의 완전한 최신 발표 데이터를 반환합니다.

요청

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

응답 예시

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "index_base": "1982-84=100",
  "released_on": "2026-08-12"
}

Python 및 JavaScript 예제

애플리케이션에서 같은 환경 변수와 엔드포인트를 사용하세요. 이 예제는 기본 제공 라이브러리를 사용합니다.

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.narwhalapi.com/v1/economics/USA/cpi",
    headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data)

JavaScript · Node.js 18+

const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
  "https://api.narwhalapi.com/v1/economics/USA/cpi",
  { headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);

사용할 API 선택

API	다음으로 시작
경제 데이터 API	공식 기관의 CPI, 인플레이션, 노동, GDP 및 무역 데이터입니다. 범위는 국가와 지표에 따라 다릅니다.
환율 API	현재 환율, 통화 환산 및 페이지 매김을 지원하는 과거 데이터를 제공하며, 각 환율에 타임스탬프가 포함됩니다.
공휴일 API	발표된 공휴일 데이터로, 전국·지역별 적용 범위와 실제 휴일 적용일 정보가 포함됩니다.
팜유 API	인도네시아와 말레이시아의 CPO 및 FFB 가격을 원래 단위와 과거 데이터와 함께 제공합니다.

국가와 지표 선택

최신 발표 작업과 이에 대응하는 과거 데이터 작업을 이용할 수 있지만, 제공되는 지표는 국가마다 다릅니다. 경제 데이터 API 레퍼런스 문서에 모든 경로와 응답 구조가 나와 있습니다.

지표	경로 접미사
CPI	`/cpi`
인플레이션	`/inflation`
실업률	`/unemployment`
경제활동참가율	`/labour-force-participation`
GDP 및 성장률	`/gdp` · `/gdp-growth`
무역	`/trade`

MCP를 통해 연결

MCP 클라이언트에서 동일한 키와 스키마를 사용하세요. 도구 검색은 4개 API 전체에서 계정이 이용할 수 있는 작업을 나열합니다. 참고 문서: MCP 가이드.

클라이언트 중립 필드 맵

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

MCP 클라이언트의 보안 시크릿 설정에서 플레이스홀더를 바꾸세요. 일반 JSON은 환경 변수를 자체적으로 확장하지 않습니다.

첫 tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

초기화 및 tools/list 호출은 할당량을 소비하지 않습니다. 성공한 각 tools/call 호출은 요청 1회를 소비합니다.

응답 읽기

통합하기 전에 각 작업의 응답 스키마를 읽으세요.

규칙	의미
`period`	공식 발표가 반환하는 정확한 월, 분기 또는 연도입니다.
`released_on`	공식 발표일입니다.
십진수 문자열	값은 이진 부동소수점으로 인한 예기치 않은 문제를 피합니다.
누락 데이터	발표 데이터가 불완전하거나 이용할 수 없으면 제공을 차단하고 오류를 반환합니다. 누락값을 0으로 바꾸지 않습니다.

읽기 Narwhal이 공식 발표를 저장하고 업데이트하는 방법.

성공 응답의 할당량 헤더

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

상태와 코드로 오류 처리

먼저 HTTP 상태를 확인한 다음 사용할 값: code —애플리케이션 로직에서 사용하세요. detail 필드는 로그와 디버깅용입니다. 다음 문서: 오류 및 할당량 가이드 문서에 모든 공개 상태가 나와 있습니다.

RFC 9457 문제 응답

{
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50"
}

키와 관련해 도움이 필요하신가요? Narwhal API에 문의하세요.

새로운 내용을 확인할 문서: 변경 로그.

LLM? llms.txt를 읽으세요.