# Portfolio at Block: A Complete Guide

> Query a wallet's exact decoded portfolio at any historical block on Ethereum, Linea and Monad — decoded Uniswap V4 everywhere, V3 on Linea.

- **URL:** https://octav.fi/blog/portfolio-at-block-guide
- **Published:** 2026-09-16
- **Author:** Octav Team — Portfolio Intelligence for Digital Assets
- **Topic:** API & Developers
- **Tags:** api, developers, defi
- **Source:** Octav, Practical guides on crypto NAV reporting, multi-chain portfolio management and digital asset APIs, from the team behind Octav.

---
<LogoRow items="ethereum,linea,monad,uniswap" caption="Chains and protocols in this guide" />

Most portfolio APIs answer one question: what does this wallet hold *right
now*. [Portfolio at Block](https://docs.octav.fi/api/endpoints/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:

![Diagram of the Portfolio at Block mechanism: a block 19,000,000 highlighted on a chain of blocks, with a dashed line down to a card showing the decoded wallet and Lido positions and a net worth of $38,068.19 at that block](./images/figure-block-mechanism.png)

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.

| | By date | By block |
| --- | --- | --- |
| Precision | Nearest recorded day | The exact block |
| What moves between them | Prices, and every position that isn't a static balance | Nothing — the block is the ground truth |
| Works retroactively | Only from when you started recording | Any block, any time, no setup |

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](/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](/tracking-aave-positions).

## What's supported today

![Coverage matrix: Ethereum, Linea and Monad chain logos against Uniswap V3 and V4 support — Uniswap V4 is decoded on all three chains, Uniswap V3 is decoded on Linea only](./images/figure-block-coverage.png)

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

```bash
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"
```

```js
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}`);
```

| Parameter | Required | Notes |
| --- | --- | --- |
| `addresses` | Yes | One EVM address per call — this endpoint does not batch |
| `chainKey` | Yes | `ethereum`, `linea` or `monad` |
| `blockNumber` | Yes | A positive integer |

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](/crypto-portfolio-api-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](/daily-crypto-portfolio-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:

| | Snapshots | Portfolio at Block |
| --- | --- | --- |
| Direction | Records forward from subscription | Queries backward to any block |
| Needs setup in advance | Yes | No |
| Granularity | Daily | Exact block |
| Chains | All supported chains | Ethereum, Linea, Monad |
| Best for | Routine reporting you'll need repeatedly | A one-off historical question, any time |

If you already know you'll need history going forward, subscribe to
[snapshots](/daily-crypto-portfolio-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

| If you want | Go to |
| --- | --- |
| The full endpoint list and credit costs | [Endpoint reference](/crypto-portfolio-api-endpoint-reference) |
| Why LP composition changes block to block | [Valuing Uniswap V3 Positions](/valuing-uniswap-v3-positions) |
| Forward-recording history instead | [Daily Crypto Portfolio Snapshots](/daily-crypto-portfolio-snapshots) |
| The general shape of a portfolio response | [Crypto portfolio API guide](/crypto-portfolio-api-guide) |
| Everything else this API decodes on EVM | [EVM portfolio API guide](/evm-portfolio-api-guide) |