Skip to main content
GET
/
2
/
token
/
trader-positions
Get Top Token Trader Positions
curl --request GET \
  --url https://demo-api.mobula.io/api/2/token/trader-positions
{
  "data": [
    {
      "chainId": "<string>",
      "walletAddress": "<string>",
      "tokenAddress": "<string>",
      "tokenAmount": "<string>",
      "tokenAmountRaw": "<string>",
      "tokenAmountUSD": "<string>",
      "percentageOfTotalSupply": "<string>",
      "pnlUSD": "<string>",
      "realizedPnlUSD": "<string>",
      "unrealizedPnlUSD": "<string>",
      "totalPnlUSD": "<string>",
      "buys": 123,
      "sells": 123,
      "volumeBuyToken": "<string>",
      "volumeSellToken": "<string>",
      "volumeBuyUSD": "<string>",
      "volumeSellUSD": "<string>",
      "avgBuyPriceUSD": "<string>",
      "avgSellPriceUSD": "<string>",
      "walletFundAt": "<string>",
      "lastActivityAt": "<string>",
      "firstTradeAt": "<string>",
      "lastTradeAt": "<string>",
      "fundingInfo": {
        "from": "<string>",
        "date": "<string>",
        "chainId": "<string>",
        "txHash": "<string>",
        "amount": "<string>",
        "formattedAmount": 123,
        "currency": {
          "name": "<string>",
          "symbol": "<string>",
          "logo": "<string>",
          "decimals": 123,
          "address": "<string>"
        },
        "fromWalletLogo": "<string>",
        "fromWalletTag": "<string>"
      },
      "totalFeesPaidUSD": "<string>",
      "labels": [],
      "walletMetadata": {
        "entityName": "<string>",
        "entityLogo": "<string>",
        "entityLabels": [
          "<string>"
        ],
        "entityType": "<string>",
        "entityDescription": "<string>",
        "entityTwitter": "<string>",
        "entityWebsite": "<string>",
        "entityGithub": "<string>",
        "entityDiscord": "<string>",
        "entityTelegram": "<string>"
      },
      "platform": {
        "id": "<string>",
        "name": "<string>",
        "logo": "<string>"
      }
    }
  ],
  "totalCount": 123
}
Batch Support Available: This endpoint supports batch queries via POST method for fetching multiple token trader positions in a single request (up to 10 tokens). Jump to Batch Query section

​
Query Details

This endpoint requires both the blockchain and address parameters. You can further refine results using walletAddresses (specific traders) or label (trader categories). The force parameter allows bypassing cached data to fetch the most recent information. Combine parameters as needed to customize your query.

​
Query Parameters

  • blockchain (required) — Blockchain identifier (e.g., ethereum, evm:1, solana).
  • address (required) — Token contract address or mint address.
  • label (optional) — Filter by trader type: sniper | insider | bundler | proTrader | smartTrader | freshTrader | dev | liquidityPool.
  • walletAddresses (optional) — One or multiple wallet addresses (comma-separated or array).
  • limit (optional, default: 100, max: 1000) — Maximum number of positions returned.
  • force (optional, default: false) — Fetch fresh data by bypassing the cache.

​
Step-by-Step Tutorial and Video Walkthrough

  • Check out the guide: Here

​
Usage Examples

  • Query by Token Address with Blockchain
curl -X GET "https://demo-api.mobula.io/api/2/token/trader-positions?address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum"
  • Query by Token Address with Specific Wallets (comma-separated)
curl -X GET "https://demo-api.mobula.io/api/2/token/trader-positions?limit=2&address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum&walletAddresses=0xad6dc16e2b447d3941a531ae70b1e179df7ed17e,0xa12e1462d0ced572f396f58b6e2d03894cd7c8a4"
  • Query by Token Address with Label (bundler)
curl -X GET "https://demo-api.mobula.io/api/2/token/trader-positions?limit=2&address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum&label=bundler"

​
Query Response Fields

FieldTypeDescription
chainIdstringChain identifier (solana:solana, evm:1, etc.).
walletAddressstringTrader’s wallet address.
tokenAddressstringToken contract or mint address.
tokenAmountstringHuman-readable token balance (with decimals applied).
tokenAmountRawstringRaw token balance (integer, no decimals applied).
tokenAmountUSDstringToken balance value in USD (tokenAmount x current price).
percentageOfTotalSupplystringPercentage of total supply held by this wallet.
pnlUSDstringRealized profit and loss in USD (deprecated, use realizedPnlUSD).
realizedPnlUSDstringRealized profit and loss in USD (from sold tokens).
unrealizedPnlUSDstringUnrealized profit and loss in USD (current value - cost basis).
totalPnlUSDstringTotal PnL (realized + unrealized).
buysnumberTotal number of buy trades.
sellsnumberTotal number of sell trades.
volumeBuyTokenstringTotal buy volume in tokens.
volumeSellTokenstringTotal sell volume in tokens.
volumeBuyUSDstringTotal buy volume in USD.
volumeSellUSDstringTotal sell volume in USD.
avgBuyPriceUSDstringAverage buy price in USD.
avgSellPriceUSDstringAverage sell price in USD.
walletFundAtstringTimestamp when the wallet was first funded.
lastActivityAtstringTimestamp of the most recent activity.
firstTradeAtstringTimestamp of the first recorded trade.
lastTradeAtstringTimestamp of the most recent trade.
labelsstring[]Array of trader labels (sniper, insider, bundler, proTrader, smartTrader, freshTrader, dev, liquidityPool).
walletMetadataobject | nullWallet entity metadata (see below).
platformobject | nullPlatform or DEX used by this wallet (e.g., Axiom, Photon, Raydium).
fundingInfoobjectFunding source information for this wallet (see below).

