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>"
      },
      "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
}

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>"
      },
      "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
}

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`).

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

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

Introduction

Market & Token Data

History - Prices & OHLCV Candles

Trades Data

Holders Data

Pulse API

Wallet APIs

Metacore

Webhook

Misc

Get Top Token Trader Positions

Query Details

Query Parameters

Step-by-Step Tutorial and Video Walkthrough

Usage Examples

Query Response Fields

`walletMetadata` object

`platform` object

`fundingInfo` object

Query Parameters

Response

Introduction

Market & Token Data

History - Prices & OHLCV Candles

Trades Data

Holders Data

Pulse API

Wallet APIs

Metacore

Webhook

Misc

​Query Details

​Query Parameters

​Step-by-Step Tutorial and Video Walkthrough

​Usage Examples

​Query Response Fields

​walletMetadata object

​platform object

​fundingInfo object

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