Skip to main content
GET
/
2
/
wallet
/
positions
Get Wallet Positions
curl --request GET \
  --url https://demo-api.mobula.io/api/2/wallet/positions
{
  "data": [
    {
      "token": {
        "address": "<string>",
        "chainId": "<string>",
        "symbol": "<string>",
        "name": "<string>",
        "priceTokenString": "<string>",
        "approximateReserveTokenRaw": "<string>",
        "logo": "<string>",
        "bondedAt": "<string>",
        "createdAt": "<string>",
        "latestTradeDate": "<string>",
        "description": "<string>",
        "socials": {
          "twitter": "<string>",
          "website": "<string>",
          "telegram": "<string>",
          "others": {},
          "uri": "<string>"
        },
        "security": {
          "buyTax": "<string>",
          "sellTax": "<string>",
          "transferPausable": true,
          "top10Holders": "<string>",
          "isBlacklisted": true,
          "noMintAuthority": true,
          "balanceMutable": true,
          "lowLiquidity": "<string>",
          "burnRate": "<string>",
          "liquidityBurnPercentage": 123,
          "isHoneypot": true,
          "isNotOpenSource": true,
          "renounced": true,
          "locked": "<string>",
          "isWhitelisted": true,
          "isMintable": true,
          "modifyableTax": true,
          "selfDestruct": true
        },
        "liveStatus": "<string>",
        "liveThumbnail": "<string>",
        "livestreamTitle": "<string>",
        "liveReplyCount": 123,
        "decimals": 0,
        "id": null,
        "priceUSD": 0,
        "priceToken": 0,
        "approximateReserveUSD": 0,
        "approximateReserveToken": 0,
        "totalSupply": 0,
        "circulatingSupply": 0,
        "marketCapUSD": 0,
        "marketCapDilutedUSD": 0,
        "originLogoUrl": "<string>",
        "rank": null,
        "cexs": [],
        "exchange": {
          "name": "<string>",
          "logo": "<string>"
        },
        "factory": "<string>",
        "source": "<string>",
        "sourceFactory": "<string>",
        "liquidityUSD": 123,
        "liquidityMaxUSD": 123,
        "bonded": true,
        "bondingPercentage": 123,
        "bondingCurveAddress": "<string>",
        "preBondingFactory": "<string>",
        "poolAddress": "<string>",
        "blockchain": "<string>",
        "type": "<string>",
        "tokenType": "2020",
        "deployer": "<string>",
        "athUSD": 123,
        "atlUSD": 123,
        "athDate": "<string>",
        "atlDate": "<string>",
        "priceChange1minPercentage": 0,
        "priceChange5minPercentage": 0,
        "priceChange1hPercentage": 0,
        "priceChange4hPercentage": 0,
        "priceChange6hPercentage": 0,
        "priceChange12hPercentage": 0,
        "priceChange24hPercentage": 0,
        "volume1minUSD": 0,
        "volume5minUSD": 0,
        "volume15minUSD": 0,
        "volume1hUSD": 0,
        "volume4hUSD": 0,
        "volume6hUSD": 0,
        "volume12hUSD": 0,
        "volume24hUSD": 0,
        "volumeBuy1minUSD": 0,
        "volumeBuy5minUSD": 0,
        "volumeBuy15minUSD": 0,
        "volumeBuy1hUSD": 0,
        "volumeBuy4hUSD": 0,
        "volumeBuy6hUSD": 0,
        "volumeBuy12hUSD": 0,
        "volumeBuy24hUSD": 0,
        "volumeSell1minUSD": 0,
        "volumeSell5minUSD": 0,
        "volumeSell15minUSD": 0,
        "volumeSell1hUSD": 0,
        "volumeSell4hUSD": 0,
        "volumeSell6hUSD": 0,
        "volumeSell12hUSD": 0,
        "volumeSell24hUSD": 0,
        "trades1min": 0,
        "trades5min": 0,
        "trades15min": 0,
        "trades1h": 0,
        "trades4h": 0,
        "trades6h": 0,
        "trades12h": 0,
        "trades24h": 0,
        "buys1min": 0,
        "buys5min": 0,
        "buys15min": 0,
        "buys1h": 0,
        "buys4h": 0,
        "buys6h": 0,
        "buys12h": 0,
        "buys24h": 0,
        "sells1min": 0,
        "sells5min": 0,
        "sells15min": 0,
        "sells1h": 0,
        "sells4h": 0,
        "sells6h": 0,
        "sells12h": 0,
        "sells24h": 0,
        "buyers1min": 0,
        "buyers5min": 0,
        "buyers15min": 0,
        "buyers1h": 0,
        "buyers4h": 0,
        "buyers6h": 0,
        "buyers12h": 0,
        "buyers24h": 0,
        "sellers1min": 0,
        "sellers5min": 0,
        "sellers15min": 0,
        "sellers1h": 0,
        "sellers4h": 0,
        "sellers6h": 0,
        "sellers12h": 0,
        "sellers24h": 0,
        "traders1min": 0,
        "traders5min": 0,
        "traders15min": 0,
        "traders1h": 0,
        "traders4h": 0,
        "traders6h": 0,
        "traders12h": 0,
        "traders24h": 0,
        "feesPaid1minUSD": 0,
        "feesPaid5minUSD": 0,
        "feesPaid15minUSD": 0,
        "feesPaid1hUSD": 0,
        "feesPaid4hUSD": 0,
        "feesPaid6hUSD": 0,
        "feesPaid12hUSD": 0,
        "feesPaid24hUSD": 0,
        "totalFeesPaidUSD": 0,
        "totalFeesPaidNativeRaw": "0",
        "organicTrades1min": 0,
        "organicTrades5min": 0,
        "organicTrades15min": 0,
        "organicTrades1h": 0,
        "organicTrades4h": 0,
        "organicTrades6h": 0,
        "organicTrades12h": 0,
        "organicTrades24h": 0,
        "organicTraders1min": 0,
        "organicTraders5min": 0,
        "organicTraders15min": 0,
        "organicTraders1h": 0,
        "organicTraders4h": 0,
        "organicTraders6h": 0,
        "organicTraders12h": 0,
        "organicTraders24h": 0,
        "organicVolume1minUSD": 0,
        "organicVolume5minUSD": 0,
        "organicVolume15minUSD": 0,
        "organicVolume1hUSD": 0,
        "organicVolume4hUSD": 0,
        "organicVolume6hUSD": 0,
        "organicVolume12hUSD": 0,
        "organicVolume24hUSD": 0,
        "organicVolumeBuy1minUSD": 0,
        "organicVolumeBuy5minUSD": 0,
        "organicVolumeBuy15minUSD": 0,
        "organicVolumeBuy1hUSD": 0,
        "organicVolumeBuy4hUSD": 0,
        "organicVolumeBuy6hUSD": 0,
        "organicVolumeBuy12hUSD": 0,
        "organicVolumeBuy24hUSD": 0,
        "organicVolumeSell1minUSD": 0,
        "organicVolumeSell5minUSD": 0,
        "organicVolumeSell15minUSD": 0,
        "organicVolumeSell1hUSD": 0,
        "organicVolumeSell4hUSD": 0,
        "organicVolumeSell6hUSD": 0,
        "organicVolumeSell12hUSD": 0,
        "organicVolumeSell24hUSD": 0,
        "organicBuys1min": 0,
        "organicBuys5min": 0,
        "organicBuys15min": 0,
        "organicBuys1h": 0,
        "organicBuys4h": 0,
        "organicBuys6h": 0,
        "organicBuys12h": 0,
        "organicBuys24h": 0,
        "organicSells1min": 0,
        "organicSells5min": 0,
        "organicSells15min": 0,
        "organicSells1h": 0,
        "organicSells4h": 0,
        "organicSells6h": 0,
        "organicSells12h": 0,
        "organicSells24h": 0,
        "organicBuyers1min": 0,
        "organicBuyers5min": 0,
        "organicBuyers15min": 0,
        "organicBuyers1h": 0,
        "organicBuyers4h": 0,
        "organicBuyers6h": 0,
        "organicBuyers12h": 0,
        "organicBuyers24h": 0,
        "organicSellers1min": 0,
        "organicSellers5min": 0,
        "organicSellers15min": 0,
        "organicSellers1h": 0,
        "organicSellers4h": 0,
        "organicSellers6h": 0,
        "organicSellers12h": 0,
        "organicSellers24h": 0,
        "holdersCount": 123,
        "twitterReusesCount": 0,
        "twitterRenameCount": 0,
        "twitterRenameHistory": [],
        "deployerMigrationsCount": 0,
        "deployerTokensCount": 0,
        "dexscreenerListed": false,
        "dexscreenerHeader": null,
        "dexscreenerAdPaid": false,
        "dexscreenerAdPaidDate": null,
        "dexscreenerSocialPaid": false,
        "dexscreenerSocialPaidDate": null,
        "dexscreenerBoosted": false,
        "dexscreenerBoostedDate": null,
        "dexscreenerBoostedAmount": 0,
        "trendingScore1min": 0,
        "trendingScore5min": 0,
        "trendingScore15min": 0,
        "trendingScore1h": 0,
        "trendingScore4h": 0,
        "trendingScore6h": 0,
        "trendingScore12h": 0,
        "trendingScore24h": 0,
        "isMayhemMode": null,
        "isCashbackCoin": null,
        "isAgentMode": null,
        "top10HoldingsPercentage": 123,
        "top50HoldingsPercentage": 123,
        "top100HoldingsPercentage": 123,
        "top200HoldingsPercentage": 123,
        "devHoldingsPercentage": 123,
        "insidersHoldingsPercentage": 123,
        "bundlersHoldingsPercentage": 123,
        "snipersHoldingsPercentage": 123,
        "proTradersHoldingsPercentage": 123,
        "freshTradersHoldingsPercentage": 123,
        "smartTradersHoldingsPercentage": 123,
        "insidersCount": 123,
        "bundlersCount": 123,
        "snipersCount": 123,
        "freshTradersCount": 123,
        "proTradersCount": 123,
        "smartTradersCount": 123,
        "freshTradersBuys": 123,
        "proTradersBuys": 123,
        "smartTradersBuys": 123
      },
      "balance": 123,
      "rawBalance": "<string>",
      "amountUSD": 123,
      "buys": 123,
      "sells": 123,
      "volumeBuyToken": 123,
      "volumeSellToken": 123,
      "volumeBuy": 123,
      "volumeSell": 123,
      "avgBuyPriceUSD": 123,
      "avgSellPriceUSD": 123,
      "realizedPnlUSD": 123,
      "unrealizedPnlUSD": 123,
      "totalPnlUSD": 123,
      "firstDate": "<string>",
      "lastDate": "<string>",
      "totalFeesPaidUSD": 123,
      "labels": []
    }
  ],
  "wallet": {
    "fundingInfo": null,
    "entity": null,
    "labels": []
  },
  "pagination": {
    "page": 123,
    "offset": 123,
    "limit": 123,
    "pageEntries": 123
  }
}
Batch support available! Use POST /api/2/wallet/positions to fetch positions for up to 10 wallets in a single request. Jump to batch docs.

