> ## 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.

# Crypto Portfolio API

> Integrate multi-chain crypto portfolio tracking, decoded DeFi positions and transaction history into your application with the Octav REST API.

Welcome to the Octav API documentation. Here you'll find everything you need to integrate cryptocurrency portfolio tracking, transaction history, and analytics into your applications.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/api/quickstart">
    Get started with your first API call in minutes
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="API Reference" icon="code" href="/api/endpoints/portfolio">
    Explore all available endpoints
  </Card>

  <Card title="Pricing" icon="credit-card" href="/api/pricing">
    Understand our credit-based pricing model
  </Card>
</CardGroup>

***

## What You Can Build

The Octav API enables you to:

<AccordionGroup>
  <Accordion title="Portfolio Tracking" icon="wallet">
    * Retrieve real-time portfolio balances across multiple chains
    * Track assets in wallets and DeFi protocols
    * Monitor net worth and PnL metrics
    * Include protocol positions
  </Accordion>

  <Accordion title="Transaction History" icon="clock-rotate-left">
    * Access complete transaction history
    * Filter by chain, protocol, transaction type
    * Search transactions with full-text search
    * Track fees and profit/loss per transaction
  </Accordion>

  <Accordion title="Token Analytics" icon="chart-line">
    * Get detailed token breakdowns by protocol
    * View token distribution across positions
    * Track token balances and valuations
    * Monitor historical token holdings
  </Accordion>

  <Accordion title="Historical Data" icon="calendar">
    * Retrieve historical portfolio snapshots
    * Subscribe to addresses for daily snapshots
    * Analyze portfolio performance over time
    * Track net worth changes
  </Accordion>
</AccordionGroup>

***

## Key Features

<CardGroup cols={3}>
  <Card title="Multi-Chain Support" icon="link">
    Support for 20+ blockchain networks including Ethereum, Arbitrum, Base, Solana, and more
  </Card>

  <Card title="Real-Time Data" icon="bolt">
    Fresh data with 1-minute caching and on-demand sync capabilities
  </Card>

  <Card title="DeFi Protocol Coverage" icon="vault">
    Track positions across hundreds of DeFi protocols automatically
  </Card>

  <Card title="Credit-Based Pricing" icon="coins">
    Pay only for what you use with our flexible credit system
  </Card>

  <Card title="SOC 2 Compliant" icon="https://mintcdn.com/octav-0131e508/anHQal-NxcOY-dXz/logo/SOC2_Logo_Revised_1_.591b2acad61e2.png?fit=max&auto=format&n=anHQal-NxcOY-dXz&q=85&s=42d93e509c50fd269247cb4f2bb1ba55" width="802" height="802" data-path="logo/SOC2_Logo_Revised_1_.591b2acad61e2.png">
    Enterprise-grade security and compliance standards
  </Card>

  <Card title="Production Ready" icon="check-circle">
    Rate limiting, error handling, and status monitoring built-in
  </Card>
</CardGroup>

***

## API Overview

### Base URL

```
https://api.octav.fi
```

### Authentication

