Token traders API

GET/tokens/:chain/:address/traders

A token's traders ranked by PnL, realized PnL or volume, over a window or all time, or its first buyers; each with its position, labels and first buy.

Parameters

Name	In	Type	Default	Allowed values
`chain`	path	string	required	`evm:56` (BSC), `solana`, `evm:8453` (Base), `evm:4663` (Robinhood Chain) or `evm:1` (Ethereum)
`address`	path	string	required	Token address (BSC) or mint (Solana)
`sort`	query	string	`pnl`	`pnl` (total), `realized`, `volume` (bought + sold USD), `first` (first buyers, earliest first)
`window`	query	string	`all`	`1h`, `6h`, `24h`, `7d`, `30d`, `all`
`label`	query	string	any	Only traders with this label
`limit`	query	integer	`50`	1–100
`cursor`	query	string	first page	The previous page's `next`, as it came

Response

Field	Type	Meaning
`chain`, `token`, `indexedSince`, `sort`, `window`	string, object, number, string, string	`token` is `{ address, symbol, name, decimals }`; `indexedSince` as in Wallets and PnL.
`traders[]`	array	In `sort` order: highest first (a null PnL last), or for `first` earliest first.
`traders[].wallet`, `labels`	string, string[]	The wallet and its labels.
`traders[].firstBuy`	{ time, block, tx } \| null	The wallet's first buy of the token. `null` for a wallet that only sold it.
`traders[].quote`	boolean	A stablecoin, or the native or wrapped native token: listed, but left out of every wallet total.
`traders[].trades`, `buys`, `sells`, `unpricedTrades`	number	The swaps of the token. A buy is one where the wallet received it. `unpricedTrades` had no USD price and are left out of the USD figures.
`traders[].bought`, `sold`	string	Token amounts, decimals applied.
`traders[].open`	string	`bought − sold`, at least 0: what the trades leave held. Transfers are not counted, so it can differ from the balance.
`traders[].boughtUsd`, `soldUsd`	number	USD value of the priced buys and sells.
`traders[].avgBuyPriceUsd`, `avgSellPriceUsd`	number \| null	USD per token over the priced buys, and sells. Null without one.
`traders[].priceUsd`, `priceAt`	number \| null	The token's price now, and the start of the hour of the swap it came from, unix ms (see Wallets and PnL).
`traders[].realizedPnlUsd`, `unrealizedPnlUsd`, `totalPnlUsd`	number \| null	See Wallets and PnL. Null is unknown, never 0.
`traders[].firstTradeAt`, `lastTradeAt`	number	Unix ms.
`next`	string \| null	Cursor for the next page. `null` on the last.

Example

Captured 2026-09-28 18:03 UTC on a test instance, trimmed to 2 traders.

curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/tokens/evm:56/0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777/traders?sort=first&limit=2'

{
  "chain": "evm:56",
  "token": {
    "address": "0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777",
    "symbol": "TAX",
    "name": "Tax Token",
    "decimals": 18
  },
  "indexedSince": 1790546261920,
  "sort": "first",
  "window": "all",
  "traders": [
    {
      "wallet": "0x0883bc322b58788f1cce720a8a285db72a4facc4",
      "labels": [
        "insider"
      ],
      "firstBuy": {
        "time": 1790546861920,
        "block": 1000002,
        "tx": "0x4517764dd3b9782c02c5a640714b20335ea2585b394946c4b0f5f44bc1a7bf12"
      },
      "quote": false,
      "trades": 20,
      "buys": 20,
      "sells": 0,
      "unpricedTrades": 0,
      "bought": "5019000",
      "sold": "0",
      "open": "5019000",
      "boughtUsd": 174,
      "soldUsd": 0,
      "avgBuyPriceUsd": 0.0000346682606096832,
      "avgSellPriceUsd": null,
      "priceUsd": 0.006,
      "priceAt": 1790618400000,
      "realizedPnlUsd": 0,
      "unrealizedPnlUsd": null,
      "totalPnlUsd": 0,
      "firstTradeAt": 1790546861920,
      "lastTradeAt": 1790615861920
    },
    {
      "wallet": "0x000000000000000000000000000000000000a00c",
      "labels": [
        "sniper"
      ],
      "firstBuy": {
        "time": 1790546864920,
        "block": 1000003,
        "tx": "0x5221ff9327bd2f842642692502d948d77a28f3b6fcda5992a0f8b3174155f12c"
      },
      "quote": false,
      "trades": 12,
      "buys": 8,
      "sells": 4,
      "unpricedTrades": 0,
      "bought": "2011000",
      "sold": "3920",
      "open": "2007080",
      "boughtUsd": 96,
      "soldUsd": 24,
      "avgBuyPriceUsd": 0.00004773744405768274,
      "avgSellPriceUsd": 0.006122448979591836,
      "priceUsd": 0.006,
      "priceAt": 1790618400000,
      "realizedPnlUsd": 23.81286921929388,
      "unrealizedPnlUsd": 11946.667130780706,
      "totalPnlUsd": 11970.48,
      "firstTradeAt": 1790546864920,
      "lastTradeAt": 1790615861920
    }
  ],
  "next": "2"
}

Notes

With a window, a trader's trade counts, amounts and realized PnL are the window's (its sells against the all-time average buy); the average buy, open and unrealized PnL are all-time. Windows are whole clock hours, the current one included: 24h is the last 24 hours rounded down to the hour.
first ranks by the hour of each wallet's first buy, exactly, then by its first trade in that hour; with a window, only wallets whose first buy falls in it.
Wallets that traded the token, not its holders: one that only received it is not here (token holders). Every swap of the token counts, whether it was the base or the quote.
Cached 15 s. With label, a page examines 500 ranked traders. 404 {"error":"unknown token"} for a token Aurelia has never stored.

Try it in the interactive docs Create a free account