Screener and rankings
Filtered and sorted views over tokens and pools, and named rankings that publish their own formula.
The screener makes no editorial claim: filters and sort key are yours and it returns what matches. Each named ranking returns its formula and every input per row, so the order can be recomputed rather than trusted.
3 routes. Every path below is served under /index/v1/{chain}, and every request carries an x-api-key header, so those two are not repeated per route. The shared contract for pagination, snapshots, precision and absence is in Read API.
Rankings Catalog
GET /rankingsSelf-describing catalogue of the named rankings, their formulas and parameters. Static, no store read.
Rankings
GET /rankings/{preset}One named ranking. Publishes its formula and every input per row so the order can be recomputed.
| Parameter | In | Required | Notes |
|---|---|---|---|
preset | path | yes | - |
allowScan | query | no | Required acknowledgement for the preset's bounded enumerator scan. |
grain | query | no | pool or token_pair. Defaults to token_pair. |
quote | query | yes | REQUIRED. The asset every ranked volume is denominated in. |
base | query | no | Restrict the ranking to one base asset. |
window | query | no | 5m, 1h, 4h, or 24h. Defaults to 5m. |
metric | query | no | The window figure largest orders on. Refused for every other preset, which have formulas rather than metrics. |
order | query | no | Sort direction: this route's accepted values and default are on the schema (enum/default); a route whose backing index has no reverse walk accepts only asc. See Pagination for the shared contract. |
limit | query | no | Page row cap. See Pagination for the shared contract; the exact default and maximum for this route are on the schema. |
cursor | query | no | Opaque page cursor. See Pagination. |
recency_floor_block | query | no | Narrows the enumerator scan to subjects that last traded at or after this block, and is republished in equivalentScreenerQuery. |
Screener
GET /screenerFiltered, sorted page over tokens and pools. Filters and sort key are caller-chosen; the response makes no editorial claim. base/quote carry symbol/name; every row carries holderCount { value, status, asOfBlock, burnSinkHolders } (one point read per distinct base). sort=holders ranks by holderCount.value descending (exact counts first) WITHIN a labelled candidate set: the top 100 subjects by total_volume_quote under the request's filters, because holder counts are not in the rolling ring the scan can prefilter on; holdersRanking names that set, rank is null and rankWithinPrefilterSet is the position within it. The candidate-set 503 carries suggestedRecencyFloorBlock, candidatesScanned, ceiling, rankedAtBlock as fields.
| Parameter | In | Required | Notes |
|---|---|---|---|
allowScan | query | no | Required acknowledgement for this route's bounded enumerator scan. |
grain | query | no | pool or token_pair. Defaults to token_pair. |
quote | query | yes | REQUIRED. The asset every ranked volume is denominated in. |
base | query | no | Restrict the ranking to one base asset. |
window | query | no | 5m, 1h, 4h, or 24h. Defaults to 5m. |
sort | query | no | The ordering key. Defaults to total_volume_quote. |
order | query | no | Sort direction: this route's accepted values and default are on the schema (enum/default); a route whose backing index has no reverse walk accepts only asc. See Pagination for the shared contract. |
limit | query | no | Page row cap. See Pagination for the shared contract; the exact default and maximum for this route are on the schema. |
cursor | query | no | Opaque page cursor. See Pagination. |
recency_floor_block | query | no | Narrows the enumerator scan to subjects that last traded at or after this block. Bound-safe, and the response republishes it. |
min_total_volume_quote | query | no | Inclusive lower bound on the row's totalVolumeQuote, exact quote-native base units as a decimal string. |
min_buy_volume_quote | query | no | Inclusive lower bound on the row's buyVolumeQuote, exact quote-native base units as a decimal string. |
min_sell_volume_quote | query | no | Inclusive lower bound on the row's sellVolumeQuote, exact quote-native base units as a decimal string. |
min_trades | query | no | Inclusive lower bound on the row's trades count. |
min_buys | query | no | Inclusive lower bound on the row's buys count. |
min_sells | query | no | Inclusive lower bound on the row's sells count. |
min_distinct_traders_lower_bound | query | no | Inclusive lower bound on the row's distinctTraders.lowerBound: the proven floor, not the (possibly higher) estimate. |
max_total_volume_quote | query | no | Inclusive upper bound on the row's totalVolumeQuote, exact quote-native base units as a decimal string. |
max_trades | query | no | Inclusive upper bound on the row's trades count. |
max_buys | query | no | Inclusive upper bound on the row's buys count. |
max_sells | query | no | Inclusive upper bound on the row's sells count. |
min_covered_blocks | query | no | Inclusive lower bound on the row's window.coveredBlocks: excludes a subject whose ranked span was clipped short (a young chain, a thin history) below this many blocks. |
require_window_fully_covered | query | no | When true, excludes any row where window.windowFullyCovered is false: the exact-only counterpart to minCoveredBlocks. |
require_distinct_exact | query | no | When true, excludes any row whose distinct-trader counts are not proven exact (distinctBuyers/distinctSellers/distinctTraders' own exact field), rather than accepting a sketch estimate. |