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>",
        "fromWalletMetadata": {
          "entityName": "<string>",
          "entityLogo": "<string>",
          "entityLabels": [
            "<string>"
          ],
          "entityType": "<string>",
          "entityDescription": "<string>",
          "entityTwitter": "<string>",
          "entityWebsite": "<string>",
          "entityGithub": "<string>",
          "entityDiscord": "<string>",
          "entityTelegram": "<string>",
          "extra": {}
        }
      },
      "totalFeesPaidUSD": "0",
      "buyFeesPaidUSD": "0",
      "sellFeesPaidUSD": "0",
      "nativeBalance": "0",
      "nativeBalanceRaw": "0",
      "labels": [],
      "walletMetadata": {
        "entityName": "<string>",
        "entityLogo": "<string>",
        "entityLabels": [
          "<string>"
        ],
        "entityType": "<string>",
        "entityDescription": "<string>",
        "entityTwitter": "<string>",
        "entityWebsite": "<string>",
        "entityGithub": "<string>",
        "entityDiscord": "<string>",
        "entityTelegram": "<string>",
        "extra": {}
      },
      "platform": {
        "id": "<string>",
        "name": "<string>",
        "logo": "<string>"
      }
    }
  ],
  "totalCount": 123
}

GET

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>",
        "fromWalletMetadata": {
          "entityName": "<string>",
          "entityLogo": "<string>",
          "entityLabels": [
            "<string>"
          ],
          "entityType": "<string>",
          "entityDescription": "<string>",
          "entityTwitter": "<string>",
          "entityWebsite": "<string>",
          "entityGithub": "<string>",
          "entityDiscord": "<string>",
          "entityTelegram": "<string>",
          "extra": {}
        }
      },
      "totalFeesPaidUSD": "0",
      "buyFeesPaidUSD": "0",
      "sellFeesPaidUSD": "0",
      "nativeBalance": "0",
      "nativeBalanceRaw": "0",
      "labels": [],
      "walletMetadata": {
        "entityName": "<string>",
        "entityLogo": "<string>",
        "entityLabels": [
          "<string>"
        ],
        "entityType": "<string>",
        "entityDescription": "<string>",
        "entityTwitter": "<string>",
        "entityWebsite": "<string>",
        "entityGithub": "<string>",
        "entityDiscord": "<string>",
        "entityTelegram": "<string>",
        "extra": {}
      },
      "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

Field	Type	Description
`chainId`	`string`	Chain identifier (`solana:solana`, `evm:1`, etc.).
`walletAddress`	`string`	Trader’s wallet address.
`tokenAddress`	`string`	Token contract or mint address.
`tokenAmount`	`string`	Human-readable token balance (with decimals applied).
`tokenAmountRaw`	`string`	Raw token balance (integer, no decimals applied).
`tokenAmountUSD`	`string`	Token balance value in USD (tokenAmount x current price).
`percentageOfTotalSupply`	`string`	Percentage of total supply held by this wallet.
`pnlUSD`	`string`	Realized profit and loss in USD (deprecated, use `realizedPnlUSD`).
`realizedPnlUSD`	`string`	Realized profit and loss in USD (from sold tokens).
`unrealizedPnlUSD`	`string`	Unrealized profit and loss in USD (current value - cost basis).
`totalPnlUSD`	`string`	Total PnL (realized + unrealized).
`buys`	`number`	Total number of buy trades.
`sells`	`number`	Total number of sell trades.
`volumeBuyToken`	`string`	Total buy volume in tokens.
`volumeSellToken`	`string`	Total sell volume in tokens.
`volumeBuyUSD`	`string`	Total buy volume in USD.
`volumeSellUSD`	`string`	Total sell volume in USD.
`avgBuyPriceUSD`	`string`	Average buy price in USD.
`avgSellPriceUSD`	`string`	Average sell price in USD.
`walletFundAt`	`string`	Timestamp when the wallet was first funded.
`lastActivityAt`	`string`	Timestamp of the most recent activity.
`firstTradeAt`	`string`	Timestamp of the first recorded trade.
`lastTradeAt`	`string`	Timestamp of the most recent trade.
`labels`	`string[]`	Array of trader labels (`sniper`, `insider`, `bundler`, `proTrader`, `smartTrader`, `freshTrader`, `dev`, `liquidityPool`).
`walletMetadata`	`object \| null`	Wallet entity metadata (see below).
`platform`	`object \| null`	Platform or DEX used by this wallet (e.g., Axiom, Photon, Raydium).
`fundingInfo`	`object`	Funding source information for this wallet (see below).

`walletMetadata` object

Field	Type	Description
`entityName`	`string \| null`	Name of the entity (e.g., CEX name, project name).
`entityLogo`	`string \| null`	Logo URL of the entity.
`entityLabels`	`string[]`	Labels associated with the entity.
`entityType`	`string \| null`	Type of entity (e.g., `cex`, `fund`, `project`).
`entityDescription`	`string \| null`	Short description of the entity.
`entityTwitter`	`string \| null`	Twitter URL.
`entityWebsite`	`string \| null`	Website URL.
`entityGithub`	`string \| null`	GitHub URL.
`entityDiscord`	`string \| null`	Discord URL.
`entityTelegram`	`string \| null`	Telegram URL.

`platform` object

Field	Type	Description
`id`	`string`	Platform identifier.
`name`	`string`	Platform name (e.g., `Axiom`, `Photon`, `Raydium`).
`logo`	`string \| null`	Platform logo URL.

`fundingInfo` object

Field	Type	Description
`from`	`string \| null`	Address that funded this wallet.
`date`	`string \| null`	Timestamp of the funding transaction.
`chainId`	`string \| null`	Chain where the funding occurred.
`txHash`	`string \| null`	Transaction hash of the funding.
`amount`	`string \| null`	Raw amount of the funding transaction.
`formattedAmount`	`number \| null`	Human-readable amount of the funding.
`currency`	`object \| null`	Currency used for funding (`name`, `symbol`, `logo`, `decimals`, `address`).
`fromWalletLogo`	`string \| null`	Logo of the funding wallet (if known entity).
`fromWalletTag`	`string \| null`	Tag/label of the funding wallet (e.g., `Binance`, `Coinbase`).
`fromWalletMetadata`	`object \| null`	Full entity metadata of the funding wallet (entityName, entityType, entityLogo, entityLabels, socials), if known.

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

chainId

string

Blockchain chain ID (e.g., "evm:56", "solana:solana")

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,

locker

limit

number | null

Maximum number of results (default: 100)

offset

number | null

Offset for pagination

walletAddresses

Comma-separated wallet addresses to filter

useSwapRecipient

required

Use swap recipient mode for accurate Account Abstraction tracking

includeFees

required

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

Response

200 - application/json

Top Token Trader response

data

object[]

required

Show child attributes

totalCount

number

required

Get Pair Trades Get Token Holder Positions

⌘I

Documentation Index

​Query Details

​Query Parameters

​Step-by-Step Tutorial and Video Walkthrough

​Usage Examples

​Query Response Fields

​walletMetadata object

​platform object

​fundingInfo object

​POST Method - Batch Query

​Request Body

​Body Parameters

​Usage Examples

​Response Format

Query Parameters

Response

Query Details

Query Parameters

Step-by-Step Tutorial and Video Walkthrough

Usage Examples

Query Response Fields

`walletMetadata` object

`platform` object

`fundingInfo` object

POST Method - Batch Query

Request Body

Body Parameters

Usage Examples

Response Format