> ## 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. # Get Crypto Holdings ### Query details * **Either `wallet` or `wallets` must 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`](/rest-api-reference/endpoint/wallet-positions) or [`/wallet/position`](/rest-api-reference/endpoint/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) **Performance Tip**: For the fastest response times, explicitly specify only the blockchains you need using the `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](https://docs.mobula.io/guides/how-to-view-wallet-portfolio-holdings) *** ### Usage Examples * Query multiple wallets with a chain filter ```bash theme={null} curl -X GET /wallet/portfolio?wallets=0xBb7Ae0458b0dAe031460E6EE9f014b275db49f7f,0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&blockchains=ethereum ``` * Query a portfolio using cached data with stale tolerance ```bash theme={null} curl -X GET /wallet/portfolio?wallets=0x3406bf0fdf29c2928988a9420f4b320fe4eca538,0x21d93ea2a1aa8ac5b482c2b2992ea8fe5ad6c329&cache=true&unlistedAssets=false&stale=3600&blockchains=base ``` * Query Portfolio — All Chains, ≥ \$10,000 Liquidity, Maximum Accuracy ```bash theme={null} curl -X GET /wallet/portfolio?wallet=0x63b696e9ecef8093aa74d75db3146546745e0b3a&fetchAllChains=true&minliq=10000&accuracy=maximum ``` * Query portfolio with 24h price change data ```bash theme={null} curl -X GET /wallet/portfolio?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&shouldFetchPriceChange=24h ``` ### 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 * `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` always indicates the native token of the chain referenced by `chainId` (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 is `0x4200000000000000000000000000000000000006`. * 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. Example excerpt for the wallet `0x57d7b62c7b877f315b2d0cac98c4775f5bd3cd0b` on Arbitrum: ``` { "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "chainId": "evm:42161", "balance": 39.25753168459394, "tokenType": "erc20" }, { "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1", "chainId": "evm:42161", "balance": 4.80184389862177, "tokenType": "erc20" } ``` Use the `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. ## OpenAPI ````yaml get /1/wallet/portfolio openapi: 3.0.0 info: version: 1.0.0 title: Mobula API description: >- Documentation of the Mobula API **Demo API**: The default server (demo-api.mobula.io) is a demo API with rate limits. For production use, please use api.mobula.io with an API key from https://admin.mobula.io servers: - url: https://demo-api.mobula.io/api/ description: Demo API (rate limited, for testing only) - url: https://api.mobula.io/api/ description: Production API (requires API key) security: [] tags: - name: V2 - Token description: Token details, price, security, ATH, and holder data - name: V2 - Market Data description: Market details, OHLCV history, and lighthouse metrics - name: V2 - Trades description: Token trades, enriched trades, and trade filters - name: V2 - Wallet description: Wallet positions, activity, trades, analysis, and labels - name: V2 - Assets description: Cross-chain asset details and price history - name: V2 - Swap description: Swap quoting and execution - name: V2 - Perps description: Perpetual futures quoting, execution, and positions - name: V2 - Bridge description: Cross-chain bridge quoting and intent status (Alpha Preview) - name: V2 - DeFi description: Bonding pools and pulse data - name: V2 - Search description: Universal fast search - name: V2 - Usage description: Per-key API and WebSocket usage history - name: V2 - Blockchains description: System metadata and chain listings - name: V2 - Prediction Markets description: >- Polymarket markets/events, wallet positions, and the full execution stack (auth, order build/submit/cancel, approvals, pUSD wrap/unwrap, deploy, deposit/withdraw, redeem). Alpha — see /api/2/pm/*. - name: V1 - Market Data description: Market prices, history, sparklines, pairs, and multi-data - name: V1 - Wallet description: Wallet portfolio, transactions, history, and NFTs - name: V1 - Token description: First buyers - name: V1 - Trades description: Market trades by pair - name: V1 - Metadata description: Token metadata, categories, and news - name: V1 - Assets description: List all assets - name: V1 - Search description: Search for assets, tokens, and pairs - name: V1 - DeFi description: Bonding pool pulse data - name: V1 - Blockchains description: Blockchain listings, pairs, and stats - name: V1 - Webhooks description: Webhook management - name: V1 - Feed description: Custom feed creation paths: /1/wallet/portfolio: get: tags: - V1 - Wallet summary: Get wallet portfolio parameters: - schema: type: string description: Wallet address required: false description: Wallet address name: wallet in: query - schema: type: string description: Comma-separated wallet addresses required: false description: Comma-separated wallet addresses name: wallets in: query - schema: type: string description: Portfolio ID required: false description: Portfolio ID name: portfolio in: query - schema: type: string description: Comma-separated blockchain IDs required: false description: Comma-separated blockchain IDs name: blockchains in: query - schema: type: string description: Filter by specific asset required: false description: Filter by specific asset name: asset in: query - schema: type: string description: Start date required: false description: Start date name: from in: query - schema: type: string description: End date required: false description: End date name: to in: query - schema: type: string description: Portfolio display settings required: false description: Portfolio display settings name: portfolio_settings in: query - schema: type: string description: Include unlisted assets required: false description: Include unlisted assets name: unlistedAssets in: query - schema: type: string description: Time period required: false description: Time period name: period in: query - schema: type: string description: Data accuracy level required: false description: Data accuracy level name: accuracy in: query - schema: type: string description: Include testnet data required: false description: Include testnet data name: testnet in: query - schema: type: string description: Minimum liquidity threshold required: false description: Minimum liquidity threshold name: minliq in: query - schema: type: string description: Filter spam tokens required: false description: Filter spam tokens name: filterSpam in: query - schema: type: string description: Include PnL data required: false description: Include PnL data name: pnl in: query - schema: type: string required: false name: rpc in: query responses: '200': description: Wallet portfolio response content: application/json: schema: type: object properties: data: type: object properties: total_wallet_balance: type: number wallets: type: array items: type: string assets: type: array items: type: object properties: contracts_balances: type: array items: type: object properties: address: type: string balance: type: number balanceRaw: type: string chainId: type: string decimals: type: number tokenType: type: string nullable: true enum: - '2020' - '2022' - erc20 - trc10 - trc20 security: type: object nullable: true properties: buyTax: type: string nullable: true sellTax: type: string nullable: true transferPausable: type: boolean top10Holders: type: string isBlacklisted: type: boolean noMintAuthority: type: boolean isFreezable: type: boolean balanceMutable: type: boolean lowLiquidity: type: string burnRate: type: string liquidityBurnPercentage: type: number transferTax: type: string nullable: true isHoneypot: type: boolean isNotOpenSource: type: boolean renounced: type: boolean locked: type: string isWhitelisted: type: boolean isMintable: type: boolean modifyableTax: type: boolean selfDestruct: type: boolean frozen: type: boolean lamports: type: string nullable: true tokenAccount: type: string nullable: true required: - address - balance - balanceRaw - chainId - decimals cross_chain_balances: type: object additionalProperties: type: object properties: balance: type: number balanceRaw: type: string chainId: type: string address: type: string required: - balance - balanceRaw - chainId - address price_change_24h: type: number estimated_balance: type: number price: type: number liquidity: type: number token_balance: type: number allocation: type: number asset: type: object properties: id: type: number nullable: true name: type: string symbol: type: string logo: type: string nullable: true decimals: type: array items: type: string pattern: ^d+$ contracts: type: array items: type: string blockchains: type: array items: type: string required: - id - name - symbol - decimals - contracts - blockchains wallets: type: array items: type: string realized_pnl: type: number unrealized_pnl: type: number price_bought: type: number total_invested: type: number min_buy_price: type: number max_buy_price: type: number required: - contracts_balances - cross_chain_balances - price_change_24h - estimated_balance - price - liquidity - token_balance - allocation - asset - wallets win_rate: type: number tokens_distribution: type: object properties: 10x+: type: number 4x - 10x: type: number 2x - 4x: type: number 10% - 2x: type: number '-10% - 10%': type: number '-50% - -10%': type: number '-100% - -50%': type: number required: - 10x+ - 4x - 10x - 2x - 4x - 10% - 2x - '-10% - 10%' - '-50% - -10%' - '-100% - -50%' pnl_history: type: object properties: 1y: type: array items: type: array items: anyOf: - type: string nullable: true - type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized minItems: 2 maxItems: 2 7d: type: array items: type: array items: anyOf: - type: string nullable: true - type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized minItems: 2 maxItems: 2 24h: type: array items: type: array items: anyOf: - type: string nullable: true - type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized minItems: 2 maxItems: 2 30d: type: array items: type: array items: anyOf: - type: string nullable: true - type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized minItems: 2 maxItems: 2 required: - 1y - 7d - 24h - 30d total_realized_pnl: type: number total_unrealized_pnl: type: number total_pnl_history: type: object properties: 24h: type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized 7d: type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized 30d: type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized 1y: type: object properties: realized: type: number unrealized: type: number required: - realized - unrealized required: - 24h - 7d - 30d - 1y balances_length: type: number required: - total_wallet_balance - wallets - assets - balances_length backfill_status: type: string enum: - processed - processing - pending required: - data ````