Token - Top traders

curl --request GET \
  --url https://public-api.birdeye.so/defi/v2/tokens/top_traders \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://public-api.birdeye.so/defi/v2/tokens/top_traders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "items": [
      {
        "tokenAddress": "3xF8fgj5maAgFwprsEs26bJNmaPDS24zT1VTtELspump",
        "owner": "CEikLmYN9dcDtHZC9qfwPpaUcLm3CNWMrR55Ub5mRyUn",
        "tags": [
          "fresh",
          "bundler",
          "sniper"
        ],
        "type": "24h",
        "trade": 27,
        "tradeBuy": 1,
        "tradeSell": 26,
        "volume": 696438428.401387,
        "volumeBuy": 427829917.472286,
        "volumeSell": 268608510.92910105,
        "volumeUsd": 6260.822052904342,
        "volumeBuyUSD": 1551.8066478152505,
        "volumeSellUSD": 4709.0154050890915,
        "totalPnl": 3438.2253375103355,
        "unrealizedPnl": -296.5045959543089,
        "realizedPnl": 3734.7299334646445,
        "holdVolume": 0,
        "holdVolumeUsd": 0,
        "holdAvgPrice": 0.0000036271578597954727,
        "avgBuyPrice": 0.0000036271578597954727,
        "avgSellPrice": 0.000017531147426419527,
        "firstTradeUnixTime": 1784802145,
        "lastTradeUnixTime": 1784802524,
        "netWorth": 0,
        "solBalance": 0,
        "funding": {
          "funder": "7iVfPjXEMnuGQkaYbxmvi4BRnzpS6dthWwNQB32D61nz",
          "unixTime": 1784802145,
          "amount": 21.372,
          "txHash": "61oxPM8LXQ9wCurgLxzdqxv516rZPtrnxtGXdLnVCLuhYkRyW5nHwEr7Wzzi5YHaZzCGzRNiCs7egH7kCQQyPTDQ"
        },
        "isScaledUiToken": false,
        "multiplier": null
      }
    ]
  }
}

GET

defi

tokens

top_traders

Token - Top traders

curl --request GET \
  --url https://public-api.birdeye.so/defi/v2/tokens/top_traders \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://public-api.birdeye.so/defi/v2/tokens/top_traders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "items": [
      {
        "tokenAddress": "3xF8fgj5maAgFwprsEs26bJNmaPDS24zT1VTtELspump",
        "owner": "CEikLmYN9dcDtHZC9qfwPpaUcLm3CNWMrR55Ub5mRyUn",
        "tags": [
          "fresh",
          "bundler",
          "sniper"
        ],
        "type": "24h",
        "trade": 27,
        "tradeBuy": 1,
        "tradeSell": 26,
        "volume": 696438428.401387,
        "volumeBuy": 427829917.472286,
        "volumeSell": 268608510.92910105,
        "volumeUsd": 6260.822052904342,
        "volumeBuyUSD": 1551.8066478152505,
        "volumeSellUSD": 4709.0154050890915,
        "totalPnl": 3438.2253375103355,
        "unrealizedPnl": -296.5045959543089,
        "realizedPnl": 3734.7299334646445,
        "holdVolume": 0,
        "holdVolumeUsd": 0,
        "holdAvgPrice": 0.0000036271578597954727,
        "avgBuyPrice": 0.0000036271578597954727,
        "avgSellPrice": 0.000017531147426419527,
        "firstTradeUnixTime": 1784802145,
        "lastTradeUnixTime": 1784802524,
        "netWorth": 0,
        "solBalance": 0,
        "funding": {
          "funder": "7iVfPjXEMnuGQkaYbxmvi4BRnzpS6dthWwNQB32D61nz",
          "unixTime": 1784802145,
          "amount": 21.372,
          "txHash": "61oxPM8LXQ9wCurgLxzdqxv516rZPtrnxtGXdLnVCLuhYkRyW5nHwEr7Wzzi5YHaZzCGzRNiCs7egH7kCQQyPTDQ"
        },
        "isScaledUiToken": false,
        "multiplier": null
      }
    ]
  }
}

Usage Note
Accessibility
Chain Supported