​
walletMetadata object

FieldTypeDescription
entityNamestring | nullName of the entity (e.g., CEX name, project name).
entityLogostring | nullLogo URL of the entity.
entityLabelsstring[]Labels associated with the entity.
entityTypestring | nullType of entity (e.g., cex, fund, project).
entityDescriptionstring | nullShort description of the entity.
entityTwitterstring | nullTwitter URL.
entityWebsitestring | nullWebsite URL.
entityGithubstring | nullGitHub URL.
entityDiscordstring | nullDiscord URL.
entityTelegramstring | nullTelegram URL.

​
platform object

FieldTypeDescription
idstringPlatform identifier.
namestringPlatform name (e.g., Axiom, Photon, Raydium).
logostring | nullPlatform logo URL.

​
fundingInfo object

FieldTypeDescription
fromstring | nullAddress that funded this wallet.
datestring | nullTimestamp of the funding transaction.
chainIdstring | nullChain where the funding occurred.
txHashstring | nullTransaction hash of the funding.
amountstring | nullRaw amount of the funding transaction.
formattedAmountnumber | nullHuman-readable amount of the funding.
currencyobject | nullCurrency used for funding (name, symbol, logo, decimals, address).
fromWalletLogostring | nullLogo of the funding wallet (if known entity).
fromWalletTagstring | nullTag/label of the funding wallet (e.g., Binance, Coinbase).

​
POST Method - Batch Query

Retrieve trader positions for multiple tokens in a single request for improved efficiency (up to 10 tokens).

​
Request Body

[
  {
    "blockchain": "ethereum",
    "address": "0x68bbed6a47194eff1cf514b50ea91895597fc91e",
    "limit": 10
  },
  {
    "blockchain": "solana",
    "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
    "limit": 5,
    "label": "sniper"
  }
]

​
Body Parameters

The request body is an array of query objects (max 10), where each object contains:
  • blockchain (optional) — Blockchain identifier (e.g., ethereum, evm:1, solana).
  • address (optional) — Token contract address or mint address.
  • label (optional) — Filter by trader type: sniper | insider | bundler | proTrader | smartTrader | freshTrader | dev | liquidityPool.
  • walletAddresses (optional) — One or multiple wallet addresses (comma-separated or array).
  • limit (optional, default: 100) — Maximum number of positions returned.
  • offset (optional, default: 0) — Offset for pagination.
  • useSwapRecipient (optional, default: true) — Use swap recipient mode for accurate Account Abstraction tracking.
  • includeFees (optional, default: false) — Include total fees paid (gas + platform + MEV) and deduct from PnL.

​
Usage Examples

# Batch query for two tokens
curl -X POST "https://api.mobula.io/api/2/token/trader-positions" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '[
    {
      "blockchain": "ethereum",
      "address": "0x68bbed6a47194eff1cf514b50ea91895597fc91e",
      "limit": 10
    },
    {
      "blockchain": "solana",
      "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
      "limit": 5
    }
  ]'

​
Response Format

{
  "payload": [
    {
      "address": "0x68bbed6a47194eff1cf514b50ea91895597fc91e",
      "blockchain": "ethereum",
      "data": [ ... ],
      "totalCount": 150
    },
    {
      "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
      "blockchain": "solana",
      "data": [ ... ],
      "totalCount": 42
    }
  ]
}

Query Parameters

​
blockchain
string

Blockchain name or chain ID

​
address
string

Token contract address

​
label
enum<string>

Filter by wallet label (e.g. sniper, bundler, insider)

Available options:
sniper,
insider,
bundler,
proTrader,
smartTrader,
freshTrader,
dev,
liquidityPool
​
limit
number | null

Maximum number of results (default: 100)

​
offset
number | null

Offset for pagination

​
walletAddresses

Comma-separated wallet addresses to filter

​
useSwapRecipient
boolean | null

Use swap recipient mode for accurate Account Abstraction tracking

​
includeFees
boolean | null

Include total fees paid (gas + platform + MEV) and deduct from PnL

Response

200 - application/json

Top Token Trader response

​
data
object[]
required
​
totalCount
number
required