​
Query details

ParameterTypeRequiredDescription
walletstringYesSingle wallet address to query.
blockchainsstringNoComma-separated list of blockchain IDs (e.g., "ethereum,base,solana:solana"). If omitted, all chains.
limitnumberNoNumber of positions per page (1-500, default: 100).
offsetnumberNoOffset for pagination (default: 0).
cursorstringNoCursor for cursor-based pagination (takes precedence over offset).
cursorDirectionstringNoCursor direction: before or after (default: after).
sortBystringNoSort field: lastActivity or realizedPnl (default: lastActivity).
orderstringNoSort order: asc or desc (default: desc).
includeFeesbooleanNoInclude fees in PnL calculation (deduct total_fees_paid_usd from PnL). Default: false.
useSwapRecipientbooleanNoUse swap recipient mode (query wallet_positions_recipients table). Default: false.
includeAllBalancesbooleanNoInclude all tokens the wallet holds, not just tokens with trading history. Default: false.

​
Step-by-Step Tutorial and Video Walkthrough

  • Check out the guide: Here

​
Usage Examples

  • Query Wallet Positions on Solana
curl -X GET "https://demo-api.mobula.io/api/2/wallet/positions?wallet=CmbwXRT5z5aCxCzATqm5aZr7XpTh2AN7ToG35csw7YV&blockchains=solana:solana"
  • Query Wallet Positions on Ethereum with pagination
