Browse all documentation

SDKs

Typed clients for Python, TypeScript, Rust and C. Each one reads your API key from NARWHAL_API_KEY and returns exact decimal values.

Install

Python needs 3.10 or newer. TypeScript needs Node.js 22 or newer and runs on the server only. Rust needs 1.82 or newer.

Terminal
pip install narwhalapi

Then set your key. Sign up to get one; every account gets $10 of calls each month.

Terminal
export NARWHAL_API_KEY="nw_live_..."

First call

The latest US CPI and two exchange rates against the dollar:

Request
from narwhalapi import Narwhal

with Narwhal() as nw:  # reads NARWHAL_API_KEY
    cpi = nw.economics.cpi("USA")
    print(cpi.period, cpi.value)
    rates = nw.fx.rates("USD", currencies=["EUR", "JPY"])
    for r in rates.rates:
        print(r.currency, r.rate)
Output
2026-10 337.511
EUR 0.91100
JPY 159.24

Values come back as exact decimals (Python Decimal, TypeScript string), never floats, so a rate keeps every digit the source published.

Clients

Python has synchronous and asynchronous clients. Rust has an async client and a blocking one behind the blocking feature. The C library is a thin C interface over the Rust client.

What the clients cover

The clients call the same REST API as the API reference: economics, exchange rates, calendars and holidays, commodity prices, stocks, funds, crypto, company calendars, company filings and financials, prediction markets, events and webhooks.

Endpoints added after a client release work over plain REST until the next release. Every change is in the changelog. Agents can use the MCP server instead, which always lists every tool.

Errors and retries

Each client turns an error response into a typed error with the problem code and request ID, and retries short rate-limit waits, plus GET requests that hit a 503 or a dropped connection, on its own. A used-up monthly allowance is returned at once, never retried. The codes are listed in Errors and credits.

Was this page helpful?