Skip to main content
The official Octav CLI lets you interact with the Octav API directly from your terminal. Built in Rust for speed, it outputs structured JSON — making it ideal for shell scripts, CI pipelines, and AI agent tool-use.
Quick Install — One command to get started:
curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh

​
Why Use the CLI?

AI Agent Tool-Use

Structured JSON output that AI agents can parse and act on — no SDK or HTTP client needed

Terminal Workflows

Pipe portfolio data into jq, scripts, cron jobs, or monitoring systems

Fast & Lightweight

Written in Rust — single binary, no runtime dependencies, instant startup

x402 Agent Payments

Built-in support for the x402 payment protocol — AI agents can pay per request without API keys

​
Installation

​
Authentication

Store your API key once and it’s used automatically for all commands. 
# Store your API key (get one at https://data.octav.fi)
octav auth set-key YOUR_API_KEY

# Verify it's set
octav auth show
The API key is resolved in priority order:
  1. --api-key flag (highest precedence)
  2. OCTAV_API_KEY environment variable
  3. ~/.octav/config.json config file
For AI agent workflows, set the OCTAV_API_KEY environment variable so the agent doesn’t need to manage config files.

​
Commands

​
Portfolio

Full portfolio including DeFi positions across all chains.
octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Cost: 1 credit per address
Wallet token balances only (excludes DeFi protocol positions).
octav portfolio wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Cost: 1 credit per address
Net asset value in a specified currency.
octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --currency EUR
Supported currencies: USD (default), EUR, GBP, JPY, CNY.Cost: 1 credit per address
Aggregated token distribution across all chains for a specific date.
octav portfolio token-overview \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --date 2024-06-01
Cost: 1 credit per address

​
Transactions

Query transaction history with filtering and pagination.
octav transactions get \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --chain ethereum \
  --type swap \
  --start-date 2024-01-01 \
  --end-date 2024-06-30 \
  --limit 100
FlagDescriptionDefault
--chainFilter by chainall
--typeFilter by transaction typeall
--start-dateStart date (YYYY-MM-DD)—
--end-dateEnd date (YYYY-MM-DD)—
--offsetPagination offset0
--limitResults per page (max 250)50
Cost: 1 credit per address
Trigger manual transaction synchronization.
octav transactions sync --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Cost: 1 credit per address

​
Historical

Portfolio snapshot for a specific date.
octav historical get \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --date 2024-01-01
Cost: 1 credit per address
Subscribe to automatic daily portfolio snapshots.
octav historical subscribe-snapshot \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --description "Main wallet daily snapshot"
Cost: 1 credit per address

​
Metadata & Specialized

Check sync status for addresses.
octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Cost: Free
Check API credit balance.
octav credits
Cost: Free
Check Solana airdrop eligibility.
octav airdrop --address 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
Cost: 1 credit
Get Polymarket prediction market positions.
octav polymarket --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Cost: 1 credit

​
Agent Commands (x402)

For AI agents that pay per request using the x402 payment protocol — no API key required.
Wallet holdings via x402 payment.
octav agent wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
Full portfolio via x402 payment.
octav agent portfolio --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

​
Using with AI Agents

The CLI outputs structured JSON, making it a natural fit for AI agent tool-use. Agents can invoke octav commands via shell execution and parse the JSON response directly.

​
Example: Claude Code / Cursor Agent

"Check the portfolio value for 0xABC... using the octav CLI,
then analyze the DeFi positions and suggest rebalancing opportunities."
The agent runs: 
octav portfolio get --addresses 0xABC... --raw
And receives structured JSON it can reason over.

​
Example: Autonomous Monitoring Script

#!/bin/bash
# Daily portfolio snapshot with alerts

ADDR="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
NAV=$(octav portfolio nav --addresses $ADDR --raw | jq -r '.nav')

echo "Portfolio value: $NAV"

# Agent can parse this output and decide on actions

​
Output Format

All commands return JSON. Pretty-printed by default, compact with --raw: 
# Pretty-printed (default)
octav credits
# => {
# =>   "credits": 42
# => }

# Compact JSON (ideal for piping / agent parsing)
octav credits --raw
# => {"credits":42}
The --raw flag also disables field stripping, returning the full API response.

​
Multiple Addresses

Most commands accept multiple addresses as a comma-separated list: 
octav portfolio get \
  --addresses 0xABC...123,0xDEF...456,7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
Maximum 10 addresses per request.

​
Error Handling

Errors are returned as JSON on stdout with a non-zero exit code: 
{
  "error": {
    "type": "auth",
    "message": "Invalid API key",
    "status": 401
  }
}
ErrorCauseSolution
Invalid address formatAddress doesn’t match EVM or Solana formatUse 0x... (40 hex chars) for EVM or base58 for Solana
Authentication failureMissing or invalid API keyRun octav auth set-key or set OCTAV_API_KEY
Insufficient creditsNot enough credits for the requestPurchase more at data.octav.fi

​
Resources

GitHub

Source code and issues

API Docs

Full REST API reference

Pricing

Credit packages and costs