API Reference

Authentication#

Send the same wn_ key to both surfaces in an HTTP header. Authorization takes precedence when both headers are present:

1. Authorization: Bearer wn_...: recommended (works with the OpenAI/Anthropic SDKs and most HTTP clients).
2. X-API-Key: wn_...

Keys created before October 2026 start with tengu_ and keep working; TENGU_API_KEY is still read by the SDKs.

Query authentication using the api_key parameter remains available for compatibility. URLs may be recorded in access logs, browser history, and monitoring tools, so use a header to keep the credential out of the URL.

Most FIRM responses are a JSON envelope: { "ok": true, "timestamp": "<ISO-8601>", ...data }. The data keys differ per endpoint (e.g. items for feeds, results for search, quote for a quote). The product guides note the exceptions: Crypto Market Data puts its payload under data, beside freshness fields (Crypto), and the ML weights routes answer without the envelope (Quant Signals).

Discover every live endpoint (method, path, params) at any time, with no key required:

curl https://firm.wealthnow.io/api/capabilities | jq '{manifest_version, tool_count, groups}'

Products, costs & per-plan access#

Which products your key can call depends on your plan. Calling a product outside your plan returns 402 plan_required and is non-billable. Read detail for the product and required plan; don't assume an unlocked_by[] field exists in every error envelope.

The table describes access permissions, not guaranteed output availability. When a paid route marks its own result unavailable (ok: false or available: false in the body), the caller gets a 503 that consumes no credits (for example, VWAP without a fully observed session). A 200 from a paid route is billed even when it holds no data. Many routes answer a 200 with an empty list, a null value, found: false, or a warning or note when there is nothing to return: for example kelly_uncertainty for a ticker with no stored prediction or with its size withheld, a private-markets relation with no rows, or an unknown private-markets id. Some report a problem in an error field instead: trading_plan and technical_analysis (ta_master) when price history is too short, and research_fetch_url when a page is blocked or cannot be fetched. Check these fields before using a result. Quant intervals and Kelly sizes can be withheld when supporting evidence is missing.

No-auth routes (no key needed): /api/capabilities, /api/health, /api/openapi.json. They are unmetered, and so are the MCP account_status and search_tools tools. Private Markets search and suggestions cost 5 credits and require Pro+ or the Private Markets add-on.

À-la-carte add-ons: buy on top of any paid plan (each is its own subscription that unlocks one product + tops your wallet): Private Markets $299/mo (or Private Markets Pro $799/mo) and Options Flow $79/mo.

