ETF API 레퍼런스: ETF와 펀드

개요

ETF와 뮤추얼 펀드의 시세, 가격 이력, 분배금, 프로필, 검색을 제공합니다. 모든 요청에 Bearer 키가 필요하며, REST와 MCP는 하나의 크레딧 잔액을 함께 사용합니다.

ETF id는 ARCX:SPY처럼 해당 종목 id입니다. 뮤추얼 펀드 id는 FUND, 콜론, 티커 순서로 쓰며 FUND:VFIAX가 그 예입니다. SPY처럼 티커만 보내는 경우에도 미국 종목 하나를 가리키면 사용할 수 있습니다. 펀드 경로에 주식 id를 보내면 404 not_found가 반환되고, 주식 경로에 펀드 id를 보내면 301로 이 경로로 이동합니다.

ETF에는 가격이 있습니다. 뮤추얼 펀드에는 하루에 한 번 순자산가치(NAV)가 있으며 nav, previous_nav, date 필드에 담깁니다. 가격 응답의 type 필드로 어느 쪽인지 구분할 수 있습니다.

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

모든 계정에 제공되는 것

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

• 뮤추얼 펀드 NAV는 장 마감 시점의 값이며 지연되지 않습니다. 다음 영업일보다 오래되면 stale로 표시됩니다.
• 뮤추얼 펀드에는 1분봉이 없습니다. 1분봉을 요청하면 400 invalid_interval이 반환됩니다.
• 뮤추얼 펀드의 일봉은 NAV입니다. 시가, 고가, 저가, 종가가 모두 같은 값이고 거래량은 없습니다.
• 분배금의 kind는 출처에서 값을 제공하기 전까지 생략됩니다.

엔드포인트

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

티커 또는 이름으로 ETF와 뮤추얼 펀드 검색

GET /v1/funds/search

티커 또는 이름이 q로 시작하는 펀드를 대소문자 구분 없이 찾습니다. 정확히 일치하는 티커가 먼저, 그다음 다른 티커, 그다음 이름 순입니다. 선택 필터로 type(etf 또는 mutual_fund)과 country(세 글자)를 쓸 수 있습니다. 한 페이지에 최대 50개이며 next_cursor가 함께 반환됩니다. 자체 심볼 목록에서 읽으므로 모든 계정에서 사용할 수 있고 호출 1회로 계산됩니다.

MCP: 도구 funds, action search.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/search?q=vanguard&type=mutual_fund"

{
  "results": [
    {
      "id": "ARCX:SPY",
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "type": "etf",
      "mic": "ARCX",
      "country": "USA",
      "currency": "USD"
    },
    {
      "id": "FUND:VFIAX",
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "type": "mutual_fund",
      "country": "USA",
      "currency": "USD"
    }
  ],
  "next_cursor": null
}

펀드 하나의 프로필

GET /v1/funds/{id}

자체 심볼 목록에 있는 그대로 펀드의 심볼, 이름, 유형(etf 또는 mutual_fund), 거래소(ETF만 해당), 국가, 통화를 반환합니다. 모든 계정에서 사용할 수 있습니다. 알 수 없는 필드는 생략됩니다.

MCP: 도구 funds, action profile.

매개변수

응답 필드

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

{
  "id": "ARCX:SPY",
  "symbol": "SPY",
  "name": "SPDR S&P 500 ETF Trust",
  "type": "etf",
  "mic": "ARCX",
  "country": "USA",
  "currency": "USD"
}

펀드 하나의 최신 가격

GET /v1/funds/{id}/price

ETF는 주식 가격 형식에 type: etf를 더한 최종 가격을, 뮤추얼 펀드는 최신 NAV를 반환합니다(type: mutual_fund: nav, previous_nav, change, change_percent, NAV 기준일 date. 장 마감 시점의 값이며 지연되지 않고, 다음 영업일보다 오래되면 stale이 됩니다). change_percent는 퍼센트 단위입니다. 주식 id는 404 not_found입니다.

MCP: 도구 funds, action price.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY/price"

