EVM Portfolio API: A Complete Guide

"EVM support" sounds like one feature. It is not — it is the same integration problem repeated on every chain a wallet has ever touched, and the count is higher than most teams assume.

A single portfolio request for vitalik.eth returns value on 44 EVM chains, out of 66 the response enumerates. Ethereum holds 93.2% of it. The other 43 chains hold $77,714 — the part a report either includes or silently loses.

Ethereum is left off that chart on purpose. At linear scale it flattens everything else to nothing — which is exactly the mistake the chart is arguing against.

Why EVM is not one problem

Solana is one chain with hard-to-decode programs. EVM is the opposite: the decoding is well understood, and the difficulty is that you have to do it everywhere, forever.

The multiplication is the whole story. Supporting Aave is one integration. Supporting Aave across chains is one integration re-verified on every chain it deploys to, because the addresses differ and the deployments drift.

Here is what that looks like in a real response — the same protocol, one wallet, two chains, five separate positions:

An API that indexes Ethereum and calls it "Uniswap support" returns three of those five.

What actually sits in an EVM wallet

Four position types, only one of which a balance query returns correctly:

The lending case is the one that inverts meaning rather than nudging a number. A wallet supplying 6,586 WETH against 2,294,767 USDC of borrow holds a net position near $10.3M — but summing the tokens it holds adds the debt as a positive and reports something closer to $12.6M. The mechanics are in Tracking Aave Positions.

The four things that break EVM decoding

Receipt tokens look like ordinary ERC-20s. aUSDC, cDAI, stETH and thousands of vault shares are transferable tokens with a balance and a symbol. Treat them as spot holdings and you double-count the underlying.

Liquidity is often not a token at all. A Uniswap V3 position is an NFT whose contents depend on the pool's current tick. There is no balance to read — the amounts have to be derived. See Valuing Uniswap V3 Positions.

Proxies hide the implementation. Most major EVM protocols sit behind upgradeable proxies, so the address you integrated against is not the logic you decoded. Upgrades change response shapes without changing addresses.

The same symbol is not the same asset. USDC on Ethereum, bridged USDC.e on an L2 and a third-party bridge wrapper are different assets with different risk. Collapsing them by symbol produces a tidy, wrong total.

Querying every chain in one request

The practical requirement is that chain count stops being your problem. One address in, every chain out:

curl -s https://api.octav.fi/v1/portfolio \
  -H "Authorization: Bearer $OCTAV_API_KEY" \
  -G --data-urlencode "addresses=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Positions come back grouped by protocol, then chain, so per-chain exposure is a read rather than a reconciliation. Batching several addresses into one request is also the main cost lever — the full parameter and credit table is in the endpoint reference.

If you would rather not hold a key at all while evaluating, Authless answers the same question for any EVM address with no account.

How to evaluate an EVM provider

Run these against a wallet whose contents you can verify independently. Each one fails a different class of provider:

1. Query an address with activity on an L2 you rarely think about. Does the position appear at all? This is chain coverage, and it is where most of the variance lives.
2. Query a wallet with an open lending borrow. Is the debt negative in the total, or added to it?
3. Query a wallet with a Uniswap V3 position. Is it present, and are both sides of the pair itemised?
4. Check a vault or staked position. Is it valued at the share price or at 1:1?
5. Ask what happens on an unsupported protocol. "Omitted silently" and "flagged as unsupported" are very different products.

Question 1 is the one to weight. Decoding gaps are visible once you look; missing chains are invisible by construction, because nothing in the response says a chain was never checked.

Measured results across nine providers, including where competitors beat us, are in the benchmark — and the mechanism behind the disagreements is in Why Portfolio APIs Disagree.

Where to go next

The multi-chain problem in the abstract — why enumeration is the hard part — is covered in Tracking DeFi Positions Across Multiple Chains.