Skip to main content

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.

Want to know how much SOL, ETH, USDC, or any token a wallet holds — along with full PnL data? The Wallet Position endpoint (/api/2/wallet/position) returns the balance, USD value, and complete trading history for a single token in one call.
Quick Start: Get your free API key at admin.mobula.io to start querying immediately.

​
Overview

The /api/2/wallet/position endpoint returns everything you need about a wallet’s holding of a specific token on a specific blockchain:
  • Balance (token amount + USD value)
  • PnL (realized, unrealized, total)
  • Trading stats (buys, sells, volume, avg prices)
  • Full token metadata (price, market cap, liquidity, logo, etc.)

​
Parameters

ParameterTypeRequiredDescription
walletstringYesThe wallet address to query
assetstringYesThe token contract address. Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native tokens (ETH, BNB, SOL, etc.)
blockchainstringYesThe blockchain to query (e.g. Solana, 1 for Ethereum, 8453 for Base, etc.)

​
Examples

​
1. Get Native Token Balance (SOL on Solana)

Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee as the asset address to query any chain’s native token. cURL 
curl -X GET "https://api.mobula.io/api/2/wallet/position?wallet=3GKvD6Fbj19HKnKdJJboMSZM1Mt9MZeehPGcq1DHBAGS&asset=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&blockchain=Solana" \
  -H "Authorization: YOUR_API_KEY"
TypeScript 
const response = await fetch(
  "https://api.mobula.io/api/2/wallet/position?" +
    new URLSearchParams({
      wallet: "3GKvD6Fbj19HKnKdJJboMSZM1Mt9MZeehPGcq1DHBAGS",
      asset: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      blockchain: "Solana",
    }),
  { headers: { Authorization: "YOUR_API_KEY" } }
);

const { data } = await response.json();

console.log(`${data.token.symbol} balance: ${data.balance}`);
console.log(`USD value: $${data.amountUSD.toFixed(2)}`);
console.log(`Realized PnL: $${data.realizedPnlUSD.toFixed(2)}`);
console.log(`Unrealized PnL: $${data.unrealizedPnlUSD.toFixed(2)}`);
Python 
import requests

response = requests.get(
    "https://api.mobula.io/api/2/wallet/position",
    params={
        "wallet": "3GKvD6Fbj19HKnKdJJboMSZM1Mt9MZeehPGcq1DHBAGS",
        "asset": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "blockchain": "Solana",
    },
    headers={"Authorization": "YOUR_API_KEY"},
)

data = response.json()["data"]
print(f"{data['token']['symbol']} balance: {data['balance']}")
print(f"USD value: ${data['amountUSD']:.2f}")
Response 
{
  "data": {
    "token": {
      "address": "So11111111111111111111111111111111111111112",
      "chainId": "solana:solana",
      "symbol": "SOL",
      "name": "Solana",
      "priceUSD": 181.20,
      "marketCapUSD": 46111177215,
      "logo": "https://metadata.mobula.io/assets/logos/solana_solana_So11111111111111111111111111111111111111112.webp"
    },
    "balance": 12.5,
    "rawBalance": "12500000000",
    "amountUSD": 2265.0,
    "buys": 5,
    "sells": 2,
    "volumeBuy": 1800.0,
    "volumeSell": 500.0,
    "avgBuyPriceUSD": 160.0,
    "avgSellPriceUSD": 175.0,
    "realizedPnlUSD": 30.0,
    "unrealizedPnlUSD": 265.0,
    "totalPnlUSD": 295.0
  }
}

​
2. Get ETH Balance on Ethereum

curl -X GET "https://api.mobula.io/api/2/wallet/position?wallet=0x77A89C51f106D6cD547542a3A83FE73cB4459135&asset=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&blockchain=1" \
  -H "Authorization: YOUR_API_KEY"

​
3. Get USDC Balance on Ethereum

Pass the USDC contract address as the asset parameter: 
curl -X GET "https://api.mobula.io/api/2/wallet/position?wallet=0x77A89C51f106D6cD547542a3A83FE73cB4459135&asset=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&blockchain=1" \
  -H "Authorization: YOUR_API_KEY"

​
4. Get USDT Balance on Arbitrum

curl -X GET "https://api.mobula.io/api/2/wallet/position?wallet=0x77A89C51f106D6cD547542a3A83FE73cB4459135&asset=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9&blockchain=42161" \
  -H "Authorization: YOUR_API_KEY"

​
5. Query Multiple Chains at Once (Batch)

Need the same token balance on multiple chains? Use the POST batch endpoint to send multiple queries in a single request: 
const response = await fetch("https://api.mobula.io/api/2/wallet/position", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        wallet: "0x77A89C51f106D6cD547542a3A83FE73cB4459135",
        asset: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        blockchain: "1",
      },
      {
        wallet: "0x77A89C51f106D6cD547542a3A83FE73cB4459135",
        asset: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        blockchain: "42161",
      },
      {
        wallet: "0x77A89C51f106D6cD547542a3A83FE73cB4459135",
        asset: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        blockchain: "8453",
      },
    ],
  }),
});

const { payload } = await response.json();

for (const position of payload) {
  if ("error" in position) continue;
  console.log(`${position.token.symbol} on chain ${position.token.chainId}: ${position.balance} ($${position.amountUSD.toFixed(2)})`);
}

​
6. Using the Mobula SDK

import { Mobula } from "@mobula/sdk";

const mobula = new Mobula({ apiKey: "YOUR_API_KEY" });

// Single position
const position = await mobula.fetchWalletPosition({
  wallet: "3GKvD6Fbj19HKnKdJJboMSZM1Mt9MZeehPGcq1DHBAGS",
  asset: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  blockchain: "Solana",
});

console.log(`SOL balance: ${position.data.balance}`);
console.log(`PnL: $${position.data.totalPnlUSD.toFixed(2)}`);

​
Common Contract Addresses

Here are some commonly queried token addresses:
TokenChainAddress
Native (ETH/SOL/BNB/…)Any0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
USDCEthereum (1)0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
USDTEthereum (1)0xdAC17F958D2ee523a2206206994597C13D831ec7
USDCArbitrum (42161)0xaf88d065e77c8cC2239327C5EDb3A432268e5831
USDTArbitrum (42161)0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9
USDCBase (8453)0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
USDCSolanaEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

​
Tips

  • Native token shortcut: 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee works for native tokens on every chain — the API automatically resolves it to the actual native address (WETH, WSOL, WBNB, etc.).
  • Zero position: If the wallet has never traded this token, the endpoint still returns the current balance and token metadata — PnL fields will be zero.
  • Batch for multi-chain: Use the POST batch endpoint when you need the same token across several chains — it’s faster than individual calls.

​
Need Assistance?

Our support team is ready to help you with any questions or integration challenges.

Support

Telegram

Support

Slack

Support

Discord

Email Support

Email