curl -X GET "https://demo-api.mobula.io/api/2/wallet/positions?wallet=0x7a16ff8270133f063aab6c9977183d9e72835428&blockchains=ethereum&limit=50&sortBy=realizedPnl&order=desc"

​
Query Response

{
  "token": {
    "address": "5Pfr5KHJSaig9ymGSzhWMKnjF59hK4CEYuYk5nLi6Mqb",
    "chainId": "solana:solana",
    "symbol": "JV",
    "name": "Joint Venture",
    "decimals": 6,
    "id": 0,
    "priceUSD": 0.0000124966129297575,
    "priceToken": 5.8400430997142966e-8,
    "priceTokenString": "0.00000005840043099714296638224172",
    "approximateReserveUSD": 9278.730767214403,
    "approximateReserveTokenRaw": "742499653255601",
    "approximateReserveToken": 742499653.255601,
    "totalSupply": 1000000000,
    "circulatingSupply": 1000000000,
    "marketCapUSD": 12496.612929757499,
    "marketCapDilutedUSD": 12496.612929757499,
    "logo": "https://ipfs.io/ipfs/bafybeicsn6mw4nu4agzaqy2yudj6byza6jwcdwllokt5kcmcflbqqjk4d4",
    "exchange": {
      "name": "PumpFun",
      "logo": "https://metadata.mobula.io/assets/logos/6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P.webp"
    },
    "factory": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "source": "pumpfun",
    "liquidityUSD": 9276.859805176831, // Current liquidity in USD
    "liquidityMaxUSD": 18555.590572391236, // Maximum historical liquidity
    "bonded": false, // Whether token is bonded in liquidity pool
    "bondingPercentage": 41.67196403283306, // % of token bonded in pool
    "preBondingFactory": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "poolAddress": "CP7U6XiMBjFo7C4SRTrYBhwhjkTS39CXrBZ5ktrESkJC",
    "top10HoldingsPercentage": 39.4455631257905, // % held by top 10 wallets
    "devHoldingsPercentage": 1.4157084169093999, // % held by developers
    "insidersHoldingsPercentage": 2.1154393942554, // % held by insiders
    "bundlersHoldingsPercentage": 24.1373383039381, // % held by bundlers
    "blockchain": "Solana",
    "type": "pumpfun",
    "deployer": "6jMBHEHDzuoYN4hQdqV7dTPys6Q1TEt67L9QzRsxe3Yn",
    "bondedAt": null,
    "athUSD": 0.00008339681028533523, // All-time high in USD
    "atlUSD": 0.00000610192172852442, // All-time low in USD
    "athDate": "2025-09-24T02:07:24.500Z",
    "atlDate": "2025-09-24T02:03:50.500Z",
    "priceChange1minPercentage": 0,
    "priceChange5minPercentage": -0.1172131118790119,
    "priceChange1hPercentage": 0.2398170569406069,
    "priceChange4hPercentage": -0.6875004215632496,
    "priceChange6hPercentage": -6.498135278981028,
    "priceChange12hPercentage": -41.46193222781062,
    "priceChange24hPercentage": 71.61865300993004,
    "volume1minUSD": 0,
    "volume5minUSD": 1.86765618577485,
    "volume15minUSD": 20.31173539932883,
    "volume1hUSD": 20.31173539932883,
    "volume4hUSD": 441.2916947502766,
    "volume6hUSD": 763.1516638661021,
    "volume12hUSD": 76636.366643982,
    "volume24hUSD": 362588.2902590606,
    "volumeBuy24hUSD": 182820.5522236792, // Total buy volume in USD last 24h
    "volumeSell24hUSD": 179767.7380353815, // Total sell volume in USD last 24h
    "trades24h": 3373, // Number of trades last 24h
    "buys24h": 1820, // Number of buy trades last 24h
    "sells24h": 1552, // Number of sell trades last 24h
    "buyers24h": 1324, // Unique buyers last 24h
    "sellers24h": 1135, // Unique sellers last 24h
    "traders24h": 1879, // Total unique traders last 24h
    "feesPaid24hUSD": 5655.843475417249, // Fees paid in USD last 24h
    "organicTrades24h": 3329, // Trades by non-bot/organic users last 24h
    "organicTraders24h": 1868, // Unique organic traders last 24h
    "organicVolume24hUSD": 359555.5128803363, // Organic trade volume in USD last 24h
    "organicVolumeBuy24hUSD": 180743.5484531335, // Organic buy volume in USD last 24h
    "organicVolumeSell24hUSD": 178811.9644272029, // Organic sell volume in USD last 24h
    "organicBuys24h": 1795, // Organic buy trades last 24h
    "organicSells24h": 1534, // Organic sell trades last 24h
    "organicBuyers24h": 1305, // Organic unique buyers last 24h
    "organicSellers24h": 1123, // Organic unique sellers last 24h
    "holdersCount": 114, // Total holders count
    "socials": {
      "twitter": "x.com/JV_onSOL",
      "website": null,
      "telegram": null,
      "others": {
        "showName": true,
        "createdOn": "https://pump.fun"
      }
    },
    "security": {
      "buyTax": "0.0000", // Tax on buy
      "sellTax": "0.0000", // Tax on sell
      "transferPausable": false, // Can transfers be paused
      "top10Holders": "0.8373", // % of supply in top 10 wallets
      "isBlacklisted": false, // Whether token is blacklisted
      "noMintAuthority": true, // No new minting allowed
      "balanceMutable": false // Holder balances cannot be changed arbitrarily
    }
  },
  "balance": 0,
  "rawBalance": "0",
  "amountUSD": 0,
  "buys": 4, // User's total buys
  "sells": 1, // User's total sells
  "volumeBuyToken": 4995934.954971, // User's buy volume in token
  "volumeSellToken": 4995934.954971, // User's sell volume in token
  "volumeBuy": 84.1891028056, // User's buy volume in USD
  "volumeSell": 112.4149126911, // User's sell volume in USD
  "avgBuyPriceUSD": 0.0000168515, // Average buy price USD
  "avgSellPriceUSD": 0.0000225013, // Average sell price USD
  "realizedPnlUSD": 28.2260333086, // Realized PnL in USD
  "unrealizedPnlUSD": 0, // Unrealized PnL in USD
  "totalPnlUSD": 28.2260333086, // Total PnL in USD (if includeFees=true, fees are deducted)
  "totalFeesPaidUSD": 5.12, // Total fees paid on this position (only present when useSwapRecipient=true)
  "firstDate": "2025-09-24T02:03:26.500Z",
  "lastDate": "2025-09-24T03:33:25.100Z",
  "labels": ["bundler", "sniper"] // Token-specific labels (bundler, sniper, insider, etc.)
}

