> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobula.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Token Holder Positions > Retrieve Holder positions for a token on a specific blockchain, including holdings, trading activity, and label-based filtering. **Batch Support Available**: This endpoint supports batch queries via POST method for fetching multiple token holder positions in a single request (up to 10 tokens). [Jump to Batch Query section](#post-method-batch-query) ### 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 | locker`. * **`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](https://docs.mobula.io/guides/how-to-track-token-holders-across-ethereum-solana-bnb-base) ### Usage Examples * **Query by Token Address with Blockchain** ```bash theme={null} 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) ```bash theme={null} 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`) ```bash theme={null} 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) ```bash theme={null} # 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`, `locker`). | | `walletMetadata` | `object \| null` | Wallet entity metadata (see below). When `labels` includes `locker`, `entityType` will be `locker` and `entityName` the protocol (e.g. `Streamflow`). | | `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. | | `extra` | `object \| undefined` | Protocol-specific metadata. For lockers: `type`, `startTimestampMs`, `endTimestampMs`, `cliffTimestampMs`, `depositedAmountRaw`, `periodSeconds`, `amountPerPeriodRaw`, `cancelable`. | #### `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 holder positions for multiple tokens in a single request for improved efficiency (up to 10 tokens). ### Request Body ```json theme={null} [ { "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 | locker`. * **`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 ```bash theme={null} # Batch query for two tokens curl -X POST "https://api.mobula.io/api/2/token/holder-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 ```json theme={null} { "payload": [ { "address": "0x68bbed6a47194eff1cf514b50ea91895597fc91e", "blockchain": "ethereum", "data": [ ... ], "totalCount": 150 }, { "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump", "blockchain": "solana", "data": [ ... ], "totalCount": 42 } ] } ``` ## OpenAPI ````yaml get /2/token/holder-positions openapi: 3.0.0 info: version: 1.0.0 title: Mobula API description: >- Documentation of the Mobula API **Demo API**: The default server (demo-api.mobula.io) is a demo API with rate limits. For production use, please use api.mobula.io with an API key from https://admin.mobula.io servers: - url: https://demo-api.mobula.io/api/ description: Demo API (rate limited, for testing only) - url: https://api.mobula.io/api/ description: Production API (requires API key) security: [] tags: - name: V2 - Token description: Token details, price, security, ATH, and holder data - name: V2 - Market Data description: Market details, OHLCV history, and lighthouse metrics - name: V2 - Trades description: Token trades, enriched trades, and trade filters - name: V2 - Wallet description: Wallet positions, activity, trades, analysis, and labels - name: V2 - Assets description: Cross-chain asset details and price history - name: V2 - Swap description: Swap quoting and execution - name: V2 - Perps description: Perpetual futures quoting, execution, and positions - name: V2 - Bridge description: Cross-chain bridge quoting and intent status (Alpha Preview) - name: V2 - DeFi description: Bonding pools and pulse data - name: V2 - Search description: Universal fast search - name: V2 - Blockchains description: System metadata and chain listings - name: V1 - Market Data description: Market prices, history, sparklines, pairs, and multi-data - name: V1 - Wallet description: Wallet portfolio, transactions, history, and NFTs - name: V1 - Token description: First buyers - name: V1 - Trades description: Market trades by pair - name: V1 - Metadata description: Token metadata, categories, trendings, and news - name: V1 - Assets description: List all assets - name: V1 - Search description: Search for assets, tokens, and pairs - name: V1 - DeFi description: Bonding pool pulse data - name: V1 - Blockchains description: Blockchain listings, pairs, and stats - name: V1 - Webhooks description: Webhook management - name: V1 - Feed description: Custom feed creation paths: /2/token/holder-positions: get: tags: - V2 - Token summary: Get Token Holder Positions parameters: - schema: type: string description: Blockchain chain ID (e.g., "evm:56", "solana:solana") required: false description: Blockchain chain ID (e.g., "evm:56", "solana:solana") name: chainId in: query - schema: type: string description: Token contract address required: false description: Token contract address name: address in: query - schema: type: string enum: - sniper - insider - bundler - proTrader - smartTrader - freshTrader - dev - liquidityPool - locker description: Filter by wallet label (e.g. sniper, bundler, insider) required: false description: Filter by wallet label (e.g. sniper, bundler, insider) name: label in: query - schema: type: number nullable: true description: 'Maximum number of results (default: 100)' required: false description: 'Maximum number of results (default: 100)' name: limit in: query - schema: type: number nullable: true description: Offset for pagination required: false description: Offset for pagination name: offset in: query - schema: anyOf: - type: string - type: array items: type: string description: Comma-separated wallet addresses to filter required: false description: Comma-separated wallet addresses to filter name: walletAddresses in: query - schema: anyOf: - type: boolean - type: string description: Use swap recipient mode for accurate Account Abstraction tracking required: true description: Use swap recipient mode for accurate Account Abstraction tracking name: useSwapRecipient in: query - schema: anyOf: - type: boolean - type: string description: Include total fees paid (gas + platform + MEV) and deduct from PnL required: true description: Include total fees paid (gas + platform + MEV) and deduct from PnL name: includeFees in: query responses: '200': description: Token Holder response content: application/json: schema: type: object properties: data: type: array items: type: object properties: chainId: type: string walletAddress: type: string tokenAddress: type: string tokenAmount: type: string tokenAmountRaw: type: string tokenAmountUSD: type: string percentageOfTotalSupply: type: string pnlUSD: type: string realizedPnlUSD: type: string unrealizedPnlUSD: type: string totalPnlUSD: type: string totalFeesPaidUSD: type: string default: '0' buyFeesPaidUSD: type: string default: '0' sellFeesPaidUSD: type: string default: '0' buys: type: number sells: type: number volumeBuyToken: type: string volumeSellToken: type: string volumeBuyUSD: type: string volumeSellUSD: type: string avgBuyPriceUSD: type: string avgSellPriceUSD: type: string nativeBalance: type: string default: '0' nativeBalanceRaw: type: string default: '0' walletFundAt: type: string nullable: true lastActivityAt: type: string nullable: true firstTradeAt: type: string nullable: true lastTradeAt: type: string nullable: true labels: type: array nullable: true items: type: string default: [] walletMetadata: type: object nullable: true properties: entityName: type: string nullable: true entityLogo: type: string nullable: true entityLabels: type: array items: type: string entityType: type: string nullable: true entityDescription: type: string nullable: true entityTwitter: type: string nullable: true entityWebsite: type: string nullable: true entityGithub: type: string nullable: true entityDiscord: type: string nullable: true entityTelegram: type: string nullable: true extra: type: object additionalProperties: nullable: true required: - entityName - entityLogo - entityLabels - entityType - entityDescription - entityTwitter - entityWebsite - entityGithub - entityDiscord - entityTelegram platform: type: object nullable: true properties: id: type: string name: type: string logo: type: string nullable: true required: - id - name - logo fundingInfo: type: object properties: from: type: string nullable: true date: type: string nullable: true chainId: type: string nullable: true txHash: type: string nullable: true amount: type: string nullable: true formattedAmount: type: number nullable: true currency: type: object nullable: true properties: name: type: string symbol: type: string logo: type: string nullable: true decimals: type: number address: type: string required: - name - symbol - logo - decimals - address fromWalletLogo: type: string nullable: true fromWalletTag: type: string nullable: true fromWalletMetadata: type: object nullable: true properties: entityName: type: string nullable: true entityLogo: type: string nullable: true entityLabels: type: array items: type: string entityType: type: string nullable: true entityDescription: type: string nullable: true entityTwitter: type: string nullable: true entityWebsite: type: string nullable: true entityGithub: type: string nullable: true entityDiscord: type: string nullable: true entityTelegram: type: string nullable: true extra: type: object additionalProperties: nullable: true required: - entityName - entityLogo - entityLabels - entityType - entityDescription - entityTwitter - entityWebsite - entityGithub - entityDiscord - entityTelegram required: - from - date - chainId - txHash - amount - formattedAmount - currency - fromWalletLogo - fromWalletTag required: - chainId - walletAddress - tokenAddress - tokenAmount - tokenAmountRaw - tokenAmountUSD - percentageOfTotalSupply - pnlUSD - realizedPnlUSD - unrealizedPnlUSD - totalPnlUSD - buys - sells - volumeBuyToken - volumeSellToken - volumeBuyUSD - volumeSellUSD - avgBuyPriceUSD - avgSellPriceUSD - walletFundAt - lastActivityAt - firstTradeAt - lastTradeAt - fundingInfo totalCount: type: number required: - data - totalCount ````