Top traders ranks wallets by token trading impact and, on Solana, adds holder stats context.

Use sort_by=volume or sort_by=trade for activity leaders.
Use sort_by=total_pnl, realized_pnl, unrealized_pnl, or volume_usd for PnL and USD-volume views on supported chains.
On Solana, use sort_by=hold_volume to rank traders by the amount they still hold.
Use the optional min/max filters to narrow traders by trade count, token volume, USD volume, realized PnL, or unrealized PnL on both Solana and EVM-supported requests.
min_trade and max_trade must be non-negative integers. min_volume, max_volume, min_volume_usd, and max_volume_usd must be non-negative. PnL filters support both positive and negative values.
min_trade, max_trade, min_volume, max_volume, min_volume_usd, max_volume_usd, min_realized_pnl, max_realized_pnl, min_unrealized_pnl, and max_unrealized_pnl are not supported when sort_by=hold_volume.
On Solana, wallet_tags filters the result by wallet cohort. Supported values are dev, bundler, sniper, insider, and smart_trader.
On Solana, get_holders_networth=true adds netWorth, solBalance, and funding to each trader item. This enriches holder stats but may make the response slightly slower.

Compatibility note. This release keeps existing response fields, sorting behavior, pagination, and response shape unchanged. The new filters are additive and optional.

Reading the numbers. tradeBuy and tradeSell count buy and sell transactions. volumeBuy and volumeSell are token amounts; volumeBuyUSD, volumeSellUSD, and volumeUsd are USD values. holdVolume, holdVolumeUsd, and holdAvgPrice describe the current remaining holder position. avgBuyPrice and avgSellPrice summarize historical trade prices. firstTradeUnixTime and lastTradeUnixTime are Unix timestamps in seconds.

Wallet Tag Definitions 🏷️

dev — The wallet that created the token, based on the mint creator / initialize-mint transaction.
sniper — A wallet that bought within the first n blocks of the token, counted from the token’s first swap. On Solana, n = 5; a buy qualifies when its slot is within first_trade_slot + 5.
bundler — Coordinated buying detected at either level: Level 1 means at least 4 buy transactions in the same slot; Level 2 means at least 3 distinct wallets buying across adjacent slots where the max slot gap is 1.
insider — A wallet that received the token directly from the Chef wallet through a token transfer, not through a swap.
smart_trader — A non-bot wallet ranked in Top Realized PnL over the last 90 days with realized PnL greater than $10,000. Wallets identified as bots are excluded before ranking and never receive this tag.

Compute Unit ⚙️

This endpoint consumes 25 CU per request.

Use Cases 💡

Find the wallets that drove most token volume, trade count, or PnL during a launch or trading window.
Identify whether top traders are still holding, accumulating, or selling by comparing holdVolume against buy/sell activity.
Screen for high-conviction trader cohorts by requiring minimum trade count, token volume, USD volume, or profit thresholds.
Filter Solana results by wallet cohort to inspect developers, bundlers, snipers, insiders, or smart traders separately.
Use get_holders_networth=true to enrich wallet research with net worth, SOL balance, and funding source context.
Build token research dashboards that combine trader ranking, wallet tags, holder position stats, and PnL.

How to Use 🛠️

Provide a token address and choose x-chain.
Pick time_frame based on the analysis window. Solana additionally supports all_time.
Pick sort_by: use volume, trade, total_pnl, realized_pnl, unrealized_pnl, volume_usd, or Solana-only hold_volume.
Add any of min_trade, max_trade, min_volume, max_volume, min_volume_usd, max_volume_usd, min_realized_pnl, max_realized_pnl, min_unrealized_pnl, or max_unrealized_pnl when you want threshold-based filtering.
Do not combine those min/max filters with sort_by=hold_volume.
On Solana, pass wallet_tags=dev,sniper,smart_trader to filter by wallet cohorts.
On Solana, set get_holders_networth=true when you need net worth, SOL balance, and funding details.
Use offset and limit to page through ranked traders.

Best Practices ✅

