onFilterTokensUpdated is the live counterpart to filterTokens. It accepts the same filter and ranking inputs, sends the current matching set on the first message, then re-evaluates every 30 seconds and pushes updates as the matching set changes. Use it anywhere you would otherwise re-run filterTokens on a timer.
Boolean filtering: The
filters input supports an optional boolFilter field that accepts and, or, and not operators (nestable up to 4 levels). Use it when you need different filter conditions for a subsets of tokens, such as per-network thresholds, or across different fields. For example, you might want different filter conditions depending on whether tokens are on Solana or Base. See Advanced Filtering for details.This endpoint requires a Growth or Enterprise plan. Learn more.
Returns
FilterTokenUpdates
Arguments
TokenFilters
A set of filters to apply.
See TokenFilters
TokenPairStatisticsType
The type of statistics returned. Can be
FILTERED or UNFILTERED. Default is UNFILTERED.
See TokenPairStatisticsTypeString
A phrase to search for. Can match a token or pair contract address or partially match a token’s name or symbol.
[String]
A list of token IDs (
address:networkId) or addresses. Can be left blank to discover new tokens.[String]
A list of token IDs (
address:networkId) to exclude from results[TokenRanking]
A list of ranking attributes to apply.
See TokenRanking
Boolean
Flag to use aggregated token stats.
Int
How long, in milliseconds, to batch token updates before emitting them. Defaults to 500ms and must be between 0 and 60000.
Int
The maximum number of tokens to return.
Int
Where in the list the server should start when returning items. Use
count+page from the previous query to request the next page of results.The first message delivers all tokens matching your filters. Subsequent messages only include tokens with updated data, returned at the interval you set via
updatePeriod. Every 30 seconds, the filter itself re-evaluates: if tokens start or stop meeting your filters, the result set updates automatically.Example
Test this query in the Explorer →Example Response
Usage Guidelines
- Accepts the same filters, rankings, and limit arguments as the filterTokens query. If you’ve already built a filterTokens request, you can reuse it here as a subscription.
- The first message delivered contains the current state of the filtered set, so there’s no need to run a one-off filterTokens query first.
- Matched tokens push data updates on a configurable interval via
updatePeriod(defaults to 500ms if not specified, accepts any value in ms from 0ms to 60s). - The filter itself re-evaluates the token list every 30 seconds. If the set of matching tokens changes (a token starts meeting the filters, or stops meeting them), you’ll automatically receive updates reflecting the new set. This re-evaluation interval is not currently configurable.
- Ideal for keeping trending lists, leaderboards, or filtered dashboards live without manual polling.
- For ultra-low-latency token discovery (e.g. memescope-style interfaces) our Launchpad subscriptions may be a better fit for that use case.
- Apply the same quality filters (trendingScore, minimum volume, mcap range, liquidity, holders, etc.) you would on filterTokens to avoid low-quality tokens in the stream.
- Response limit remains 200 tokens per subscription.
Troubleshooting Tips
Do I still need to call filterTokens first to get the initial state?
Do I still need to call filterTokens first to get the initial state?
No. The first message delivered after subscribing contains the current filtered result set. You can treat the subscription as a full replacement for polling
filterTokens for most use cases.Why am I not receiving any updates after the first message?
Why am I not receiving any updates after the first message?
Tokens that match your filters will push data updates on a set
updatePeriod (default 500ms). If that period is set high (e.g. 60000 for 60s), pushes will be less frequent. The filter itself also re-evaluates every 30 seconds, so if the set of matching tokens hasn’t changed and no tokens in the set have new data in your updatePeriod window, you may see quiet stretches. Broadening your filters or lowering updatePeriod will confirm the stream is live.Can I make updates push faster than 500ms?
Can I make updates push faster than 500ms?
Yes. Set
updatePeriod to any value between 0ms and 60s. Note that 0ms means “as fast as events arrive,” which can mean high message volume on busy filter sets.Can I make the filter re-evaluate faster than every 30s?
Can I make the filter re-evaluate faster than every 30s?
Not currently. The 30-second filter re-evaluation is fixed. For very low-latency token discovery (e.g. memescope-style UIs), our launchpad subscriptions offer lower-latency streams for newly launched tokens.
Should I use this instead of polling filterTokens on an interval?
Should I use this instead of polling filterTokens on an interval?
It depends on your use case for
filterTokens, but in most instances, yes. This subscription is the intended replacement for poll-based refresh patterns on filterTokens.Can I change filters on an active subscription?
Can I change filters on an active subscription?
No. To change filters or rankings, close the current subscription and open a new one with the updated arguments.
Related Recipes
- Discover Tokens: Build token discovery pages with trending data, filters, and search
- Launchpads: Build a launchpad discovery view with real-time token lifecycle updates