Skip to main content
The Get 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, Ethereum, BNB Chain, Base, and more.

​
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 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 If you need recent token swap trades, use: Get Token Trades

​
Walkthrough to Get Token Trader Positions

​
1. Prepare your query

The token-trader-positions endpoint requires:
ParameterDescription
blockchainBlockchain identifier (example: ethereum, evm:1, solana)
addressToken contract address or mint address
Optional parameters you can use:
  • label: Filter by trader type (sniper, insider, bundler, proTrader, smartTrader, freshTrader, 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 Token Trader Positions Demo UI Docs

​
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