> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Portfolio At Block

> Retrieve a single address's portfolio valued at a specific historical block

Get a portfolio for a single Ethereum address with every balance and price pinned to a specific historical block, instead of the current state.

<Warning>
  The Portfolio at Block endpoint is an **add-on**, billed at a set monthly fee separate from your API credit pool, plus 1 credit per call. Contact sales to enable Portfolio at Block access for your account.
</Warning>

<Info>
  **Cost:** Set monthly fee under the Portfolio at Block add-on, plus 1 credit per call.
</Info>

<Note>
  **Rate limit:** 100 requests/min, on a dedicated bucket (does not count against your portfolio rate limit).
</Note>

***

## Endpoint

<CodeGroup>
  ```bash Request theme={null}
  GET https://api.octav.fi/v1/portfolio/at-block
  ```

  ```bash Example theme={null}
  curl -X GET "https://api.octav.fi/v1/portfolio/at-block?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&chainKey=ethereum&blockNumber=19000000" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

## Parameters

<ParamField query="addresses" type="string" required>
  A single EVM wallet address to retrieve portfolio data for. Only one address is accepted per call.

  ```
  addresses=0x6426af179aabebe47666f345d69fd9079673f6cd
  ```
</ParamField>

<ParamField query="chainKey" type="string" required>
  The chain the block belongs to. Currently only `ethereum` is supported.

  ```
  chainKey=ethereum
  ```
</ParamField>

<ParamField query="blockNumber" type="integer" required>
  The block number to value the portfolio at. Must be a positive integer.

  ```
  blockNumber=19000000
  ```
</ParamField>

***

## Response

Returns the same [Portfolio](/api/endpoints/portfolio) shape, with every asset balance and price valued as of `blockNumber`, plus a top-level `blockNumber` field. This endpoint does not accept `includeImages`, `includeExplorerUrls`, or `includeNFTs` — image, explorer URL, and NFT fields are never included in the response.

<ResponseField name="blockNumber" type="string">
  The block number the portfolio was valued at (echoes the `blockNumber` query parameter, returned as a string)
</ResponseField>

<ResponseField name="address" type="string">
  The wallet address
</ResponseField>

<ResponseField name="networth" type="string">
  Total portfolio net worth in USD, valued at `blockNumber`
</ResponseField>

<ResponseField name="cashBalance" type="string">
  Available cash balance at `blockNumber`
</ResponseField>

<ResponseField name="assetByProtocols" type="object">
  Assets organized by protocol (wallet, lending, staking, etc.), keyed by protocol identifier — same structure as the [Portfolio](/api/endpoints/portfolio) endpoint, valued at `blockNumber`.
</ResponseField>

<ResponseField name="chains" type="object">
  Per-chain totals, keyed by chain identifier — only `ethereum` is present, since block-pinning is Ethereum-only.
</ResponseField>

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.octav.fi/v1/portfolio/at-block?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&chainKey=ethereum&blockNumber=19000000" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```python Python theme={null}
  import requests

  address = '0x6426af179aabebe47666f345d69fd9079673f6cd'

  response = requests.get(
      'https://api.octav.fi/v1/portfolio/at-block',
      params={
          'addresses': address,
          'chainKey': 'ethereum',
          'blockNumber': 19000000
      },
      headers={'Authorization': f'Bearer {api_key}'}
  )

  portfolio = response.json()
  print(f"Net Worth at block {portfolio['blockNumber']}: ${portfolio['networth']}")
  ```

  ```typescript TypeScript theme={null}
  interface PortfolioAtBlock {
    address: string;
    networth: string;
    cashBalance: string;
    blockNumber: string;
    assetByProtocols: Record<string, unknown>;
    chains: Record<string, unknown>;
  }

  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: PortfolioAtBlock = await response.json();
  console.log(`Net Worth at block ${portfolio.blockNumber}: $${portfolio.networth}`);
  ```
</CodeGroup>

***

## Example Response

<Accordion title="View Full Response" icon="code">
  ```json theme={null}
  {
    "address": "0x6426af179aabebe47666f345d69fd9079673f6cd",
    "cashBalance": "0",
    "blockNumber": "19000000",
    "networth": "24962.30",
    "assetByProtocols": {
      "wallet": {
        "name": "Wallet",
        "key": "wallet",
        "value": "24962.30",
        "chains": {
          "ethereum": {
            "name": "Ethereum",
            "key": "ethereum",
            "value": "24962.30",
            "protocolPositions": {
              "WALLET": {
                "name": "wallet",
                "assets": [
                  {
                    "balance": "5.5",
                    "symbol": "eth",
                    "name": "ethereum",
                    "price": "3200.50",
                    "value": "17602.75",
                    "decimal": "18",
                    "contract": "0x0000000000000000000000000000000000000000",
                    "chainKey": "ethereum",
                    "chainContract": "ethereum:0x0000000000000000000000000000000000000000"
                  },
                  {
                    "balance": "7359.55",
                    "symbol": "usdc",
                    "name": "usd coin",
                    "price": "1.00",
                    "value": "7359.55",
                    "decimal": "6",
                    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
                    "chainKey": "ethereum",
                    "chainContract": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
                  }
                ],
                "protocolPositions": [],
                "totalValue": "24962.30",
                "unlockAt": "0"
              }
            }
          }
        }
      }
    },
    "chains": {
      "ethereum": {
        "name": "Ethereum",
        "key": "ethereum",
        "chainId": "1",
        "value": "24962.30",
        "valuePercentile": "100",
        "totalCostBasis": "N/A",
        "totalClosedPnl": "N/A",
        "totalOpenPnl": "N/A"
      }
    }
  }
  ```
</Accordion>

***

## Use Cases

<Tabs>
  <Tab title="Point-in-Time Valuation" icon="clock-rotate-left">
    Value a wallet exactly as it stood at a known block — useful for tax lot reconstruction, snapshot audits, or governance-vote eligibility checks:

    ```javascript theme={null}
    async function getPortfolioAtBlock(address, blockNumber) {
      const response = await fetch(
        `https://api.octav.fi/v1/portfolio/at-block?addresses=${address}&chainKey=ethereum&blockNumber=${blockNumber}`,
        { headers: { 'Authorization': `Bearer ${apiKey}` } }
      );
      return response.json();
    }

    const snapshot = await getPortfolioAtBlock('0x6426af...', 19000000);
    console.log(`Net worth at block ${snapshot.blockNumber}: $${snapshot.networth}`);
    ```
  </Tab>

  <Tab title="Compare Blocks" icon="scale-balanced">
    Diff net worth across two blocks (e.g. before/after a known event):

    ```javascript theme={null}
    const [before, after] = await Promise.all([
      fetch(`https://api.octav.fi/v1/portfolio/at-block?addresses=${address}&chainKey=ethereum&blockNumber=19000000`,
        { headers: { 'Authorization': `Bearer ${apiKey}` } }).then(r => r.json()),
      fetch(`https://api.octav.fi/v1/portfolio/at-block?addresses=${address}&chainKey=ethereum&blockNumber=19100000`,
        { headers: { 'Authorization': `Bearer ${apiKey}` } }).then(r => r.json())
    ]);

    const change = parseFloat(after.networth) - parseFloat(before.networth);
    console.log(`Change between blocks: $${change.toFixed(2)}`);
    ```
  </Tab>
</Tabs>

***

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    Input validation failed (Joi structured error).

    ```json theme={null}
    {
      "error": "Validation Failed",
      "details": {
        "query": [
          {
            "message": "\"chainKey\" must be one of [ethereum]",
            "path": ["chainKey"],
            "type": "any.only"
          }
        ]
      }
    }
    ```

    **Common causes:**

    * Missing `addresses`, `chainKey`, or `blockNumber`
    * `chainKey` is not `ethereum` (the only currently supported chain)
    * `blockNumber` is not a positive integer
    * `addresses` is not a single valid EVM address
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    Missing/invalid API key, **or** your key does not have the Portfolio at Block add-on enabled.

    ```json theme={null}
    {
      "message": "Unauthorized"
    }
    ```

    **Solution:** Check your API key in the Authorization header. If the key is valid, contact sales to enable the Portfolio at Block add-on.
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="gauge-high">
    Rate limit exceeded (100 requests/min on this endpoint's dedicated bucket).

    ```json theme={null}
    {
      "error": "Rate limit exceeded",
      "message": "You have exceeded your rate limit",
      "retry_after": 60
    }
    ```

    **Solution:** Wait for the specified time or implement retry logic.
  </Accordion>

  <Accordion title="402 Payment Required" icon="credit-card">
    Insufficient credits.

    ```json theme={null}
    {
      "error": "Insufficient credits",
      "message": "Please purchase more credits to continue"
    }
    ```

    **Solution:** Purchase more credits at [data.octav.fi](https://data.octav.fi/)
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Upstream failure fetching Portfolio at Block data.

    ```
    Error fetching block-pinned portfolio information
    ```
  </Accordion>
</AccordionGroup>

***

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Portfolio" icon="wallet" href="/api/endpoints/portfolio">
    Current portfolio state
  </Card>

  <Card title="Historical Portfolio" icon="clock" href="/api/endpoints/historical-portfolio">
    Portfolio snapshot for a specific calendar date
  </Card>

  <Card title="Chains" icon="link-simple" href="/api/endpoints/chains">
    List all supported blockchain networks
  </Card>

  <Card title="Status" icon="signal" href="/api/endpoints/status">
    Check when portfolio was last synced
  </Card>
</CardGroup>