Skip to main content
GET
GET /v1/token/top-traders · 2 credits Ranked traders of a token from our own PnL fold: realized PnL in native and USD, tokens and native bought/sold, open position, average entry, win rate over closed positions, first/last trade, and the wallet labels of each trader (dev, sniper, bundler, whale, proTrader, smartTrader, freshTrader, kol, insider). Lifetime by default, or any rolling window (1h → 30d). EVM and Solana, one shape.
Pagination. limit (1 to 1000, default 20) is the page size and offset (default 0) the number of traders to skip: the ranking goes down to the 1 000th trader (offset + limit ≤ 1000, beyond 400 INVALID_PARAM). rank is absolute across pages and meta.traderCount gives the total. Same price whatever the page size.
Wallets filter. wallets (comma-separated or a list, at most 100 addresses) ranks only these wallets, without creating a watchlist: rank and meta.traderCount are then among them. Not with watchlist.
Labels filter. labels (comma-separated or a list, any of them matches) keeps the traders carrying at least one of the requested wallet labels now: dev, sniper, bundler, whale, proTrader, smartTrader, freshTrader, kol, and insider on Solana. It searches the top 1 000 traders of the ranking you ask for (same timeframe, sortBy, order, pools, and among your wallets or watchlist when you pass one): a trader ranked below 1 000 is never returned. Each trader keeps its rank in that ranking; offset and limit page the filtered list, and meta.matched is how many of the top 1 000 carry a requested label. meta.traderCount stays the size of the whole ranking. The response carries meta.labelBasis (current) and meta.labelCoverage, as on /v1/token/holders. An unknown label, liquidityPool, or insider on EVM chains returns 400 INVALID_PARAM (details.param: "labels"). Same price.
Current balance. amount (decimal string), amountRaw (raw units) and pctSupply are the wallet’s balance now and its share of the supply, as on /v1/token/holders: "0" once the wallet sold out, null when unknown (for instance on Solana for a trade a few seconds old). openTokens stays the position of the PnL: what the trades left, capped by the balance.
Average prices. avgBuyPriceNative and avgSellPriceNative are the average buy and sell prices in native. avgBuyPriceUsd and avgSellPriceUsd are served when the row’s USD is valued at each trade’s time (meta.usdBasis: trade, every Solana ranking and EVM rolling windows); on the EVM lifetime ranking (spot) they are null, never a past price at today’s rate.
Fees. buyFeesUsd, sellFeesUsd and totalFeesUsd are the fees paid on the token’s swaps: network fees on EVM chains; network, priority tips and trading platform fees on Solana. On a rolling window, both chain families: the fees of the window’s transactions, counted once per transaction (a transaction that buys and sells the token counts on the buy side), valued like the row (meta.usdBasis); null when the network fee of one of the trader’s transactions in the window is not recorded: always on Arbitrum, Unichain, Monad and Plasma, often on BSC and X Layer, where some transactions carry no recorded fee. On the lifetime ranking: Solana, for positions opened since 2026-09-15; null on EVM chains and on older positions.
Pools. On a rolling window, pools= (a CSV of up to 200 pool addresses of the token) ranks the traders of those markets only; one pool gives the ranking of /v1/pool/top-traders. Without pools, every pool of the token. The lifetime ranking (timeframe=all, the default) covers the whole token: pools with it returns 400 INVALID_PARAM (details.param: "pools"), as does a pool of another token.
labels lists the trader’s wallet labels as they stand now, in a fixed order; isDev, isSniper and isProTrader agree with it (null when unknown). On Solana, insider marks a wallet that received at least 0.01 % of the supply in one transfer without buying it, for tokens created since 2026-10-02, as on /v1/token/holders.
Identity. entityName and entityType (cex, protocol, bridge…) name known entities; displayName, avatarUrl and twitter (the X handle, without @) are the wallet’s public profile, as /v1/wallet/profile serves it, for instance a KOL’s name and handle. Each is null when unknown.
Trading platform. platform is the trading platform the wallet trades with (a terminal, bot, wallet app, aggregator, DEX router or launchpad app), on every timeframe, the same object as /v1/wallet/labels: id (a stable lowercase identifier such as axiom, gmgn, trojan, maestro), name and logo (an https URL, null when we host no logo for that platform). platform is null when not known.
Funding. fundingFrom, fundingAt, fundingTxHash, fundingAmountNative (raw native units: wei, lamports), fundingFromTag and fundingFromLogo are the wallet’s first funding and its funder, with the same fields and rules as /v1/token/holders; null when unknown.
meta echoes the resolved timeframe, sortBy and order, plus usdBasis - the basis of every USD figure in the response.
Traders are ranked per token market: a native coin (0x0000…0000 on EVM, the SOL mint on Solana) is the quote of its chain’s markets and returns 400 INVALID_PARAM (its markets are listed by /v1/token/pools).
On a rolling window, realizedPnlNative is the wallet’s net native cashflow over the window (sold − bought) and winRatePct is null; win rate is measured over fully closed lifetime positions (timeframe=all).
positionValue*, unrealizedPnl* and totalPnl* value the wallet’s current bag at the current price: served on the lifetime ranking (timeframe=all), null on a rolling window, and null while the token has no price yet. meta.usdBasis says how boughtUsd, soldUsd and the realized PnL were computed: trade = each trade valued at the native coin’s USD price at that trade’s minute, the basis of rolling windows on EVM and Solana and of the Solana lifetime ranking; spot = native amounts converted at the current native price, the basis of the EVM lifetime ranking. meta.traderCount is the number of wallets that ever traded the token (lifetime) or the number of distinct wallets in the window.
Watchlist. watchlist=<id> ranks only the wallets of one of your watchlists, with the same timeframe, sortBy, order and limit: its wallets on the requested chain (on an EVM chain, those added with chains: "evm" too), whatever the size of the list. rank is then the position among them, meta.traderCount the number of them that traded the token (or in the window), and meta.watchlist gives the list’s id, the version applied and its wallets. A windowed ranking (timeframe other than all) over a list of more than 2,000 wallets on the chain needs at most 50,000 traders in the window: beyond, 400 INVALID_PARAM with details.param: "timeframe", use a smaller timeframe. An unknown or purged list returns 404. Same credits as without it.

