Core concepts

Envelope contract

noxstock always returns one top-level envelope:

Outcome	Shape
Success	`{ "data": ... }`
Error	`{ "error": { "code", "message", "retryable" } }`

Do not write clients that expect raw arrays or raw endpoint objects at the top level.

Freshness

Most data endpoints include one top-level freshness value:

Value	Meaning
`intraday`	Uses intraday quote/market data where available.
`end_of_day`	Last complete EOD or statement data.
`stale`	Cached/fallback value is older than normal.
`degraded`	Partial data returned because an upstream/source path was limited.
`unsupported`	The endpoint does not apply to this symbol or asset type.

Asset types

noxstock supports US-listed stocks and ETFs. Some endpoint shapes branch by asset_type.

Examples:

ETF /v2/profile returns ETF-specific fields and an unavailable holdings envelope today.
ETF /v2/earnings returns an unsupported response because ETFs do not report earnings.
Financial companies suppress misleading FCF/EV/payout metrics where the statement model makes them unreliable.

Null and omission policy

noxstock does not fill unknowns with fake precision.

Persistent provider gaps are omitted when the schema allows it.
Useful sometimes-null fields stay present with compact statuses or reasons.
Unsupported full-endpoint cases return freshness: "unsupported" and a short reason.

Plans

Plan	Intended use	Rate/quota
Free	Verify fit and build proof workflows.	30/min, 100/day
Starter	Small apps and agent workflows.	60/min, 10,000/month
Builder	Production usage and heavier automation.	300/min, 75,000/month

Free includes /v2/search, /v2/coverage, /v2/snapshot, and /v2/valuation. Other routes require Starter or Builder.

MCP tools are read-only REST passthroughs. They call the same HTTP routes with the same API key and return the same JSON envelopes. If behavior differs, REST is the source of truth.