Overview
The Codex API offers two ways to get data: queries and subscriptions. Many endpoints have both a query and a subscription version that return the same data — the difference is how you receive it.Which Should I Use?
Use a query when...
Use a query when...
- You need data once (e.g. loading a page, fetching a wallet’s history)
- You need historical data (e.g. OHLCV bars from last week)
- You need to paginate through large result sets (e.g. filtering tokens)
- You’re on a Free plan
Use a subscription when...
Use a subscription when...
- You need real-time updates (e.g. live price ticker, streaming trades)
- You want data pushed to you instantly as it happens
- You’re building a live dashboard or trading bot
- You want to avoid polling the API repeatedly
Endpoint Mapping
The table below maps each subscription to its query equivalent. Both return the same data — the query fetches it on-demand, while the subscription streams updates as they happen.Unconfirmed events: Several subscriptions accept a
commitmentLevel argument that trades latency against accuracy. confirmed (the default) delivers events only after confirmation; processed delivers them earlier (unconfirmed; may be reorged out) — on Base, processed returns Flashblocks events; preprocessed (Solana only) is the earliest signal, surfaced before transaction routing is finalized. Only Solana and Base support levels other than confirmed. This replaces the previously separate onUnconfirmed* subscriptions.Token Data
onFilterTokensUpdated is self-initializing — the first message delivers the current state, so you don’t need to pair it with a separate filterTokens query. The subscription re-evaluates internally every 30 seconds, and if the result set changes you’ll automatically start receiving updates for the new set.