​
New Response Fields

​
Position-level labels

Each position includes a labels array with token-specific trading labels:
  • bundler - Wallet used bundled transactions
  • sniper - Wallet sniped early trades
  • insider - Wallet had insider access
  • dev - Developer wallet
  • proTrader - Professional trader wallet
  • smartTrader - Smart money wallet
  • freshTrader - New trader wallet

​
Wallet Metadata

The response includes a wallet object with wallet-level metadata: 
{
  "data": [...],
  "wallet": {
    "fundingInfo": {
      "from": "FLiPGqowc82LLR173hKiFYBq2fCxLZEST5iHbHwj8xKb", // Funding source address
      "date": "2025-07-22T18:26:28.000Z", // Funding date
      "chainId": "solana:solana", // Funding chain
      "txHash": "5p3qtP8HihW6cwA8gdsLPcTnFhMLAKmirHBxPkNrHSfe...", // Funding tx hash
      "amount": "1000000000", // Raw funding amount
      "formattedAmount": 1.0, // Formatted funding amount
      "currency": {
        "name": "Solana",
        "symbol": "SOL",
        "logo": null,
        "decimals": 9,
        "address": "So11111111111111111111111111111111111111112"
      },
      "fromWalletLogo": null,
      "fromWalletTag": "Binance" // Label of funding source wallet
    },
    "entity": "Smart Money Fund", // Entity name if known
    "labels": ["mr.devvvv on Pump.fun"] // Global wallet labels
  },
  "pagination": {
    "page": 1,
    "offset": 0,
    "limit": 100,
    "pageEntries": 50
  }
}

