Get Token Holder Positions

curl --request GET \
  --url https://demo-api.mobula.io/api/2/token/holder-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

holder-positions

Get Token Holder Positions

curl --request GET \
  --url https://demo-api.mobula.io/api/2/token/holder-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 refine results by filtering with walletAddresses (for specific traders) or label (for trader type categories). The force parameter allows bypassing cached data to fetch the most recent results. Combine these parameters as needed to tailor 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.
offset (optional, default: 0) — Number of positions to skip for pagination.
force (optional, default: false) — Whether to bypass cache and fetch fresh data.

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/holder-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/holder-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/holder-positions?limit=2&address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum&label=bundler"

Query with Pagination (Infinite Scroll)

# First page
curl -X GET "https://demo-api.mobula.io/api/2/token/holder-positions?address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum&limit=20&offset=0"
# Second page
curl -X GET "https://demo-api.mobula.io/api/2/token/holder-positions?address=0x68bbed6a47194eff1cf514b50ea91895597fc91e&blockchain=ethereum&limit=20&offset=20"

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

Token Holder response

data

object[]

required

Show child attributes

totalCount

number

required

Get Top Token Trader Positions Get Pulse - GET Method

⌘I

Introduction

Market & Token Data

History - Prices & OHLCV Candles

Trades Data

Holders Data

Pulse API

Wallet APIs

Metacore

Webhook

Misc

Get Token Holder 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