과거 환율 API

기준 통화, 상대 통화 및 날짜 범위로 저장된 환율을 요청합니다.

과거 데이터 작업은 현재 승인된 저장 시계열을 오래된 순서로 반환합니다. 현재 FX 및 경제 데이터 요청과 동일한 Narwhal 키와 공유 월간 할당량을 사용합니다.

요청

REST

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/observations?currencies=EUR,NZD&start_date=2026-08-20&end_date=2026-08-28&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

매개변수	규칙
`base`	경로에 지정하는, 유통 중인 통화의 대문자 ISO 4217 코드입니다.
`currencies`	서로 다른 상대 통화 1~64개를 쉼표로 구분한 필수 목록입니다. 기준 통화는 포함할 수 없습니다.
`start_date`	필수입니다. `1971-01-01` 당일 또는 그 이후의 날짜이며 해당 날짜를 포함합니다.
`end_date`	필수입니다. 시작일 당일 또는 그 이후여야 하며 미래 날짜는 허용하지 않습니다. 해당 날짜를 포함합니다.
`limit`	페이지당 관측 날짜 수입니다. 기본값: `100`; 최대값 `366`.
`cursor`	이전 페이지의 불투명한 값입니다. 동일한 필터에서만 재사용하세요.

MCP 도구: fx_get_rate_history 해당 항목의 currencies 입력은 JSON 배열이며 다른 모든 필드는 동일한 의미를 가집니다.

응답

프로덕션 형태의 예시

{
  "base": "USD",
  "observations": [
    {
      "date": "2026-08-20",
      "rates": [
        { "currency": "EUR", "rate": "0.85609" },
        { "currency": "NZD", "rate": "1.681" }
      ]
    },
    {
      "date": "2026-08-21",
      "rates": [
        { "currency": "EUR", "rate": "0.85477" },
        { "currency": "NZD", "rate": "1.6714" }
      ]
    },
    {
      "date": "2026-08-24",
      "rates": [{ "currency": "EUR", "rate": "0.85734" }]
    }
  ],
  "next_cursor": null
}

각 환율은 십진수 문자열입니다. 기준 통화 1단위: base = 반환된 금액의 표시 통화: currency (해당 관측일 기준).

start_date와 end_date는 요금제에 따라 요청한 날짜가 변경되는 경우에만 반환됩니다.

페이지 매김

limit : 날짜 수를 세므로 같은 날짜의 통화 레코드는 여러 페이지로 나뉘지 않습니다. 다음 값: next_cursor 가 null이 아니면 base, currencies, 시작일, 종료일을 그대로 유지하여 다시 보내세요. 커서는 이 필터에 연결되어 있습니다. 필터를 변경하면 다음 오류가 반환됩니다: 400 invalid_cursor.

전체 날짜 범위에는 상한이 없습니다. 전체 과거 데이터를 채우려면 크기가 제한된 페이지를 반복 조회하세요. 종료 조건: next_cursor null입니다.

누락된 날짜와 통화는 만들어내지 않습니다

실제로 저장된 관측 날짜만 표시됩니다. 주말, 공휴일 및 발표 데이터가 없는 기타 날짜는 생략됩니다. Narwhal은 해당 날짜를 이전 값으로 채우지 않습니다.

날짜에는 요청한 통화의 일부만 포함될 수 있습니다. 예에서 NZD에는 8월 24일 레코드가 없지만 EUR에는 있습니다. 이는 부분 응답 오류가 아니라 사실에 맞는 희소 관측값입니다.

가격 바

GET /v1/fx/rates/{base}/bars는 한 통화의 USD 대비 시가, 고가, 저가, 종가를 포함하는 확정된 바를 반환합니다. MCP 도구는 fx_get_rate_bars입니다.

REST

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/bars?currency=EUR&interval=1h&start=2026-10-08T00:00:00Z&end=2026-10-08T03:00:00Z" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

매개변수	규칙
`base`	`USD`만 지원합니다. 다른 기준 통화는 `404 currency_not_supported`를 반환합니다.
`currency`	가격 수집기가 수집하는 상대 통화 하나입니다.
`interval`	`1m`, `5m`, `15m`, `1h`, `4h` 또는 `1d`(기본값).
`start / end`	둘 다 필수입니다. UTC 시각을 간격 경계에 맞춥니다(`4h`는 00, 04, 08시 등, `1d`는 자정). 시작은 포함하고 끝은 제외합니다.
`limit / cursor`	기본값은 `100`, 최댓값은 `500`입니다. 동일한 쿼리로 `next_cursor`를 재사용하세요.

각 바에는 timestamp(바의 시작 시각)와 base 한 단위당 currency 단위로 표시한 open, high, low, close가 있습니다. 빈 구간을 채우지 않으며, 누락된 바는 그대로 둡니다. 1m 및 5m 바는 30일간, 15m, 1h, 4h 및 1d 바는 무기한 보관하며, 이용 범위는 요금제의 과거 데이터 조회 기간으로 제한됩니다. 보관 기간을 벗어난 범위를 요청하면 오류가 아닌 빈 bars 목록을 반환합니다.

start와 end는 요금제에 따라 요청한 범위가 변경되는 경우에만 반환됩니다.

한 요청의 조회 범위는 1m 봉은 최대 3일, 5m 봉은 14일, 15m 봉은 60일입니다. 더 긴 범위는 400 invalid_query를 반환합니다. 더 큰 간격에는 조회 범위 제한이 없습니다.

오류

400 invalid_query —통화, 날짜 또는 페이지 크기가 잘못된 경우.
400 invalid_cursor —페이지 매김 상태의 형식이 잘못되었거나 필터와 일치하지 않는 경우.
401 invalid_api_key —Bearer 키가 없거나 유효하지 않은 경우.
403 plan_upgrade_required 요청 범위가 요금제의 과거 데이터 범위(Free 12개월, Basic 5년)보다 이전에 끝나는 경우입니다.
404 currency_not_supported —선택한 통화를 이용할 수 없는 경우.
429 rate_limit_exceeded —단기 구간 한도에 도달한 경우. 다음 헤더: Retry-After 을 확인한 후 재시도하세요.
429 quota_exhausted —공유 월간 할당량이 소진된 경우.
503 upstream_unavailable —승인된 과거 데이터를 안전하게 읽을 수 없는 경우.

다음 확인 오류 및 제한 가이드 —두 종류의 요청 제한 헤더와 재시도 동작을 확인하세요.

데이터 범위 및 제한

통화별로 데이터 제공 시작일이 다릅니다. 지원되는 저장 시계열 중 가장 이른 것은 1971년에 시작하며, 대부분의 일별 데이터는 1999년 또는 2000년부터 제공됩니다. 이 명세를 변경하지 않고도 데이터 범위가 확장될 수 있습니다.

이 인터페이스는 과거의 모든 발표 버전이 아니라 현재 승인된 과거 시계열을 반환합니다. 출처, 제공자, 라이선스, 산출 방식, 데이터가 오래되었는지 여부 및 시장 세션 필드는 생략합니다. 참고 문서: 환율 방법론 —공개 데이터 정책을 확인하세요. 다음 문서: FX 제품 페이지 —현재 제공되는 모든 작업은 이 페이지를 확인하세요.