{
  "id": "ARCX:SPY",
  "symbol": "SPY",
  "currency": "USD",
  "price": "578.12",
  "previous_close": "576.40",
  "change": "1.72",
  "change_percent": "0.30",
  "volume": "61230500",
  "market_session": "open",
  "timestamp": "2026-10-26T15:42:00Z",
  "stale": false,
  "type": "etf"
}

최대 50개 펀드의 최신 가격

GET /v1/funds/prices

나열된 각 펀드의 최신 가격으로, ETF는 최종 가격, 뮤추얼 펀드는 최신 NAV입니다. 가격이 반환된 id마다 호출 1회로 계산하며 한 번에 차감합니다. 조회에 성공한 id의 비용을 잔액으로 감당할 수 없으면 요청 전체가 402 insufficient_credits로 거부됩니다. 가격이 반환되지 않은 id는 errors에 나열되며 비용이 들지 않습니다. change_percent는 퍼센트 단위입니다.

ETF와 뮤추얼 펀드를 섞어 최대 50개의 id를 보낼 수 있습니다. 배치는 한 번에 차감됩니다. 조회에 성공한 id의 비용을 잔액으로 감당할 수 없으면 요청 전체가 402 insufficient_credits를 반환합니다.

MCP: 도구 funds, action prices.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/prices?ids=ARCX:SPY,FUND:VFIAX"

{
  "prices": [
    {
      "id": "ARCX:SPY",
      "symbol": "SPY",
      "currency": "USD",
      "price": "578.12",
      "previous_close": "576.40",
      "change": "1.72",
      "change_percent": "0.30",
      "volume": "61230500",
      "market_session": "open",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false,
      "type": "etf"
    },
    {
      "id": "FUND:VFIAX",
      "symbol": "VFIAX",
      "currency": "USD",
      "type": "mutual_fund",
      "nav": "551.07",
      "previous_nav": "549.80",
      "change": "1.27",
      "change_percent": "0.23",
      "date": "2026-10-23",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "FUND:NOPE",
      "code": "not_found"
    }
  ]
}

펀드 하나의 가격 봉

GET /v1/funds/{id}/bars

일봉(1d) 또는 1분봉(1m)을 오래된 순으로 주식 봉 형식으로 반환합니다. 뮤추얼 펀드의 일봉은 일별 NAV입니다(시가, 고가, 저가, 종가가 모두 NAV이며 거래량은 없습니다). 뮤추얼 펀드에는 1분봉이 없습니다(400 invalid_interval). 1분봉은 ETF만 해당합니다. 이력은 모든 계정에 전체 기간이 제공됩니다. 한 페이지에 최대 5,000개의 봉이 담기며 next_cursor가 함께 반환됩니다. 가격과 더 이상 맞지 않는 커서는 409 cursor_expired입니다. 페이지당 호출 1회입니다.

두 페이지 사이에 분할이나 분배금으로 이력이 바뀌면 커서가 더 이상 동작하지 않고 409 cursor_expired가 반환됩니다.

MCP: 도구 funds, action bars.

매개변수

응답 필드

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

{
  "id": "ARCX:SPY",
  "currency": "USD",
  "adjusted": true,
  "bars": [
    {
      "date": "2026-10-23",
      "timestamp": "2026-10-23T13:30:00Z",
      "open": "575.10",
      "high": "577.60",
      "low": "573.90",
      "close": "576.40",
      "volume": "48210300"
    }
  ],
  "next_cursor": null
}

펀드 하나의 분배금

GET /v1/funds/{id}/distributions

펀드 하나의 분배금을 권리락일이 최근인 순으로 페이지 단위로 반환합니다. 모든 계정에 전체 이력이 제공됩니다. 요청마다 호출 1회로 계산됩니다. 알 수 없는 id는 404 not_found입니다.

MCP: 도구 funds, action distributions.

매개변수

응답 필드

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY/distributions"

{
  "id": "ARCX:SPY",
  "distributions": [
    {
      "ex_date": "2026-09-18",
      "amount": "1.78",
      "currency": "USD",
      "pay_date": "2026-10-30",
      "record_date": "2026-09-18"
    }
  ],
  "next_cursor": null
}

오류

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