Add a filters object to the subscribe message. An empty filter, or one you leave out, means the whole channel. A filter a channel does not accept is ignored — it has no effect and is not an error.
The four filters
| Filter | Type | Accepted by | Description |
|---|
wallets | string[] | trading, fees, positions, combos, transfers, accounts, wallets | Hex addresses (0x…). Keeps events that touch a listed address (maker, taker, sender, recipient, or a decoded participant). Required on the wallets channel (at least 1). |
market_ids | string[] | trading, oracle, resolution, lifecycle, positions, combos, markets | Condition/market IDs as hex strings. Keeps events for the listed markets. |
token_ids | string[] | trading, fees, lifecycle, positions, combos, transfers, markets, clob.* | Token IDs as decimal strings. Keeps events for the listed outcome tokens. Required on every clob.* channel (at least 1). |
min_usd | integer | trading only | Smallest trade size in whole USD. Keeps fills at or above this size. Empty means all sizes. |
wallets and markets channels require their filter, or the subscribe fails. The clob.* channels likewise require token_ids.
How filters combine
Filters group into three axes:
- Wallet axis —
wallets.
- Market axis —
market_ids and token_ids together. A market’s condition id and its outcome token ids both name the same market, so they are one axis.
- Size axis —
min_usd (trading only).
The rule is AND across axes, OR within an axis:
- Within one axis, an event matches if it hits any value. Two
wallets means “wallet A or wallet B”. A market_ids and a token_ids together mean “this market or this token”.
- Across axes, an event must match every axis you set. A wallet and a market and a size.
- An axis with no filter set adds no constraint (empty filter = whole channel).
Worked example. Subscribe to trading with wallets: [a], market_ids: [m], and min_usd: 100. You get wallet a’s trades in market m at or above $100 — all three axes must match.
Confirmed vs pending matching
On the confirmed feed (confirmed: true, the default), filters run against the fields of each decoded event log.
On the pending feed (confirmed: false), the same filters run against fields read from each pending transaction’s calldata instead of event logs. A filter only works where the field is a real calldata argument, because the blockchain limits what you can read before a transaction runs. See Mempool → Filter reach for the full list.
min_usd means a different thing on each feed. On the confirmed feed it
measures the filled amount. On the pending feed it measures the pending
order’s intended fill (call.notional_usd), which may only partly fill or
never land at all.