Skip to main content
Real-time push over a single WebSocket connection: live trades, live candles, token and pool updates, launchpad views, a market screener, and the trades, balances, positions and portfolio of any wallet, or of a watchlist of thousands. Event payloads reuse the exact same shapes as their REST twins - anything you built against REST parses stream events unchanged. Endpoint : wss://ws.serialized.xyz/v1/stream. One connection, many subscriptions. Subscriptions are additive: each subscribe carries a client-chosen id, acks are explicit, and unsubscribe targets one id without touching the others.

Channels

Every channel is open to every API key. wallet-trades and wallet-balances also follow a watchlist: a list of wallets, up to thousands, kept on our side, changed over REST, cited by its id ("params": {"watchlist": "<id>"}), and counted as one subscription. On trades, a watchlist next to the token or the market keeps only the trades of the list’s wallets, also counted as one subscription. wallet-positions and wallet-portfolio follow one too, each wallet of the list as its own view, counted as one subscription per wallet.

Authentication

Send your key as the first frame within 10 seconds of connecting: {"op":"auth","apiKey":"YOUR_API_KEY"}. The server replies {"op":"auth.ok"}; any other first frame closes the connection (code 4401).

Keepalive

Send {"op":"ping"} every 15 to 30 s; the server replies {"op":"pong"}. Connections idle for more than 60 s are closed. If no pong arrives within 10 s of a ping, the network path is dead: drop the connection, then reconnect and resume (below). A quiet subscription can go a long time without events, so judge the path by the pong, never by the absence of events. To notice a dead path sooner, ping more often (every 5 s is fine).

Errors

Errors arrive as {"op":"error","id":"<sub id>","error":{"code","message","details"}} - the same machine-readable catalog as REST (INVALID_PARAM, INVALID_CHAIN, …). A bad subscribe only fails that subscription, never the connection. Three errors are notices: the subscription stays open and events keep coming. On a watchlist subscription, a RATE_LIMITED that carries details.refused is a notice too: that many wallets of the list cannot be followed for now, the others keep coming. On wallet-positions and wallet-portfolio, so is any error that carries details.wallet (it concerns that wallet of the watchlist only) and an UPSTREAM_ERROR that carries details.wallets (that many wallets of the watchlist are temporarily without live data and come back by themselves). Any other error on a subscription ends that subscription. A watchlist subscription ends with NOT_FOUND when its watchlist is deleted or purged. When it carries details.retryAfterMs (UPSTREAM_ERROR without resumes: the subscription could not be confirmed in time), send the same subscribe again after that delay. Connection close codes:

Reconnect & resume

When to reconnect. After a 1012 or 1013, wait retryAfterMs, then reconnect. After any other drop (a network error, a 1006, a refused connection), reconnect with an exponential backoff and jitter: wait a random time between 0 and the current delay, starting at 1 s and doubling up to 30 s after each failed attempt, back to 1 s once a connection is authenticated. 4401, 4402 and 1008 are not transient: reconnecting in a loop does not help, fix the key, the credits or the client first. One exception: a 1008 with the reason connection limit (… per account) reached right after many of your connections dropped at once may count connections that are already gone: for a few seconds, and usually 35 s (60 s at most) for a connection that dropped without closing. Reconnect after 5 s, then after 60 s, and only then treat it as a real limit. Every event of a single-entity subscription, and of a watchlist subscription, carries a cursor. Keep the cursor of the last event of each subscription; after a reconnect, send the same subscribe with "since": "<cursor>" next to params. A list subscription (tokens, pools or wallets) has no cursor and refuses since: subscribe again without it, and fetch what you missed over REST if you need it.
Resume a subscription
  • What comes back. trades: every trade after the cursor, then live. ohlcv: the candles closed since the cursor, then the forming candle. token-updates and pool-updates: the current state. wallet-trades and wallet-balances: every transaction after the cursor, then live (on a watchlist, a single REPLAY_TOO_OLD for the whole list when part of it cannot be replayed). pulse, pulse-pools, screener, screener-pools, wallet-positions and wallet-portfolio: the deltas you missed, or a snapshot of the current view (on a watchlist, a snapshot of each wallet, free).
  • Window. Up to 5 minutes back, from the first seconds of the subscription. Beyond it, or when the replay cannot be proven complete, you get REPLAY_TOO_OLD with details.restFromMs: fetch that part over REST (trades: /v1/token/trades with fromAt; candles: /v1/token/ohlcv); live events continue.
  • Duplicates. Events you may have received already are flagged "replay": true. Dedupe trades by their id (the same stable id as REST: data.id, or the id of each trade when data is an array, as on wallet-trades and on trades with an updatePeriod) and candles by data.time; state channels always carry the full state. Never drop an event just because it is flagged.
  • Cursors are opaque. Store them as strings, never parse them. A malformed since is refused with INVALID_PARAM (details.param: "since").
  • Order of events. On ohlcv, token-updates and pool-updates, asOf never goes back on one connection; after a reconnect, take the first state you receive as the current one, whatever its asOf. On trades, asOf is the time each trade was pushed: to order trades, use their block time (data.at), never asOf.

