Stocks API reference

Overview

Prices, price history, company events, market cap and valuation ratios for listed stocks. Every request needs a Bearer key, and REST and MCP share one account quota.

A listing id is the exchange's four-letter code, a colon and the ticker, such as XNAS:MSFT or XNYS:BRK.B. A bare US ticker such as MSFT also works when it names one US listing, and every answer carries the canonical id. Prices and amounts are decimal strings.

Each listing can carry a company_id. It links the listing to the company in the Filings API, so a price, a valuation and a financial statement meet on one id.

Base URL: https://api.narwhalapi.com. The MCP tool is equities, with one action for each route below.

A company_id joins a listing to the Filings API: financial statements, filings and holders.

Plans and limits

See pricing for plan prices and monthly request limits. Each request counts as one call unless a route says otherwise.

• Free prices are delayed by 15 minutes. A delayed answer carries delayed: true and leaves out the day volume.
• Valuation covers US and Korea listings that match a company in our filings. Korea shows P/E only for now.
• A ratio that cannot be worked out correctly is left out. It is never sent as 0.
• The earnings eps_actual is on the market data basis. The EPS behind pe_ratio comes from company filings. The two can differ, so do not compare them directly.
• Cost of capital covers US and Korea listings that match a company in our filings. You send your own equity risk premium in erp. The method is written once in the cost of capital methodology, and every answer links to it.
• A bank or an insurer returns 422 not_applicable, because interest is an operating cost for it. An input that cannot be worked out is named in 422 inputs_unavailable, never filled in.
• Valuation history has one point for each fiscal period end (quarter or year end), not one for each day. Each point uses the close on or just before that day, adjusted for splits only, and the figures as filed for that period.
• Basic reaches back 5 years and Pro has full history. When your plan cuts older rows, start comes back with the first date served.
• Earnings are past results only. Upcoming earnings dates are not included yet.
• Japan profiles carry only name, exchange, country, currency and company_id.

Endpoints

Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Search stocks by ticker or name

GET /v1/equities/search

Listings whose ticker or name starts with q, any case: an exact ticker first, then other tickers, then names. Optional country (three letters) and type filters. Up to 50 a page, with next_cursor. Read from our own symbol list, so it is open to every plan and counts one call.

MCP: tool equities, action search.

Parameters

Response fields

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
}

Profile of one stock

GET /v1/equities/{id}

The listing (symbol, name, type, exchange, country, currency), the company's sector, industry and website, and company_id when the listing matches a company in our filings. Open to every plan. Japan listings carry only name, exchange, country, currency and company_id. Fields that are not known are left out.

MCP: tool equities, action profile.

Parameters

Response fields

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"
}

Latest price of one stock

GET /v1/equities/{id}/price

Latest price of one listing. Free plans see the price 15 minutes late and the answer carries delayed: true. change_percent is in percent. An unknown id is 404 not_found; a market without prices yet is 404 not_covered.

MCP: tool equities, action price.

Parameters

Response fields

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
}

Latest prices for up to 50 stocks

GET /v1/equities/prices

Latest price of each listed id. One call is counted for each id that returns a price, taken in one step: if fewer calls are left than ids that resolved, the whole request is refused with 429 quota_exceeded. Ids that return no price are listed in errors and cost nothing. Free plans see prices 15 minutes late. change_percent is in percent.

Send up to 50 ids. A batch is charged in one step: if you have fewer calls left than ids that resolve, the whole request returns 429 quota_exceeded.

MCP: tool equities, action prices.

Parameters

Response fields

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"
    }
  ]
}

Top US stock movers

GET /v1/equities/movers

The top 25 US stocks and ETFs by direction: gainers, losers or active (most traded by value among the day's biggest gainers and losers, not the whole market). Only ordinary shares and ETFs priced at $1 or more, with at least 100,000 shares and $1 million traded today; ranked by us and cached for 10 minutes. change_percent is in percent. Basic and Pro only (Free gets 403 plan_upgrade_required). market is us for now; another market is 404 not_covered, an unknown direction is 400 invalid_query. One call.

Movers are for the US only. A different market returns 404 not_covered.

MCP: tool equities, action movers.

Parameters

Response fields

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"
}

Price bars of one stock

GET /v1/equities/{id}/bars

Daily (1d) or one-minute (1m) bars, oldest first, adjusted for splits and dividends. History: Free 12 months, Basic 5 years, Pro everything; start is sent back when the plan raised it. One-minute bars are for Basic and Pro (Free gets 403 plan_upgrade_required), reach back to 2020 and cover at most 5 days a call (400 range_too_large). Today's daily bar appears after the exchange closes, and for Free 15 minutes after; end is sent back when that cut the range. Up to 5,000 bars a page, with next_cursor; a cursor that no longer matches the prices is 409 cursor_expired. One call a page.

Bars are adjusted for splits and dividends. If a split or dividend changes the history between two pages, the cursor stops working and returns 409 cursor_expired.

MCP: tool equities, action bars.

Parameters

Response fields

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
}

Dividends of one stock

GET /v1/equities/{id}/dividends

