GET
/
2
/
token
/
holder-positions
Get Token Holder Positions
curl --request GET \
  --url https://explorer-api.mobula.io/api/2/token/holder-positions
{
  "chainId": "<string>",
  "walletAddress": "<string>",
  "tokenAddress": "<string>",
  "tokenAmount": "<string>",
  "tokenAmountRaw": "<string>",
  "pnlUSD": "<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>",
  "labels": []
}

​
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.
  • 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) — Whether to bypass cache and fetch fresh data.

​
Usage Examples

  • Query by Token Address with Blockchain
curl -X GET "https://explorer-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://explorer-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://explorer-api.mobula.io/api/2/token/holder-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).
pnlUSDstringProfit and loss in USD.
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).

Query Parameters

​
blockchain
string
​
address
string
​
force
boolean | null
default:false
​
label
enum<string>
Available options:
sniper,
insider,
bundler,
proTrader,
smartTrader,
freshTrader,
dev
​
limit
number | null
default:100
​
walletAddresses

Response

200 - application/json

Token Holder response

​
chainId
string
required
​
walletAddress
string
required
​
tokenAddress
string
required
​
tokenAmount
string
required
​
tokenAmountRaw
string
required
​
pnlUSD
string
required
​
buys
number
required
​
sells
number
required
​
volumeBuyToken
string
required
​
volumeSellToken
string
required
​
volumeBuyUSD
string
required
​
volumeSellUSD
string
required
​
avgBuyPriceUSD
string
required
​
avgSellPriceUSD
string
required
​
walletFundAt
string | null
required
​
lastActivityAt
string | null
required
​
firstTradeAt
string | null
required
​
lastTradeAt
string | null
required
​
labels
string[] | null