Skip to main content
A watchlist is a list of wallets kept on our side. You build it once, change it by adding and removing wallets, and cite it by its id instead of sending every wallet again: one list for the holders tab of your own users, however many wallets it follows. Read the holders, top traders and trades of a token among its wallets over REST (filter market endpoints), and follow their balances and trades live on one stream subscription, or the trades of a token made by them. Managing watchlists is free.

​
A watchlist

  • Its id: yours (1 to 64 characters among A-Z a-z 0-9 _ . : -, not starting with a dot), or one we generate when you create it without one (wl_ + 16 hex characters). Ids are private to your account: another account can use the same id for its own list.
  • Its wallets: each wallet is { "address": "…", "chain": "…" } (one chain, solana or evm:<id>) or { "address": "…", "chains": "evm" } (the wallet on every EVM chain, counted as one wallet). An address is either on every EVM chain or on the EVM chains you name, never both: adding { "address": "0xabc…", "chains": "evm" } to a list that has 0xabc… on Base (or the reverse) comes back in rejected (INVALID_PARAM), and the other wallets are applied. The same address on several named chains is one wallet per chain. EVM addresses are lowercased, Solana addresses kept as they are. The rules are those of the wallet and chains parameters of the wallet streams.
  • Its version: a number that moves each time its wallets change, and never goes back, even after a deletion or a purge.

​
Changing it

  • Create, optionally with its first wallets. Creating an id you already have adds the wallets to it.
  • Add and remove up to 10,000 wallets per call. Both are idempotent: sending the same call twice changes nothing the second time (alreadyIn, notIn), and the version only moves when something changed. A list is never replaced as a whole.
  • An invalid wallet does not fail the call: it comes back in rejected with its index and the error, and the other wallets are applied.
  • Clear removes every wallet at once and keeps the list and its stream subscriptions. Delete removes the list; its id is free again at once, and its stream subscriptions end.
  • Read your lists, one list and its wallets, page by page.

​
Limits

A call that would go past a limit is refused whole, nothing is written: 429 RATE_LIMITED with details.limit (watchlistWallets or watchlists), details.max and details.current. Remove wallets or delete a list, then send the call again.

​
Filter market endpoints by a watchlist

Pass watchlist=<id> to keep only the wallets of one of your watchlists:
  • The wallets that count are those of the requested chain: on an EVM chain, the wallets on that chain and those added with chains: "evm".
  • Every endpoint takes a list of any size. Up to 2,000 wallets on the chain, top traders and trades filter exactly like makers; above, trades report what each call searched in meta.watchlist.scanned (trades, from, to).
  • meta.watchlist gives the list’s id, the version applied and its wallets at that version. A change to the list shows on the next call (on token holders, within a few seconds; on top traders with more than 2,000 wallets on the chain, within 15 seconds, and meta.watchlist.version says which version the ranking reflects).
  • The credits are those of the endpoint, as without the filter, and the call counts as use of the list.

​
Unused watchlists

A watchlist that is not used for 48 hours is purged: any call on it counts as use, and so does a stream subscription that follows it, for as long as it stays open. For 30 days its id then answers 404 NOT_FOUND with details.reason: "purged" and details.purgedAt; create it again with the same id. An id you never created, or deleted, answers 404 with details.reason: "unknown".

​
Follow it live

Subscribe to a watchlist on the Wallet Balances Stream (the exact token balances of its wallets, one message per transaction and wallet while your connection keeps up) or the Wallet Trades Stream (every trade of its wallets) with "params": {"watchlist": "<id>"}:
  • One subscription, whatever the number of wallets: on these two channels it counts as one in the stream limits of your account.
  • Changes apply live. Wallets you add or remove are followed or dropped within seconds, without subscribing again.
  • The end of the list ends the subscription. When the watchlist is deleted or purged, the subscription receives NOT_FOUND (details.reason) and ends.
  • Billing is the channel’s own: 1 credit per wallet and chain in each message. A wallet that does not move costs nothing.
  • A typical holders tab: keep your users’ wallets in one watchlist; subscribe on wallet-balances with that watchlist and wait for the ack, keep the messages that arrive, read the page with token holders and watchlist=<id>, then apply the kept messages for that token on top of it, and the next ones as they come. Nothing is sent before the ack, and a holders page can take a few seconds to show a change: reading it after the ack leaves no gap.
On the Trades Stream, add "watchlist": "<id>" to the params of a token or a market: only the trades of the list’s wallets on that token are pushed and billed, the live twin of token trades with watchlist. It counts as one subscription whatever the size of the list, and changes apply live too. On the Wallet Positions Stream and the Wallet Portfolio Stream, the same "params": {"watchlist": "<id>"} follows every wallet of the list as its own view: a snapshot per wallet, then its deltas, each message with its wallet. There each wallet counts as one subscription in your limits (a list that does not fit is refused whole), changes apply live too, and billing is that of a subscription to each wallet.

​
Credits

Creating, changing, reading, clearing and deleting watchlists costs 0 credits, and these calls stay open when your credits run out: you can always remove wallets. They have their own rate group, Watchlist: 120 calls per minute per key by default, raised on request, each call counting one whatever the number of wallets it carries. It is never limited by the Wallet group, nor by filtered token holders pages; your per-minute limit and burst cap apply as to every call (rate limits). A market endpoint with watchlist costs what it costs without it: 2 credits per call for token holders, like any token holders page. Token holders with watchlist has its own rate group too, Watchlist holders: 120 calls per minute per key by default, raised on request, each call counting one whatever its page size; the X-RateLimit-Group-* headers of every response show what is left.