okx-exchange

# OKX Exchange Skill Quantitative trading agent for OKX exchange via the official V5 API. **API Docs:** https://www.okx.com/docs-v5/en/ ## Setup (First Time) ```bash # 1. Add credentials to .env cat >> ~/.openclaw/workspace/.env << 'EOF' OKX_API_KEY=your_key OKX_SECRET_KEY=your_secret OKX_PASSPHRASE=your_passphrase OKX_SIMULATED=1 EOF # 2. Run setup cd ~/.openclaw/workspace/skills/okx-exchange/scripts python setup.py ``` **Important:** `OKX_SIMULATED=1` = paper trading (safe). Set to `0` for live trading. ## Session Init On every session, load credentials first: ```bash source ~/.openclaw/workspace/.env cd ~/.openclaw/workspace/skills/okx-exchange/scripts ``` ## Unified CLI (Recommended) Use `okx.py` as the single entry point for all commands: ```bash python3 okx.py help # Show all commands python3 okx.py account # Portfolio overview python3 okx.py buy BTC-USDT market 0.01 python3 okx.py trend analyze BTC-USDT-SWAP ``` All individual scripts remain usable directly, but `okx.py` is preferred for agent use. ## Instrument ID Format | Type | Format | Example | |------|--------|---------| | Spot | `{BASE}-{QUOTE}` | `BTC-USDT` | | Perpetual Swap | `{BASE}-{QUOTE}-SWAP` | `BTC-USDT-SWAP` | | Futures | `{BASE}-{QUOTE}-{EXPIRY}` | `BTC-USDT-250328` | `tdMode`: `cash` (spot), `cross` (cross-margin), `isolated` (isolated-margin) ## Account & Portfolio ```bash python3 okx.py account # Full portfolio summary python3 okx.py account balance # Balances only python3 okx.py account balance USDT # Specific currency python3 okx.py account positions # All positions python3 okx.py account orders # Pending orders python3 okx.py account history # Filled order history (SPOT) python3 okx.py account history SWAP # Perpetual swap order history python3 okx.py account history SPOT BTC-USDT # History for specific symbol ``` ## Trading Mode (Live / Demo) ```bash python3 okx.py mode # Show current mode python3 okx.py mode demo # Switch to paper trading (safe) python3 okx.py mode live # Switch to live trading (requires confirmation + LIVE credentials) ``` Live credentials use separate env vars: ``` OKX_API_KEY_LIVE / OKX_SECRET_KEY_LIVE / OKX_PASSPHRASE_LIVE ``` ## Order Execution ```bash # Spot market buy python3 okx.py buy BTC-USDT market 0.01 # Spot limit sell python3 okx.py sell BTC-USDT limit 0.01 --px 50000 # Perpetual swap — long with TP/SL (attached to the order) python3 okx.py buy BTC-USDT-SWAP market 1 --td cross --pos long --tp 55000 --sl 42000 # Perpetual swap — short python3 okx.py sell BTC-USDT-SWAP market 1 --td cross --pos short # Close position (reduce-only) python3 okx.py sell BTC-USDT-SWAP market 1 --td cross --pos long --reduce # Cancel order python3 okx.py cancel BTC-USDT <ord_id> # Cancel all orders for symbol python3 okx.py cancel-all BTC-USDT # Set leverage python3 okx.py leverage BTC-USDT-SWAP 10 --td cross # Transfer funds between accounts (6=Funding, 18=Trading) python3 okx.py transfer USDT 500 funding trading # Funding → Trading python3 okx.py transfer USDT 500 trading funding # Trading → Funding ``` Skip confirmation prompt (for automation): ```bash python3 okx.py buy BTC-USDT market 0.01 --no-confirm ``` ## Algo Orders (Standalone TP/SL — for existing positions) Use when a position is already open and you want to add a stop-loss or take-profit separately. Unlike `--tp/--sl` flags (which attach to the entry order), algo orders are independent. ```bash # OCO: TP + SL together — whichever triggers first cancels the other python3 okx.py algo oco BTC-USDT-SWAP 1 --tp 55000 --sl 45000 --td cross --pos long --reduce # Conditional: single stop-loss only python3 okx.py algo stop BTC-USDT-SWAP 1 --sl 45000 --td cross --reduce # List all pending algo orders python3 okx.py algo list python3 okx.py algo list BTC-USDT-SWAP # filter by instrument # Cancel a specific algo order python3 okx.py algo cancel BTC-USDT-SWAP <algo_id> ``` **When to use which:** - `--tp/--sl` at order time → atomic, guaranteed to attach, best for new entries - `algo oco` → add/replace TP+SL after entry, or adjust levels mid-trade ## Strategies ### Trend Following (MA + RSI + MACD) ```bash # Analyze only (no trade) python3 okx.py trend analyze BTC-USDT-SWAP --bar 1H # Run with auto-execution python3 okx.py trend run BTC-USDT-SWAP 1 --bar 4H --tp 0.05 --sl 0.03 --td cross --pos long # Dry run (analysis only, no trade) python3 okx.py trend run BTC-USDT-SWAP 1 --dry ``` Signal logic: - **BUY**: MA_fast > MA_slow + RSI < 70 + MACD histogram > 0 - **SELL**: MA_fast < MA_slow + RSI > 30 + MACD histogram < 0 ### Grid Trading ```bash # Setup grid: BTC-USDT, range 40000-50000, 10 grids, 1000 USDT total python3 okx.py grid setup BTC-USDT 40000 50000 10 1000 # Check and rebalance filled orders (run periodically) python3 okx.py grid check BTC-USDT # Stop and cancel all grid orders python3 okx.py grid stop BTC-USDT ``` ### Spot-Futures Arbitrage ```bash # Scan all pairs for opportunities python3 okx.py arb scan # Check specific pair basis python3 okx.py arb basis BTC-USDT BTC-USDT-SWAP # Open arbitrage position (buy spot + short swap) python3 okx.py arb open BTC-USDT BTC-USDT-SWAP 1000 --min-basis 0.1 # Close arbitrage position when basis converges python3 okx.py arb close BTC-USDT BTC-USDT-SWAP 0.01 1 --max-basis 0.02 ``` ## Snapshot Report Fetches live data from the API on every run, persists the snapshot, and outputs a full report with a **real historical tracking table**. ```bash python3 okx.py snapshot ``` Output includes: - Total equity, initial capital, % change (relative to first snapshot) - Available USDT, major holdings - Contract positions (entry price, mark price, unrealized PnL, liquidation distance) - Historical tracking table (from `memory/okx-monitor-snapshots.json`, up to 48 entries) **All figures are sourced directly from the OKX API — no estimates or fabricated values.** ## Automated Monitoring (Cron) ```bash # Default: sl-tp every 5 minutes, scan every 30 minutes bash scripts/cron_setup.sh setup # Custom intervals (dynamic parameters) bash scripts/cron_setup.sh setup 1m # sl-tp every 1 minute bash scripts/cron_setup.sh setup 10m 1h # sl-tp every 10 minutes, scan every 1 hour # Stop all jobs bash scripts/cron_setup.sh teardown # Show status bash scripts/cron_setup.sh status ``` Cron jobs: - `okx-sl-tp` — periodically runs `snapshot` + `monitor sl-tp`, reports live data - `okx-scan` — periodically runs `monitor scan`, reports strategy signals ### Adjust cron interval (via user instruction) If the user asks to change the monitoring frequency (e.g. "change to every 10 minutes"): ```bash # Find the cron job ID first openclaw cron list # Then edit the interval (replace <id> with the okx-sl-tp job ID) openclaw cron edit <id> --every 10m # e.g. 1m, 5m, 15m, 30m, 1h ``` ### Manual monitor run ```bash python3 okx.py snapshot # Full account snapshot report (with history — recommended) python3 okx.py monitor # SL/TP check + strategy scan + liquidation risk python3 okx.py monitor sl-tp # Only SL/TP check python3 okx.py monitor scan # Only strategy scan python3 okx.py monitor liq-risk # Liquidation risk check (default: alert if within 10%) python3 okx.py monitor liq-risk 5 # Alert if mark price within 5% of liquidation price ``` ### CRITICAL: Cron reporting rules **Every cron report MUST call the scripts first. NEVER fabricate, estimate, or reuse previous numbers.** Recommended single command for cron: ```bash cd ~/.openclaw/workspace/skills/okx-exchange/scripts python3 okx.py snapshot python3 okx.py monitor sl-tp ``` `snapshot` automatically saves the snapshot and generates a report with historical tracking. Forward the output verbatim — do not add, remove, or rephrase any content. Report only what the scripts actually output. If a script returns an error, report the error — do not substitute with previously seen values. **Why this matters:** Each cron run is an isolated session with no memory of previous runs. Any numbers not fetched from the API in this session are either fabricated or stale. ## Performance Report ```bash python3 okx.py report daily # Today's P&L summary python3 okx.py report weekly # Last 7 days python3 okx.py report all # All-time ``` Output includes: trade count, win rate, total P&L, best/worst trade, and top-5 coin breakdown. ## Configuration View or update preferences without editing JSON directly: ```bash python3 okx.py prefs show python3 okx.py prefs set auto_trade true python3 okx.py prefs set stop_loss_pct 3.0 python3 okx.py prefs set watchlist BTC-USDT-SWAP,ETH-USDT-SWAP,SOL-USDT-SWAP ``` Full preferences schema (`~/.openclaw/workspace/memory/okx-trading-preferences.json`): ```json { "max_order_usd": 100, "max_leverage": 10, "price_impact_warn": 0.005, "price_impact_abort": 0.01, "require_confirm": true, "stop_loss_pct": 5.0, "take_profit_pct": 10.0, "auto_trade": false, "max_position_usd": 100, "max_daily_trades": 10, "default_sz": "0.01", "strategies": ["trend"], "watchlist": ["BTC-USDT-SWAP", "ETH-USDT-SWAP"] } ``` | Parameter | Default | Description | |-----------|---------|-------------| | `max_order_usd` | 100 | Max USD per single order | | `max_leverage` | 10 | Max allowed leverage | | `price_impact_warn` | 0.005 | Warn if market order impact > 0.5% | | `price_impact_abort` | 0.01 | Abort if market order impact > 1% | | `require_confirm` | true | Prompt before placing orders | | `stop_loss_pct` | 5.0 | Auto stop-loss at -X% unrealized PnL | | `take_profit_pct` | 10.0 | Auto take-profit at +X% unrealized PnL | | `auto_trade` | false | Execute trades automatically (no confirmation) | | `max_position_usd` | 100 | Max USD per position | | `max_daily_trades` | 10 | Max auto-trades per day | | `default_sz` | "0.01" | Default size for auto-trading | | `strategies` | ["trend"] | Active strategies: trend / arbitrage | | `watchlist` | [...] | Instruments for monitor scan | ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `OKX_API_KEY` | — | Demo API key | | `OKX_SECRET_KEY` | — | Demo API secret | | `OKX_PASSPHRASE` | — | Demo API passphrase | | `OKX_API_KEY_LIVE` | — | Live API key (used when `mode=live`) | | `OKX_SECRET_KEY_LIVE` | — | Live API secret | | `OKX_PASSPHRASE_LIVE` | — | Live API passphrase | | `OKX_SIMULATED` | `0` | Set `1` for paper trading (demo account) | | `OKX_WS` | `0` | Set `1` to enable WebSocket feed (real-time cache for tickers/candles/account/positions) | | `OKX_API_URL` | `https://www.okx.com` | Override API base URL | | `OKX_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` | | `OKX_LOG_FORMAT` | `text` | `text` or `json` (structured logging) | | `OKX_CRON_MODE` | `0` | Set `1` to suppress INFO output (for cron) | ### WebSocket Mode (`OKX_WS=1`) When enabled, a background thread maintains real-time caches: - **Public feed**: tickers, candles — `OKXClient.ticker()` / `candles()` read from cache first - **Private feed**: account balances, positions, orders — `balance()` / `positions()` read from cache first - REST API is used as fallback when cache is empty or WS is disabled ## Trading Rules Before making any buy/sell decision, read and apply the principles in: ``` docs/trading-rules.md ``` These rules define how to observe the market, weigh signals, size positions, and learn from outcomes. They do not prescribe a fixed strategy — the agent is expected to adapt its approach based on what the market is actually showing. ## Safety Rules 1. **Always confirm before placing orders** unless `auto_trade=true` or `--no-confirm` 2. **Price impact check**: abort if >1%, warn if >0.5% 3. **Start with `OKX_SIMULATED=1`** — validate everything before going live 4. **Never print or log credentials** — load via `source .env` only 5. **Set stop-loss on every position** — meme coins and leveraged positions can move fast 6. **Daily trade limit** — auto-trading will stop when `max_daily_trades` is reached ## Memory Files | File | Purpose | |------|---------| | `memory/okx-trading-preferences.json` | Strategy config, risk parameters, and trading mode | | `memory/okx-trading-state.json` | Runtime state (daily trade count, last scan) | | `memory/okx-trading-journal.json` | Trade history from monitor (SL/TP closures, auto-entries) | | `memory/okx-trade-journal.json` | Trade history from learning system (signal analysis) | | `memory/okx-learning-model.json` | Learning model (win rates by coin/regime, optimal params) | | `memory/okx-grid-{inst_id}.json` | Grid state per instrument | ## Kill Switch ```bash # Stop all automated trading bash scripts/cron_setup.sh teardown # Or remove OKX_API_KEY from .env to prevent any API calls ```