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
          }
        ],
        "cross_chain_balances": {},
        "price_change_24h": 123,
        "estimated_balance": 123,
        "price": 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.
  • Values are passed as strings ("true", "false").
ParameterRequiredDescription
walletCond.Single wallet address to query.
walletsCond.Comma-separated wallet addresses to query in aggregate.
blockchainsCond.Comma-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.
assetCond.Filter the net worth history to a specific asset (symbol or contract address) for the given wallet(s).
cacheCond."true" to allow returning cached results (faster responses).
staleCond.Number of seconds to allow cached data before refreshing. Example: 3600 = 1 hour.
fromCond.Start of the historical window (Unix ms timestamp or ISO 8601).
toCond.End of the historical window (Unix ms timestamp or ISO 8601).
unlistedAssetsCond."true" to include unlisted or non-indexed assets in the calculation.
periodCond.Supported values: 5min, 15min, 1h, 6h, 1d, 7d. Defines aggregation granularity.
accuracyCond.By default, to optimize response time, we will skip analyzing assets that make < 1% of the total net worth. You can set this to true` to analyze all assets.
testnetCond."true" to include testnet data.
minliqCond.Minimum liquidity threshold in USD (default: 1000). Assets below are excluded.
filterSpamCond."true" to remove spam or low-quality assets from results.
fetchUntrackedHistoryCond."true" to fetch historical prices for untracked assets.
fetchAllChainsCond."true" to query all supported chains, including those without premium RPCs. By default, only premium chains are queried.

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 portfolio with PnL over the last 30 days
curl -X GET /wallet/portfolio?wallet=0xaF88370abD82EC6943cdB3D4ec7b764B92c35B43&period=30d
  • 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

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
wallets
string
portfolio
string
blockchains
string
asset
string
cache
string
stale
string
recheck_contract
string
from
string
to
string
portfolio_settings
string
unlistedAssets
string
period
string
accuracy
string
testnet
string
minliq
string
filterSpam
string
fetchUntrackedHistory
string
fetchAllChains
string
shouldFetchPriceChange
string
backfillTransfers
string
fetchEmptyBalances
string

Response

200 - application/json

Wallet portfolio response

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