​
Batch Positions (POST)

Fetch all positions for multiple wallets in a single request. Each wallet can have its own pagination, sorting, and chain filtering. Endpoint: POST /api/2/wallet/positions Limit: Up to 10 wallets per batch request.

​
Request Body

FieldTypeRequiredDescription
itemsarrayYesArray of wallet query objects (max 10).
items[].walletstringYesWallet address.
items[].blockchainsstring[]NoArray of blockchain IDs (e.g., ["ethereum","base"]). If omitted, all chains.
items[].limitnumberNoNumber of positions per page (1-500, default: 100).
items[].offsetnumberNoOffset for pagination (default: 0).
items[].sortBystringNoSort field: lastActivity or realizedPnl (default: lastActivity).
items[].orderstringNoSort order: asc or desc (default: desc).
items[].useSwapRecipientbooleanNoUse swap recipient mode. Default: false.
items[].includeAllBalancesbooleanNoInclude all tokens the wallet holds. Default: false.

​
Example Request

curl -X POST "https://api.mobula.io/api/2/wallet/positions" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428", "blockchains": ["evm:1"], "limit": 50 },
      { "wallet": "CmbwXRT5z5aCxCzATqm5aZr7XpTh2AN7ToG35csw7YV", "blockchains": ["solana:solana"], "limit": 100 }
    ]
  }'