Limits

Limits per account, the same on pay as you go and Growth: 100 concurrent connections and 200 subscriptions in total, across all your keys, connections and channels (one connection can hold them all; each token of a tokens list counts as one subscription, a live view counts as one, a wallet-trades, wallet-balances, wallet-positions or wallet-portfolio subscription counts as one whatever the number of its chains (chains, evm included), a watchlist subscription counts as one whatever the number of its wallets on trades, wallet-trades and wallet-balances, and one per wallet on wallet-positions and wallet-portfolio (one at least), each entry of a wallets list counts as one, and ohlcv takes up to 20 subscriptions per account by default). token-updates and pool-updates each take up to 50 subscriptions per account. A connection sending more than 200 frames in 10 seconds, not counting auth and up to your subscription limit (plus 50) of subscribe / unsubscribe, is closed (1008): reopening every subscription at once after a reconnect is fine. A subscribe over a limit gets RATE_LIMITED with details.limit (subscriptions for the total, or the channel name) and details.max. On wallet-positions and wallet-portfolio, each connection can also open up to twice your subscription limit in watchlist wallets (400 by default), refilled over a minute: subscribing to all your watchlists, then resuming them once on the same connection, always fits; beyond, the subscribe gets RATE_LIMITED with details.limit: "watchlistWalletsPerMinute", details.max and details.retryAfterMs: send it again after that delay. Right after a connection dropped without closing, its subscriptions still count until we close it: usually 35 s, 60 s at most. Send a refused subscribe again after 20 s, then after 40 s. Need more? Ask us.

Billing

Streams bill the messages you receive, one by one: every message we deliver is billed once, and a message we do not deliver is never billed. The connection itself is free, however long it stays open, and a subscription that receives nothing costs nothing.
  • Live views: 1 credit per message. On pulse, pulse-pools, screener and screener-pools, every delta costs 1 credit, whatever the number of rows it carries.
  • Every other channel: 1 credit per element with on-chain activity. A message costs 1 credit for each element it carries that had an on-chain event since the previous message of the subscription. An element counts once in its message, however many times it changed in between: three pools that traded cost 3, one pool that traded five times costs 1.
  • Free. An element with no on-chain event behind its message: a token or a pool revalued only because the native coin’s USD price moved, updates of labels, security, metadata or holder counts, and data corrections (a corrected closed candle, the balance of a wallet trade confirmed by its transfer, a trade taken back because its tokens went to another address, a position completed from our records). Also free: the full states we send again on our own, every 60 s ("reason": "periodic") or after a hiccup ("reason": "resync"), the notices (REPLAY_TOO_OLD, UPSTREAM_ERROR, OVERLOADED), and a message lost to backpressure (gap). With tradeUpdatesOnly: true on wallet-positions and wallet-portfolio, a delta costs 1 only when it carries a new trade of the wallet.
  • The first message of a subscription (its photo, "reason": "subscribe") costs 1 credit, whatever its size: one state, a whole list of states, a view snapshot, even an empty one. trades, wallet-trades and wallet-balances have no photo.
  • Resume. You are never billed twice. When you resume with since on trades, wallet-trades, wallet-balances or ohlcv, anything up to your cursor that comes back is flagged "replay": true and free (on a watchlist subscription, this can include a few messages from the seconds around your disconnection); what comes after your cursor is billed like live events, even when flagged "replay": true. On the view channels (pulse, pulse-pools, screener, screener-pools, wallet-positions, wallet-portfolio), the deltas you missed are billed like live deltas, and deltas flagged "replay": true are free. When the view sends a snapshot instead, that snapshot is free ("reason": "resync"), however old your cursor.
  • Each subscription is billed on its own: two subscriptions that receive the same message both pay for it.

