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 a1012 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-updatesandpool-updates: the current state.wallet-tradesandwallet-balances: every transaction after the cursor, then live (on a watchlist, a singleREPLAY_TOO_OLDfor the whole list when part of it cannot be replayed).pulse,pulse-pools,screener,screener-pools,wallet-positionsandwallet-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_OLDwithdetails.restFromMs: fetch that part over REST (trades:/v1/token/tradeswithfromAt; candles:/v1/token/ohlcv); live events continue. - Duplicates. Events you may have received already are flagged
"replay": true. Dedupe trades by theirid(the same stableidas REST:data.id, or theidof each trade whendatais an array, as onwallet-tradesand ontradeswith anupdatePeriod) and candles bydata.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
sinceis refused withINVALID_PARAM(details.param: "since"). - Order of events. On
ohlcv,token-updatesandpool-updates,asOfnever goes back on one connection; after a reconnect, take the first state you receive as the current one, whatever itsasOf. Ontrades,asOfis the time each trade was pushed: to order trades, use their block time (data.at), neverasOf.
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 atokens 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,screenerandscreener-pools, everydeltacosts 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). WithtradeUpdatesOnly: trueonwallet-positionsandwallet-portfolio, adeltacosts 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-tradesandwallet-balanceshave no photo. - Resume. You are never billed twice. When you resume with
sinceontrades,wallet-trades,wallet-balancesorohlcv, anything up to your cursor that comes back is flagged"replay": trueand free (on awatchlistsubscription, 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": trueare free. When the view sends asnapshotinstead, 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-updatesand the forming candle ofohlcv, 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-updatesandpool-updatessent at most one event per second per entity: send"updatePeriod": 1000to keep that pace. - On
pulse,pulse-pools,screenerandscreener-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 onedeltawhen the period ends. - On
wallet-positionsandwallet-portfolio, a change is delivered at once, and the changes that follow within the period come together in onedeltaat its end. - On
tradesandwallet-trades, a period above 0 delivers one message per period carrying every trade of the period, in order, as"data": [trade, ...], with thecursorof the last one. If more than 256 trades pile up in one period, the oldest are dropped and the message carries"gap": true. Onwallet-tradesevery 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