> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Track Top Token Trader Positions Across Ethereum, Solana, BNB, Base & More

> Use the Token Trader Positions endpoint to retrieve the top trader positions for a token on a specific blockchain.

The [**Get Token Trader Positions**](https://docs.mobula.io/rest-api-reference/endpoint/token-trader-positions) endpoint lets you retrieve the top trader positions for a token on a specific blockchain.

This helps you understand who holds the token, how they traded it, and how their PnL evolves across chains like [Solana](https://docs.mobula.io/blockchains/solana), [Ethereum](https://docs.mobula.io/blockchains/ethereum), [BNB Chain](https://docs.mobula.io/blockchains/bsc), [Base](https://docs.mobula.io/blockchains/base), and more.

***

<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
  <iframe src="https://www.youtube.com/embed/FMlYS9FN-zc" title="YouTube video player" style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0 }} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />
</div>

***

## What this endpoint does

With this API, you can:

* Retrieve trader positions for a token on a specific blockchain
* Return holdings, trading activity, and PnL fields per trader wallet
* Filter results by trader label categories and specific wallet addresses
* Control response size with a `limit` parameter
* Optionally bypass cache with `force=true`

***

## What you’ll need

* Basic knowledge of REST APIs
* A token contract address
* A Mobula API key

Note: All Mobula endpoints require an API key.\
Get a free API key: [Here](https://admin.mobula.io/)

Optional:

* DexScreener (to quickly find token addresses)

***

## When to use Token Trader Positions

Use this endpoint when you want to:

* Identify the top wallets holding a token and their share of total supply
* Analyze trader activity like buys, sells, and buy or sell volumes
* Track realized and unrealized PnL per wallet for the token
* Filter results by trader categories like sniper, insider, bundler, smartTrader, or dev
* Pull positions for specific wallets using `walletAddresses`

If you need top holders without PnL breakdown, use: [**Get Token Holders**](https://docs.mobula.io/rest-api-reference/endpoint/market-token-holders)

If you need recent token swap trades, use: [**Get Token Trades**](https://docs.mobula.io/rest-api-reference/endpoint/token-trades)

***

## Walkthrough to Get Token Trader Positions

### 1. Prepare your query

The `token-trader-positions` endpoint requires:

| Parameter    | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `blockchain` | Blockchain identifier (example: `ethereum`, `evm:1`, `solana`) |
| `address`    | Token contract address or mint address                         |

Optional parameters you can use:

* `label`: Filter by trader type (`sniper`, `insider`, `bundler`, `proTrader`, `smartTrader`, `freshTrader`, `freshTrader30d`, `dev`)
* `walletAddresses`: One or multiple wallet addresses (comma-separated or array)
* `limit`: Maximum number of positions returned (default: `100`, max: `1000`)

### 2. Find a token address to test

To retrieve real token data:

* Open DexScreener
* Pick any token
* Copy the token contract address from the token page

This address is used as the `address` parameter.

### 3. Fill the API form

Once your token address is ready:

* Enter the blockchain (example: `solana`)
* Paste the token contract into the `address` field
* (Optional) add trader filters like `label=smartTrader`
* Click **Send** to retrieve the top trader positions

***

## Reviewing the response

Each item represents a trader position for the token:

* `chainId`: Chain identifier for the position (example: `solana:solana`, `evm:1`)
* `walletAddress`: Trader wallet address
* `tokenAddress`: Token contract or mint address
* `tokenAmount` / `tokenAmountRaw`: Token balance in human-readable form and raw integer units
* `tokenAmountUSD`: Estimated USD value of the wallet’s token balance
* `percentageOfTotalSupply`: Share of the token’s total supply held by this wallet
* `realizedPnlUSD`: Realized PnL from sold tokens
* `unrealizedPnlUSD`: Unrealized PnL based on current value minus cost basis
* `totalPnlUSD`: Total PnL combining realized and unrealized
* `buys` / `sells`: Total trade counts for the wallet
* `volumeBuyToken` / `volumeSellToken`: Token-denominated buy and sell volumes
* `volumeBuyUSD` / `volumeSellUSD`: USD-denominated buy and sell volumes
* `avgBuyPriceUSD` / `avgSellPriceUSD`: Average buy and sell prices in USD
* `walletFundAt`: Timestamp when the wallet was first funded
* `firstTradeAt` / `lastTradeAt`: Timestamps for first and most recent recorded trades
* `lastActivityAt`: Timestamp of the most recent activity
* `labels`: Array of trader labels associated with the wallet

***

## Try It Live with Mobula Token Trader Positions Demo (UI)

[Demo UI Homepage](https://mobula-demo-endpoint-production.up.railway.app/)

[Token Trader Positions Demo UI](https://mobula-demo-endpoint-production.up.railway.app/token-trader-positions)

[Docs](https://docs.mobula.io/rest-api-reference/endpoint/token-trader-positions)

***

## Summary

The Get Token Trader Positions endpoint helps you:

* Retrieve top trader positions for a token on a specific blockchain
* Analyze holdings, trade counts, volumes, and realized/unrealized PnL per wallet
* Filter by trader labels or specific wallets
* Visualize results instantly in the demo UI

***

## Try Mobula for Free

Try our free API today and start building in minutes.\
Get your free API key: [Here](https://admin.mobula.io/)