Command reference

Every OpenSwap command on one page. If you're new, start with the Quickstart — this page is for looking things up.

A note on examples: placeholders are written in angle brackets, like <AMOUNT> or <ADDRESS>. Replace them with real values — never paste a placeholder into a command that moves money.

How output works

OpenSwap adapts its output to where it's running. In a normal terminal you get the interactive experience. Piped into another program, it switches to clean, stable text automatically. For scripts and bots there are explicit modes:

| Flag | What you get | | --- | --- | | (nothing, in a terminal) | Interactive mode with prompts | | (nothing, piped) | Plain text, tab-separated, no prompts ever | | --plain | The same stable plain text, explicitly | | --json | Exactly one JSON result object on stdout | | --jsonl | One JSON object per line (for streaming commands) | | --no-input | Never prompt; missing input becomes an error | | --no-color | No colors (the NO_COLOR env var works too) |

The JSON result always has the same shape: {schema_version, command, ok, data | error, warnings, meta}. Errors include a machine-readable code, a human message, whether the problem is retryable, an honest funds_may_have_moved flag, and actions — safe next commands to run.

Exit codes

These are frozen — you can script against them and they will not change: 0 success · 1 internal error · 2 bad usage · 3 auth/config problem · 4 no route found or policy said no · 5 temporary upstream problem (retry) · 6 signer problem · 7 broadcast problem · 130 you pressed Ctrl-C.

Everyday commands

openswap

Run with nothing else, it opens the menu: pick a pair, watch routes stream in, trade.

openswap quote -a <amount> -f <from> -t <to>

Compare prices across every route. Read-only and free — no wallet involved. Routes are sorted by what you'd actually receive, and fees are shown honestly: if a provider doesn't price a fee, it says not priced instead of pretending it's zero. Useful extras: --slippage-bps <n> to set your slippage tolerance, --refresh to refetch the asset list.

openswap swap -a <amount> -f <from> -t <to>

The full swap, start to finish: compare routes, lock one, get a deposit address and QR, pay from any wallet, and track to delivery. In scripts, you must be explicit: --to-address, --refund-address, and --yes are all required, because creating a deposit address is a real action. --dry-run rehearses everything without creating anything. --protocol <name> preselects a route.

openswap status [id] [--watch] and openswap resume [id]

Check on a swap, or watch it live until it finishes. With no id, they use your latest swap. A swap ends as success, failed, refunded, or — if a deposit was never paid — deposit_expired.

openswap history

Every swap you've made from this machine, newest first. Pick one to see full details and live tracking.

openswap assets list and openswap assets search <query>

Browse or search the 7,000+ supported assets. --chain <C> filters to one chain; results are cached for a day.

openswap balances <address> --chains A,B,C

Check what an address holds across several chains at once.

Keys and configuration

openswap auth login | status | logout

Store your own API key in the operating system's keychain, see which key is active, or remove it. The key is typed in privately — never passed as a flag, never written to a file. For CI, set OPENSWAP_API_KEY instead. See Keys, fees & founding keys.

openswap config list | get | set

Non-secret settings only. Anything that looks like a secret is refused — secrets belong in the keychain or environment.

openswap doctor

A health check: runtime, terminal capabilities, credential validity, API reachability, and storage. Run it first when something seems off.

Practice and automation

openswap tour

A guided two-minute walkthrough with real prices and a simulated payment. Nothing is saved and nothing real can move.

openswap test …

The sandbox. on/off toggles it, pay simulates paying a deposit, fund sets a pretend balance, scenario picks a default outcome, reset starts a fresh simulated world. Full guide: Test mode.

openswap watch -a <amount> -f <from> -t <to> --jsonl

A live price feed: quotes stream continuously as JSON lines. Built for bots. --once exits after the first full round.

openswap bot init | check | run

Policy-gated automation: init builds your policy file interactively, check tests a trade against it with zero side effects, run executes (simulating first by default). Full guide: Bots & automation.

openswap wallet setup | status

The optional signing wallet, used only for routes that can't work with a deposit address. Setup recommends creating a fresh dedicated wallet rather than importing your main one.

openswap agent setup | status | docs

For AI agents: setup installs the Claude Code skill, docs prints the complete machine contract. See For AI agents.

openswap receipts list | show | export <id>

The raw receipt store — durable local records of every swap. export prints a receipt as JSON, handy for support. See Receipts & data on disk.

openswap feedback

Send a bug or idea straight to the team. It shows you exactly what diagnostic info would be included and asks before sending anything.

Environment variables

| Variable | What it does | | --- | --- | | OPENSWAP_API_KEY (or LEOKIT_API_KEY) | Your API key, for CI and bots. Lookup order: environment → keychain → built-in community key | | OPENSWAP_TEST_MODE | 1 forces the sandbox on, 0 forces it off | | OPENSWAP_TEST_TIMESCALE | Speeds up simulated swaps (CI and agents) | | OPENSWAP_TEST_SEED | Makes simulated outcomes reproducible | | OPENSWAP_EVM_PRIVATE_KEY | Bot signer hot key (prefer the keystore) | | OPENSWAP_EVM_KEYSTORE + OPENSWAP_EVM_KEYSTORE_PASSWORD | Encrypted keystore signer for bots | | OPENSWAP_EVM_RPC_URL | Your own RPC endpoint for the signing lane | | NO_COLOR | Disables colors everywhere |

Which platforms work?

macOS and Linux are fully supported. On Windows, run it under WSL — the native Windows credential store isn't wired up yet, so use the OPENSWAP_API_KEY environment variable there.

Our compatibility promise

Scripts you write today keep working: JSON fields are only ever added, never changed in place; exit codes are frozen; renamed commands get a deprecation window with warnings first.