Authorizations

Authorization
string
header
required

Your raw API key (not needed on the demo server).

Query Parameters

chain
string
required

Public chain id - evm:<id> or solana.

address
string

Token address. Or send it as tokenAddress.

tokenAddress
string

The explicit name of address (the token): send one of the two.

timeframe
default:all

all (default) ranks over the token's lifetime; 1h, 4h, 1d, 7d or 30d ranks over a rolling window. On a window, realizedPnlNative is the net native cashflow over the window and winRatePct is null.

Available options:
all
sortBy

pnl (default, realized PnL in native), pnlUsd (realized PnL in USD, realizedPnlUsd), bought, sold or txns.

Available options:
pnl
order

desc (default) or asc.

Available options:
asc
limit
integer
default:20

1-100. Default 20.

Required range: 1 <= x <= 1000
offset
integer
default:0

Traders to skip; offset + limit never exceeds 1000

Required range: 0 <= x <= 999
wallets

Rank only these wallets, comma-separated or as a list (at most 100); rank and traderCount among them. Not with watchlist

pools
string

Optional CSV of up to 200 pool addresses of the token: ranks the traders of those markets only, over a rolling timeframe (1h to 30d); one pool gives the ranking of /v1/pool/top-traders. Not with timeframe=all (the default): 400. Default: every pool of the token.

watchlist
string

Id of one of your watchlists: the same ranking among its wallets on the chain (on an EVM chain, those added with chains: "evm" too), any list size. rank is the position among them, meta.traderCount the number of them that traded the token (or in the window), meta.watchlist the list applied (wallets: its size at that version). Above 2,000 wallets on the chain, a windowed ranking needs at most 50,000 traders in the window (beyond: 400 on timeframe). The all-time ranking with watchlist counts 4 against the Traders group cap.

labels

Keep only the traders carrying at least one of these labels now, comma-separated or as a list: dev, sniper, bundler, whale, proTrader, smartTrader, freshTrader, kol, insider (Solana only). Searched among the top 1000 traders of the requested ranking; each trader keeps its rank, and offset and limit page the filtered list (meta.matched counts the matching traders).

Response

200

Standard { data, meta } envelope.