> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Copy-pasteable CLI commands and scripts for portfolio monitoring, data export, and AI agent workflows

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

<Tip>
  Want scheduled automations? See the [Automations](/cli/automations) page for production-ready cron jobs — airdrop scanners, transaction monitors, nightly exports, and more.
</Tip>

<Info>
  All examples assume you've already authenticated with `octav auth set-key YOUR_API_KEY`. See [Authentication](/cli/overview#authentication) for setup.
</Info>

***

## 1. Quick Portfolio Check

Start with simple one-liners to explore a wallet.

```bash theme={null}
# Get net asset value
octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
```

```json theme={null}
{
  "nav": 184230.41,
  "currency": "USD",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
}
```

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

```json theme={null}
[
  { "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" }
]
```

```bash theme={null}
# Check remaining API credits
octav credits
```

```json theme={null}
{
  "credits": 4872
}
```

***

## 2. Daily Portfolio Monitor

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

```bash theme={null}
#!/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:

```bash theme={null}
# 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.

```bash theme={null}
#!/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"
```

```text theme={null}
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.

```bash theme={null}
# 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
```

```csv theme={null}
"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.

```bash theme={null}
#!/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
```

```text theme={null}
[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.

<Steps>
  <Step title="You give the agent an instruction">
    ```text theme={null}
    Check the portfolio value for 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68,
    then analyze the DeFi positions and suggest rebalancing opportunities.
    ```
  </Step>

  <Step title="The agent runs CLI commands">
    ```bash theme={null}
    octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --raw
    ```
  </Step>

  <Step title="The agent receives structured JSON">
    ```json theme={null}
    {
      "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
        }
      ]
    }
    ```
  </Step>

  <Step title="The agent produces analysis">
    ```text theme={null}
    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
    ```
  </Step>
</Steps>

***

## 7. Airdrop Checker

Quick check for Solana airdrop eligibility with formatted output.

```bash theme={null}
# 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)"
  '
```

```text theme={null}
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

<AccordionGroup>
  <Accordion title="Use --raw for scripting" icon="code">
    The `--raw` flag outputs compact JSON and includes the full API response — ideal for piping to `jq` or feeding to AI agents.

    ```bash theme={null}
    # Pretty-printed (human-friendly)
    octav credits

    # Compact JSON (script-friendly)
    octav credits --raw
    ```
  </Accordion>

  <Accordion title="Live monitoring with watch" icon="eye">
    Use `watch` for a live-updating dashboard in your terminal.

    ```bash theme={null}
    # Update NAV every 60 seconds
    watch -n 60 'octav portfolio nav \
      --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
      --raw | jq .'
    ```
  </Accordion>

  <Accordion title="Error handling in scripts" icon="shield">
    Always check the exit code and handle errors gracefully.

    ```bash theme={null}
    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')
    ```
  </Accordion>

  <Accordion title="Credit budgeting" icon="tag">
    Most commands cost 1 credit per address. Plan your scripts accordingly.

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Install CLI" icon="bolt" href="/cli/overview#installation">
    One-command install for macOS and Linux
  </Card>

  <Card title="All Commands" icon="terminal" href="/cli/overview#commands">
    Full command reference with flags
  </Card>

  <Card title="MCP Server" icon="robot" href="/mcp/overview">
    Connect to AI assistants directly via MCP
  </Card>
</CardGroup>