API Reference

The Wealthnow API has two surfaces that share one key and one credit wallet:

Authentication#

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

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

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.

Every FIRM response is 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).

Discover every live endpoint (method, path, params) at any time — 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. Portfolio VaR and calibrated execution estimates are unavailable and return 503 without consuming credits. Quant intervals and Copilot return or sizing fields can be withheld when supporting evidence is missing.

No-auth routes (no key needed): /api/capabilities, /api/health, /api/openapi.json.

Unmetered health/discovery routes: /api/status, /api/ml/health, /api/v3/monitoring/system_health. 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, Options Flow $79/mo, Copilot $199/mo. So a Starter or Pro customer can add Copilot without going Enterprise.

Included credits/month: Free 1,000 · Starter 250,000 · Pro 2,000,000 · Expert 5,000,000 · Enterprise 20,000,000. Rate limits: Free 30 · Starter 120 · Pro 600 · Expert 1,200 · 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:

1curl -H "Authorization: Bearer $TENGU_API_KEY" \2  "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).

Market Data — Free+ · 1 credit#

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. See Real-Time Streaming.

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

Alt-Data — Pro+ · 3 credits#

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

Execution & Research — Pro+ · 4 credits#

TWAP is an arithmetic schedule, not a prediction of fills or trading costs. Calibrated cost estimates and VWAP without an empirical volume curve return typed 503 responses without consuming credits. See Execution & Research for availability limits.

Risk Analytics — Pro+ · 5 credits#

Portfolio VaR, stress, and crash outputs are unavailable until verified account positions, NAV, and calibrated evidence are bound to the calculation. Unavailable portfolio-risk requests do not consume credits. Other research routes have separate evidence requirements; see Risk Analytics.

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 WRDS / S&P Capital IQ 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 S&P Capital IQ 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.

Copilot — Expert+ (or $199/mo add-on on Starter/Pro) · 10 credits#

Research ranking is not authorization to trade. Return estimates, intervals, and sizing can be withheld; inspect capital_authorized and the returned evidence. The ticker aggregation's candidate_weight_pct is echoed context reserved for a separate sizing integration, not a portfolio-aware sizing calculation. See Copilot.

Brain agent endpoints — Enterprise#

Base URL https://brain.wealthnow.io/v1. Auth Authorization: Bearer tengu_....

Both support streaming (stream: true). Brain is stateless per request — send the full messages[] history to continue a conversation. A successful turn's authoritative USD cost is multiplied by 2,500 and rounded up to shared-wallet credits. Returned token counts describe the main query and can omit auxiliary work; they are not an invoice calculation. max_tokens accepts integers from 1 through 64,000 and limits each provider response, not input tokens or dollar cost. See Brain billing and usage. Brain requires the Enterprise plan (it has autonomous access to the full product suite); a key without Brain entitlement returns 403 CHAT_ENTITLEMENT_REQUIRED.

Error responses#

FIRM uses a flat error envelope: {"ok": false, "error": "<code>", "detail": "<message>", "request_id": "...", "doc_url": "..."} (message instead of detail with ?shape=firm). When one parameter caused the error, param names it. doc_url links to this section. The code is usually also on the X-Error-Code header and the id on X-Request-ID.

Example 422 validation body:

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

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.

Example 402 plan_required body:

1{2  "ok": false,3  "error": "plan_required",4  "detail": "your plan 'free' does not include 'congressional' — upgrade to Starter to access it. Manage your plan at https://app.wealthnow.io",5  "request_id": "example-request-id"6}

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. 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.

Response headers#

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