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.
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.
Authentication and limits
| Auth | Authorization: Bearer <key> — keys from 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.
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.
Other ways in
The same data is available through an MCP server for AI agents, a Rust CLI and x402, and an embeddable widget if you want UI rather than JSON.
Keep reading
API & DevelopersHow to Choose a Crypto Portfolio API
A buyer's guide to evaluating crypto portfolio APIs — the tests to run, the questions vendors dislike, and the trade-offs between coverage, cost and latency.
2 min read
API & DevelopersHow to Pull Portfolio Data From a Crypto API
A practical walkthrough of fetching multi-chain wallet balances, protocol positions and transaction history from a crypto portfolio API, with worked examples.
1 min read
API & DevelopersEvery Octav Tool and When to Use It
A map of the Octav toolset — dashboard, API, CLI, MCP server, widgets, snapshots, transparency pages and free utilities — and which one fits which job.
2 min read