CLI

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 currencies: USD (default), EUR, GBP, JPY, CNY.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

octav historical subscribe-snapshot

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.

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

Documentation Index

​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