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}| Param | In | Description |
|---|---|---|
address | path | Wallet address. Invalid → 400 "Invalid address". |
chainId | query | 1 or 11155111; otherwise the deployment default. |
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
| discovery | Configured by | Behaviour |
|---|---|---|
alchemy | ALCHEMY_API_KEY | alchemy_getTokenBalances — every ERC-20 with a non-zero balance. |
etherscan | ETHERSCAN_API_KEY | Contracts seen in the last 200 token transfers, max 80 tokens. |
none | neither | Only 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;nullon Sepolia.historyis current holdings valued at historical prices over 30 days (ETH plus up to 4 CoinGecko-listed tokens, listed inincluded). It is not realised P&L.- The portfolio is cached for 45 s per chain and owner.
