Skip to main content
Real-world automation scripts that run on a schedule and notify you when something matters. Each workflow includes the full script, scheduler setup (cron + macOS launchd), realistic output, and customization tips.
All scripts assume you’ve already authenticated with octav auth set-key YOUR_API_KEY. See Authentication for setup. For basic CLI usage and one-liners, see Examples.

1. Daily Airdrop Scanner

Checks a Solana wallet for unclaimed airdrops every day at 2pm. Sends a macOS desktop notification when new airdrops are found and logs results for history.
Sample log output:
Add with crontab -e or pipe it in:
  • Multiple wallets: Loop over an array of addresses and check each one
  • Slack instead of macOS notifications: Replace the osascript line with a curl to a Slack webhook (see the Transaction Watchdog below for an example)
  • Minimum value filter: Add | select(.value_usd > 50) to the jq filter to ignore dust airdrops

2. Transaction Watchdog

Monitors wallets every 10 minutes for new activity. Tracks state to avoid duplicate alerts and supports both macOS notifications and Slack webhooks.
Sample alert output:
  • Multiple wallets: Create separate state files per address — tx-watchdog-${ADDR:0:8}.txt
  • Value filter: Add | select(.value_usd > 1000) to only alert on large transactions
  • Slack setup: Create a webhook at api.slack.com/messaging/webhooks and paste the URL into SLACK_WEBHOOK

3. Nightly Transaction Export

Runs at midnight, exports the day’s transactions to a monthly CSV file. Handles pagination for wallets with high daily activity and appends without duplicates.
Sample CSV output (transactions-2025-01.csv):
File structure:
  • Multiple wallets: Loop over addresses and write to separate files or add an address column
  • Weekly instead of monthly files: Change the filename to transactions-$(date +%Y-W%V).csv
  • Compression: Add gzip "$MONTH_FILE.bak" at the end of each month to archive old files

4. Portfolio Tracker with Weekly Report

Two scripts that work together: a daily NAV snapshot recorder and a weekly report generator that runs every Sunday.

Daily snapshot

Weekly report (Sundays)

Sample weekly report:
Scheduler setup:
  • Multiple wallets: Track each wallet in a separate CSV and combine totals in the weekly report
  • Monthly reports: Add a similar script triggered on the 1st of each month with 0 10 1 * *
  • Historical chart: Feed nav-history.csv into a plotting tool like gnuplot or a Google Sheet for visual trends

5. Credit Usage Guardian

A wrapper script that checks remaining credits before running any CLI command. Tracks daily consumption and alerts when credits drop below a configurable threshold.
Installation:
Sample output — normal operation:
Sample output — credit guard triggered:
Sample daily usage log (credit-usage.log):
  • Shell alias: Add alias octav="octav-safe" to your ~/.bashrc or ~/.zshrc to protect all commands by default
  • Daily summary: Add a cron job that parses the usage log and reports daily consumption — grep "$(date +%Y-%m-%d)" "$USAGE_LOG" | wc -l gives you the day’s command count
  • Tiered warnings: Add a second threshold (e.g., 500) that prints a warning but still allows the command to run

Setting Up launchd on macOS

macOS uses launchd instead of cron for scheduled tasks. While cron works on macOS, launchd is the native scheduler and handles sleep/wake correctly — your task runs after waking up even if the Mac was asleep at the scheduled time.

Step 1: Create the plist file

Each scheduled task needs a .plist file in ~/Library/LaunchAgents/. Use reverse-DNS naming:

Step 2: Load and manage

Step 3: Debug

If your script isn’t running, check the logs:
Common pitfall: launchd doesn’t source your shell profile. If octav isn’t found, use the full path (/usr/local/bin/octav or wherever it’s installed). Find it with which octav.

Next Steps

CLI Overview

Installation, authentication, and full command reference

CLI Examples

One-liners, scripts, and jq patterns

MCP Server

Connect the Octav API directly to AI assistants