How to Get Wallet Balance of a Single Token Across All Chains

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

Parameter	Type	Required	Description
`wallet`	string	Yes	The wallet address to query
`asset`	string	Yes	The token contract address. Use `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` for native tokens (ETH, BNB, SOL, etc.)
`blockchain`	string	Yes	The 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:

Token	Chain	Address
Native (ETH/SOL/BNB/…)	Any	`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
USDC	Ethereum (1)	`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
USDT	Ethereum (1)	`0xdAC17F958D2ee523a2206206994597C13D831ec7`
USDC	Arbitrum (42161)	`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
USDT	Arbitrum (42161)	`0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9`
USDC	Base (8453)	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
USDC	Solana	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

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.

Overview

Extra

Guides

How to Get Wallet Balance of a Single Token Across All Chains

Overview

Parameters

Examples

1. Get Native Token Balance (SOL on Solana)

2. Get ETH Balance on Ethereum

3. Get USDC Balance on Ethereum

4. Get USDT Balance on Arbitrum

5. Query Multiple Chains at Once (Batch)

6. Using the Mobula SDK

Common Contract Addresses

Tips

Need Assistance?

Support

Support

Support

Email Support

Overview

Extra

Guides

​Overview

​Parameters

​Examples

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

​2. Get ETH Balance on Ethereum

​3. Get USDC Balance on Ethereum

​4. Get USDT Balance on Arbitrum

​5. Query Multiple Chains at Once (Batch)

​6. Using the Mobula SDK

​Common Contract Addresses

​Tips

​Need Assistance?

Support

Support

Support

Email Support

Overview

Parameters

Examples

1. Get Native Token Balance (SOL on Solana)

2. Get ETH Balance on Ethereum

3. Get USDC Balance on Ethereum

4. Get USDT Balance on Arbitrum

5. Query Multiple Chains at Once (Batch)

6. Using the Mobula SDK

Common Contract Addresses

Tips

Need Assistance?