All API requests require an API key passed in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Info>
  **Get Your API Key** — Create and manage API keys at [data.octav.fi](https://data.octav.fi/)
</Info>

### Rate Limits

<Card title="Rate Limit" icon="gauge">
  **360 requests / minute / API key**

  Higher limits available upon request
</Card>

### Response Format

All endpoints return JSON responses with consistent structure:

```json theme={null}
{
  "data": { ... },
  "status": "success"
}
```

***

## All Endpoints

The complete API surface. Every endpoint uses `Authorization: Bearer YOUR_API_KEY` against the base URL `https://api.octav.fi`.

| Endpoint | Method | Description | Cost |
| - | - | - | - |
| [`/v1/portfolio`](/api/endpoints/portfolio) | GET | Holdings across wallets and DeFi protocols | 1 credit |
| [`/v1/portfolio/at-block`](/api/endpoints/portfolio-at-block) | GET | Portfolio valued at a historical block (Ethereum, Linea, Monad) | Add-on + 1 credit |
| [`/v1/virtual-users`](/api/endpoints/virtual-users) | GET | List virtual users (Pro) | 1 credit |
| [`/v1/virtual-users/portfolio`](/api/endpoints/virtual-users) | GET | Virtual user holdings (Pro) | 1 credit / address |
| [`/v1/nav`](/api/endpoints/nav) | GET | Net Asset Value — `{nav, currency, conversionPrice}` | 1 credit |
| [`/v1/wallet`](/api/endpoints/wallet) | GET | Wallet token balances, excluding DeFi positions | 1 credit |
| [`/v1/transactions`](/api/endpoints/transactions) | GET | Transaction history with filtering and search | 1 credit |
| [`/v1/approvals/{chain}`](/api/endpoints/approvals) | GET | ERC-20 token approval records | 1 credit |
| [`/v1/token-overview`](/api/endpoints/token-overview) | GET | Token breakdown by protocol (Pro) | 1 credit |
| [`/v1/airdrop`](/api/endpoints/airdrop) | GET | Claimable airdrops (Solana) | 1 credit |
| [`/v1/historical`](/api/endpoints/historical-portfolio) | GET | Portfolio snapshot for a past date | 1 credit |
| [Subscribe Snapshot](/api/endpoints/subscribe-snapshot) | POST | Enable daily portfolio snapshots | 1200 credits |
| [`/v1/sync-transactions`](/api/endpoints/sync) | POST | Trigger transaction indexing | 1 credit + 1 / 250 txns |
| [`/v1/contract-protocol`](/api/endpoints/contract-protocol) | GET | Resolve a contract address to its DeFi protocol | 5 credits (refunded on 404) |
| [`/v1/beacon/validators/*`](/api/endpoints/beacon-validators) | GET | Ethereum validator details, rewards, withdrawals, deposits | Add-on |
| [`/v1/chains`](/api/endpoints/chains) | GET | Supported blockchain networks | Free |
| [`/v1/chains/{chainKey}/protocols`](/api/endpoints/protocols) | GET | Protocols available on a chain | Free |
| [`/v1/status`](/api/endpoints/status) | GET | Sync status and data freshness | Free |
| [`/v1/credits`](/api/endpoints/credits) | GET | Remaining credit balance | Free |

<Note>
  **This API-key REST API is the default way to use Octav.** A subset of five endpoints is also available without an API key via the x402 payment protocol at [`/v1/agent/*`](/api/endpoints/agent-x402) — use that only if you specifically want pay-per-call, or your agent holds a wallet and cannot store an API key. Transaction history is **not** available over x402.
</Note>

### Most-used endpoints

<CardGroup cols={2}>
  <Card title="Portfolio" icon="wallet" href="/api/endpoints/portfolio">
    **GET** `/v1/portfolio`

    Retrieve portfolio holdings with asset breakdown by protocol and chain

    **Cost:** 1 credit per call
  </Card>

  <Card title="Virtual Users" icon="users" href="/api/endpoints/virtual-users">
    **GET** `/v1/virtual-users` · `/v1/virtual-users/portfolio`

    List virtual users and retrieve their portfolio holdings (Pro)

    **Cost:** 1 credit per call / per address
  </Card>

  <Card title="Nav" icon="wallet" href="/api/endpoints/nav">
    **GET** `/v1/nav`

    Retrieve Net Asset Value of an address

    **Cost:** 1 credit per call
  </Card>

  <Card title="Transactions" icon="receipt" href="/api/endpoints/transactions">
    **GET** `/v1/transactions`

    Get paginated transaction history with filtering and search

    **Cost:** 1 credit per call
  </Card>

  <Card title="Token Overview" icon="coins" href="/api/endpoints/token-overview">
    **GET** `/v1/token-overview`

    Detailed token breakdown across wallet and protocol positions

    **Cost:** 1 credit per call
  </Card>

  <Card title="Historical Portfolio" icon="clock" href="/api/endpoints/historical-portfolio">
    **GET** `/v1/historical`

    Retrieve historical portfolio snapshots for any date

    **Cost:** 1 credit per call
  </Card>

  <Card title="Sync Transactions" icon="arrows-rotate" href="/api/endpoints/sync">
    **POST** `/v1/sync-transactions`

    Trigger transaction synchronization for an address

    **Cost:** 1 credit + 1 per 250 txns
  </Card>

  <Card title="Status" icon="signal" href="/api/endpoints/status">
    **GET** `/v1/status`

    Check sync status and data freshness

    **Cost:** Free (0 credits)
  </Card>

  <Card title="Credits" icon="credit-card" href="/api/endpoints/credits">
    **GET** `/v1/credits`

    Check your remaining credit balance

    **Cost:** Free (0 credits)
  </Card>
</CardGroup>

***

## Next Steps

<Steps>
  <Step title="Get Your API Key" icon="key">
    Visit [data.octav.fi](https://data.octav.fi/) to create your API key
  </Step>

  <Step title="Make Your First Request" icon="code">
    Follow our [Quickstart Guide](/api/quickstart) to make your first API call
  </Step>

  <Step title="Explore Endpoints" icon="compass">
    Browse the [API Reference](/api/endpoints/portfolio) to see all available endpoints
  </Step>

  <Step title="Monitor Usage" icon="chart-line">
    Track your credit usage and manage your account at the [Dev Portal](https://data.octav.fi/)
  </Step>
</Steps>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Join Discord" icon="discord" href="https://discord.com/invite/qvcknAa73A">
    Get help from the team and community
  </Card>

  <Card title="Contact Us" icon="envelope" href="/docs/contact-us">
    Reach out for enterprise support
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.