Examples - Octav Developer Docs

Practical examples that build from one-liners to full automation scripts. Every command is copy-pasteable and every JSON output is realistic.

Want scheduled automations? See the Automations page for production-ready cron jobs — airdrop scanners, transaction monitors, nightly exports, and more.

All examples assume you’ve already authenticated with octav auth set-key YOUR_API_KEY. See Authentication for setup.

1. Quick Portfolio Check

Start with simple one-liners to explore a wallet.

# Get net asset value
octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

{
  "nav": 184230.41,
  "currency": "USD",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
}

# Get top tokens by value using jq
octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --raw \
  | jq '[.tokens | sort_by(-.value) | .[:5][] | {symbol, value: (.value | round), chain}]'

[
  { "symbol": "ETH", "value": 82903, "chain": "ethereum" },
  { "symbol": "USDC", "value": 38088, "chain": "ethereum" },
  { "symbol": "WBTC", "value": 27634, "chain": "ethereum" },
  { "symbol": "ARB", "value": 14738, "chain": "arbitrum" },
  { "symbol": "AAVE", "value": 11053, "chain": "ethereum" }
]

# Check remaining API credits
octav credits

{
  "credits": 4872
}

2. Daily Portfolio Monitor

A cron-ready script that logs NAV to a CSV and alerts on drops.

#!/bin/bash
# daily-monitor.sh — Track portfolio value and alert on drops

ADDR="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
LOG_FILE="$HOME/portfolio-nav.csv"
THRESHOLD=150000  # Alert if NAV drops below this

# Initialize CSV if it doesn't exist
[ ! -f "$LOG_FILE" ] && echo "date,nav" > "$LOG_FILE"

# Fetch current NAV
NAV=$(octav portfolio nav --addresses "$ADDR" --raw | jq -r '.nav')
DATE=$(date +%Y-%m-%d)

# Append to log
echo "$DATE,$NAV" >> "$LOG_FILE"

echo "[$DATE] Portfolio NAV: \$$NAV"

# Alert on significant drop
if (( $(echo "$NAV < $THRESHOLD" | bc -l) )); then
  echo "ALERT: Portfolio below \$$THRESHOLD — current value: \$$NAV"
  # Add your notification here (email, Slack webhook, etc.)
fi

Set it up with cron:

# Run daily at 8am
crontab -e
# Add: 0 8 * * * /path/to/daily-monitor.sh

3. Multi-Wallet Aggregation

Aggregate NAV across multiple wallets into a summary.

#!/bin/bash
# aggregate-nav.sh — Sum NAV across all treasury wallets

WALLETS="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68,0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B,7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

echo "Treasury NAV Report — $(date +%Y-%m-%d)"
echo "================================"

# Fetch NAV for all wallets in one call
RESULT=$(octav portfolio nav --addresses "$WALLETS" --raw)

# Parse and display per-wallet breakdown
echo "$RESULT" | jq -r '
  .wallets[] |
  "  \(.address[0:6])...\(.address[-4:]): $\(.nav | round)"
'

# Calculate total
TOTAL=$(echo "$RESULT" | jq '[.wallets[].nav] | add | round')
echo "================================"
echo "  Total: \$$TOTAL"

Treasury NAV Report — 2025-01-15
================================
  0x742d...2bD68: $184230
  0xAb58...eC9B: $2847102
  7xKXtg...gAsU: $163230
================================
  Total: $3194562

4. Transaction Export to CSV

Fetch a year of transactions and convert to a spreadsheet-ready CSV.

# Fetch all 2024 transactions
octav transactions get \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --limit 250 \
  --raw \
  | jq -r '
    ["date","type","chain","token","amount","value_usd"],
    (.transactions[] |
      [.date, .type, .chain, .token_symbol, .amount, .value_usd]
    ) | @csv
  ' > transactions-2024.csv

# Preview the first few rows
head -5 transactions-2024.csv

"date","type","chain","token","amount","value_usd"
"2024-01-03","swap","ethereum","ETH","2.5","5875.00"
"2024-01-03","swap","ethereum","USDC","-5875.00","-5875.00"
"2024-01-07","transfer","ethereum","ETH","1.0","2340.00"

5. Whale Alert Script

Monitor a wallet for large transactions and log alerts.

#!/bin/bash
# whale-alert.sh — Detect large transactions

ADDR="0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
ALERT_THRESHOLD=50000  # USD value
CHECK_INTERVAL=300     # seconds (5 minutes)
LAST_CHECK_FILE="/tmp/whale-alert-last-check"

# Initialize last check time
[ ! -f "$LAST_CHECK_FILE" ] && date -u +%Y-%m-%d > "$LAST_CHECK_FILE"

SINCE=$(cat "$LAST_CHECK_FILE")

while true; do
  echo "[$(date)] Checking for whale transactions since $SINCE..."

  # Fetch recent transactions
  TXNS=$(octav transactions get \
    --addresses "$ADDR" \
    --start-date "$SINCE" \
    --limit 50 \
    --raw)

  # Filter for large transactions
  echo "$TXNS" | jq -r --argjson threshold "$ALERT_THRESHOLD" '
    .transactions[]
    | select(.value_usd > $threshold)
    | "WHALE ALERT: \(.type) \(.amount) \(.token_symbol) ($\(.value_usd)) on \(.chain) — \(.date)"
  '

  # Update last check
  date -u +%Y-%m-%d > "$LAST_CHECK_FILE"
  sleep "$CHECK_INTERVAL"