Examples

GET /v1/usage/breakdown reports each channel under WS <channel>: credits as above, and requests the number of billed messages, including those that came to 0 credits; messages that are free by nature (replays of messages you already had, the periodic and resync states) are not counted. Connection time is under WS /v1/stream, at 0 credits.

Choosing your pace: updatePeriod

Every subscribe accepts an optional updatePeriod: the pace of the subscription, in milliseconds (0 to 60000), or "block". A number snaps up to the next step of 0, 100, 200, 250, 500, 1000, 2000, 5000, 10000, 30000, 60000 (150 becomes 200), and the ack carries the value applied.
  • On token-updates, pool-updates and the forming candle of ohlcv, each period delivers the latest state, which is all you need; a subscription that was quiet gets its next state at once. A closed candle is always delivered immediately.
  • Coming from a previous version of this stream, where token-updates and pool-updates sent at most one event per second per entity: send "updatePeriod": 1000 to keep that pace.
  • On pulse, pulse-pools, screener and screener-pools, you receive at most one message per period: the first change after a quiet period is delivered at once, and the changes that follow come together in one delta when the period ends.
  • On wallet-positions and wallet-portfolio, a change is delivered at once, and the changes that follow within the period come together in one delta at its end.
  • On trades and wallet-trades, a period above 0 delivers one message per period carrying every trade of the period, in order, as "data": [trade, ...], with the cursor of the last one. If more than 256 trades pile up in one period, the oldest are dropped and the message carries "gap": true. On wallet-trades every message is "data": [trade, ...], at any period: at 0, one message per transaction of the wallet, and above 0 the bound counts transactions (256, or 256 KB of them), dropped whole.
  • On wallet-balances, a period above 0 delivers the latest balance of each wallet, chain and token that changed in the period. A period that piles up more than 256 balances is sent at once and the next one starts: no balance is left out.
"updatePeriod": "block", on every channel but wallet-balances and watchlist subscriptions on trades and wallet-trades: one message per chain and per block, sent as soon as the block is complete, with everything of that block (every trade, the latest state of each entity, the changes of a view). On the chains that publish sub-blocks (Unichain, X Layer, MegaETH), one message every 200 ms. On ohlcv, the forming candle never waits longer than its interval, and a closed candle is always delivered at once. A subscription over several chains (a view, a list, a wallet with chains) receives one message per chain and per block. Under exceptional load, a block can come in more than one message, each billed as usual. The ack carries "updatePeriod": "block". It is never a default: ask for it. A longer period costs less or the same, never more. On the views, a longer period sends fewer messages, so it costs fewer credits. On the other channels, an element that changes several times within one period counts once in its message: on trades, "updatePeriod": "block" costs 1 credit per pool and per block. maxUpdatesPerMinute (integer, 1 to 6000) is still accepted as an alias: 60 is "updatePeriod": 1000, 600 is 100; give one or the other, never both. On trades, maxUpdatesPerMinute keeps its original meaning: each window delivers only the latest trade, as a single object ("data": {...}), the first one at once.
Subscribe with at most one message per second
Ack

Connection walkthrough