Portfolio at Block: A Complete Guide

Most portfolio APIs answer one question: what does this wallet hold right now. Portfolio at Block answers a harder one — what did it hold at block 19,000,000, decoded exactly the way it would have been at that moment, DeFi positions included.

What does Portfolio at Block actually return?

One request, one address, one chain, one block. The response is the same decoded shape as a live portfolio call — token balances, DeFi positions, USD values — pinned to that block instead of to now:

Every figure in that diagram is Octav's own published example for this endpoint — same address, same block, same numbers as the docs.

Why is this hard to do at all?

A date gets you close. A block gets you exact — and for anything holding a DeFi position, the difference is not academic.

A spot token balance barely cares which block you pick within a day. A Uniswap V3 position does. Concentrated liquidity is priced by the pool's current tick, and the tick moves with every swap — the same position can be 90% one asset at one block and 60% the other a thousand blocks later. There is no "the position, roughly" for something like that; there is only the position at a specific block. The mechanics are in Valuing Uniswap V3 Positions.

Lending positions have the same problem in a different shape: a health factor and a net position are both functions of the block you read them at, covered in Tracking Aave Positions.

What's supported today

Uniswap V4 decodes on all three chains. Uniswap V3 decodes on Linea for now — Ethereum and Monad are next.

As far as we can tell, Octav is the first portfolio API to reconstruct decoded Uniswap positions at an arbitrary historical block, rather than only spot balances. Chain and protocol coverage is expanding from here — this matrix is the one to check back on, not a ceiling.

Calling the endpoint

curl -s https://api.octav.fi/v1/portfolio/at-block \
  -H "Authorization: Bearer $OCTAV_API_KEY" \
  -G --data-urlencode "addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \
  --data-urlencode "chainKey=ethereum" \
  --data-urlencode "blockNumber=19000000"

const address = "0x6426af179aabebe47666f345d69fd9079673f6cd";
const response = await fetch(
  `https://api.octav.fi/v1/portfolio/at-block?addresses=${address}&chainKey=ethereum&blockNumber=19000000`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const [portfolio] = await response.json();
console.log(`Net worth at block ${portfolio.blockNumber}: $${portfolio.networth}`);

Three things that differ from the live /v1/portfolio endpoint: only one address per call, only the requested chain comes back, and includeImages, includeExplorerUrls and includeNFTs are not accepted. Everything else — the decoded assetByProtocols shape — is the same structure covered in the endpoint reference.

Portfolio at Block runs on its own rate limit — 100 requests per minute on a dedicated bucket, separate from your regular portfolio quota — and bills a monthly add-on fee plus 1 credit per call.

When you would actually use this

Tax cost-basis reconstruction. A position's value at the exact block of disposal, not an end-of-day approximation your auditor has to caveat.

Governance and airdrop eligibility. Snapshot votes and airdrop allocations are defined at a specific block. This is the API call that answers "what did this wallet hold at that block", after the fact, for any wallet — including the LP and lending positions a token-only snapshot tool would miss entirely.

Dispute resolution. "What was this position worth right before it moved" is a block-level question. Approximating it by date is how disputes stay disputes.

Fund NAV reconstruction. If daily snapshots were not running yet, Portfolio at Block is the only way to answer "what was the NAV on that date" after the fact — as precisely as the chain itself records it.

How this differs from snapshots

Both answer questions about the past. They are not the same tool:

If you already know you'll need history going forward, subscribe to snapshots. If the question is about a moment that already happened, Portfolio at Block is the one that can still answer it.

Where to go next