| name | wooo-cli |
| description | Guide for using wooo-cli, the all-in-one crypto terminal CLI for trading, DeFi, and on-chain execution. Use this skill whenever the user wants to: trade or buy/sell crypto on exchanges (OKX, Binance, Bybit spot or futures), swap tokens on DEXes (Uniswap, Curve, Jupiter), lend/borrow/supply on DeFi (Aave, Morpho), stake ETH (Lido), open leveraged long/short positions (Hyperliquid perps), check prediction markets (Polymarket), bridge tokens cross-chain (LI.FI, OKX Bridge), check token prices or market rankings, view on-chain token volume/candles/holders/trades, query wallet balances or portfolio PnL across chains, resolve ENS names, inspect transactions, read smart contracts, manage wallets (create/import/switch/connect hardware), or configure exchange API keys. Trigger on any crypto CLI operation — even when the user doesn't say "wooo" explicitly. If they mention buying BTC, swapping tokens, checking DeFi positions, staking rewards, funding rates, bridging USDC, token rankings, or portfolio overview from the terminal, this skill applies. Do NOT trigger for: writing smart contracts or dApps, using ethers.js/web3.js/viem in code, deploying contracts with Hardhat/Foundry, building trading bots in Python, or general blockchain education questions.
|
wooo-cli Usage Guide
wooo-cli is a terminal-native crypto CLI that unifies CEX trading, DEX swaps, DeFi lending, staking, perps, prediction markets, cross-chain bridges, and on-chain utilities into a single tool with consistent flags, structured output, and built-in wallet management.
The CLI binary is wooo-cli (not wooo). Always use the full name.
Core Philosophy
wooo-cli treats real money the same way a gun treats bullets — every command that moves funds has a safety mechanism. Your job is to keep that safety on until the user is ready to fire.
The Safety Checklist (follow for every write operation):
- Verify prerequisites — Is the wallet set up? Are API keys configured? Is there enough balance?
- Dry-run first — Always run with
--dry-run before executing. This shows the full execution plan without spending anything.
- Confirm chain and amounts — Read back what will happen: "This will swap 1 ETH for ~3,200 USDC on Arbitrum. Gas estimated at ~$0.03."
- Let the user confirm — Never add
--yes unless the user explicitly asks for unattended execution.
- Execute — Only after the user reviews and approves.
Read-only commands (price, balance, positions, markets) are always safe and don't need this ceremony.
Command Structure
wooo-cli [global-flags] <group> <protocol> <action> [args]
Universal commands are top-level: config, wallet, market, portfolio, chain, swap.
Protocol commands are grouped by type:
| Group | Protocols | Actions |
|---|
cex | okx, binance, bybit | buy, sell, long, short, balance, positions |
dex | uniswap, curve, jupiter | swap, quote, tokens/pools |
lend | aave, morpho | markets, supply, withdraw, borrow, repay, positions, rates |
stake | lido | stake, balance, rewards |
perps | hyperliquid | long, short, positions, funding |
prediction | polymarket | markets, events, clob, approve, and CLOB trading |
bridge | lifi, okx | bridge, quote, status, chains |
pay | mpp, x402 | machine payment protocols |
Global Flags
Available on every command:
| Flag | Purpose |
|---|
--json | Force JSON output (useful for piping or automation) |
--format table|json|csv | Choose output format |
--chain <name> | Target chain (see Chain Support below) |
--wallet <name> | Use a specific wallet instead of the active one |
--yes | Skip confirmation prompts — use with caution |
--dry-run | Preview execution plan without sending transactions |
--verbose | Show debug output |
--quiet | Suppress non-essential output |
Chain Support
| Chain | Canonical Name | Aliases |
|---|
| Ethereum | ethereum | eth, mainnet |
| Arbitrum | arbitrum | arb |
| Optimism | optimism | op |
| Polygon | polygon | matic, poly |
| Base | base | — |
| BSC | bsc | — |
| Avalanche | avalanche | — |
| Solana | solana | sol |
EVM protocols (Uniswap, Curve, Aave, Morpho, Lido, bridges) work on EVM chains only.
Jupiter is Solana-only (no --chain flag needed).
Aggregated swap (wooo-cli swap) auto-routes to the right DEX based on chain — uses Jupiter for Solana, Uniswap/Curve for EVM.
Validation Policy
For external testing, default to the mainnet-fork Anvil E2E flow rather than testnets.
This repo treats fork-backed validation as the authoritative way to verify protocol
addresses, token manifests, and execution paths without risking real funds.
If you are acting as an agent:
- Prefer
bun run test:e2e:anvil when validating on-chain changes.
- Assume mainnet addresses are the source of truth unless the repo explicitly says otherwise.
- Do not present testnet support as a guarantee unless the CLI docs say so.
- If a change touches protocol constants or routing, make sure fork-backed E2E coverage exists.
Setup & Configuration
First-Time Setup
npm install -g wooo-cli
wooo-cli config init
wooo-cli wallet create my-wallet
Or import an existing key:
wooo-cli wallet import my-key 0xprivatekey...
wooo-cli wallet import my-mnemonic --mnemonic
wooo-cli wallet import from-file --file /path/to/keyfile
For non-interactive / automation:
wooo-cli secret set ows/passphrase
wooo-cli secret set ows/api-key
CEX API Keys
Required for any wooo-cli cex commands. Use auth for the normal flow:
wooo-cli auth set okx
wooo-cli auth set binance
wooo-cli auth set bybit
Advanced secret-ref overrides:
wooo-cli config set okx.apiKeyRef keychain:okx/api-key
wooo-cli config set okx.apiSecretRef keychain:okx/api-secret
wooo-cli config set okx.passphraseRef keychain:okx/passphrase
OKX Onchain / Web3 / DEX API (separate credentials)
Required for market okx, portfolio okx, chain okx, and OKX bridge/DEX
commands. These credentials come from the OKX Web3 Developer Portal and are
separate from OKX Exchange keys:
wooo-cli auth set okx-onchain --project-id <project-id>
Complete Command Reference
Wallet Management
wooo-cli wallet create <name> [--words 12|24]
wooo-cli wallet import <name> [key] [--mnemonic] [--file <path>] [--chain evm|solana]
wooo-cli wallet export <name> --confirm
wooo-cli wallet list
wooo-cli wallet info <name>
wooo-cli wallet switch <name>
wooo-cli wallet delete <name> --confirm
wooo-cli wallet balance [address] [--chain <chain>]
Remote / hardware wallets:
wooo-cli wallet discover --signer http://127.0.0.1:8787/
wooo-cli wallet connect <name> --signer <url> [--address <addr>] [--auth-ref <ref>]
wooo-cli wallet disconnect <name>
Wallet custody mode is explicit and does not fall back between local and remote
custody. The default is local-only. Set WOOO_WALLET_MODE=remote to use
connected remote accounts; resolution will fail instead of using a local wallet.
Use WOOO_WALLET_MODE=local or leave it unset for local-only custody.
Policy & API key management:
wooo-cli wallet policy create <file.json>
wooo-cli wallet policy list
wooo-cli wallet policy show <id>
wooo-cli wallet policy delete <id>
wooo-cli wallet key create <name> --wallet <wallet> --policy <policy-id>
wooo-cli wallet key list
wooo-cli wallet key revoke <key-id>
Market Data (read-only, always safe)
wooo-cli market price <symbol>
wooo-cli market search <keyword>
wooo-cli market search <keyword> --exchange binance
OKX Onchain data (requires OKX Onchain API credentials):
wooo-cli market okx chains
wooo-cli market okx search <query> --chains ethereum,base [--max 20]
wooo-cli market okx token <chain> <address>
wooo-cli market okx metrics <chain> <address>
wooo-cli market okx price <chain> <address>
wooo-cli market okx trades <chain> <address> [--limit 20]
wooo-cli market okx candles <chain> <address> [--bar 1m|5m|15m|1H|4H|1D]
wooo-cli market okx holders <chain> <address> [--tag whale]
wooo-cli market okx ranking --chains ethereum,base [--sort volume|change|market-cap] [--window 5m|1h|4h|24h]
wooo-cli market okx filter --instType SPOT|SWAP|FUTURES [--sortBy volUsd24h|oiUsd|fundingRate|last|chg24hPct|marketCapUsd|listTime]
wooo-cli market okx oi-history <instId> [--bar 5m|15m|1H|4H|1D] [--limit 50]
wooo-cli market okx oi-change --instType SWAP|FUTURES [--bar 5m|15m|1H|4H|1D] [--sortBy oiDeltaPct|oiDeltaUsd|oiUsd|volUsd24h|last]
OKX news / sentiment radar (requires OKX API credentials):
wooo-cli news okx latest [--coins BTC,ETH] [--platform blockbeats] [--lang zh-CN|en-US] [--limit 10]
wooo-cli news okx important [--coins BTC,ETH] [--lang zh-CN|en-US] [--limit 10]
wooo-cli news okx by-coin --coins BTC,ETH [--importance high|low] [--platform blockbeats]
wooo-cli news okx search <keyword> [--coins BTC] [--sentiment bullish|bearish|neutral]
wooo-cli news okx by-sentiment --sentiment bullish|bearish|neutral [--coins BTC]
wooo-cli news okx detail <id>
wooo-cli news okx platforms
wooo-cli news okx coin-sentiment --coins BTC,ETH [--period 1h|4h|24h]
wooo-cli news okx coin-trend <coin> [--period 1h|4h|24h] [--points 24]
wooo-cli news okx sentiment-rank [--period 1h|4h|24h] [--sortBy hot|bullish|bearish]
Token Swaps
Aggregated swap (auto-picks best DEX route):
wooo-cli swap <tokenIn> <tokenOut> <amount> --chain <chain> [--dry-run] [--yes]
wooo-cli swap ETH USDC 1 --chain arbitrum --dry-run
wooo-cli swap SOL USDC 10 --chain solana --dry-run
Direct DEX access:
wooo-cli dex uniswap swap <tokenIn> <tokenOut> <amount> --chain <chain> [--dry-run]
wooo-cli dex uniswap quote <tokenIn> <tokenOut> <amount> --chain <chain>
wooo-cli dex uniswap tokens --chain <chain>
wooo-cli dex curve swap <tokenIn> <tokenOut> <amount> --chain <chain> [--dry-run]
wooo-cli dex curve quote <tokenIn> <tokenOut> <amount> --chain <chain>
wooo-cli dex curve pools --chain <chain>
wooo-cli dex jupiter swap <tokenIn> <tokenOut> <amount> [--dry-run]
wooo-cli dex jupiter quote <tokenIn> <tokenOut> <amount>
wooo-cli dex jupiter tokens
CEX Trading
Same pattern for all exchanges (okx, binance, bybit):
wooo-cli cex <exchange> balance
wooo-cli cex <exchange> positions
wooo-cli cex <exchange> buy <pair> <amount> [--dry-run]
wooo-cli cex <exchange> sell <pair> <amount> [--dry-run]
wooo-cli cex <exchange> long <symbol> <size> [--leverage <n>] [--dry-run]
wooo-cli cex <exchange> short <symbol> <size> [--leverage <n>] [--dry-run]
<pair>: Trading pair like BTC/USDT, ETH/USDC<amount>: Amount in quote currency for buy, base currency for sell<symbol>: Futures symbol like BTC/USDT:USDT<size>: Position size in USD--leverage: Leverage multiplier (default: 1)
Lending — Aave V3
wooo-cli lend aave markets --chain <chain>
wooo-cli lend aave rates <token> --chain <chain> --market <market>
wooo-cli lend aave positions --chain <chain> --market <market>
wooo-cli lend aave supply <token> <amount> --chain <chain> --market <market> [--dry-run]
wooo-cli lend aave withdraw <token> [amount] [--all] --chain <chain> --market <market> [--dry-run]
wooo-cli lend aave borrow <token> <amount> --chain <chain> --market <market> [--dry-run]
wooo-cli lend aave repay <token> [amount] [--all] --chain <chain> --market <market> [--dry-run]
Important: On chains with multiple Aave markets, --market is required for token-specific and position commands. Discover available markets first with wooo-cli lend aave markets --chain <chain>. The market name looks like AaveV3Ethereum — use it exactly.
Lending — Morpho Markets V1
wooo-cli lend morpho markets --chain <chain> [--search <q>] [--loan-token <sym>] [--collateral-token <sym>] [--limit 10]
wooo-cli lend morpho market <marketId> --chain <chain>
wooo-cli lend morpho positions --chain <chain>
wooo-cli lend morpho supply <marketId> <amount> --chain <chain> [--dry-run]
wooo-cli lend morpho withdraw <marketId> [amount] [--all] --chain <chain> [--dry-run]
wooo-cli lend morpho supply-collateral <marketId> <amount> --chain <chain> [--dry-run]
wooo-cli lend morpho withdraw-collateral <marketId> [amount] [--all] --chain <chain> [--dry-run]
wooo-cli lend morpho borrow <marketId> <amount> --chain <chain> [--dry-run]
wooo-cli lend morpho repay <marketId> [amount] [--all] --chain <chain> [--dry-run]
Staking — Lido
wooo-cli stake lido stake <amount> [--dry-run]
wooo-cli stake lido balance
wooo-cli stake lido rewards
Perpetual Futures — Hyperliquid
wooo-cli perps hyperliquid long <symbol> <size> [--leverage <n>] [--dry-run]
wooo-cli perps hyperliquid short <symbol> <size> [--leverage <n>] [--dry-run]
wooo-cli perps hyperliquid positions
wooo-cli perps hyperliquid funding
<symbol>: Asset symbol like BTC, ETH<size>: Position size in USD--leverage: Leverage multiplier (default: 1)
Prediction Markets — Polymarket
wooo-cli prediction polymarket markets list [--limit 10]
wooo-cli prediction polymarket events get <eventId>
wooo-cli prediction polymarket clob ok
wooo-cli prediction polymarket deposit supported-assets
wooo-cli prediction polymarket deposit addresses
wooo-cli prediction polymarket deposit status <address>
wooo-cli prediction polymarket deposit-wallet address
wooo-cli prediction polymarket deposit-wallet deploy [--dry-run]
wooo-cli prediction polymarket approve check
wooo-cli prediction polymarket approve set [--dry-run]
wooo-cli prediction polymarket clob create-order --token <tokenId> --side buy --price 0.42 --size 10 [--dry-run]
wooo-cli prediction polymarket clob market-order --token <tokenId> --side buy --amount 20 [--dry-run]
Polymarket trading uses deposit wallets and CLOB POLY_1271 signatures. The
active signer comes from WOOO_WALLET_MODE; the target deposit wallet resolves
from config polymarket.owner, config polymarket.depositWallet,
--deposit-wallet, or, when no target is configured, the active signer as
owner. If both owner and deposit wallet are provided, the deposit wallet must be
the deterministic wallet for that owner. The CLI has no Polymarket session mode;
owner/session authority belongs to the signer and Deposit Wallet contract.
Deposit wallet deployment and approval writes go through the Polymarket relayer;
use wooo-cli auth set polymarket-relayer and config
polymarket.relayerApiKeyAddress for relayer authentication.
Cross-Chain Bridges
wooo-cli bridge lifi bridge <token> <amount> --from-chain <chain> --to-chain <chain> [--to <destToken>] [--dry-run]
wooo-cli bridge lifi quote <token> <amount> --from-chain <chain> --to-chain <chain> [--to <destToken>]
wooo-cli bridge lifi status <txHash> --from-chain <chain> --to-chain <chain>
wooo-cli bridge lifi chains [--tokens]
wooo-cli bridge okx bridge <token> <amount> --from-chain <chain> --to-chain <chain> [--to <destToken>] [--dry-run]
wooo-cli bridge okx quote <token> <amount> --from-chain <chain> --to-chain <chain> [--to <destToken>]
wooo-cli bridge okx status <txHash>
wooo-cli bridge okx chains [--tokens]
Bridge flags use --from-chain and --to-chain (not --chain). Both are EVM-only in this version.
On-Chain Utilities
wooo-cli chain tx <hash> [--chain <chain>]
wooo-cli chain balance <address> [--token <tokenAddr>] [--chain <chain>]
wooo-cli chain ens <nameOrAddress>
wooo-cli chain call <contract> <signature> [args] [--chain <chain>]
OKX Onchain history:
wooo-cli chain okx history <address> --chains ethereum,base [--token <addr>] [--limit 20]
wooo-cli chain okx tx <chain> <txHash>
Portfolio
wooo-cli portfolio overview
wooo-cli portfolio okx chains
wooo-cli portfolio okx overview <address> <chain> [--window 1d|3d|7d|1m|3m]
wooo-cli portfolio okx value <address> --chains ethereum,base [--asset-type all|token|defi]
wooo-cli portfolio okx balances <address> --chains ethereum,base
wooo-cli portfolio okx balance <address> <chain> <token|native>
wooo-cli portfolio okx recent-pnl <address> <chain> [--limit 20]
wooo-cli portfolio okx latest-pnl <address> <chain> <tokenAddress>
wooo-cli portfolio okx dex-history <address> <chain> <beginMs> <endMs> [--type buy,sell]
Configuration
wooo-cli config init
wooo-cli config set <key> <value>
wooo-cli config get <key>
wooo-cli config list
Decision Guide: What Command to Use
| User wants to... | Command |
|---|
| Check token price | wooo-cli market price <symbol> |
| Swap tokens (any chain) | wooo-cli swap <in> <out> <amount> --chain <chain> --dry-run |
| Swap on specific DEX | wooo-cli dex <protocol> swap ... |
| Buy crypto on exchange | wooo-cli cex <exchange> buy <pair> <amount> --dry-run |
| Check exchange balance | wooo-cli cex <exchange> balance |
| Open leveraged long | wooo-cli perps hyperliquid long <sym> <size> --leverage <n> --dry-run |
| Lend on Aave | wooo-cli lend aave supply <token> <amount> --chain <chain> --market <market> --dry-run |
| Check DeFi positions | wooo-cli lend aave positions --chain <chain> --market <market> |
| Stake ETH | wooo-cli stake lido stake <amount> --dry-run |
| Bridge tokens | wooo-cli bridge lifi bridge <token> <amount> --from-chain <src> --to-chain <dst> --dry-run |
| Check wallet balance | wooo-cli wallet balance [--chain <chain>] |
| Check on-chain balance | wooo-cli chain balance <address> --chain <chain> |
| Look up ENS name | wooo-cli chain ens <name> |
| View portfolio PnL | wooo-cli portfolio okx overview <addr> <chain> --window 7d |
| Find trending tokens | wooo-cli market okx ranking --chains ethereum,base --sort volume --window 24h |
Troubleshooting
| Error | Cause | Fix |
|---|
| "No wallet found" | No active wallet | wooo-cli wallet list → wooo-cli wallet create <name> |
| "API key not configured" | Missing CEX credentials | env | grep WOOO_ or set env vars |
| "Chain not supported" | Wrong chain for protocol | Check protocol's supported chains |
| "Market not found" (Aave) | Missing --market flag | wooo-cli lend aave markets --chain <chain> to find name |
| Transaction fails | Insufficient balance/gas | Check balance first, use --dry-run to preview |
| "Unknown chain" | Typo or unsupported | Use canonical names or aliases: eth, arb, op, matic, base, sol |
External Testing
Use the fork-backed suite when you need confidence that the CLI will work against
real protocol deployments:
bun run test:e2e:anvil
Useful overrides:
ANVIL_FORK_URLS_ETHEREUM="https://ethereum.publicnode.com https://rpc.flashbots.net" \
ANVIL_FORK_BLOCK_NUMBER=24652791 \
bun run test:e2e:anvil
This is the preferred path for agent verification because it exercises the same
mainnet contract addresses used by chain, dex uniswap, swap, lend aave,
and lend morpho.
Agent / Automation Patterns
For scripts, CI/CD, or agent-driven workflows:
wooo-cli market price BTC --json
wooo-cli swap ETH USDC 1 --chain ethereum --dry-run --json
wooo-cli swap ETH USDC 1 --chain ethereum --yes
wooo-cli secret set ows/passphrase
wooo-cli secret set ows/api-key
The --dry-run --json combination returns an ExecutionPlan object describing every step (approvals, transactions, estimated costs) without executing. This is the foundation for building approval workflows where a human or policy engine reviews before committing.
