# Crypto Portfolio API Endpoint Reference

> Every Octav API endpoint with its parameters, credit cost and response, plus authentication, rate limits and caching behaviour for building on portfolio data.

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

---
A working reference for the Octav REST API. Base URL `https://api.octav.fi`,
Bearer token authentication, credit-based billing.

For the conceptual walkthrough, start with
[How to Pull Portfolio Data From a Crypto API](/crypto-portfolio-api-guide).

## Authentication and limits

| | |
| --- | --- |
| Auth | `Authorization: Bearer <key>` — keys from [data.octav.fi](https://data.octav.fi) |
| Rate limit | 360 requests/minute per key |
| Rate headers | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` |
| Billing | Credits, roughly $0.020–$0.025 each; most endpoints cost 1 |
| Caching | Portfolio 1 minute, transactions 10 minutes |
| Addresses | EVM (`0x…`) and Solana (base58), comma-separated in one request |

Batching addresses into a single request is the main cost lever: one call with
three addresses costs one credit, three calls cost three.

## Portfolio and valuation

| Endpoint | Method | Credits | Returns |
| --- | --- | --- | --- |
| `/v1/portfolio` | GET | 1 | Multi-chain holdings, decoded DeFi positions, net worth |
| `/v1/nav` | GET | 1 | A single net asset value figure |
| `/v1/wallet` | GET | 1 | Token balances and USD values only |
| `/v1/token-overview` | GET | 1 | Token breakdown by protocol — PRO only |
| `/v1/portfolio/at-block` | GET | 1 + add-on | Valuation at a specific Ethereum block |
| `/v1/historical` | GET | 1 | Portfolio snapshot at a past date |

`/v1/portfolio` is the core endpoint and the one that decodes positions.
`/v1/wallet` deliberately does not — use it when you only want token balances
and want to pay less for them.

## Transactions

| Endpoint | Method | Credits | Returns |
| --- | --- | --- | --- |
| `/v1/transactions` | GET | 1 | Labelled transaction history |
| `/v1/sync-transactions` | POST | 1 + 1 per 250 txns | Triggers indexing for an address |

`/v1/transactions` filters on `limit`, `offset`, `sort`, `chain`, `type`,
`protocol` and `dateRange`, across 53 transaction types. First sync of a busy
address has a variable cost, which is worth knowing before you loop over a
fund's whole address book.

## Snapshots and history

| Endpoint | Method | Credits | Returns |
| --- | --- | --- | --- |
| `/v1/subscribe-snapshot` | POST | 1200 | Enables daily automatic snapshots |
| `/v1/historical` | GET | 1 | Portfolio as of a past date |

Snapshots only record forward from the moment you subscribe — see
[Daily Crypto Portfolio Snapshots](/daily-crypto-portfolio-snapshots).

## Discovery and account (free)

| Endpoint | Credits | Returns |
| --- | --- | --- |
| `/v1/chains` | Free | Supported blockchains |
| `/v1/chains/{chainKey}/protocols` | Free | Protocols on a chain |
| `/v1/status` | Free | Sync status and data freshness for an address |
| `/v1/credits` | Free | Remaining credit balance |

Call `/v1/status` before trusting a portfolio response in a reporting pipeline;
it tells you how fresh the underlying data is.

## Specialised

| Endpoint | Credits | Notes |
| --- | --- | --- |
| `/v1/approvals/{chain}` | 1 | Token approvals — security review |
| `/v1/contract-protocol` | 5 (refunded on 404) | Resolve a contract to a protocol |
| `/v1/airdrop` | 1 | Airdrop eligibility — Solana only |
| `/v1/beacon/validators/*` | Add-on | Ethereum validator details and rewards |
| `/v1/virtual-users` | 1 | PRO only |
| `/v1/virtual-users/portfolio` | 1 per address | PRO only |

## Errors worth handling

| Code | Meaning | What to do |
| --- | --- | --- |
| 401 | Bad or missing key | Check the `Authorization` header |
| 402 | Out of credits | Top up at data.octav.fi |
| 403 | PRO endpoint | Subscribe, or use a non-PRO equivalent |
| 404 | Address not indexed | Above 100k transactions, contact support |
| 429 | Rate limited | Honour `Retry-After`, back off exponentially |

402 is the one people forget. An unhandled 402 in a nightly NAV job produces a
silent gap in your reporting rather than a loud failure.

## Coverage

33+ decoded DeFi position types across lending, liquidity, staking, vaults,
perpetuals and margin, spanning EVM chains, Solana and Hyperliquid. What that
covers in practice is measured in
[the portfolio API benchmark](/crypto-portfolio-api-benchmark).

## Other ways in

The same data is available through an [MCP server](/crypto-portfolio-mcp-server)
for AI agents, a [Rust CLI](/octav-cli-rust) and [x402](/x402-pay-per-call-api), and an
[embeddable widget](/embed-crypto-portfolio-widget) if you want UI rather than
JSON.