Skip to main content
WS channel: trades Every new trade of a token (all its pools by default, or a pool subset) or of one market, pushed as it lands. Events are the exact REST /v1/token/trades shape, one event per trade: the live twin of /v1/token/trades and /v1/pool/trades.
string
required
Public chain id - evm:<id> or solana. Example: evm:8453
string
Token address (EVM hex, case-insensitive; Solana base58). Required unless you pass pool. tokenAddress is accepted as the same parameter. Example: 0xb2000000000000000000007bf6d5cbb0e24cb301
string
Comma-separated pool addresses to restrict the tape of address, 1 to 50 (REST /v1/token/trades accepts up to 200; beyond 50, the subscription is refused with INVALID_PARAM). Default: token-wide (every pool of the token).
string
One market instead of a token: the tape of that pool, the live twin of /v1/pool/trades. Pass chain and pool, without address. poolAddress is accepted as the same parameter. Example: 0x0ca6485b7e9cf814a3fd09d81672b07323535b64
Native coins (0x0000…0000 and 0xeeee…eeee on every chain, Solana included, the wrapped native such as WETH or WBNB, and the SOL mint) stream the trades of the coin’s main USD markets, seen from the coin, like REST /v1/token/trades: buying the stablecoin with ETH is a sell of ETH, amountToken is in the coin, quoteToken and amountQuote are the stablecoin, priceUsd is the trade’s own rate. pools accepts a subset of those markets, the first rows of /v1/token/pools.
string
Comma-separated wallet labels: only the trades whose maker carries at least one of them at the time of the trade are pushed (dev, sniper, bundler, whale, proTrader, smartTrader, freshTrader, kol). The same rule as the labels filter of /v1/token/trades without a wallet filter. On a native coin’s feed only proTrader, smartTrader, freshTrader and kol apply. Example: whale,kol
Every event carries the maker’s wallet labels at the time of the trade in labels, the same list as REST.
string
The id of one of your watchlists: only the trades whose maker is a wallet of the list are pushed, and only those are billed. It narrows the token (address, with or without pools) or the market (pool) you subscribe to, and combines with labels: the same rule as the watchlist filter of /v1/token/trades. The wallets that count are those of the chain of the subscription; on an EVM chain, also those added with chains: "evm". Any list size: one subscription follows a list of 200,000 wallets. Wallets you add or remove over REST are applied within seconds, without subscribing again. Not with updatePeriod: "block". Example: app-users
integer | string
Milliseconds, 0 to 60000, or "block"; default 0 (every trade as it lands, one event per trade). Above 0, one message per period carries 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. "block": one message per chain and per block, with every trade of that block. The ack carries the value applied (snapped up to 0, 100, 200, 250, 500, 1000, 2000, 5000, 10000, 30000, 60000). See Choosing your pace.
Events are the exact REST /v1/token/trades Trade shape, including the stable id for dedup, the transaction fees by part (gasFeesUsd, mevFeesUsd, platformFeesUsd, totalFeesUsd), the raw amounts amountTokenRaw / amountQuoteRaw (Solana; null on EVM chains), the maker’s public profile (displayName, avatarUrl, twitter) and entity (entityName, entityType) and the token’s fully diluted valuation at the price of the trade (fdvUsd = priceUsd × the token’s total supply, fdvNative the same in the native coin). These raw amounts, profile and entity fields and valuations may be null on an event when the value is not known at the moment the trade is pushed: GET / POST /v1/token/trades is the reference. isWash is a boolean on Solana and null on EVM (no wash tagging there). On Solana, at carries the sub-second time of the trade, in the same second as the at REST serves for the same id: merge by id, and order trades inside a second by their cursor.

Billing

1 credit per pool with a trade in each message: every trade costs 1 at the default pace, and a batch (updatePeriod) costs 1 per pool it carries. With watchlist, only the trades of the list’s wallets are sent, and only what is sent is billed: a token traded all day by other wallets costs nothing. Details in Billing.

Following a watchlist

  • The ack carries watchlist: the list’s id, the version applied and its wallets at that version. Nothing is sent before it.
  • Changes apply live: wallets you add or remove over REST are followed or dropped within seconds. A cleared list sends nothing until you add wallets again.
  • The end of the list ends the subscription: when the watchlist is deleted or purged, the subscription receives NOT_FOUND with details.watchlist and details.reason, and ends. An unknown id is refused the same way at subscribe.
  • When the list cannot be read right now, the subscribe is refused with UPSTREAM_ERROR and details.retryAfterMs: send it again after that delay.
  • One subscription, whatever the size of the list; reading the trades of a list counts as use of the list (unused watchlists).
  • The page behind it: read the recent trades of the list’s wallets with /v1/token/trades and watchlist=<id>, then apply the events as they come, deduped by data.id.

Resume

Every event carries a cursor. After a reconnect, subscribe again with "since": "<cursor of the last trade you received>": you receive every trade after it (up to 5 minutes back), then live. With watchlist, send the same watchlist: the trades replayed are those of the list’s wallets, after the ack. Trades you may already have are flagged "replay": true: dedupe them by data.id. If the replay is not available, a REPLAY_TOO_OLD notice gives details.restFromMs: fetch /v1/token/trades with fromAt from there, the subscription keeps going. See Reconnect & resume.

Close codes

When the close reason carries restFromMs (JSON, on a 1012 or a 1008), some trades of this connection may be missing: fetch them with fromAt from there. After a 1012 or 1013, reconnect (with a backoff, see Reconnect & resume) and resume each subscription with since.
Ack
type:object

Server acknowledgement: the subscription is live.

Trade
type:object

Server push frame (Trade).

Subscribe
type:object

Client frame opening the subscription (additive, ack is explicit).