OKX Exchange

OKX quantitative trading agent. Supports spot, USDT-M perpetual swap, and coin-M futures. Strategies: grid trading, trend following (MA/RSI/MACD), spot-futur...

Security Scan

The skill appears to implement an OKX trading agent as described, but its metadata omits required credentials/dependencies and it installs recurring automation (cron) that will run with your API keys — review env handling, cron behavior, and undeclared binaries before installing.

Purpose & Capability

The skill's declared registry metadata lists no required environment variables or binaries, yet the SKILL.md and README instruct the user to add OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE (and LIVE variants) into ~/.openclaw/workspace/.env and to run Python scripts. The cron helper requires an 'openclaw' CLI to be present but that binary is not declared. The absence of declared credentials and required CLI/tools in metadata is an incoherence: a trading skill legitimately needs API keys and a runtime, so those should be declared.

Instruction Scope

Runtime instructions explicitly tell the agent/user to source ~/.openclaw/workspace/.env (loading API keys) every session and to run scripts that will read/write memory files and execute trades. The cron_setup.sh creates scheduled jobs whose messages instruct the cron agent to 'source ~/.openclaw/workspace/.env' and to execute snapshot and monitor commands and 'send the raw output' — meaning account snapshots and monitor outputs (which include balances/positions) will be periodically produced and emitted by the agent. The instructions allow skipping confirmations and switching to live mode with separate live env vars, so misconfiguration could lead to autonomous live trading. These behaviors are within the stated trading purpose, but they broaden what gets read/transmitted (sensitive account data) and grant the skill the ability to schedule recurring automated actions — all of which should be explicit in metadata and reviewed by the user.

Install Mechanism

No formal install spec is declared (instruction-only install), but the bundle contains many Python scripts and a requirements.txt recommending 'pip install -r requirements.txt'. There are no downloads from untrusted URLs or extracted archives. The lack of an automated install step means the user must run pip/setup manually; that's acceptable but should be made explicit in registry metadata. No direct evidence of malicious install sources.

Credentials

The skill requires sensitive OKX API credentials to function (demo and live keys), but the registry's required env vars list is empty — a mismatch that can mislead users and automated permission systems. The code persists state and journals under ~/.openclaw/workspace/memory and instructs to store keys in ~/.openclaw/workspace/.env; storing credentials in a workspace file is convenient but increases risk if that file is not properly protected. Multiple env names (demo vs LIVE) are justified by live/paper modes, but the omission from metadata is a meaningful coherence problem.

Persistence & Privilege

always:false (good). However, cron_setup.sh programmatically registers periodic jobs via 'openclaw cron add' that will run the skill's monitoring and snapshot commands and instruct the cron agent to 'send' outputs. That creates persistent automation (periodic account snapshots and scans) and will run with sourced env keys. This is expected for a trading bot but increases the skill's ongoing footprint and potential blast radius if keys are compromised or misconfigured. The skill does not request to modify other skills' configs.

What to consider before installing

This skill appears to be a real OKX trading bot, but there are mismatches you should resolve before installing: - It needs OKX API keys (demo and optional live keys) and expects you to store them in ~/.openclaw/workspace/.env, yet the registry metadata did not declare any required env vars. Treat this as a red flag: only provide demo keys initially (OKX_SIMULATED=1) and do not add live keys until you audit the code. - The cron setup uses an 'openclaw' CLI to register recurring jobs that will source your .env and execute monitor/snapshot commands and forward the raw output. Understand and accept that these jobs will periodically run and publish account/position information via your agent channels. If you don't want recurring automation, do not run cron_setup.sh or run 'teardown' after setup. - Review the code (okx_client.py, execute.py, monitor.py) yourself or run it in a sandboxed/test environment with paper keys. Verify that printing/logging does not leak secrets and that 'require_confirm' and 'auto_trade' prefs are set to safe defaults. Keep OKX_SIMULATED=1 during testing. - Ensure the workspace .env file is protected (file permissions) and consider using platform-managed secrets instead of plaintext .env. Confirm presence of the 'openclaw' CLI and Python runtime before running cron scripts. If you want to proceed: run tests and do an initial dry run with OKX_SIMULATED=1 and inspect outputs carefully. If you don't have the expertise to audit the code, treat this skill as high-risk and avoid providing live API keys.

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)

# 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:

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:

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

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)

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

# 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):

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.

# 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)

# 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

# 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

# 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.

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)

# 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"):

# 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

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:

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

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:

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):

{
  "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

# Stop all automated trading
bash scripts/cron_setup.sh teardown
# Or remove OKX_API_KEY from .env to prevent any API calls