Cash dividends of one listing, newest ex-date first, paged. The list may include announced future rows. The plan sets how far back the past goes: Free 12 months, Basic 5 years, Pro full. start is sent only when older rows were cut off; upcoming rows are never cut. Each request counts one call. An unknown id is 404 not_found; a market without data yet is 404 not_covered.

MCP: tool equities, action dividends.

Parameters

Response fields

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
}

Splits of one stock

GET /v1/equities/{id}/splits

Share splits of one listing, newest first. The plan sets how far back the past goes: Free 12 months, Basic 5 years, Pro full. start is sent only when older rows were cut off; upcoming rows are never cut. Each request counts one call. An unknown id is 404 not_found; a market without data yet is 404 not_covered.

MCP: tool equities, action splits.

Parameters

Response fields

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"
    }
  ]
}

Earnings of one stock

GET /v1/equities/{id}/earnings

Past earnings reports of one listing (dated today or earlier at the exchange), with estimate, actual and surprise, newest first, paged. Upcoming report dates are not included yet. surprise_percent is in percent. eps_actual is on the market data basis and can differ from the filings EPS in the valuation. filing_id names the annual or quarterly report that covers a past report when we hold it. The plan sets how far back the past goes: Free 12 months, Basic 5 years, Pro full. start is sent only when older rows were cut off. Each request counts one call. An unknown id is 404 not_found; a market without data yet is 404 not_covered.

This route returns past reports only. Upcoming report dates are not included yet.

filing_id links a past report to the filing that covers it. Pass it to GET /v1/filings/{filing_id} in the Filings API.

MCP: tool equities, action earnings.

Parameters

Response fields

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
}

Market cap, P/E, P/S, P/B and dividend yield of one stock

GET /v1/equities/{id}/valuation

Market cap (latest price times shares outstanding), P/E (latest price over trailing 12-month diluted EPS from company filings, GAAP or IFRS as reported), P/S (market cap over trailing 12-month revenue), P/B (market cap over total equity of the latest balance sheet) and dividend yield (trailing 12-month dividends per share over the price, in percent) of one US or Korean listing, with the inputs and the dates they are as of. Korea has P/E only for now; market cap, P/S, P/B and yield come with share counts and dividends. A figure that cannot be worked out correctly is left out, never sent as 0: market cap after a split since the share count, for several share classes without a count each, and for a depositary receipt or foreign filer; P/E when EPS is negative or under 0.01, reported in another currency, or for a depositary receipt. Another class of a company, such as a preferred line, has no figures of its own and shows none. Basic and Pro only (Free gets 403 plan_upgrade_required). A listing outside the US and Korea, or without a clean company match, is 404 not_covered. One call; paid plans see live prices.

Each ratio comes with its inputs and the dates they are as of: shares_as_of, eps_period_end, revenue_period_end, equity_as_of and dividends_period_end. Paid plans see live prices.

MCP: tool equities, action valuation.

Parameters

Response fields

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"
}

Beta, cost of equity, cost of debt and WACC of one stock

GET /v1/equities/{id}/cost-of-capital

Beta of one US or Korean stock against a benchmark ETF (weekly returns over two years by default, from prices adjusted for splits and dividends), the risk-free rate (the 10-year point of the country's government yield curve, or yours), the cost of equity (risk-free plus beta times the equity risk premium: yours in erp, or by default our own published total premium of the stock's country), the cost of debt (interest expense over average total debt from company filings, or, where that cannot be used, the risk-free rate plus a public table's default spread for the company's interest coverage; before and after tax, with the country's corporate tax rate from a public table unless you send tax_rate) and WACC, weighted by market cap and total debt. Every input is in the answer with its value, its basis and its date. Banks and insurers are 422 not_applicable; an input that cannot be worked out correctly is named in 422 inputs_unavailable, never repaired; a number that is shown but needs care comes with a warnings entry. Basic and Pro only (Free gets 403 plan_upgrade_required). One call.

erp is required. Korea has no yield curve here, so send risk_free for a Korean stock. Every input comes with its value and date, and warnings lists numbers to check before you rely on them.

MCP: tool equities, action cost_of_capital.

Parameters

Response fields

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"
}

Valuation history of one stock

GET /v1/equities/{id}/valuation/history

Market cap, P/E, P/S, P/B and dividend yield at every fiscal period end (quarter or year end) of one US or Korean listing, oldest first. Each point is the closing price on or just before that day, adjusted for splits only, and the figures filed for that period (trailing 12-month EPS, revenue and dividends, total equity, the nearest share count), so a later restatement is in it. A figure that cannot be worked out is left out, never sent as 0, by the same rules as the valuation. History: Basic 5 years, Pro everything; start is sent back when the plan cut older periods. Basic and Pro only (Free gets 403 plan_upgrade_required). A listing outside the US and Korea, or without a clean company match, is 404 not_covered. One call.

MCP: tool equities, action valuation_history.

Parameters

Response fields

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"
    }
  ]
}

Errors

Errors use the shared problem shape with a request_id. See Errors and quota for the shape and the quota headers. Failed requests are not charged.