Included credits/month: Free 1,000 · Starter 250,000 · Pro 2,000,000 · Expert 11,200,000 (10,000,000 plus Private Markets Pro's 1,200,000 pack) · Enterprise 20,000,000. Rate limits: Free 30 · Starter 120 · Pro 600 · Expert 1,500 · Enterprise 6,000 req/min. See Pricing & credits.

Pagination#

Many list endpoints accept ?limit (results per call). Most return one window and take no page parameter: narrow it with the endpoint's filters or a date range instead. A few routes page:

• ?page= (1-based): /api/v3/fundamentals/screener, /api/v3/fundamentals/tickers, and 14 news routes under /api/v3/news/ and /api/v3/news_crypto/ (for example ticker_news, alerts, ratings).
• ?offset= (0-based): /api/crypto/universe and /api/v3/private_markets/companies.

Defaults and maxima vary by endpoint. The authoritative params are in GET /api/openapi.json and GET /api/capabilities. Example:

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/sec_filings?ticker=AAPL&limit=10"

FIRM data endpoints#

Paths are relative to https://firm.wealthnow.io. {ticker} is a symbol like AAPL. This lists the most-used routes per product; the full versioned catalog is in GET /api/capabilities (filter by tool_count/groups), and the curated public spec is GET /api/openapi.json. The MCP tool column is the route's operationId and its tool name on the MCP server. Server-sent-event streams are REST only: MCP cannot relay a stream, so they have no tool.

Market Data: Free+ · 1 credit#

See Crypto for the derivatives, on-chain and exchange-event routes.

Fundamentals: Free+ · 1 credit#

Public Filings (SEC / EDGAR): Free+ · 1 credit#

Congressional / Politician Trades: Starter+ · 2 credits#

News & Sentiment: Starter+ · 2 credits#

Macro, Rates, FX & Commodities: Starter+ · 2 credits#

Quant Signals: Starter+ · 3 credits#

Check interval availability and calibration separately. Recent realized coverage is withheld; a stored interval does not establish measured coverage or a 90% band. See Quant Signals for nullable fields and authorization gates.

Streams are long-lived SSE connections billed once per connection, not per frame. After a reconnect, GET /api/v3/events (Transcripts & Events, below) returns the retained market events you missed. See Real-Time Streaming.

Funds & Institutional (13F + Form-4): Starter+ · 4 credits#

When the 13F archive and its fallback cannot answer, the 13F routes return 503 upstream_unavailable with error_code archive_read_timeout, archive_read_failed or upstream_dead_no_archive, not billed, instead of an empty list. See When the 13F archive cannot answer.

Alt-Data: Pro+ · 3 credits#

See Alt-Data, Fundamentals for point-in-time data, and Reference Data for the identifier crosswalk.

Options Flow & Dealer Positioning: Pro+ · 4 credits#

Execution & Research: Pro+ · 4 credits#

TWAP is an arithmetic schedule and VWAP a historical allocation; neither predicts fills or trading costs. VWAP without a complete observed session returns a route-level 503 without consuming credits. See Execution & Research for availability limits.

Risk Analytics: Pro+ · 5 credits#

kelly_uncertainty is billed as Quant Signals, and its size is withheld today; see Kelly sizing.

Private Markets: Pro+ or add-on · 5 credits, including search#

Tape & Intraday History: Pro+ · 3 credits#

FIRM's own self-collected tick tape: minute bars, per-print options/futures trades, and a historical options chain with greeks/IV/OI. Full catalogue in Tape & Intraday History.

Credit & Fixed-Income: Pro+ · 4 credits#

Institutional corporate-credit stack from licensed institutional archives (served at the latest available lag). Full catalogue in Credit & Fixed-Income.

Research Datasets: cost varies by product group#

Row-level access to the licensed research archives. Full catalogue in Research Datasets.

Transcripts & Corporate Events: Pro+ · 3 credits#

Full-text earnings-call transcripts + the Key Developments corporate-event ledger back to 1990. Full catalogue in Transcripts & Corporate Events.

LLM Research: Pro+ · 6 credits#

Source publication dates can be missing. A response timestamp records retrieval, not the age of the cited information. Inspect source dates before making a freshness claim; see LLM Research.

Social Sentiment: Pro+ · 2,500 credits#

Each answer runs a live grounded search. A repeat of the same ticker or query within 5 minutes is served from that answer and billed the same. See LLM Research.

Volatility & Positioning: Pro+ · 4 credits#

See Macro, Rates & FX.

Crypto History: Pro+ · 3 credits#

See Crypto for all five routes.

Not offered on the API#

The Copilot and the Brain agent are not sold on the API. A key that calls a Copilot route gets 403 not_offered, whatever its plan, and is not charged. Every other route on this page is sold on the plans above.

Error responses#

FIRM uses a flat error envelope: {"ok": false, "error": "<code>", "detail": "<message>", "request_id": "...", "doc_url": "..."} (?shape=firm adds a message field; detail is still there). When one parameter caused the error, param names it. doc_url links to this section. A route's own fields follow the envelope keys; see Detail fields below. The code is usually also on the X-Error-Code header and the id on X-Request-ID.

Example 422 validation body:

{  "ok": false,  "error": "validation",  "detail": "invalid 'limit': Input should be a valid integer, unable to parse string as an integer (query.limit)",  "request_id": "example-request-id",  "doc_url": "https://app.wealthnow.io/docs/api-reference#error-responses",  "param": "limit"}

Some 503 responses come from the route itself: they carry status (such as unavailable_symbol_volume_curve), reason, available: false, billable: false, and retryable, with no error field and no X-Error-Code header. Read status as the code.

Every non-2xx response is non-billable. A request refused before its credit reservation is never debited; one that fails after it is refunded and reports X-Credits-Settlement: refunded with X-Credits-Cost: 0. See Pricing & credits for the credit headers.

A 404 names what was not found, and the code depends on the route: unknown_ticker on the v3 routes, ticker_not_found on the legacy quote, and a typed code on the routes listed below. The code is also on X-Error-Code. The crypto market and derivatives, COT, transcript and ai_analyze routes, and crypto_model_unavailable, repeat it as error_code. A 404 is a standing answer: the same request gets the same one.

Example 402 plan_required body:

{  "ok": false,  "error": "plan_required",  "detail": "your plan 'free' does not include 'congressional' ...",  "request_id": "example-request-id"}

Retry 429 and 502, and a 503 only when it carries Retry-After or "retryable": true, honoring Retry-After with exponential backoff capped at 120 seconds. Do not retry a 503 that says "retryable": false or whose Retry-After is longer than 120 seconds: the answer will not change soon. Before retrying 401, 402, 403, 404, or 422, check credential delivery, permissions, the wallet or plan restriction, and the requested path. A 401 alone does not justify rotating a key. See the Quickstart for the Free-plan quote check and the reference clients.

Detail fields#

An error body carries the fields its route names, after the envelope keys (ok, error, detail, request_id, doc_url), so a client can act on the refusal without parsing the sentence in detail:

A route's field never replaces an envelope key, and X-Error-Code is unchanged. Example, a 404 from /api/crypto/ZZZZQ:

{  "ok": false,  "error": "unknown_crypto_symbol",  "detail": "'ZZZZQ' is not a crypto pair the market-data feed lists. ...",  "request_id": "example-request-id",  "doc_url": "https://app.wealthnow.io/docs/api-reference#error-responses",  "param": "ticker",  "symbol": "ZZZZQ",  "hint": "Pass a crypto symbol as BTC, BTCUSD or X:BTCUSD (non-USD quote currencies via ?vs=, e.g. ?vs=EUR). ...",  "timestamp": "2026-10-02T16:12:40.634451+00:00",  "normalized_pair": "X:ZZZZQUSD"}

Unverified symbols#

A symbol known not to exist is a 404 unknown_ticker, not billed. A symbol is checked against the market-data listing and the security master, and sometimes that check cannot finish in time. When a metered call's answer is empty and its symbol could not be verified, the call answers 200 with the route's usual empty body plus two fields, and is not billed. Abridged, from /api/v3/fundamentals/full/ZZQXV:

{  "ok": true,  "ticker": "ZZQXV",  "snapshot": {},  "company_facts": {},  "insider_trades_recent": [],  "ticker_verification": "unverified",  "ticker_verification_note": "The symbol could not be verified against the market-data listing and the security master in time, so this empty answer was not billed."}

The headers say the same: X-Credits-Cost: 0, X-Credits-Settlement: refunded, and Cache-Control: no-store. Read ticker_verification: "unverified" as "this symbol may not exist", not as "this company has no data": check the spelling, or look the company up with fundamentals_search. An answer that carries data is served and billed as usual and never carries the field. It applies to single-symbol equity calls on metered routes, not to a tickers list, a crypto symbol or an asset_class call.

A symbol that is a current listing in the security master counts as verified even when the live check cannot finish, so an empty answer about it (for example news/latest?ticker=AAPL over a quiet minute) is an ordinary empty answer: billed, without ticker_verification.

When a dataset is unavailable#

A route whose dataset was never built, or whose read came back with nothing, answers 503 with error: "upstream_unavailable" and error_code: "dataset_unavailable" (also on X-Error-Code) instead of a billed empty list. The body has no result field, names the public dataset, and says why in reason:

The call is not billed. Do not poll a table_missing refusal: report that the data is not available. Retry the other two after Retry-After. Among the documented routes, this refusal can come from insider clusters, regime history, the importance, drift and decay routes on Quant Signals, the regime forecast while its book is loading (Retry-After: 5), price history when its 2025-to-date bars cannot be read, and the market-event catch-up when the stream holds no events.

Response headers#

Every authenticated response carries these headers, so a client can pace itself and reconcile credits without extra calls.