Skip to content

Portfolio

Balances, valuations and recent transactions for a wallet.

Read-only view of any address. Balances are read on-chain; which ERC-20s are checked depends on the discovery provider configured on the server.

GET /api/portfolio/{address}

GET/api/portfolio/{address}?chainId={chainId}
ParamInDescription
addresspathWallet address. Invalid → 400 "Invalid address".
chainIdquery1 or 11155111; otherwise the deployment default.
lib/services/portfolio.ts
type Portfolio = {  owner: `0x${string}`;  chainId: number;  eth: { balance: number; priceUsd: number | null; valueUsd: number | null };  holdings: {    address: `0x${string}`;    name: string;    symbol: string;    decimals: number;    balance: number;           // whole tokens    priceUsd: number | null;    valueUsd: number | null;    logo: string | null;    priced: boolean;    liquidity: number | null;  // USD liquidity of the best DexScreener pair  }[];  totalValueUsd: number | null; // mainnet only  unpricedCount: number;  transactions: {               // up to 25, needs ETHERSCAN_API_KEY    hash: string; time: number; from: string; to: string;    value: string /* ETH */; method: string; failed: boolean;  }[];  discovery: "alchemy" | "etherscan" | "none";  history: { points: { t: number; v: number }[]; included: string[] } | null; // mainnet only};

Token discovery

discoveryConfigured byBehaviour
alchemyALCHEMY_API_KEYalchemy_getTokenBalances — every ERC-20 with a non-zero balance.
etherscanETHERSCAN_API_KEYContracts seen in the last 200 token transfers, max 80 tokens.
noneneitherOnly the ETH balance; holdings is empty.

Valuation

  • Prices are applied on mainnet only: the CoinGecko price when the token is listed, otherwise the DexScreener price only if the pair has at least $5,000 liquidity. Everything else stays unpriced (priced: false).
  • totalValueUsd = ETH value + priced holdings; null on Sepolia.
  • history is current holdings valued at historical prices over 30 days (ETH plus up to 4 CoinGecko-listed tokens, listed in included). It is not realised P&L.
  • The portfolio is cached for 45 s per chain and owner.