Listing ids
A listing id combines a four-letter exchange code and ticker, such as XNAS:MSFT for Microsoft. Unique bare US tickers work; answers return the canonical id.
All APIs
Stocks API for listed stocks
Get prices and company events for listed stocks, with market cap and valuation ratios on Basic and Pro. Use a Bearer key for every request; REST and MCP share one account quota.
First request
Quickstart →curl --request GET \
--url "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/price" \
--header "Authorization: Bearer $NARWHAL_API_KEY"Example response Illustrative response · not a live request
{
"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
}Endpoints
GETSearch stocks by ticker or name/v1/equities/search
GETProfile of one stock/v1/equities/{id}
GETLatest price of one stock/v1/equities/{id}/price
GETLatest prices for up to 50 stocks/v1/equities/prices
GETTop US stock movers/v1/equities/movers
GETPrice bars of one stock/v1/equities/{id}/bars
GETDividends of one stock/v1/equities/{id}/dividends
GETSplits of one stock/v1/equities/{id}/splits
GETEarnings of one stock/v1/equities/{id}/earnings
GETMarket cap, P/E, P/S, P/B and dividend yield of one stock/v1/equities/{id}/valuation
GETBeta, cost of equity, cost of debt and WACC of one stock/v1/equities/{id}/cost-of-capital
GETValuation history of one stock/v1/equities/{id}/valuation/history
Stock data and access
Plan quotas
Free is $0 for 5,000 requests a month. Basic is $59 a month for 100,000; Pro is $149 a month for 1,000,000. Free permits commercial use.
Price access
Free stock, ETF and crypto prices are delayed 15 minutes. Basic and Pro get live prices. Batch calls accept up to 50 ids and count each returned price.
Paid stock data
US-only movers require Basic or Pro, as do valuation history and cost of capital with beta. Valuation matches US and Korea listings to filings; Korea has P/E only.
Coverage
View coverage →Search and profiles are available on every plan. Daily bars and past earnings cover the last 12 months on Free, last 5 years on Basic and full history on Pro; dividends and splits follow the same limits. One-minute bars require Basic or Pro within those limits. Day volume is paid only and omitted when unknown. Market cap and P/E, P/S, P/B and dividend yield require Basic or Pro. Prices and amounts are decimal strings.
Response fields
id- Canonical listing id returned for the requested stock.
symbol- Ticker used for this stock on its exchange.
currency- Currency for every price field, with pence converted to pounds.
price- Last stock price, returned as a decimal string in currency.
previous_close- Previous session's close, omitted when that value is unknown.
change- Price minus previous_close, omitted whenever previous_close is omitted.
change_percent- Change since previous_close in percent; 1.5 means 1.5%.
volume- Shares traded today, omitted when unknown and always omitted from delayed answers.
market_session- Exchange state at timestamp: pre, open, post or closed; only US exchanges have pre and post.
timestamp- Time the price was valid, in UTC with whole seconds.
stale- True if refresh failed or over 15 minutes old while open; closed markets are never stale.
delayed- Present as true only when a price carries the Free plan delay.
Explore related pages
Stocks API reference
Read stock routes and response fields, including beta, cost of equity, cost of debt and WACC.
Read the reference →Plans and monthly quotas
Compare monthly request quotas and history limits, with live prices on Basic and Pro.
See pricing →Connect stocks to company filings
Use a listing's company_id to join its prices and valuations with company financial statements.
Explore the API →Funds API for ETF prices and mutual fund NAVs
ETF prices and daily mutual fund net asset values
Explore the API →Crypto API for live and historical pair prices
Crypto pair prices and history through REST and MCP
Explore the API →Common questions
Does the Stocks API include upcoming earnings or Japan prices?
The earnings route returns past results only; upcoming earnings dates are unavailable. Japan prices are unavailable; profiles carry only name, exchange, country, currency and company_id. Earnings eps_actual uses the market data basis, while EPS behind pe_ratio comes from company filings. The two can differ and should not be compared directly.
How does valuation history work?
Valuation history has one point per fiscal period end, quarterly or yearly. Each uses the close on or just before that date, adjusted only for splits, and figures as filed for that period. Basic covers 5 years; Pro covers full history. When plan limits cut older rows, start gives the first date served.
What does cost of capital require?
Cost of capital covers US and Korea listings matched to a company in our filings, and every answer links to the cost of capital methodology. Send your equity risk premium in erp. Banks and insurers return 422 not_applicable because interest is an operating cost. An input that cannot be worked out is named in 422 inputs_unavailable instead of being estimated.
How do prices connect to company filings?
A listing can carry company_id, which joins it to a company in the Filings API. Use that id to connect prices and valuations with financial statements. Ratios that cannot be calculated correctly are left out without sending 0 in their place.
Create a free key and call the API from your own code. Get a free API key