CLI Reference — swarm
A terminal wallet and trading desk over the same package the SDK exposes: one Turnkey wallet, every supported chain, four trading venues, and a guard rail in front of anything that spends.
npm i -g @swarm-ai-labs/turnkey-extensions # or: npx swarm …
swarm login --email you@example.com
swarm holdings
swarm positionsEvery command is one line of a shell script and one tool of an agent: reads print a table (or --json), writes preview first and do nothing until --confirm.
The execution model
Four rules cover every command that can move money.
1. Dry run by default. A write prints the exact order, transfer or route it would send and stops. --confirm is the only thing that reaches the key. The preview and the receipt have the same shape, so nothing is hidden between them.
2. A budget is mandatory to confirm. SWARM_BUDGET_USD caps what a single invocation may commit, and --confirm without it is refused. The cap is reserved before signing, so an over-budget order never reaches the key. A leveraged order reserves its notional, not its margin — a cap exists to bound exposure.
3. Standing limits outlive the invocation. swarm risk set stores a daily loss ceiling, a per-order ceiling, a leverage ceiling and a withdrawal whitelist. They are checked before any --confirm signs, and again per reservation. A daily-loss limit that cannot be evaluated stops the run.
4. Paper is not a preview. --simulate replaces the order with one written to the paper ledger. A dry run checks the account you have; paper trading exists to trade one you do not. --simulate with --confirm is refused — one of them is real money.
swarm market hyperliquid buy --coin ETH --notional 250 --leverage 3 # preview
SWARM_BUDGET_USD=500 swarm market hyperliquid buy --coin ETH --notional 250 --leverage 3 --confirmAddressing: profiles, aliases, flags
| Flag | What it does |
|---|---|
--account <name> | Use a saved profile's addressing (swarm config profile add). |
--turnkey-key <key> --wallet <name> | Discover addresses via the local turnkey CLI. |
--org <sub-org-id> | The wallet lives in a sub-organization. |
--evm --sol --btc --tron --ton --sui | Pass addresses directly. NEAR is derived from the Solana key. |
Naming any address flag opts out of the profile entirely — the two are never mixed, so --evm 0x… inspects exactly that wallet.
@alias expands from the address book before the command runs, so a dry-run preview always shows the address it will really send to.
Command reference
Identity
| Command | What it does |
|---|---|
login | Email-OTP into a Turnkey sub-org. --expiration <seconds> widens the 1 h default. |
whoami | Who signs right now: session email, sub-org, time left. |
logout | Drop the stored session. |
Portfolio and reads
| Command | What it does |
|---|---|
holdings | The whole wallet across every chain plus ADI and 0G, valued. --sort, --hide-zero, --chain, --testnet. |
balances <pairs…> | Explicit chain:SYMBOL pairs. Accepts @file, - for stdin, and chain:* for every token on a chain. |
positions | Every open position across Hyperliquid, Binance, Polymarket and ADI, valued, with PnL. |
orders | Every resting order across those venues. |
pnl [--since 7d] | Realized, unrealized, fees and funding per venue. Venues that can only report lifetime figures say so. |
report [--since 30d] | The executed trades behind that PnL. --csv writes data to stdout and caveats to stderr. |
cancel --all | Pull resting orders everywhere. --order / --instrument need one --venue. |
rebalance --to <venue> --usd N | Where collateral sits, and the route to move some. Each leg is waited out before the next starts. |
rebalance list | status <id> | resume <id> | A route that died mid-way is resumed from its journal, never reconstructed. |
prices <SYMBOL…> | Spot USD price and 24h change. |
activity [--chain X] | On-chain history: native coin plus every token actually touched, across every chain with an address. |
history [--pages N] | The same wallet, paged — a cursor per feed, walking back N pages. |
chart <SYMBOL> | A price line in the terminal. --tf, --spark, and --watch for a live one. |
dash | Positions, orders and PnL stacked in one view, built from those same commands. |
A venue that cannot be read is named in a NOTE line. It is never rendered as "no positions".
Transfers
| Command | What it does |
|---|---|
send <chain:SYMBOL> --to <addr> --amount N | Transfer a coin or token. Dry run unless --confirm. |
send --eip3009 | Sign an EIP-712 transfer authorization instead of a plain transfer (USDC and friends). |
send --relayer <addr> | Someone else submits the authorization and pays the gas; the owner spends no ETH. |
send --batch @payouts.csv | Many transfers from one file, under one budget. A single bad row refuses the whole file. |
deposit adi:USDC --amount N | Fund the ADI vault with USDC. --qr prints a scannable transfer code. |
Swaps and limit orders
| Command | What it does |
|---|---|
swap --from … --to … --amount N | Swap a pair. Same-chain defaults to Uniswap, cross-chain to 1Click. |
swap --provider <name> | Pick the venue: 1click, uniswap, gaszip, lifi, or auto to quote them all and take the best. |
swap --providers | List the venues, what each reaches, and any key it needs. |
swap --intents | Swap the balance already inside intents.near — one signed token_diff, no origin transaction. |
swap --eip3009 | Cross-chain only: sign the origin deposit as an authorization instead of a transfer. |
swap --fee-service | Quote through Aurora's keyed proxy so integrator fees are attributed. |
limit --from … --to … --amount N --price P | An on-chain limit order via CoW Protocol — costs no gas and outlives this process. |
limit list | cancel --uid <id> | --all | Orders on the book. |
Nothing re-routes silently: omitting --provider keeps today's routing.
Perpetual futures (market hyperliquid)
| Command | What it does |
|---|---|
markets [--search X] | The perp board: mark, 24h, funding, OI, max leverage. |
market --coin ETH | One perp in detail. |
book --coin ETH | The order book — what is available to trade against. |
status / positions / orders / fills / funding | Account value and free collateral; positions; resting orders; trades; funding paid. |
buy | sell --coin ETH --notional 100 | Open or add to a position. --margin sizes by own funds, --limit-px for a limit order, --tp/--sl attach triggers, --idempotent makes a retry safe. |
close --coin ETH [--fraction 0.5] | Flatten a position, or part of one, at market. |
cancel --order <oid> | --all [--coin X] | Pull resting orders. |
leverage --coin ETH --value 5 [--isolated] | The leverage the next position on a coin opens at. |
tpsl --coin ETH [--tp N] [--sl N] | Protect a position that is already open. |
margin --coin ETH --add 25 | --remove 25 | Move an isolated position's liquidation price. |
dead-man --minutes 10 | --off | Cancel every resting order if nothing checks in. |
deposit --amount N / withdraw --amount N | USDC from Arbitrum onto the exchange, and back. |
Prediction markets (market polymarket, market adi)
| Command | What it does |
|---|---|
polymarket markets --search <text> | Tradable markets. --closed includes resolved ones. |
polymarket book --asset <token id> | The order book for an outcome. |
polymarket status | Trading readiness on both the chain and the exchange. |
polymarket setup --confirm | Deploy the Deposit Wallet and grant approvals. --fund N moves collateral in. |
polymarket bet --asset <id> --side buy --price P --size N | Place a bet; --market-order --amount N for market. |
polymarket close --asset <id> | Sell the whole held position at market. |
polymarket orders | positions | cancel | withdraw | Your book, your shares, pulling an order, freeing pUSD out. |
adi markets | book | positions | balances | orders | ADI PredictStreet, public and per-wallet reads. |
adi place | cancel | deposit | withdraw | Order lifecycle and vault funds. Withdrawals are dual-signed. |
Tokenized equities (market xstocks)
| Command | What it does |
|---|---|
xstocks list [--search X] | Active curated Solana xStocks from the inventory. |
xstocks quote --side buy --symbol AAPLX --amount N | A Jupiter USDC ↔ xStock quote. No wallet, no signature. |
xstocks buy | sell --symbol AAPLX --amount N | Build and inspect the Jupiter transaction. |
0G Compute (zg)
| Command | What it does |
|---|---|
zg status | Ledger balance, provider sub-accounts, the wallet's own 0G. |
zg providers [--search X] | Inference providers, price per 1M tokens, uptime. |
zg fund | refund | retrieve | Open or top up the ledger, take funds back, reclaim parked sub-accounts. |
zg ack --provider X | Acknowledge a provider's TEE signer, opening its sub-account. |
zg topup --provider X --amount N | Add to a provider's sub-account. |
zg chat --prompt "…" [--verify] | Ask a provider and stream the reply, with TEE attestation. |
zg delete-ledger | Close the ledger. |
All zg actions take --testnet for 0G Galileo; writes are dry run unless --confirm.
AI signals (signals)
| Command | What it does |
|---|---|
signals list | Live AI trade signals. --active, --coin, --limit. |
signals show <id> | One signal, with the rule that fired it. |
signals watch | Tail the live stream until Ctrl-C. |
signals watch --auto-open --usd N | Also take them as they arrive, under three ceilings: one shared budget, --max-concurrent, --max-signals. |
signals strategies | The strategy catalogue behind the signals. |
signals open <id> --usd N | Take a signal as a perp position. --usd is the notional, not your margin. |
Backlog on connect is never taken — only signals arriving live.
Automation
| Command | What it does |
|---|---|
alert add --when "price:BTC < 90000" | A rule that fires on the crossing, with a cooldown. --webhook, --telegram, --exec. |
alert list | rm <id> | run | run is the daemon; it re-reads rules each sweep and reports failed deliveries. |
exec twap --coin ETH --side buy --notional 5000 --slices 10 --over 30m | One large order released as many. ladder and iceberg too. |
exec list | status <id> | resume <id> | cancel <id> | The journal is written after every slice, so a crash leaves a record. |
strategy check | backtest | run <file.json> | A declarative recipe: alert-grammar conditions, execution-layer actions. |
trail --coin ETH --distance 2% | A trailing stop Hyperliquid does not have natively. It exists only while the process runs — and says so. |
The budget is reserved for the whole parent order: ten $99 slices must not slip past a $100 cap, each honestly under it. Child order ids are derived from the parent, so a resend after a crash is refused as a duplicate rather than filling twice.
Safety and maintenance
| Command | What it does |
|---|---|
risk status | Standing limits, and today's realized PnL against them. |
risk set --max-daily-loss 200 --max-order 1000 --max-leverage 5 --withdraw-whitelist @treasury | Limits that outlive one command. Pass 0 (or an empty list) to clear one. |
approvals list | ERC-20 allowances this tool grants, riskiest first, with its scope printed. |
approvals revoke --spender <addr> --chain <id> | Set one to zero, naming what stops working first. |
tx speedup | cancel --chain <id> | Replace a pending transaction: same nonce, higher fee. cancel sends 0 to yourself. |
fork --chain 1 --to <addr> --data <hex> | Run a transaction on a throwaway forked chain and report gas and balance deltas. Needs anvil. |
cex add binance --key <k> --secret <s> | Store an exchange key — verified first, and refused if it can withdraw. |
cex list | test | rm binance | test re-verifies: permissions can widen on the exchange without the file changing. |
paper positions | pnl | fills | reset | The book --simulate writes to, shaped like the real one. |
Discovery and screening
| Command | What it does |
|---|---|
screen funding [--min-apr 20%] | Perps ranked by annualised funding, with the side that collects named. |
screen spread [--min-spread 10%] | Where Hyperliquid and Binance disagree about funding — a carry with no direction. |
screen edge [--min-edge 0.01] | Prediction markets whose outcome prices do not sum to 1. Every caveat prints with it. |
inventory chains | tokens | What the inventory knows: chains, tokens and deployments. |
Agent surfaces
| Command | What it does |
|---|---|
mcp [--allow-writes] | Serve the CLI as MCP tools over stdio. --confirm is stripped from every call, so no agent can move money by asking; --allow-writes only adds tools that price an order. |
shell | A REPL over the same commands. It does not strip --confirm — there is a human at the keyboard. set --account X carries a flag into every later line. |
Configuration
| Command | What it does |
|---|---|
config show | Profiles, address book, and which profile is active. |
config profile add <name> [--evm … ] | Name an addressing set so commands stop repeating it. |
config profile use | rm | list | Switch, drop or list them. |
config address add <alias> <address> | The address book. Any flag written @alias expands before the run. |
State lives under ~/.config/swarm-cli in 0600 files: session.json, config.json, risk.json, paper.json, cex.json, alerts.json, plus the exec/ and routes/ journals. The SDK reads the same documents through fsStore().
Global options
| Option | What it does |
|---|---|
--confirm | Actually do it. Required for every write; refused without SWARM_BUDGET_USD. |
--simulate | Trade on paper instead of for real. Refused together with --confirm. |
--json | Machine-readable output; live progress becomes one JSON object per line on stderr. |
--watch [--interval 30s] | Re-run a read on an interval and redraw in place. Refused with --confirm — a write must never repeat on a timer. |
--no-progress | Silence the live status lines (on by default, so a slow write does not look like a hang). |
--log [info|debug] | Report signing requests, prepared transactions, broadcasts and venue calls to stderr. |
--log-json / --log-file <path> | Those events as JSON lines, to stderr or appended to a file. |
--slippage <bps> | Same-chain swap tolerance (default 50 = 0.5%). |
--testnet | Testnet endpoints, where a command supports them. |
A failed --watch refresh keeps the last good frame under a STALE banner: an empty table where your positions were reads as having none.
Environment
| Variable | What it does |
|---|---|
SWARM_BUDGET_USD | Mandatory USD spend cap for the invocation. Required by --confirm. |
SWARM_TURNKEY_KEY | Turnkey CLI key name (default default). |
INVENTORY_API_BASE | Inventory API base. |
SOLANA_RPC_URL | Solana JSON-RPC endpoint. |
JUPITER_API_BASE | Jupiter Swap V2 API base. |
ENVY_STREAM_URL | The signals proxy base (or --envy <url>). |
ADI_API_KEY | ADI PredictStreet API key, instead of --api-key. |
SWARM_ANVIL | Path to anvil, for fork. |
Exit codes
| Code | Meaning |
|---|---|
0 | It worked (including a dry run that printed a plan). |
2 | The operator got something wrong — a bad flag, a refused limit. |
1 | Something else broke: an RPC, a venue, the network. |
The split is deliberate: a script can retry a 1 and must not retry a 2.
The same thing headlessly
Every command here is a call on the SDK's product API — swarm holdings is swarm.portfolio.holdings(), market hyperliquid buy is perps.open(). If you are automating rather than typing, see SDK.md.