주가 API 레퍼런스
상장 주식의 가격, 이력, 기업 이벤트, 밸류에이션 비율
개요
상장 주식의 시세, 가격 이력, 기업 이벤트, 시가총액, 밸류에이션 비율을 제공합니다. 모든 요청에 Bearer 키가 필요하며, REST와 MCP는 하나의 크레딧 잔액을 함께 사용합니다.
종목 ID는 거래소의 4자리 코드, 콜론, 티커로 이루어지며 XNAS:MSFT, XNYS:BRK.B 같은 형식입니다. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 모든 응답에는 정식 ID가 포함됩니다. 가격과 금액은 십진 문자열입니다.
각 종목에는 company_id가 있을 수 있습니다. 이 ID는 종목을 Filings API의 기업과 연결하므로, 가격, 밸류에이션, 재무제표를 하나의 ID로 함께 조회할 수 있습니다.
기본 URL: https:/. MCP 도구: equities, with one action 를 아래 각 라우트에 대응해 둡니다.
A company_ 종목을 다음과 연결합니다: 공시 API: 재무제표, 공시, 보유자 정보를 제공합니다.
모든 계정에 제공되는 것
| 항목 | 모든 계정 |
|---|---|
| 최신 가격 | 라이브 |
| 시세의 당일 거래량 | 포함 |
| 일봉과 과거 배당, 분할, 실적 | 전체 이력 |
| 1분봉 | 포함 |
| 검색 및 프로필 | 포함 |
| 급등락 종목 | 포함 |
| 시가총액, P/E, P/S, P/B, 배당수익률 | 포함 |
| 밸류에이션 이력 | 전체 이력 |
| 자본비용과 베타 | 포함 |
확인 요금 페이지에서 호출당 비용을 확인할 수 있습니다. 라우트에 별도 안내가 없으면 요청은 해당 API의 가격으로 청구됩니다.
- 밸류에이션은 당사 공시의 기업과 일치하는 미국 및 한국 종목을 대상으로 합니다. 한국은 현재 P/E만 제공합니다.
- 정확하게 산출할 수 없는 비율은 제외됩니다. 0으로 전송되지 않습니다.
- 실적의 eps_actual은 시장 데이터 기준입니다. pe_ratio의 기초가 되는 EPS는 기업 공시에서 가져옵니다. 두 값은 다를 수 있으므로 직접 비교하지 마십시오.
- 자본비용은 당사 공시의 기업과 일치하는 미국 및 한국 종목을 대상으로 합니다. 주식 위험 프리미엄은 erp로 직접 전달합니다. 산출 방법은 자본비용 방법론에 한 번 기술되어 있으며, 모든 응답에 해당 링크가 포함됩니다.
- 은행과 보험사는 이자가 영업 비용이므로 422 not_applicable을 반환합니다. 산출할 수 없는 입력값은 임의로 채우지 않고 422 inputs_unavailable에 명시합니다.
- 밸류에이션 이력은 일별이 아니라 회계 기간 종료일(분기 또는 연말)마다 하나의 시점을 제공합니다. 각 시점은 해당 일 또는 그 직전의 종가(분할만 조정)와 해당 기간에 제출된 수치를 사용합니다.
- 실적은 과거 결과만 포함합니다. 예정된 실적 발표일은 아직 포함되지 않습니다.
- 일본 프로필에는 name, exchange, country, currency, company_id만 포함됩니다.
엔드포인트
모든 경로는 GET이며, 키를 다음 헤더에 담아 보내야 합니다: Authorization: Bearer 헤더입니다. 예시는 응답의 형태를 보여 줄 뿐이며 실시간 데이터가 아닙니다.
티커 또는 이름으로 주식 검색
GET /v1/equities/search
티커 또는 이름이 q로 시작하는 종목을 대소문자 구분 없이 반환합니다. 순서는 정확히 일치하는 티커, 그 외 티커, 이름 순입니다. 선택 필터로 country(3글자)와 type을 사용할 수 있습니다. 한 페이지에 최대 50건이며 next_를 제공합니다. 자체 심볼 목록에서 읽으므로 모든 계정에서 사용할 수 있고 1회 호출로 계산됩니다.
MCP: 도구 equities, action search.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
q | 쿼리 | 예 | 문자열 | 티커 또는 회사 이름의 앞부분, 대소문자 구분 없음, 2자 이상(예: ms 또는 micro). 순서: 정확히 일치하는 티커, 그 외 티커, 이름의 시작 부분, 이름 중 뒤쪽 단어의 시작 부분 순이며, 각 구간에서 미국 주 상장 종목이 먼저 옵니다. |
country | 쿼리 | 아니요 | 문자열 | 해당 국가의 종목만 반환합니다. 3글자 코드(USA, KOR). |
type | 쿼리 | 아니요 | 다음 중 하나: common_stock, preferred_stock, depositary_receipt, reit, closed_end_fund, unit, right, warrant, other | 해당 종류의 종목만 반환합니다. |
cursor | 쿼리 | 아니요 | 문자열 | 이전 페이지의 next_. 다른 매개변수는 동일하게 유지합니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
results | 객체 목록 | 항상 | 한 페이지에 최대 50건. |
results[].id | 문자열 | 항상 | 정식 종목 ID. |
results[].symbol | 문자열 | 항상 | 해당 거래소의 티커. |
results[].name | 문자열 | 항상 | 자체 심볼 목록에 있는 그대로의 이름입니다. |
results[].type | 다음 중 하나: common_stock, preferred_stock, depositary_receipt, reit, closed_end_fund, unit, right, warrant, other | 항상 | 상품의 종류입니다. |
results[].mic | 문자열 | 항상 | 거래소의 4자리 코드. |
results[].country | 문자열 | 선택 | 종목의 국가, 3글자 코드. |
results[].currency | 문자열 | 항상 | 가격의 통화입니다. |
results[].company_ | 문자열 | 선택 | 종목이 하나의 기업과 명확히 일치할 때 해당 기업의 공시 ID. |
next_ | 문자열 | 항상 | 다음 페이지를 읽으려면 이 값을 다시 전달합니다. 마지막 페이지에서는 null입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/search?q=micro"{
"results": [
{
"id": "XNAS:MSFT",
"symbol": "MSFT",
"name": "Microsoft Corporation",
"type": "common_stock",
"mic": "XNAS",
"country": "USA",
"currency": "USD",
"company_id": "usa:0000789019"
}
],
"next_cursor": null
}주식 한 종목의 프로필
GET /v1/equities/{id}
종목(symbol, name, type, exchange, country, currency), 기업의 섹터, 업종, 웹사이트, 그리고 종목이 당사 공시의 기업과 일치하는 경우 company_를 반환합니다. 모든 계정에서 사용할 수 있습니다. 일본 종목에는 name, exchange, country, currency, company_만 포함됩니다. 알 수 없는 필드는 제외됩니다.
MCP: 도구 equities, action profile.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
symbol | 문자열 | 항상 | 해당 거래소의 티커. |
name | 문자열 | 항상 | 자체 심볼 목록에 있는 그대로의 이름입니다. |
type | 다음 중 하나: common_stock, preferred_stock, depositary_receipt, reit, closed_end_fund, unit, right, warrant, other | 항상 | 상품의 종류입니다. |
mic | 문자열 | 항상 | 거래소의 4자리 코드. |
country | 문자열 | 선택 | 종목의 국가, 3글자 코드. |
currency | 문자열 | 항상 | 가격의 통화입니다. |
sector | 문자열 | 선택 | 섹터. 프로필 텍스트가 없는 일본 종목에서는 제외됩니다. |
industry | 문자열 | 선택 | 업종. 일본 종목에서는 제외됩니다. |
website | 문자열 | 선택 | 기업의 웹사이트. 일본 종목에서는 제외됩니다. |
logo_ | 문자열 | 선택 | 당사가 보관 중인 기업 로고 사본. 없으면 제외됩니다. |
company_ | 문자열 | 선택 | 종목이 하나의 기업과 명확히 일치할 때 해당 기업의 공시 ID. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT"{
"id": "XNAS:MSFT",
"symbol": "MSFT",
"name": "Microsoft Corporation",
"type": "common_stock",
"mic": "XNAS",
"country": "USA",
"currency": "USD",
"sector": "Technology",
"industry": "Software",
"website": "https://www.microsoft.com",
"company_id": "usa:0000789019"
}주식 한 종목의 최신 시세
GET /v1/equities/{id}/price
종목 하나의 최신 시세. change_는 퍼센트 단위입니다. 알 수 없는 ID는 404 not_found이며, 아직 시세가 없는 시장은 404 not_covered입니다.
MCP: 도구 equities, action price.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
symbol | 문자열 | 항상 | 해당 거래소의 티커. |
currency | 문자열 | 항상 | 모든 가격 필드의 통화. 펜스는 파운드로 환산됩니다. |
price | 문자열 | 항상 | currency 기준의 최종 가격. |
previous_ | 문자열 | 선택 | 직전 거래일 종가. 알 수 없으면 제외됩니다. |
change | 문자열 | 선택 | price에서 previous_를 뺀 값. previous_가 제외되면 함께 제외됩니다. |
change_ | 문자열 | 선택 | previous_ 대비 변동, 퍼센트 단위(1.5는 1.5%를 의미). |
volume | 문자열 | 선택 | 오늘 거래된 주식 수. 알 수 없으면 제외되며, 지연 응답에서는 항상 제외됩니다. |
market_ | 다음 중 하나: pre, open, post, closed | 항상 | timestamp 시점의 종목 거래소 상태: pre, open, post, closed 중 하나. pre와 post는 미국 거래소에만 있습니다. |
timestamp | 날짜·시간 | 항상 | 가격이 유효했던 시각(UTC, 초 단위). |
stale | 불리언 | 항상 | 거래소가 열려 있는 동안 가격이 15분보다 오래되었거나 갱신하지 못한 경우 true입니다. 휴장 중인 시장은 지연으로 처리되지 않습니다. |
delayed | 항상 true | 선택 | 전송되지 않음: 모든 계정에서 가격은 실시간입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/price"{
"id": "XNAS:MSFT",
"symbol": "MSFT",
"currency": "USD",
"price": "421.35",
"previous_close": "418.90",
"change": "2.45",
"change_percent": "0.58",
"volume": "18234100",
"market_session": "open",
"timestamp": "2026-10-26T15:42:00Z",
"stale": false
}최대 50개 주식의 최신 시세
GET /v1/equities/prices
나열한 각 ID의 최신 시세. 시세를 반환한 ID마다 1회 호출로 계산하며, 한 번에 처리합니다. 확인된 ID의 비용을 잔액으로 감당할 수 없으면 전체 요청이 402 insufficient_credits로 거부됩니다. 시세를 반환하지 않은 ID는 errors에 나열되며 비용이 없습니다. change_는 퍼센트 단위입니다.
최대 50개의 ID를 보낼 수 있습니다. 배치는 한 번에 과금됩니다. 확인된 ID의 비용을 잔액으로 감당할 수 없으면 전체 요청이 402 insufficient_credits를 반환합니다.
MCP: 도구 equities, action prices.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
ids | 쿼리 | 예 | 문자열 | 쉼표로 구분한 종목 ID, 중복 제거 후 최대 50개. 각 ID는 단일 시세 경로와 같은 규칙을 따릅니다. 시세를 반환한 ID마다 1회 호출로 계산됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
prices | 객체 목록 | 항상 | 확인된 ID별 시세 하나씩. |
prices[].id | 문자열 | 항상 | 정식 종목 ID. |
prices[].symbol | 문자열 | 항상 | 해당 거래소의 티커. |
prices[].currency | 문자열 | 항상 | 모든 가격 필드의 통화. 펜스는 파운드로 환산됩니다. |
prices[].price | 문자열 | 항상 | currency 기준의 최종 가격. |
prices[].previous_ | 문자열 | 선택 | 직전 거래일 종가. 알 수 없으면 제외됩니다. |
prices[].change | 문자열 | 선택 | price에서 previous_를 뺀 값. previous_가 제외되면 함께 제외됩니다. |
prices[].change_ | 문자열 | 선택 | previous_ 대비 변동, 퍼센트 단위(1.5는 1.5%를 의미). |
prices[].volume | 문자열 | 선택 | 오늘 거래된 주식 수. 알 수 없으면 제외되며, 지연 응답에서는 항상 제외됩니다. |
prices[].market_ | 다음 중 하나: pre, open, post, closed | 항상 | timestamp 시점의 종목 거래소 상태: pre, open, post, closed 중 하나. pre와 post는 미국 거래소에만 있습니다. |
prices[].timestamp | 날짜·시간 | 항상 | 가격이 유효했던 시각(UTC, 초 단위). |
prices[].stale | 불리언 | 항상 | 거래소가 열려 있는 동안 가격이 15분보다 오래되었거나 갱신하지 못한 경우 true입니다. 휴장 중인 시장은 지연으로 처리되지 않습니다. |
prices[].delayed | 항상 true | 선택 | 전송되지 않음: 모든 계정에서 가격은 실시간입니다. |
errors | 객체 목록 | 항상 | 시세를 반환하지 않은 ID. 과금되지 않습니다. |
errors[].id | 문자열 | 항상 | 요청한 그대로의 ID. |
errors[].code | 다음 중 하나: not_found, not_covered, upstream_busy | 항상 | not_found: 해당 종목 없음. not_covered: 해당 거래소는 아직 시세가 없음. upstream_busy: 지금은 시세를 가져올 수 없으므로 잠시 후 다시 시도하십시오. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/prices?ids=XNAS:MSFT,XNAS:NVDA"{
"prices": [
{
"id": "XNAS:MSFT",
"symbol": "MSFT",
"currency": "USD",
"price": "421.35",
"previous_close": "418.90",
"change": "2.45",
"change_percent": "0.58",
"volume": "18234100",
"market_session": "open",
"timestamp": "2026-10-26T15:42:00Z",
"stale": false
},
{
"id": "XNAS:NVDA",
"symbol": "NVDA",
"currency": "USD",
"price": "188.20",
"previous_close": "187.10",
"change": "1.10",
"change_percent": "0.59",
"volume": "152003400",
"market_session": "open",
"timestamp": "2026-10-26T15:42:00Z",
"stale": false
}
],
"errors": [
{
"id": "XNAS:NOPE",
"code": "not_found"
}
]
}미국 주식 상위 등락 종목
GET /v1/equities/movers
direction에 따른 미국 주식과 ETF 상위 25개: gainers, losers, active(당일 상승 및 하락 상위 종목 중 거래대금이 가장 큰 종목이며 시장 전체 기준이 아님). 가격이 $1 이상이고 오늘 거래량 100,000주 이상, 거래대금 $1 million 이상인 보통주와 ETF만 포함하며, 당사가 순위를 매기고 10분간 캐시합니다. change_는 퍼센트 단위입니다. market은 현재 us만 가능하며 다른 시장은 404 not_covered, 알 수 없는 direction은 400 invalid_query입니다. 1회 호출.
급등락 종목은 미국만 지원합니다. 다른 시장은 404 not_covered를 반환합니다.
MCP: 도구 equities, action movers.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
market | 쿼리 | 아니요 | 문자열 | 순위를 매길 시장. 현재는 us만 가능하며 다른 시장은 404 not_covered입니다. |
direction | 쿼리 | 아니요 | 문자열 | gainers(가장 크게 상승), losers(가장 크게 하락), active(당일 상승 및 하락 상위 종목 중 거래대금이 가장 큼, 시장 전체 기준이 아님). 그 외 값은 400 invalid_query입니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
market | 항상 "us" | 항상 | 순위를 매긴 시장. |
direction | 다음 중 하나: gainers, losers, active | 항상 | 요청한 순위. |
movers | 객체 목록 | 항상 | 최대 25개, 상위 순. 가격이 $1 이상이고 오늘 거래량 100,000주 이상, 거래대금 $1 million 이상인 보통주와 ETF만 포함합니다. |
movers[].id | 문자열 | 항상 | 정식 종목 ID. |
movers[].symbol | 문자열 | 항상 | 해당 거래소의 티커. |
movers[].name | 문자열 | 항상 | 회사 또는 펀드 이름. |
movers[].price | 문자열 | 항상 | 미국 달러 기준 최신 가격. |
movers[].change_ | 문자열 | 항상 | 직전 종가 대비 변동, 퍼센트 단위(31.4는 31.4%를 의미), 소수 둘째 자리. |
movers[].volume | 문자열 | 항상 | 오늘 거래된 주식 수. |
timestamp | 날짜·시간 | 항상 | 목록에서 가장 최신인 가격이 유효했던 시각(UTC). |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/movers?market=us&direction=gainers"{
"market": "us",
"direction": "gainers",
"movers": [
{
"id": "XNAS:NVDA",
"symbol": "NVDA",
"name": "NVIDIA Corporation",
"price": "188.20",
"change_percent": "4.12",
"volume": "152003400"
}
],
"timestamp": "2026-10-26T15:42:00Z"
}주식 한 종목의 가격 봉
GET /v1/equities/{id}/bars
일봉(1d) 또는 1분봉(1m)을 오래된 순으로 반환하며, 분할과 배당이 반영되어 조정됩니다. 이력: 모든 계정에 전체 제공. 1분봉은 2020년까지 거슬러 올라가며 한 번 호출에 최대 5일을 포함합니다(400 range_too_large). 당일 일봉은 거래소 마감 후에 나타납니다. 한 페이지에 최대 5,000개의 봉이며 next_를 제공합니다. 가격과 더 이상 일치하지 않는 커서는 409 cursor_expired입니다. 페이지당 1회 호출.
봉은 분할과 배당이 반영되어 조정됩니다. 두 페이지 사이에 분할이나 배당으로 이력이 바뀌면 커서가 작동하지 않으며 409 cursor_expired를 반환합니다.
MCP: 도구 equities, action bars.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
interval | 쿼리 | 아니요 | 다음 중 하나: 1d, 1m | 1d(세션당 봉 하나) 또는 1m(1분봉). 그 외 값은 400 invalid_interval입니다. |
start | 쿼리 | 아니요 | 문자열 | 첫 봉. 1d: 날짜(YYYY-MM-DD), 해당 일 포함, 생략하면 가장 오래된 봉. 1m: UTC 시각(YYYY-MM-DDTHH:MM:SSZ, 또는 00:00 UTC를 뜻하는 날짜), 포함, 생략하면 end의 하루 전. |
end | 쿼리 | 아니요 | 문자열 | 마지막 봉. 1d: 날짜, 해당 일 포함, 생략하면 봉이 나온 가장 최근 세션. 1m: UTC 시각, 해당 시각 미포함, 생략하면 현재 또는 start로부터 5일 뒤. 1m에서 start와 end 사이는 최대 5일입니다(400 range_too_large). |
cursor | 쿼리 | 아니요 | 문자열 | 이전 페이지의 next_. 다른 매개변수는 동일하게 유지합니다. 커서 뒤의 가격이 바뀌면(분할 또는 배당) 커서가 작동하지 않으며 409 cursor_expired입니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
currency | 문자열 | 항상 | 모든 가격의 통화. 펜스는 파운드가 됩니다. |
adjusted | 불리언 | 항상 | 항상 true: 가격은 분할과 배당이 반영되어 조정됩니다. 한 페이지와 다음 페이지는 항상 일치하며, 두 페이지 사이에 분할이나 배당으로 이력이 바뀌면 둘을 섞지 않고 커서가 작동하지 않습니다(409 cursor_expired). |
start | 문자열 | 선택 | 전송되지 않음: start는 이동되지 않습니다. |
end | 문자열 | 선택 | 전송되지 않음: 일봉은 잘리지 않습니다. |
bars | 객체 목록 | 항상 | 한 페이지에 최대 5,000개의 봉. |
bars[].date | 문자열 | 선택 | 세션 날짜(YYYY-MM-DD). 일봉에만 있으며 1분봉에서는 제외됩니다. |
bars[].timestamp | 날짜·시간 | 항상 | 봉 기간의 시작(UTC): 일봉은 거래소 개장 시각, 1분봉은 해당 분. |
bars[].open | 문자열 | 항상 | 해당 기간의 첫 가격입니다. |
bars[].high | 문자열 | 항상 | 해당 기간의 최고가입니다. |
bars[].low | 문자열 | 항상 | 해당 기간의 최저가입니다. |
bars[].close | 문자열 | 항상 | 해당 기간의 마지막 가격입니다. |
bars[].volume | 문자열 | 선택 | 기간 중 거래된 주식 수. 알 수 없으면 제외됩니다. |
next_ | 문자열 | 항상 | 다음 페이지를 읽으려면 이 값을 다시 전달합니다. 마지막 페이지에서는 null입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/bars?interval=1d&start=2026-10-01"{
"id": "XNAS:MSFT",
"currency": "USD",
"adjusted": true,
"bars": [
{
"date": "2026-10-23",
"timestamp": "2026-10-23T13:30:00Z",
"open": "417.10",
"high": "420.55",
"low": "415.80",
"close": "418.90",
"volume": "21034500"
}
],
"next_cursor": null
}주식 한 종목의 배당
GET /v1/equities/{id}/dividends
종목 하나의 현금 배당을 배당락일 최신 순으로 페이지 단위로 반환합니다. 발표된 미래 항목이 포함될 수 있습니다. 모든 계정에 전체 이력을 제공합니다. 예정 항목은 잘리지 않습니다. 요청당 1회 호출로 계산됩니다. 알 수 없는 ID는 404 not_found이며, 아직 데이터가 없는 시장은 404 not_covered입니다.
MCP: 도구 equities, action dividends.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
cursor | 쿼리 | 아니요 | 문자열 | 이전 페이지의 next_. 다른 매개변수는 동일하게 유지합니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
start | 날짜 | 선택 | 전송되지 않음: 모든 계정에 전체 이력을 제공합니다. |
dividends | 객체 목록 | 항상 | 배당락일 최신 순. 발표된 미래 항목이 포함될 수 있습니다. |
dividends[].ex_ | 날짜 | 항상 | 배당 없이 주식이 거래되는 첫 날(배당락일). |
dividends[].amount | 문자열 | 항상 | 주당 배당금, currency 기준. |
dividends[].currency | 문자열 | 항상 | amount의 통화. 펜스는 파운드로 환산됩니다. |
dividends[].pay_ | 날짜 | 선택 | 지급일. 알 수 없으면 제외됩니다. |
dividends[].record_ | 날짜 | 선택 | 주주가 명부에 올라 있어야 하는 날(기준일). 알 수 없으면 제외됩니다. |
next_ | 문자열 | 항상 | 다음 페이지를 읽으려면 cursor로 전달합니다. 마지막 페이지에서는 null입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/dividends"{
"id": "XNAS:MSFT",
"dividends": [
{
"ex_date": "2026-08-20",
"amount": "0.91",
"currency": "USD",
"pay_date": "2026-09-10",
"record_date": "2026-08-20"
}
],
"next_cursor": null
}주식 한 종목의 분할
GET /v1/equities/{id}/splits
종목 하나의 주식 분할을 최신 순으로 반환합니다. 모든 계정에 전체 이력을 제공합니다. 예정 항목은 잘리지 않습니다. 요청당 1회 호출로 계산됩니다. 알 수 없는 ID는 404 not_found이며, 아직 데이터가 없는 시장은 404 not_covered입니다.
MCP: 도구 equities, action splits.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
start | 날짜 | 선택 | 전송되지 않음: 모든 계정에 전체 이력을 제공합니다. |
splits | 객체 목록 | 항상 | 최신 순. |
splits[].date | 날짜 | 항상 | 주식이 분할 조정 기준으로 거래되는 첫 날. |
splits[].ratio | 문자열 | 항상 | 구주 대비 신주: 10:1은 보유 1주당 10주를 지급하며, 1:10은 주식병합입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:NFLX/splits"{
"id": "XNAS:NFLX",
"splits": [
{
"date": "2025-11-17",
"ratio": "10:1"
}
]
}주식 한 종목의 실적
GET /v1/equities/{id}/earnings
종목 하나의 과거 실적 보고(거래소 기준 오늘 이전 날짜)를 추정치, 실제치, 서프라이즈와 함께 최신 순으로 페이지 단위로 반환합니다. 예정된 보고일은 아직 포함되지 않습니다. surprise_는 퍼센트 단위입니다. eps_은 시장 데이터 기준이며 밸류에이션의 공시 EPS와 다를 수 있습니다. filing_는 당사가 보유한 경우 과거 보고를 다루는 연간 또는 분기 보고서를 가리킵니다. 모든 계정에 전체 이력을 제공합니다. 요청당 1회 호출로 계산됩니다. 알 수 없는 ID는 404 not_found이며, 아직 데이터가 없는 시장은 404 not_covered입니다.
이 경로는 과거 보고만 반환합니다. 예정된 보고일은 아직 포함되지 않습니다.
filing_id는 과거 보고를 해당 보고를 다루는 공시와 연결합니다. 이 값을 Filings API의 GET /v1/filings/{filing_id}에 전달합니다.
MCP: 도구 equities, action earnings.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
cursor | 쿼리 | 아니요 | 문자열 | 이전 페이지의 next_. 다른 매개변수는 동일하게 유지합니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
start | 날짜 | 선택 | 전송되지 않음: 모든 계정에 전체 이력을 제공합니다. |
earnings | 객체 목록 | 항상 | 과거 보고만, 최신 순. 예정된 보고일은 아직 포함되지 않습니다. |
earnings[].date | 날짜 | 항상 | 보고일(거래소 기준 오늘 또는 그 이전). |
earnings[].time | 다음 중 하나: before_open, after_close, during | 선택 | 하루 중 보고 시점. 알 수 없으면 제외됩니다. |
earnings[].eps_ | 문자열 | 선택 | 애널리스트의 주당순이익 추정치. 없으면 제외됩니다. |
earnings[].eps_ | 문자열 | 선택 | 시장 데이터 기준으로 보고된 주당순이익이며, 밸류에이션의 eps_에 있는 공시 EPS와 다를 수 있습니다. 보고되기 전에는 제외됩니다. |
earnings[].surprise | 문자열 | 선택 | eps_에서 eps_를 뺀 값, 소수 둘째 자리 반올림. |
earnings[].surprise_ | 문자열 | 선택 | surprise를 추정치 대비 퍼센트로 나타낸 값(8.31은 8.31%를 의미), 소수 둘째 자리. |
earnings[].filing_ | 문자열 | 선택 | 이 보고를 다루는 당사 공시의 연간, 반기 또는 분기 보고서입니다. 이 값을 공시의 GET /에 전달합니다. 기업에 일치하는 공시가 없거나 날짜에 맞는 보고서가 없으면 제외됩니다. |
next_ | 문자열 | 항상 | 다음 페이지를 읽으려면 cursor로 전달합니다. 마지막 페이지에서는 null입니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/earnings"{
"id": "XNAS:MSFT",
"earnings": [
{
"date": "2026-07-29",
"time": "after_close",
"eps_estimate": "3.31",
"eps_actual": "3.45",
"surprise": "0.14",
"surprise_percent": "4.23",
"filing_id": "usa:0000789019:0000950170-26-000123"
}
],
"next_cursor": null
}주식 한 종목의 시가총액, P/E, P/S, P/B, 배당수익률
GET /v1/equities/{id}/valuation
미국 또는 한국 종목 하나의 시가총액(최신 가격 곱하기 발행 주식 수), P/E(최신 가격을 기업 공시의 최근 12개월 희석 EPS로 나눈 값, 보고된 GAAP 또는 IFRS 기준), P/S(시가총액을 최근 12개월 매출로 나눈 값), P/B(시가총액을 최신 대차대조표의 총자본으로 나눈 값), 배당수익률(최근 12개월 주당 배당금을 가격으로 나눈 값, 퍼센트)을 입력값과 그 기준일과 함께 반환합니다. 한국은 현재 P/E만 제공하며, 시가총액, P/S, P/B, 배당수익률은 주식 수와 배당 데이터가 갖춰지면 제공됩니다. 정확하게 산출할 수 없는 수치는 0으로 보내지 않고 제외합니다. 시가총액은 주식 수 기준일 이후 분할이 있었던 경우, 여러 주식 종류에 각각의 주식 수가 없는 경우, 예탁증서나 외국 기업 제출자의 경우에 제외됩니다. P/E는 EPS가 음수이거나 0.01 미만인 경우, 다른 통화로 보고된 경우, 예탁증서의 경우에 제외됩니다. 우선주 같은 기업의 다른 주식 종류에는 자체 수치가 없으며 아무것도 표시되지 않습니다. 미국과 한국 이외의 종목이나 기업이 명확히 일치하지 않는 종목은 404 not_covered입니다. 1회 호출.
각 비율은 입력값과 그 기준일과 함께 제공됩니다: shares_as_of, eps_period_end, revenue_period_end, equity_as_of, dividends_period_end.
MCP: 도구 equities, action valuation.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
currency | 문자열 | 항상 | market_과 pe_의 기초가 되는 가격의 통화. |
market_ | 문자열 | 선택 | 최신 가격 곱하기 shares_, currency 기준, 정수 단위. shares_ 이후 분할이 있었던 경우, 기업에 여러 주식 종류가 있고 각각의 주식 수가 없는 경우, 예탁증서나 외국 기업 제출자의 경우 제외됩니다. 한국은 아직 시가총액이 없으며, 한국 종목은 현재 P/E만 표시됩니다. |
pe_ | 문자열 | 선택 | 최신 가격을 eps_으로 나눈 값, 소수 둘째 자리. eps_이 음수이거나 0.01 미만인 경우, 보고 통화가 currency와 다른 경우, eps_ 이후 분할이 있었던 경우, 예탁증서의 경우 제외됩니다. |
ps_ | 문자열 | 선택 | 주가매출비율: market_을 revenue_으로 나눈 값, 소수 둘째 자리. market_이 제외되면 항상 제외되며, 매출이 0보다 크지 않은 경우와 currency와 다른 통화로 보고된 경우에도 제외됩니다. |
pb_ | 문자열 | 선택 | 주가순자산비율: market_을 total_로 나눈 값, 소수 둘째 자리. market_이 제외되면 항상 제외되며, 총자본이 0 또는 음수인 경우와 currency와 다른 통화로 보고된 경우에도 제외됩니다. |
dividend_ | 문자열 | 선택 | 최근 12개월 주당 배당금을 최신 가격으로 나눈 값, 퍼센트 단위(0.71은 0.71%를 의미), 소수 둘째 자리. 해당 12개월에 기록된 배당이 없는 경우(배당을 하지 않는 기업 포함), dividends_ 이후 분할이 있었던 경우, 배당이 currency와 다른 통화인 경우, 예탁증서의 경우 제외됩니다. |
shares_ | 문자열 | 선택 | 기업 주력 보통주의 발행 주식 수. 우선주 같은 다른 종류의 종목에는 여기에 주식 수가 없으므로 제외됩니다. |
shares_ | 날짜 | 선택 | shares_을 집계한 기준일. 주식 수가 표시되면 항상 표시됩니다. |
eps_ | 문자열 | 선택 | 기업 공시의 최근 12개월 희석 EPS(보고된 GAAP 또는 IFRS 기준). 4분기는 연간 수치에서 1~3분기를 뺀 값입니다. 산출할 수 있으면 항상 표시되며, 기업의 다른 주식 종류인 종목에서는 제외됩니다. 시장 데이터 기준인 주식 실적의 eps_과 다를 수 있습니다. |
eps_ | 날짜 | 선택 | eps_에 포함된 가장 최근 분기의 종료일. eps_이 표시되면 항상 표시됩니다. |
revenue_ | 문자열 | 선택 | 기업 공시의 최근 12개월 매출, 보고 통화의 정수 단위(4분기는 연간 수치에서 1~3분기를 뺀 값). 4개 분기 또는 전체 연도가 기록되어 있지 않은 경우와 기업의 다른 주식 종류인 종목에서는 제외됩니다. |
revenue_ | 날짜 | 선택 | revenue_에 포함된 가장 최근 분기의 종료일. revenue_이 표시되면 항상 표시됩니다. |
total_ | 문자열 | 선택 | 비지배지분을 포함한 최신 대차대조표의 총자본, 보고 통화의 정수 단위. 음수일 수 있습니다. |
equity_ | 날짜 | 선택 | total_의 대차대조표 기준일. total_가 표시되면 항상 표시됩니다. |
dividend_ | 문자열 | 선택 | 최근 12개월 동안 주력 보통주에 선언된 주당 배당금, 보고 통화 기준. 산출할 수 있으면 항상 표시됩니다. |
dividends_ | 날짜 | 선택 | dividend_에 포함된 가장 최근 분기의 종료일. dividend_이 표시되면 항상 표시됩니다. |
company_ | 문자열 | 항상 | 종목이 일치하는 당사 공시의 기업. |
timestamp | 날짜·시간 | 항상 | 응답의 기초가 되는 가격이 유효했던 시각(UTC). |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation"{
"id": "XNAS:MSFT",
"currency": "USD",
"market_cap": "3130000000000",
"pe_ratio": "33.50",
"ps_ratio": "11.40",
"pb_ratio": "10.20",
"dividend_yield": "0.86",
"shares_outstanding": "7430000000",
"shares_as_of": "2026-07-24",
"eps_ttm": "12.58",
"eps_period_end": "2026-06-30",
"revenue_ttm": "274500000000",
"revenue_period_end": "2026-06-30",
"total_equity": "307000000000",
"equity_as_of": "2026-06-30",
"dividend_per_share_ttm": "3.64",
"dividends_period_end": "2026-06-30",
"company_id": "usa:0000789019",
"timestamp": "2026-10-26T15:42:00Z"
}주식 한 종목의 베타, 자기자본비용, 부채비용, WACC
GET /v1/equities/{id}/cost-of-capital
미국 또는 한국 주식 하나의 베타(벤치마크 ETF 대비, 기본값은 분할과 배당을 반영한 가격으로 계산한 2년간 주간 수익률), 무위험 이자율(해당 국가 국채 수익률 곡선의 10년물 시점, 또는 사용자가 지정한 값), 자기자본비용(무위험 이자율 더하기 베타 곱하기 주식 위험 프리미엄: 사용자가 erp로 보낸 값, 또는 기본값으로 당사가 공표하는 해당 국가의 총 프리미엄), 부채비용(기업 공시의 이자비용을 평균 총부채로 나눈 값, 이를 사용할 수 없는 경우 무위험 이자율에 기업의 이자보상배율에 대한 공개 표의 기본 스프레드를 더한 값. 세전과 세후이며, tax_를 보내지 않으면 공개 표의 해당 국가 법인세율 사용), 그리고 시가총액과 총부채로 가중한 WACC를 반환합니다. 모든 입력값은 값, 기준, 날짜와 함께 응답에 포함됩니다. 은행과 보험사는 422 not_applicable입니다. 정확하게 산출할 수 없는 입력값은 임의로 보정하지 않고 422 inputs_unavailable에 명시합니다. 표시되지만 주의가 필요한 수치에는 warnings 항목이 붙습니다. 1회 호출.
erp는 필수입니다. 한국은 여기에 수익률 곡선이 없으므로 한국 주식에는 risk_free를 보내십시오. 모든 입력값은 값과 날짜와 함께 제공되며, warnings에는 의존하기 전에 확인해야 할 수치가 나열됩니다.
MCP: 도구 equities, action cost_.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
erp | 쿼리 | 아니요 | 문자열 | 사용자의 주식 위험 프리미엄, 퍼센트 단위(5는 5%를 의미). 생략하면 당사가 공표하는 해당 국가의 총 주식 위험 프리미엄입니다(응답에 날짜와 기준이 표시됨). 당사가 공표하지 않는 국가에서는 이 값이 없으면 400 erp_required입니다. 0보다 크고 25 이하. |
benchmark | 쿼리 | 아니요 | 문자열 | 베타를 측정할 기준이 되는 시장 대용 종목의 ID: 해당 주식과 같은 통화로 거래되는 ETF, 펀드 또는 주식. 생략하면 미국 주식은 ARCX:SPY, 한국 주식은 XKRX:069500, 일본 주식은 XTKS:1306이며, 그 외 시장은 이 값이 필요합니다. |
window | 쿼리 | 아니요 | 다음 중 하나: 2y, 5y | 수익률을 거슬러 올라가는 기간: 2y(기본값) 또는 5y. |
frequency | 쿼리 | 아니요 | 다음 중 하나: weekly, monthly | 수익률 간격: weekly(기본값, 각 ISO 주의 마지막 공통 거래일) 또는 monthly. |
beta | 쿼리 | 아니요 | 다음 중 하나: raw, adjusted | 자기자본비용에 사용할 베타: raw(기본값) 또는 adjusted(raw의 0.67배에 0.33을 더한 값). 두 값은 항상 응답에 포함됩니다. |
risk_ | 쿼리 | 아니요 | 문자열 | 사용자가 지정하는 무위험 이자율, 퍼센트 단위. 생략하면 해당 국가 국채 수익률 곡선의 10년물 시점입니다. 곡선이 없는 곳(한국)에서 필요하며, 없으면 422 risk_free_unavailable입니다. |
tax_ | 쿼리 | 아니요 | 문자열 | 부채의 절세 효과에 사용할 세율, 퍼센트 단위. 생략하면 Damodaran의 공개 표(PwC 세율)에 있는 해당 주식 국가의 법인세율입니다. 0에서 60 사이. |
period | 쿼리 | 아니요 | 다음 중 하나: ttm, annual | 이자비용 기간: 최근 12개월(ttm, 기본값) 또는 최근 전체 회계연도(annual). 한국과 일본은 연간 수치만 있으므로 annual이 적용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
currency | 문자열 | 항상 | 금액 필드의 통화. |
company_ | 문자열 | 항상 | 종목이 일치하는 당사 공시의 기업. |
beta | 객체 | 항상 | |
beta.benchmark | 객체 | 항상 | |
beta.benchmark.id | 문자열 | 항상 | 벤치마크의 종목 ID. |
beta.benchmark.default | 항상 true | 선택 | 벤치마크가 해당 주식 시장의 당사 기본값이면 true로 표시됩니다. |
beta.window | 다음 중 하나: 2y, 5y | 항상 | |
beta.frequency | 다음 중 하나: weekly, monthly | 항상 | |
beta.start | 날짜 | 항상 | 첫 번째 수익률의 기초가 되는 첫 가격의 날짜. |
beta.end | 날짜 | 항상 | 마지막 수익률의 기초가 되는 마지막 가격의 날짜. |
beta.observations | 정수 | 항상 | 회귀에 사용된 수익률의 수. |
beta.raw | 문자열 | 항상 | 벤치마크 수익률에 대한 주식 수익률의 기울기이며, 둘 다 분할과 배당을 반영한 가격으로 계산됩니다. |
beta.adjusted | 문자열 | 항상 | 0.67 곱하기 raw 더하기 0.33. |
beta.used | 다음 중 하나: raw, adjusted | 항상 | cost_에 사용된 베타. |
beta.r_ | 문자열 | 항상 | 설명되는 주식 분산의 비율. |
beta.std_ | 문자열 | 항상 | raw의 표준오차. |
risk_ | 객체 | 항상 | |
risk_ | 문자열 | 항상 | 무위험 이자율, 퍼센트 단위(4.25는 4.25%를 의미). |
risk_ | 다음 중 하나: yield_curve, caller | 항상 | |
risk_ | 다음 중 하나: ours, caller | 항상 | ours: 당사가 공표하는 공식 국채 수익률 곡선. caller: 사용자가 지정한 값. |
risk_ | 문자열 | 선택 | 수익률 곡선의 국가. caller에서는 전송되지 않습니다. |
risk_ | 항상 "10y" | 선택 | 곡선의 시점. caller에서는 전송되지 않습니다. |
risk_ | 항상 "P10Y" | 선택 | maturity의 ISO 8601 기간 표기. caller에서는 전송되지 않습니다. |
risk_ | 문자열 | 선택 | 곡선의 호가 방식(par, zero-coupon, Svensson, 만기수익률): 국가마다 조금씩 다릅니다. caller에서는 전송되지 않습니다. |
risk_ | 날짜 | 선택 | 곡선의 날짜. caller에서는 전송되지 않습니다. |
equity_ | 객체 | 항상 | |
equity_ | 문자열 | 항상 | 주식 위험 프리미엄, 퍼센트 단위(4.25는 4.25%를 의미). |
equity_ | 다음 중 하나: narwhal, caller | 항상 | 설정 주체: narwhal은 당사가 공표하는 해당 주식 국가의 총 주식 위험 프리미엄, caller는 사용자가 보낸 erp. |
equity_ | 문자열 | 선택 | 당사 프리미엄의 국가, ISO 3166-1 alpha-3. narwhal에만 해당. |
equity_ | 날짜 | 선택 | 당사 프리미엄이 나타내는 날짜. narwhal에만 해당. |
equity_ | 다음 중 하나: observed, modelled, table | 선택 | 당사 총 프리미엄의 산출 방식: observed는 당사 자체 데이터에서, modelled는 당사 스프레드 모델로, table은 국가 부분을 공개 표에서 가져온 것. narwhal에만 해당. |
cost_ | 문자열 | 항상 | 무위험 이자율 더하기 베타 곱하기 주식 위험 프리미엄, 퍼센트 단위(4.25는 4.25%를 의미). |
cost_ | 객체 | 선택 | 공시에 부채가 없는 기업에서는 제외됩니다. |
cost_ | 문자열 | 항상 | 이자비용을 평균 총부채로 나눈 값, 퍼센트 단위(4.25는 4.25%를 의미). 이를 사용할 수 없고(이자가 양수가 아니거나 결과가 0.1% 미만 또는 30% 초과) EBIT가 기록되어 있는 경우: 무위험 이자율에 공개 표의 기업 이자보상배율에 대한 기본 스프레드를 더한 값이며, basis가 어느 쪽인지 알려 줍니다. |
cost_ | 다음 중 하나: ours, table | 항상 | ours: 기업 공시의 이자비용을 평균 부채로 나눈 값. table: 무위험 이자율에 표의 기본 스프레드를 더한 값. |
cost_ | 문자열 | 선택 | EBIT를 이자비용으로 나눈 값. table에만 해당하며 이자가 없으면 제외됩니다. |
cost_ | 문자열 | 선택 | 해당 이자보상배율의 기본 스프레드, 퍼센트 단위(4.25는 4.25%를 의미). table에만 해당. |
cost_ | 문자열 | 선택 | 스프레드 표의 이름. table에만 해당. |
cost_ | 문자열 | 선택 | 표의 갱신 시점, 예: January 2026. table에만 해당. |
cost_ | 문자열 | 선택 | 표가 공표된 곳. table에만 해당. |
cost_ | 문자열 | 선택 | pre_에 1에서 세율을 뺀 값을 곱한 값. 세율을 알 수 없는 동안은 제외됩니다. |
cost_ | 다음 중 하나: ttm, annual | 항상 | |
cost_ | 날짜 | 항상 | 이자에 포함된 가장 최근 분기 또는 연도의 종료일. |
cost_ | 문자열 | 항상 | 해당 기간의 이자비용, currency의 정수 단위. |
cost_ | 문자열 | 항상 | 기간 시작 시점과 종료 시점의 총부채를 평균한 값이며, 시작 시점이 기록되어 있지 않으면 종료 시점 잔액만 사용합니다. currency의 정수 단위이며 리스는 제외합니다. |
cost_ | 문자열 | 선택 | period_로부터 1년 전의 총부채. 기록되어 있지 않으면 제외됩니다. |
cost_ | 문자열 | 항상 | period_ 시점의 총부채. |
tax_ | 객체 | 선택 | 표에 해당 국가의 세율이 없으면 제외됩니다. 세율을 설정하려면 tax_를 보내십시오. |
tax_ | 문자열 | 항상 | 부채에 적용하는 세율, 퍼센트 단위(4.25는 4.25%를 의미). |
tax_ | 다음 중 하나: table, caller | 항상 | table: 공개 표의 해당 국가 세율. caller: 사용자가 지정한 값. |
tax_ | 다음 중 하나: country_table, caller | 항상 | country_: 공개 표의 해당 주식 국가 법인세율. caller: 사용자가 보낸 tax_. |
tax_ | 문자열 | 선택 | 세율이 해당하는 국가의 ISO 3166-1 alpha-3 코드. 표 세율에만 해당. |
tax_ | 문자열 | 선택 | 표의 이름, 발행처와 출처 포함. 표 세율에만 해당. |
tax_ | 문자열 | 선택 | 세율의 출처가 된 표의 갱신 시점, 예: January 2026. |
tax_ | 문자열 | 선택 | 표가 공표된 곳. 표 세율에만 해당. |
weights | 객체 | 항상 | |
weights.equity | 문자열 | 항상 | 시가총액을 시가총액과 부채의 합으로 나눈 값, 퍼센트 단위(4.25는 4.25%를 의미). |
weights.debt | 문자열 | 항상 | 부채를 시가총액과 부채의 합으로 나눈 값, 퍼센트 단위(4.25는 4.25%를 의미). |
weights.market_ | 문자열 | 항상 | 최신 가격 곱하기 발행 주식 수, currency의 정수 단위. |
weights.market_ | 날짜·시간 | 항상 | market_의 기초가 되는 가격이 유효했던 시각. |
weights.total_ | 문자열 | 항상 | 기록된 최신 총부채, currency의 정수 단위. 리스는 제외합니다. |
weights.total_ | 날짜 | 항상 | total_의 대차대조표 기준일. |
wacc | 문자열 | 선택 | 가중평균자본비용, 퍼센트 단위(4.25는 4.25%를 의미). 부채가 없는 기업에서는 cost_와 같습니다. 부채가 있는데 세율을 알 수 없는 동안은 제외됩니다. |
warnings | 객체 목록 | 항상 | 수치를 사용하기 전에 확인할 사항. 없으면 비어 있습니다. |
warnings[].code | 문자열 | 항상 | 변하지 않는 기계 판독용 코드. |
warnings[].message | 문자열 | 항상 | 쉬운 말로 설명한 의미. |
methodology_ | 문자열 | 항상 | 각 수치를 산출하는 방법. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/cost-of-capital?erp=5"{
"id": "XNAS:MSFT",
"currency": "USD",
"company_id": "usa:0000789019",
"beta": {
"benchmark": {
"id": "ARCX:SPY",
"default": true
},
"window": "2y",
"frequency": "weekly",
"start": "2024-10-25",
"end": "2026-10-16",
"observations": 103,
"raw": "1.0842",
"adjusted": "1.0564",
"used": "raw",
"r_squared": "0.5731",
"std_error": "0.0894"
},
"risk_free": {
"rate": "4.1200",
"source": "yield_curve",
"basis": "ours",
"country": "USA",
"maturity": "10y",
"curve_type": "nominal_par",
"as_of": "2026-10-22"
},
"equity_risk_premium": {
"rate": "5.0000",
"source": "caller"
},
"cost_of_equity": "9.5410",
"cost_of_debt": {
"pre_tax": "3.9100",
"basis": "ours",
"after_tax": "2.9078",
"period": "ttm",
"period_end": "2026-06-30",
"interest_expense": "2900000000",
"average_debt": "74200000000",
"opening_debt": "72000000000",
"closing_debt": "76400000000"
},
"tax_rate": {
"rate": "25.6300",
"source": "country_table",
"basis": "table",
"country": "USA",
"table": "Damodaran, corporate marginal tax rates by country (PwC, January 2026 update)",
"table_update": "January 2026",
"table_url": "https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/countrytaxrates.html"
},
"weights": {
"equity": "98.0000",
"debt": "2.0000",
"market_cap": "3893412000000",
"market_cap_as_of": "2026-10-26T15:42:00Z",
"total_debt": "76400000000",
"total_debt_as_of": "2026-06-30"
},
"wacc": "9.4083",
"warnings": [],
"methodology_url": "https://narwhalapi.com/methodology/cost-of-capital"
}주식 한 종목의 밸류에이션 이력
GET /v1/equities/{id}/valuation/history
미국 또는 한국 종목 하나의 모든 회계 기간 종료일(분기 또는 연말)의 시가총액, P/E, P/S, P/B, 배당수익률을 오래된 순으로 반환합니다. 각 시점은 해당 일 또는 그 직전의 종가(분할만 조정)와 해당 기간에 제출된 수치(최근 12개월 EPS, 매출, 배당, 총자본, 가장 가까운 주식 수)를 사용하므로 이후의 정정 공시가 반영됩니다. 산출할 수 없는 수치는 밸류에이션과 같은 규칙으로 0으로 보내지 않고 제외합니다. 이력: 모든 계정에 전체 제공. 미국과 한국 이외의 종목이나 기업이 명확히 일치하지 않는 종목은 404 not_covered입니다. 1회 호출.
MCP: 도구 equities, action valuation_.
매개변수
| 매개변수 | 위치 | 필수 | 유형 | 의미 |
|---|---|---|---|---|
id | 경로 | 예 | 문자열 | 종목 ID: 거래소의 4자리 코드, 콜론, 티커 순이며 예: XNAS:MSFT, XNYS:BRK.B. MSFT 같은 미국 티커 단독 표기도 미국 종목 하나를 가리키면 사용할 수 있으며, 응답에는 정식 ID가 포함됩니다. 주식 종류는 점으로 구분하며(BRK.B) BRK-B도 허용됩니다. |
응답 필드
| 필드 | 유형 | 전송 | 의미 |
|---|---|---|---|
id | 문자열 | 항상 | 정식 종목 ID. |
currency | 문자열 | 항상 | 모든 가격과 시가총액의 통화. |
company_ | 문자열 | 항상 | 종목이 일치하는 당사 공시의 기업. |
start | 날짜 | 선택 | 전송되지 않음: 모든 계정에 전체 이력을 제공합니다. |
points | 객체 목록 | 항상 | 기업의 회계 기간 종료일마다 하나의 시점, 오래된 순. 각 시점은 당시 알려진 값이 아니라 해당 기간에 제출된 수치와 그날의 가격으로 산출되므로 이후의 정정 공시가 반영됩니다. 가격이 없거나 수치가 하나도 없는 기간에는 시점이 없습니다. |
points[].date | 날짜 | 항상 | 기업의 회계 기간 종료일(분기 또는 연말): 시점의 모든 수치가 이 날짜 기준입니다. |
points[].price | 문자열 | 선택 | price_의 종가, currency 기준이며 분할만 조정하고(배당은 조정하지 않음) 현재 주식 기준입니다. 해당 기간의 가격을 지금 읽을 수 없으면 아래의 모든 수치와 함께 제외됩니다. 나중에 다시 시도하십시오. |
points[].price_ | 날짜 | 선택 | 가격을 가져온 date 또는 그 이전의 마지막 거래일(최대 7일 이전). |
points[].market_ | 문자열 | 선택 | price 곱하기 date에 가장 가까운 주식 수(date 130일 전부터 45일 후까지 집계), 현재 주식 기준, currency의 정수 단위. 해당 주식 수가 없는 경우, 여러 주식 종류에 각각의 주식 수가 없는 경우, 예탁증서나 외국 기업 제출자의 경우 제외됩니다. |
points[].pe_ | 문자열 | 선택 | price를 date로 끝나는 4개 분기 희석 EPS로 나눈 값, 소수 둘째 자리. EPS가 음수이거나 0.01 미만인 경우, currency로 보고되지 않은 경우, date로 끝나는 4개 분기(또는 해당 연도)가 기록되어 있지 않은 경우, 예탁증서의 경우 제외됩니다. |
points[].ps_ | 문자열 | 선택 | market_을 date로 끝나는 4개 분기 매출로 나눈 값, 소수 둘째 자리. market_이 제외되면 항상 제외되며, 매출이 기록되어 있지 않거나 0보다 크지 않거나 currency가 아닌 경우에도 제외됩니다. |
points[].pb_ | 문자열 | 선택 | market_을 date 날짜 대차대조표의 총자본으로 나눈 값, 소수 둘째 자리. market_이 제외되면 항상 제외되며, 총자본이 기록되어 있지 않거나 0보다 크지 않거나 currency가 아닌 경우에도 제외됩니다. |
points[].dividend_ | 문자열 | 선택 | date로 끝나는 4개 분기의 주당 배당금을 price로 나눈 값, 퍼센트 단위(0.71은 0.71%를 의미), 소수 둘째 자리. 해당 분기에 기록된 배당이 없는 경우, currency가 아닌 경우, 예탁증서의 경우 제외됩니다. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation/history"{
"id": "XNAS:MSFT",
"currency": "USD",
"company_id": "usa:0000789019",
"points": [
{
"date": "2026-06-30",
"price": "497.40",
"price_date": "2026-06-30",
"market_cap": "3697000000000",
"pe_ratio": "39.54",
"ps_ratio": "13.47",
"pb_ratio": "12.04",
"dividend_yield": "0.73"
}
]
}오류
오류는 공통 문제 형식을 사용하며, 다음 필드를 포함합니다: request_. 확인 API 오류 코드와 크레딧 형식과 크레딧 헤더에 대한 설명이 있습니다. 실패한 요청에는 요금이 부과되지 않습니다.
| 코드 | 상태 | 의미 |
|---|---|---|
invalid_ | 400 | 매개변수가 없거나, 알 수 없거나, 중복되었거나, 범위를 벗어났습니다. |
invalid_ | 400 | id 또는 페어가 이 API에서 요구하는 형식과 다릅니다. |
too_ | 400 | 배치에 50개를 넘는 id가 들어 있습니다. |
invalid_ | 400 | interval이 1d 또는 1m이 아니거나, 이 상품에서는 사용할 수 없습니다. |
range_ | 400 | 기간이 이 경로에서 허용하는 길이를 넘었습니다. |
not_ | 404 | 해당하는 종목, 펀드 또는 페어가 없습니다. |
not_ | 404 | 해당 시장, 국가 또는 기업은 아직 제공되지 않습니다. |
invalid_ | 400 | 이 요청이 반환한 커서가 아니거나, 다른 요청의 커서입니다. |
cursor_ | 409 | 커서가 가리키는 가격이 바뀌었습니다. 커서 없이 처음부터 다시 요청하십시오. |
insufficient_ | 402 | 크레딧 잔액이 요청 비용보다 적습니다. |
upstream_ | 503 | 지금은 가격을 가져올 수 없습니다. 배치에서는 errors에 나열됩니다. 잠시 후 다시 시도하십시오. |
area_ | 503 | 이 영역은 지금 응답할 수 없습니다. |
erp_ | 400 | 퍼센트 단위의 주식 위험 프리미엄인 erp를 보내십시오. |
insufficient_ | 422 | 해당 주식과 벤치마크가 공통으로 가진 수익률이 기간의 80%에 미치지 못합니다. |
risk_ | 422 | 이 국가의 수익률 곡선이 없습니다. risk_free를 보내십시오. |
not_ | 422 | 은행이나 보험사에는 WACC가 의미가 없습니다. |
currency_ | 422 | 벤치마크 또는 공시의 통화가 가격의 통화와 다릅니다. |
inputs_ | 422 | 입력값을 올바르게 계산할 수 없습니다. 상세 내용에 해당 입력값이 표시됩니다. |
이 페이지가 도움이 되었나요?