Skip to main content
GET
/
1
/
wallet
/
portfolio
Get wallet portfolio
curl --request GET \
  --url https://demo-api.mobula.io/api/1/wallet/portfolio
{
  "data": {
    "total_wallet_balance": 123,
    "wallets": [
      "<string>"
    ],
    "assets": [
      {
        "contracts_balances": [
          {
            "address": "<string>",
            "balance": 123,
            "balanceRaw": "<string>",
            "chainId": "<string>",
            "decimals": 123,
            "tokenType": "2020",
            "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,
              "frozen": true
            },
            "lamports": "<string>",
            "tokenAccount": "<string>"
          }
        ],
        "cross_chain_balances": {},
        "price_change_24h": 123,
        "estimated_balance": 123,
        "price": 123,
        "liquidity": 123,
        "token_balance": 123,
        "allocation": 123,
        "asset": {
          "id": 123,
          "name": "<string>",
          "symbol": "<string>",
          "decimals": [
            "<string>"
          ],
          "contracts": [
            "<string>"
          ],
          "blockchains": [
            "<string>"
          ],
          "logo": "<string>"
        },
        "wallets": [
          "<string>"
        ],
        "realized_pnl": 123,
        "unrealized_pnl": 123,
        "price_bought": 123,
        "total_invested": 123,
        "min_buy_price": 123,
        "max_buy_price": 123
      }
    ],
    "balances_length": 123,
    "win_rate": 123,
    "tokens_distribution": {
      "10x+": 123,
      "4x - 10x": 123,
      "2x - 4x": 123,
      "10% - 2x": 123,
      "-10% - 10%": 123,
      "-50% - -10%": 123,
      "-100% - -50%": 123
    },
    "pnl_history": {
      "1y": [
        [
          "<string>"
        ]
      ],
      "7d": [
        [
          "<string>"
        ]
      ],
      "24h": [
        [
          "<string>"
        ]
      ],
      "30d": [
        [
          "<string>"
        ]
      ]
    },
    "total_realized_pnl": 123,
    "total_unrealized_pnl": 123,
    "total_pnl_history": {
      "24h": {
        "realized": 123,
        "unrealized": 123
      },
      "7d": {
        "realized": 123,
        "unrealized": 123
      },
      "30d": {
        "realized": 123,
        "unrealized": 123
      },
      "1y": {
        "realized": 123,
        "unrealized": 123
      }
    }
  },
  "backfill_status": "processed"
}

Query details

  • Either wallet or wallets must be provided.
  • Boolean parameters are passed as strings ("true", "false").
ParameterRequiredDefaultDescription
walletCond.Single wallet address to query (can also accept comma-separated addresses).
walletsCond.Comma-separated wallet addresses to query in aggregate.
blockchainsNoPremium chainsComma-separated list of chains (e.g., ethereum,base). 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.
cacheNofalse"true" to allow returning cached results (faster responses).
staleNo300Number of seconds to allow cached data before refreshing. Example: 3600 = 1 hour.
fromNo0Start of the historical window (Unix ms timestamp).
toNoNowEnd of the historical window (Unix ms timestamp).
unlistedAssetsNotrue"true" to include unlisted or non-indexed assets in the calculation.
accuracyNomaximumSet to "maximum" to analyze all assets. By default, to optimize response time, assets making < 1% of total net worth may be skipped.
testnetNofalse"true" to include testnet data.
minliqNo1000Minimum liquidity threshold in USD. Assets below are excluded.
filterSpamNotrue"true" to remove spam or low-quality assets from results.
fetchUntrackedHistoryNofalse"true" to fetch historical prices for untracked assets.
fetchAllChainsNofalse"true" to query all supported chains, including those without premium RPCs.
shouldFetchPriceChangeNofalseSet to "24h" to include 24-hour price change data. Note: This parameter accepts the value "24h", not "true".
backfillTransfersNofalse"true" to trigger backfilling of transfer history for the wallet(s). Returns backfill_status in the response.
fetchEmptyBalancesNofalse"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)
Performance Tip: For the fastest response times, explicitly specify only the blockchains you need using the blockchains parameter (e.g., blockchains=ethereum,base). This reduces latency and improves query efficiency. To query all supported chains (including non-premium ones), use fetchAllChains=true.

Usage Examples

  • Query multiple wallets with a chain filter
curl -X GET /wallet/portfolio?wallets=0xBb7Ae0458b0dAe031460E6EE9f014b275db49f7f,0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&blockchains=ethereum
  • Query a portfolio using cached data with stale tolerance
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
curl -X GET /wallet/portfolio?wallet=0x63b696e9ecef8093aa74d75db3146546745e0b3a&fetchAllChains=true&minliq=10000&accuracy=maximum
  • Query portfolio with 24h price change data
curl -X GET /wallet/portfolio?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&shouldFetchPriceChange=24h

Top-Level Response Fields

FieldTypeDescription
total_wallet_balancenumberTotal portfolio value in USD across all assets
walletsarrayList of queried wallet addresses
assetsarrayArray of asset holdings (see below)
total_realized_pnlnumberTotal realized PnL in USD (optional)
total_unrealized_pnlnumberTotal unrealized PnL in USD (optional)
total_pnl_historyobjectPnL broken down by period: 24h, 7d, 30d, 1y — each with realized and unrealized (optional)
tokens_distributionobjectDistribution of tokens by return range: 10x+, 4x - 10x, 2x - 4x, 10% - 2x, -10% - 10%, -50% - -10%, -100% - -50% (optional)
win_ratenumberOverall win rate percentage (optional)
balances_lengthnumberNumber of unique token balances
backfill_statusstringTransfer backfill status: processed, processing, or pending (only present when backfillTransfers=true)

Asset Fields (per item in assets[])

FieldTypeDescription
pricenumberCurrent price in USD
price_change_24hnumber24-hour price change percentage
liquiditynumberTotal liquidity in USD across all DEX pools
token_balancenumberTotal token balance held
estimated_balancenumberTotal value in USD (token_balance * price)
allocationnumberPercentage of total portfolio value
contracts_balancesarrayDetailed balance breakdown per chain/contract
cross_chain_balancesobjectAggregated balances per blockchain
walletsarrayWallet addresses holding this asset
realized_pnlnumberRealized PnL in USD for this asset (optional)
unrealized_pnlnumberUnrealized PnL in USD for this asset (optional)
price_boughtnumberAverage buy price in USD (optional)
total_investednumberTotal invested in USD (optional)
min_buy_pricenumberMinimum buy price (optional)
max_buy_pricenumberMaximum 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.

Query Parameters

wallet
string

Wallet address

wallets
string

Comma-separated wallet addresses

portfolio
string

Portfolio ID

blockchains
string

Comma-separated blockchain IDs

asset
string

Filter by specific asset

from
string

Start date

to
string

End date

portfolio_settings
string

Portfolio display settings

unlistedAssets
string

Include unlisted assets

period
string

Time period

accuracy
string

Data accuracy level

testnet
string

Include testnet data

minliq
string

Minimum liquidity threshold

filterSpam
string

Filter spam tokens

pnl
string

Include PnL data

Response

200 - application/json

Wallet portfolio response

data
object
required
backfill_status
enum<string>
Available options:
processed,
processing,
pending