Get wallet portfolio
Wallet APIs
Get Crypto Holdings
GET
Get wallet portfolio
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.
Query details
- Either
walletorwalletsmust be provided. - Boolean parameters are passed as strings (
"true","false").
| Parameter | Required | Default | Description |
|---|---|---|---|
wallet | Cond. | — | Single wallet address to query (can also accept comma-separated addresses). |
wallets | Cond. | — | Comma-separated wallet addresses to query in aggregate. |
blockchains | No | Premium chains | Comma-separated list of chains (e.g., ethereum,base,solana). Solana is supported — pass solana alongside any EVM chains. By default, only premium chains are queried (see list below). For optimal performance and fastest response times, we strongly recommend specifying only the blockchains you need. To query all chains, use fetchAllChains=true. |
cache | No | false | "true" to allow returning cached results (faster responses). |
stale | No | 300 | Number of seconds to allow cached data before refreshing. Example: 3600 = 1 hour. |
from | No | 0 | Start of the historical window (Unix ms timestamp). |
to | No | Now | End of the historical window (Unix ms timestamp). |
unlistedAssets | No | true | "true" to include unlisted or non-indexed assets in the calculation. |
accuracy | No | maximum | Set to "maximum" to analyze all assets. By default, to optimize response time, assets making < 1% of total net worth may be skipped. |
testnet | No | false | "true" to include testnet data. |
minliq | No | 1000 | Minimum liquidity threshold in USD. Assets below are excluded. |
filterSpam | No | true | "true" to remove spam or low-quality assets from results. |
fetchUntrackedHistory | No | false | "true" to fetch historical prices for untracked assets. |
fetchAllChains | No | false | "true" to query all supported chains, including those without premium RPCs. |
shouldFetchPriceChange | No | false | Set to "24h" to include 24-hour price change data. Note: This parameter accepts the value "24h", not "true". |
backfillTransfers | No | false | "true" to trigger backfilling of transfer history for the wallet(s). Returns backfill_status in the response. |
fetchEmptyBalances | No | false | "true" to include tokens with zero balance in the response. |
Looking for PnL data? This endpoint returns current holdings and balances. For profit/loss (PnL) data including realized and unrealized gains, use the
/wallet/positions or /wallet/position endpoints instead.Premium Chains (Default)
By default, the API queries only chains with premium RPCs for optimal performance and reliability. These chains are:ethereum(Ethereum Mainnet)base(Base)arbitrum(Arbitrum One)polygon(Polygon PoS)avalanche(Avalanche C-Chain)bnb(BNB Smart Chain)optimism(Optimism)sonic(Sonic)solana(Solana)
blockchains parameter (e.g., blockchains=ethereum,base,solana). This reduces latency and improves query efficiency.
To query all supported chains (including non-premium ones), use fetchAllChains=true.
Step-by-Step Tutorial and Video Walkthrough
- Check out the guide: Here
Usage Examples
- Query multiple wallets with a chain filter
- Query a portfolio using cached data with stale tolerance
- Query Portfolio — All Chains, ≥ $10,000 Liquidity, Maximum Accuracy
- Query portfolio with 24h price change data
Top-Level Response Fields
| Field | Type | Description |
|---|---|---|
total_wallet_balance | number | Total portfolio value in USD across all assets |
wallets | array | List of queried wallet addresses |
assets | array | Array of asset holdings (see below) |
total_realized_pnl | number | Total realized PnL in USD (optional) |
total_unrealized_pnl | number | Total unrealized PnL in USD (optional) |
total_pnl_history | object | PnL broken down by period: 24h, 7d, 30d, 1y — each with realized and unrealized (optional) |
tokens_distribution | object | Distribution of tokens by return range: 10x+, 4x - 10x, 2x - 4x, 10% - 2x, -10% - 10%, -50% - -10%, -100% - -50% (optional) |
win_rate | number | Overall win rate percentage (optional) |
balances_length | number | Number of unique token balances |
backfill_status | string | Transfer backfill status: processed, processing, or pending (only present when backfillTransfers=true) |
Asset Fields (per item in assets[])
| Field | Type | Description |
|---|---|---|
price | number | Current price in USD |
price_change_24h | number | 24-hour price change percentage |
liquidity | number | Total liquidity in USD across all DEX pools |
token_balance | number | Total token balance held |
estimated_balance | number | Total value in USD (token_balance * price) |
allocation | number | Percentage of total portfolio value |
contracts_balances | array | Detailed balance breakdown per chain/contract |
cross_chain_balances | object | Aggregated balances per blockchain |
wallets | array | Wallet addresses holding this asset |
realized_pnl | number | Realized PnL in USD for this asset (optional) |
unrealized_pnl | number | Unrealized PnL in USD for this asset (optional) |
price_bought | number | Average buy price in USD (optional) |
total_invested | number | Total invested in USD (optional) |
min_buy_price | number | Minimum buy price (optional) |
max_buy_price | number | Maximum buy price (optional) |
Native vs. Wrapped Assets
0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeealways indicates the native token of the chain referenced bychainId(e.g.,evm:42161= ETH on Arbitrum,evm:8453= ETH on Base). Mobula normalizes native balances under this canonical placeholder so that the asset is easily identifiable across chains.- Wrapped versions of native tokens are returned as their real ERC-20 contract addresses. For example, Arbitrum WETH is
0x82af49447d8a07e3bd95bd0d56f35241523fbab1, while the canonical WETH contract on both Base and Optimism is0x4200000000000000000000000000000000000006. - In the response, you may therefore see two separate entries for the same wallet: one for the native gas token (via
0xeeee...) and another for any wrapped balance. This lets you distinguish spendable gas from ERC-20-wrapped liquidity.
0x57d7b62c7b877f315b2d0cac98c4775f5bd3cd0b on Arbitrum:
address field to decide whether a position is the native token placeholder or a wrapped contract so you can interpret balances correctly in your integration.Query Parameters
Wallet address
Comma-separated wallet addresses
Portfolio ID
Comma-separated blockchain IDs
Filter by specific asset
Start date
End date
Portfolio display settings
Include unlisted assets
Time period
Data accuracy level
Include testnet data
Minimum liquidity threshold
Filter spam tokens
Include PnL data