​
Example Response

{
  "payload": [
    {
      "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
      "data": [/* TokenPosition[] - same format as GET response */],
      "walletMetadata": {
        "fundingInfo": { ... },
        "entity": "Smart Money Fund",
        "labels": ["whale"]
      },
      "pagination": { "page": 1, "offset": 0, "limit": 50, "pageEntries": 42 }
    },
    {
      "wallet": "CmbwXRT5z5aCxCzATqm5aZr7XpTh2AN7ToG35csw7YV",
      "data": [/* TokenPosition[] */],
      "walletMetadata": { ... },
      "pagination": { "page": 1, "offset": 0, "limit": 100, "pageEntries": 15 }
    }
  ],
  "hostname": "api-pod-xyz"
}
All wallets are processed in parallel, so batch latency ≈ slowest single wallet, not the sum of all wallets.

​
SDK Usage

import { MobulaSDK } from '@mobula/sdk';

const sdk = new MobulaSDK({ apiKey: 'YOUR_API_KEY' });

const result = await sdk.fetchWalletPositionsBatch({
  items: [
    { wallet: '0x7a16ff8270133f063aab6c9977183d9e72835428', blockchains: ['evm:1'], limit: 50 },
    { wallet: 'CmbwXRT5z5aCxCzATqm5aZr7XpTh2AN7ToG35csw7YV', blockchains: ['solana:solana'] },
  ],
});

for (const entry of result.payload) {
  if ('error' in entry) {
    console.error(`Failed for ${entry.wallet}: ${entry.error}`);
  } else {
    console.log(`${entry.wallet}: ${entry.data.length} positions`);
  }
}

Query Parameters

​
wallet
string
required

Wallet address

​
blockchains
string

Comma-separated list of blockchain IDs (e.g., "ethereum,base,solana:solana"). If omitted, all chains.

​
limit
number

Number of positions per page (1-500, default: 100)

Required range: 1 <= x <= 500
​
offset
number | null

Offset for pagination (default: 0)

Required range: x >= 0
​
cursor
string

Cursor for cursor-based pagination (takes precedence over offset)

​
cursorDirection
enum<string>

Cursor direction (default: after)

Available options:
before,
after
​
sortBy
enum<string>

Sort field (default: lastActivity)

Available options:
lastActivity,
realizedPnl
​
order
enum<string>

Sort order (default: desc)

Available options:
asc,
desc
​
includeFees
required

Include fees in PnL calculation (deduct total_fees_paid_usd from PnL)

​
useSwapRecipient
required

Use swap recipient mode (query wallet_positions_recipients table instead of wallet_positions)

​
includeAllBalances
required

Include all tokens the wallet holds, not just tokens with trading history

Response

200 - application/json

Wallet positions response

​
data
object[]
required
​
wallet
object
​
pagination
object