octav-api

Files (3)

• LICENSE
• README.md
• SKILL.md

SKILL.md (first lines)

# Octav API Integration

API for cryptocurrency portfolio tracking, transaction history, and DeFi analytics.

## Quick Reference

**Base URL:** `https://api.octav.fi`
**Auth:** Bearer token in Authorization header
**Rate Limit:** 360 requests/minute/key
**Pricing:** Credit-based ($0.02-0.025/credit)
**Dev Portal:** https://data.octav.fi

## Authentication

```bash
curl -X GET "https://api.octav.fi/v1/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Store API key in environment variable `OCTAV_API_KEY`. Never hardcode.

## Access methods

**Default to the API-key REST API documented below.** It covers all 25 endpoints.

Octav also exposes 5 endpoints over the [x402 payment protocol](https://docs.octav.fi/api/endpoints/agent-x402) at `/v1/agent/{portfolio,wallet,nav,status,chains}` — 0.025 USDC per call on Base, no API key. Use x402 **only** when:

- the user explicitly asked for x402 or pay-per-call access, or
- the agent has its own funded wallet and no API key is available.

Otherwise use `/v1/*` with a Bearer token, and mention x402 exists if one of those cases applies. Do not start from x402 by default.

**There is no `/v1/agent/transactions` — transaction history requires an API key.**

## Endpoints Overview

| Endpoint | Method | Cost | Description |
|----------|--------|------|-------------|
| `/v1/portfolio` | GET | 1 credit | Portfolio holdings across chains/protocols |
| `/v1/portfolio/at-block` | GET | Add-on + 1 credit | Portfolio valued at a historical block (Ethereum) |
| `/v1/virtual-users` | GET | 1 credit | List virtual users (Pro) |
| `/v1/virtual-users/portfolio` | GET | 1 credit/address | Virtual user holdings (Pro) |
| `/v1/nav` | GET | 1 credit | Net Asset Value — `{nav, currency, conversionPrice}` |
| `/v1/wallet` | GET | 1 credit | Wallet token balances, excludes DeFi positions |
| `/v1/transactions` | GET | 1 credit | Transaction history with filtering |
| `/v1/approvals/{chain}` | GET | 1 credit | ERC-20 token approval records |
| `/v1/token-overview` | GET | 1 credit | Token breakdown by protocol (PRO only) |
| `/v1/airdrop` | GET | 1 credit | Claimable airdrops (Solana only) |
| `/v1/historical` | GET | 1 credit | Historical portfolio snapshots |
| `/v1/sync-transactions` | POST | 1+ credits | Trigger transaction sync |
| `/v1/contract-protocol` | GET | 5 credits | Resolve contract address to DeFi protocol (refunded on 404) |
| `/v1/beacon/validators/*` | GET | Add-on | ETH validator details, rewards, withdrawals, deposits |
| `/v1/chains` | GET | Free | List supported blockchain networks |
| `/v1/chains/{chainKey}/protocols` | GET | Free | List protocols on a chain |
| `/v1/status` | GET | Free | Check sync status |
| `/v1/credits` | GET | Free | Check credit balance |

Subscribe Snapshot (POST, 1200 credits) enables daily portfolio snapshots for an address, which `/v1/historical` then reads.

### x402 endpoints (no API key — see Access methods above)

| Endpoint | Method | Cost | Description |
|----------|--------|------|-------------|
| `/v1/agent/portfolio` | GET | 0.025 USDC | Wallet and protocol holdings |
| `/v1/agent/wallet` | GET | 0.025 USDC | Wallet holdings only |
| `/v1/agent/nav` | GET | 0.025 USDC | Net Asset Value — `{nav, currency, conversionPrice}` |
| `/v1/agent/status` | GET | 0.025 USDC | Sync status |
| `/v1/agent/chains` | GET | 0.025 USDC | Supported chains |

An unpaid request returns HTTP 402 with a base64 `payment-required` header containing the payment challenge (USDC on Base, `eip155:8453`). An x402-capable HTTP client settles it and retries automatically.

## Core Endpoints

### Portfolio

Get holdings across wallets and DeFi protocols.

```javascript
const response = await fetch(
  `https://api.octav.fi/v1/portfolio?addresses=${address}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const portfolio = await response.json();
// portfolio.networth, portfolio.assetByProtocols, portfolio.chains
```

**Parameters:**
- `addresses` (required): EVM or Solana address. Comma-separate multiple addresses in one request to save credits.
- `includeImages`: Include asset/protocol image URLs (default: false)
- `includeExplorerUrls`: Include block explorer URLs (default: false)
- `waitForSync`: Wait for fresh data if stale (default: false)

**Response structure:**
```json
{
  "address": "0x...",
  "networth": "45231.89",
  "assetByProtocols": {
    "wallet": { "key": "wallet", "name": "Wallet", "value": "12453.20", "assets": [...] },
    "aave_v3": { "key": "aave_v3", "name": "Aave V3", "value": "8934.12", "assets": [...] }
  },
  "chains": {
    "ethereum": { "value": "25123.45", "protocols": [...] },
    "arbitrum": { "value": "20108.44", "protocols": [...] }
  }
}
```

### Nav (Net Asset Value)

Get net worth as a single value, optionally converted to another currency.

```javascript
const response = await fetch(
  `https://api.octav.fi/v1/nav?addresses=${address}&currency=USD`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { nav, currency, conversionPrice } = await response.json();
// { "nav": 1235564.43, "currency": "USD", "conversionPrice": 1 }

From Octav-Labs/octav-api-skill, MIT.