CLI - Octav Developer Docs

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

Shell Script (Recommended)
Cargo
From Source

Works on macOS and Linux:

curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh

If you have Rust installed:

cargo install octav

Clone and build:

git clone https://github.com/Octav-Labs/octav-cli.git
cd octav-cli
cargo build --release
cp target/release/octav /usr/local/bin/

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:

--api-key flag (highest precedence)
OCTAV_API_KEY environment variable
~/.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

octav portfolio get

Full portfolio including DeFi positions across all chains.

octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit per address

octav portfolio wallet

Wallet token balances only (excludes DeFi protocol positions).

octav portfolio wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit per address

octav portfolio nav

Net asset value in a specified currency.

octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --currency EUR

Supported fiat currencies: USD (default), EUR, CAD, AED, CHF, SGD. Crypto: ETH, SOL, cbBTC, EURC, BNB.Cost: 1 credit per address

octav portfolio token-overview

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

octav transactions get

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

Flag	Description	Default
`--chain`	Filter by chain	all
`--type`	Filter by transaction type	all
`--start-date`	Start date (YYYY-MM-DD)	—
`--end-date`	End date (YYYY-MM-DD)	—
`--offset`	Pagination offset	`0`
`--limit`	Results per page (max 250)	`50`

Cost: 1 credit per address

octav transactions sync

Trigger manual transaction synchronization.

octav transactions sync --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit per address

Historical

octav historical get

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

octav status

Check sync status for addresses.

octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: Free

octav credits

Check API credit balance.

octav credits

Cost: Free

octav airdrop

Check Solana airdrop eligibility.

octav airdrop --address 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

Cost: 1 credit

octav polymarket

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.

Use these only when the user explicitly asks for x402, or when the agent has a funded wallet and no API key — otherwise use the API-key commands above. Only wallet, portfolio, nav, status, and chains are available over x402; everything else, including transaction history, needs an API key. See Agent Endpoints (x402).

octav agent wallet

Wallet holdings via x402 payment.

octav agent wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

octav agent portfolio

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
  }
}

Error	Cause	Solution
Invalid address format	Address doesn’t match EVM or Solana format	Use `0x...` (40 hex chars) for EVM or base58 for Solana
Authentication failure	Missing or invalid API key	Run `octav auth set-key` or set `OCTAV_API_KEY`
Insufficient credits	Not enough credits for the request	Purchase more at data.octav.fi

Resources

GitHub

Source code and issues

API Docs

Full REST API reference

Pricing

Credit packages and costs

​Why Use the CLI?

AI Agent Tool-Use

Terminal Workflows

Fast & Lightweight

x402 Agent Payments

​Installation

​Authentication

​Commands

​Portfolio

​Transactions

​Historical

​Metadata & Specialized

​Agent Commands (x402)

​Using with AI Agents

​Example: Claude Code / Cursor Agent

​Example: Autonomous Monitoring Script

​Output Format

​Multiple Addresses

​Error Handling

​Resources

GitHub

API Docs

Pricing

Why Use the CLI?

Installation

Authentication

Commands

Portfolio

Transactions

Historical

Metadata & Specialized

Agent Commands (x402)

Using with AI Agents

Example: Claude Code / Cursor Agent

Example: Autonomous Monitoring Script

Output Format

Multiple Addresses

Error Handling

Resources