Portfolio API

Endpoints for aggregating a wallet's full portfolio and retrieving swap history.

Get Portfolio

GET /api/portfolio/{wallet}

Returns the complete portfolio for a wallet address, including token balances, LP positions, and their USD values. The backend uses multicall to efficiently batch on-chain balance reads in a single RPC call.

Path Parameters:

Parameter	Type	Description
wallet	string	User wallet address

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID

Response:

{
  "success": true,
  "data": {
    "wallet": "0x...",
    "total_value_usd": 54230.45,
    "tokens": [
      {
        "address": "0x...",
        "symbol": "WETH",
        "name": "Wrapped Ether",
        "balance": "5.234",
        "balance_raw": "5234000000000000000",
        "price_usd": 3245.67,
        "value_usd": 16991.94
      },
      {
        "address": "0x...",
        "symbol": "USDC",
        "name": "USD Coin",
        "balance": "25000.00",
        "balance_raw": "25000000000",
        "price_usd": 1.00,
        "value_usd": 25000.00
      }
    ],
    "lp_positions": [
      {
        "pool_address": "0x...",
        "token0_symbol": "WETH",
        "token1_symbol": "USDC",
        "lp_balance": "1234567890000000000",
        "value_usd": 12238.51,
        "share_percent": 0.85
      }
    ]
  }
}

How Multicall Works

Rather than issuing individual balanceOf calls for each token, the backend batches all balance queries into a single multicall RPC request. This significantly reduces latency and RPC usage, especially for wallets holding many tokens.

Swap History

GET /api/history

Returns recent swap transactions for a wallet.

Query Parameters:

Parameter	Type	Description
wallet	string	User wallet address
chain_id	integer	Target chain ID
limit	integer	Number of results (default: 20)
offset	integer	Pagination offset (default: 0)

Response:

{
  "success": true,
  "data": [
    {
      "tx_hash": "0x...",
      "timestamp": 1700000000,
      "token_in": { "address": "0x...", "symbol": "WETH", "amount": "1.0" },
      "token_out": { "address": "0x...", "symbol": "USDC", "amount": "3245.67" },
      "value_usd": 3245.67,
      "pool_address": "0x..."
    }
  ],
  "total": 156
}