done

[2025-01-15 14:30:01] Checking for whale transactions since 2025-01-15...
WHALE ALERT: swap 80.0 ETH ($276000) on ethereum — 2025-01-15
WHALE ALERT: transfer 500000.0 USDC ($500000) on ethereum — 2025-01-15

6. AI Agent Tool-Use

See how an AI agent like Claude Code uses the CLI as a tool.

You give the agent an instruction

Check the portfolio value for 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68,
then analyze the DeFi positions and suggest rebalancing opportunities.

The agent runs CLI commands

octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --raw

The agent receives structured JSON

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
  "nav": 184230.41,
  "tokens": [
    { "symbol": "ETH", "balance": 22.4, "value": 82903, "chain": "ethereum" },
    { "symbol": "USDC", "balance": 38088, "value": 38088, "chain": "ethereum" },
    { "symbol": "WBTC", "balance": 0.42, "value": 27634, "chain": "ethereum" }
  ],
  "protocols": [
    {
      "name": "Aave V3",
      "chain": "ethereum",
      "supplied": 55400,
      "borrowed": 8200,
      "health_factor": 2.14
    },
    {
      "name": "Uniswap V3",
      "chain": "arbitrum",
      "liquidity": 12303,
      "in_range": true
    }
  ]
}

The agent produces analysis

Portfolio Analysis — $184,230

Your DeFi positions look healthy:
• Aave V3: $55.4K supplied, $8.2K borrowed (health factor 2.14 — safe)
• Uniswap V3: $12.3K LP, currently in range

Rebalancing Suggestions:
1. Your WBTC ($27.6K) is sitting idle — deposit into Aave to earn
   0.5-2% APY and improve capital efficiency
2. Consider narrowing your Uniswap V3 range for higher fee capture
   (current range may be too wide)
3. 45% ETH concentration is aggressive — if you're bearish short-term,
   rotating 10% to stables would bring you to a more neutral position

7. Airdrop Checker

Quick check for Solana airdrop eligibility with formatted output.

# Check airdrop eligibility
octav airdrop --address 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU --raw \
  | jq -r '
    "Airdrop Eligibility — \(.address[0:6])...\(.address[-4:])\n",
    (.airdrops[] |
      if .eligible then
        "  ✓ \(.program): \(.amount) \(.token) (~$\(.value_usd))"
      elif .claimed then
        "  ✔ \(.program): CLAIMED"
      else
        "  ✗ \(.program): Not eligible"
      end
    ),
    "",
    "Unclaimed value: $\([.airdrops[] | select(.eligible) | .value_usd] | add)"
  '

Airdrop Eligibility — 7xKXtg...gAsU

  ✓ Jupiter (JUP): 847 JUP (~$512)
  ✔ Tensor (TNSR): CLAIMED
  ✓ Parcl (PRCL): 340 PRCL (~$89)
  ✗ Drift (DRIFT): Not eligible

Unclaimed value: $601

Tips & Patterns

Use --raw for scripting

The --raw flag outputs compact JSON and includes the full API response — ideal for piping to jq or feeding to AI agents.

# Pretty-printed (human-friendly)
octav credits

# Compact JSON (script-friendly)
octav credits --raw

Live monitoring with watch

Use watch for a live-updating dashboard in your terminal.

# Update NAV every 60 seconds
watch -n 60 'octav portfolio nav \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --raw | jq .'

Error handling in scripts

Always check the exit code and handle errors gracefully.

RESULT=$(octav portfolio nav --addresses "$ADDR" --raw 2>&1)
if [ $? -ne 0 ]; then
  echo "Error: $RESULT" >&2
  exit 1
fi
NAV=$(echo "$RESULT" | jq -r '.nav')

Credit budgeting

Most commands cost 1 credit per address. Plan your scripts accordingly.

# Check credits before a big batch job
CREDITS=$(octav credits --raw | jq -r '.credits')
NEEDED=30  # 10 addresses × 3 commands
if [ "$CREDITS" -lt "$NEEDED" ]; then
  echo "Need $NEEDED credits but only have $CREDITS"
  exit 1
fi

Next Steps

Install CLI

One-command install for macOS and Linux

All Commands

Full command reference with flags

MCP Server

Connect to AI assistants directly via MCP

​1. Quick Portfolio Check

​2. Daily Portfolio Monitor

​3. Multi-Wallet Aggregation

​4. Transaction Export to CSV

​5. Whale Alert Script

​6. AI Agent Tool-Use

​7. Airdrop Checker

​Tips & Patterns

​Next Steps

Install CLI

All Commands

MCP Server

1. Quick Portfolio Check

2. Daily Portfolio Monitor

3. Multi-Wallet Aggregation

4. Transaction Export to CSV

5. Whale Alert Script

6. AI Agent Tool-Use

7. Airdrop Checker

Tips & Patterns

Next Steps