> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serialized.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Token Top Traders
> 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 dev/sniper/pro-trader badges. Lifetime by default, or any rolling window (1h → 30d).
`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 dev/sniper/pro-trader badges. Lifetime by default, or any rolling window (`1h` → `30d`). EVM and Solana, one shape.
`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: the EVM native coin (`0x0000…0000`), which has no market of its own, returns `400` `INVALID_PARAM` (its markets are listed by [`/v1/token/pools`](/endpoints/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. On Solana (`usdBasis` `trade`), `boughtUsd`, `soldUsd` and the realized PnL are valued at the SOL price at the time of each trade; on EVM chains (`usdBasis` `spot`), native amounts are converted at the current native price. `meta.traderCount` is the number of wallets that ever traded the token (lifetime) or the number of distinct wallets in the window.
```bash cURL theme={null}
curl 'https://api.serialized.xyz/v1/token/top-traders?chain=evm:8453&address=0x3c5cd672b204ba0fc48e93b98c0922920a87912d&limit=3' \
-H 'Authorization: YOUR_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"rank": 1,
"address": "0x16380ab7951906dd53ca6095d51f091ef2614127",
"buys": 42,
"sells": 18,
"boughtTokens": "184320551.884",
"soldTokens": "151002317.9",
"boughtNative": 6.421889,
"soldNative": 11.038742,
"boughtUsd": 12073.15,
"soldUsd": 20752.83,
"openTokens": "33318233.984",
"positionValueNative": 1.532638,
"positionValueUsd": 2881.36,
"unrealizedPnlNative": 0.373139,
"unrealizedPnlUsd": 701.5,
"totalPnlNative": 4.989992,
"totalPnlUsd": 9380.81,
"realizedPnlNative": 4.616853,
"realizedPnlUsd": 8679.31,
"avgBuyPriceNative": 0.0000000348,
"winRatePct": 71.42857142857143,
"isDev": false,
"isSniper": true,
"isProTrader": true,
"firstTradeAt": 1785903211000,
"lastTradeAt": 1786901550000
},
{
"rank": 2,
"address": "0x82d4cd9bf16017fd518511d8bbe6d0493af31a10",
"buys": 9,
"sells": 7,
"boughtTokens": "52140339.11",
"soldTokens": "52140339.11",
"boughtNative": 1.884201,
"soldNative": 3.201778,
"boughtUsd": 3542.3,
"soldUsd": 6019.34,
"openTokens": "0",
"positionValueNative": 0,
"positionValueUsd": 0,
"unrealizedPnlNative": 0,
"unrealizedPnlUsd": 0,
"totalPnlNative": 1.317577,
"totalPnlUsd": 2477.02,
"realizedPnlNative": 1.317577,
"realizedPnlUsd": 2477.02,
"avgBuyPriceNative": 0.0000000361,
"winRatePct": 85.71428571428571,
"isDev": false,
"isSniper": false,
"isProTrader": null,
"firstTradeAt": 1786010044000,
"lastTradeAt": 1786877301000
}
],
"meta": {
"asOf": 1786901933078,
"usdBasis": "spot",
"sortBy": "pnl",
"order": "desc",
"timeframe": "all",
"traderCount": 18422
}
}
```
## OpenAPI
````yaml openapi.json GET /v1/token/top-traders
openapi: 3.1.0
info:
title: Serialized Data API
description: >-
On-chain data for trading apps - tokens, candles, token filters. Built on
our own indexers. 18 EVM chains + Solana, live.
version: 0.1.0
servers:
- url: https://demo.serialized.xyz
description: 'Demo: no key needed, read endpoints, rate-limited per IP'
- url: https://api.serialized.xyz
description: 'Production: your API key in the Authorization header'
security:
- apiKey: []
- {}
paths:
/v1/token/top-traders:
get:
summary: Token Top Traders
description: >-
Ranked traders of a token, from our own PnL fold (per wallet and token):
realized PnL in native and USD, tokens bought/sold, open position,
average entry, win rate over closed positions, first/last trade.
Lifetime by default (`timeframe=all`), or any rolling window from `1h`
to `30d`. Default sort is `pnl` on both families; `sortBy` accepts
`pnl`, `bought`, `sold` or `txns`.
operationId: token-top-traders
parameters:
- schema:
type: string
x-default: evm:8453
in: query
name: chain
required: true
description: Public chain id - `evm:` or `solana`.
example: evm:8453
- schema:
type: string
in: query
name: address
required: true
description: Token address.
- schema:
default: all
anyOf:
- type: string
enum:
- all
- type: string
enum:
- 1h
- type: string
enum:
- 4h
- type: string
enum:
- 1d
- type: string
enum:
- 7d
- type: string
enum:
- 30d
x-default: all
in: query
name: timeframe
required: false
description: >-
`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`.
example: all
- schema:
anyOf:
- type: string
enum:
- pnl
- type: string
enum:
- bought
- type: string
enum:
- sold
- type: string
enum:
- txns
in: query
name: sortBy
required: false
description: '`pnl` (default), `bought`, `sold` or `txns`.'
- schema:
anyOf:
- type: string
enum:
- asc
- type: string
enum:
- desc
in: query
name: order
required: false
description: '`desc` (default) or `asc`.'
- schema:
minimum: 1
maximum: 100
default: 20
type: integer
x-default: 20
in: query
name: limit
required: false
description: 1-100. Default 20.
example: 20
responses:
'200':
description: Standard `{ data, meta }` envelope.
components:
securitySchemes:
apiKey:
type: apiKey
name: Authorization
in: header
description: Your raw API key (not needed on the demo server).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.