Start with sort_by=volume or trade to find active wallets, then switch to PnL or holder fields to understand outcomes.
Use min/max filters to turn this endpoint into a trader screener, not just a leaderboard.
Use hold_volume on Solana to separate traders who exited from traders still exposed to the token.
Compare realizedPnl and unrealizedPnl with holdVolumeUsd to distinguish realized profit from open exposure.
Use wallet tag filters to reduce noise when investigating launch behavior or suspicious cohorts.
Enable get_holders_networth only when holder net worth and funding context are needed, because it may add latency.

Limitations ⚠️

all_time, hold_volume, wallet_tags, holder position stats, and get_holders_networth are Solana-only additions.
Non-Solana chains keep their existing supported intervals, sort fields, parameters, and response behavior.
Min/max trade, volume, USD-volume, realized-PnL, and unrealized-PnL filters are not supported with sort_by=hold_volume.
wallet_tags accepts dev, bundler, sniper, insider, and smart_trader.
get_holders_networth=true may return netWorth or solBalance as 0 when holder net worth data is unavailable.
Results are paginated with offset and limit.

Authorizations

X-API-KEY

string

header

required

API key for authentication

Headers

x-chain

enum<string>

default:solana

A chain name listed in supported networks.

Available options:

solana,

ethereum,

bsc,

base,

robinhood,

sui,

mantle,

hyperevm,

arbitrum,

avalanche,

optimism,

polygon,

zksync,

monad,

aptos,

fogo,

megaeth

Query Parameters

address

string

required

The address of the token contract.

time_frame

enum<string>

default:24h

required

Available options:

30m,

1h,

2h,

4h,

6h,

8h,

12h,

24h,

2d,

3d,

7d,

14d,

30d,

60d,

90d,

all_time

sort_type

enum<string>

default:desc

required

Specify the sort order.

Available options:

desc,

asc

sort_by

enum<string>

default:volume

required

Specify the sort field.

Available options:

volume,

trade,

total_pnl,

unrealized_pnl,

realized_pnl,

volume_usd,

hold_volume

offset

integer

default:0

Pagination start position. offset + limit <= 10000

Required range: 0 <= x <= 10000

limit

integer

default:10

Number of items per page.

Required range: 1 <= x <= 10

ui_amount_mode

enum<string>

default:scaled

Indicate whether to use the scaled amount for scaled ui amount tokens. Only support solana

Available options:

raw,

scaled

wallet_tags

enum<string>[]

Filter Solana traders by wallet tags. Supports comma-separated values.

Available options:

dev,

bundler,

sniper,

insider,

smart_trader

get_holders_networth

boolean

default:false

Solana only. When true, the response includes netWorth, solBalance, and funding for each trader. This may make the response slightly slower than when disabled.

min_trade

number

Filter top traders with trade count greater than or equal to this value. Not supported when sort_by=hold_volume.

max_trade

number

Filter top traders with trade count less than or equal to this value. Not supported when sort_by=hold_volume.

min_volume

number

Filter top traders with token volume greater than or equal to this value. On Solana with ui_amount_mode=scaled, this value uses scaled UI amount. Not supported when sort_by=hold_volume.

max_volume

number

Filter top traders with token volume less than or equal to this value. On Solana with ui_amount_mode=scaled, this value uses scaled UI amount. Not supported when sort_by=hold_volume.

min_volume_usd

number

Filter top traders with USD volume greater than or equal to this value. Not supported when sort_by=hold_volume.

max_volume_usd

number

Filter top traders with USD volume less than or equal to this value. Not supported when sort_by=hold_volume.

min_realized_pnl

number

Filter top traders with realized PnL greater than or equal to this value. Not supported when sort_by=hold_volume.

max_realized_pnl

number

Filter top traders with realized PnL less than or equal to this value. Not supported when sort_by=hold_volume.

min_unrealized_pnl

number

Filter top traders with unrealized PnL greater than or equal to this value. Not supported when sort_by=hold_volume.

max_unrealized_pnl

number

Filter top traders with unrealized PnL less than or equal to this value. Not supported when sort_by=hold_volume.

Response

JSON object containing a list of top traded tokens

Response containing a ranked list of top traders for a token.

success

boolean

required

Indicates whether the request was successful.

data

object

required

Top-trader ranking result.

Show child attributes