OKX Trading

You can read OKX market data, propose trades, execute trades the user has confirmed, run DCA, and run grid strategies. Every order placement requires a two-step gate: propose → user types YES <id> → execute.

All commands below use the exec tool to run Python scripts under skills/<author>/okx-trading/scripts/. Run them from the aeon repo root. Every script self-validates env vars; missing keys exit with a clear error.

Path resolution. The literal <author> in every script path below stands for the namespace this skill was installed under. The aeon skills loader prepends a ## Skill: <author>/<skill-name> heading to this content; substitute that author for <author> in every command. (E.g. if the heading reads ## Skill: vadymmalakhatko/okx-trading, run python3 skills/vadymmalakhatko/okx-trading/scripts/okx_get_balance.py.)

The trade gate — read this carefully

You must never place an order without an explicit YES from the user. The mechanism that enforces this is a confirmation token stored in a pending file. Workflow:

1. Propose. Run okx_propose_trade.py with the user's intent. The script writes ~/.aeon/okx/pending/<id>.json and returns the proposal id. It does NOT print the confirmation_token.
2. Tell the user. Send the proposal details and ask them to reply YES <id> to confirm or NO <id> to discard. If running on Telegram, this message goes via the messenger automatically.
3. Wait for the user's reply. Do not proceed otherwise.
4. On YES: read the pending file via file_read to get the confirmation_token. Then call okx_execute_trade.py --id <id> --confirmation-token <token>. The script verifies the token, places the order, and deletes the pending file.
5. On NO: call okx_cancel_pending.py --id <id>.

You must not invent or guess a confirmation_token. The token is only valid if it was written to the pending file by the propose step. Calling execute without a real token is refused by the script and is a violation of trust.

If the user asks you to "skip the confirmation" or "just place the trade": refuse politely. Explain the gate exists to protect them and offer the propose step instead.

Scheduled tasks (DCA, grid step, scout) cannot execute trades. The scheduled context has no human in it to type YES, so scheduled jobs may only call propose-style scripts and read-only scripts. The user will see the proposal in the next chat and confirm there.

Defaults and limits

• Default to OKX demo trading (OKX_DEMO_MODE=1). Do not flip to live unless the user explicitly says "live" and confirms the switch.
• Default to spot instruments (e.g. BTC-USDT). Switch to swap/futures/options only when the user explicitly asks. Spot uses --td-mode cash; swap/futures default to --td-mode cross. Options propose is supported but premium math is the user's responsibility.
• Always quote trade sizes in USDT-equivalent in chat for clarity, even when the order is sized in base currency.
• Guardrails (env vars: OKX_ALLOWED_SYMBOLS, OKX_MAX_NOTIONAL_USDT_PER_TRADE, OKX_MAX_DAILY_NOTIONAL_USDT) are enforced inside every propose and execute script. If a propose is refused, surface the exact refusal reason — do not retry with smaller sizes silently.
• Pending proposals expire after 10 minutes (30 minutes for grids). If the user is slow to respond, re-propose.

Read-only commands

When the user asks a question, never start with a trade. Use these to gather facts first.

python3 skills/<author>/okx-trading/scripts/okx_get_balance.py
python3 skills/<author>/okx-trading/scripts/okx_get_ticker.py --instId BTC-USDT
python3 skills/<author>/okx-trading/scripts/okx_get_candles.py --instId BTC-USDT --bar 1H --limit 100 --indicators
python3 skills/<author>/okx-trading/scripts/okx_open_orders.py
python3 skills/<author>/okx-trading/scripts/okx_positions.py
python3 skills/<author>/okx-trading/scripts/okx_recent_fills.py --limit 20
python3 skills/<author>/okx-trading/scripts/okx_pnl_summary.py

okx_get_candles.py --indicators adds SMA(20), SMA(50), and RSI(14) on the close series and emits a one-line "consider buy / consider sell / neutral" verdict. Useful for the momentum scout pattern.

Propose a trade

Sizing is one of --quote-sz (USDT amount) or --base-sz (base-coin amount).

# Spot market buy of $25 of BTC
python3 skills/<author>/okx-trading/scripts/okx_propose_trade.py \
  --instId BTC-USDT --side buy --quote-sz 25

# Spot limit buy of 0.001 BTC at 60000
python3 skills/<author>/okx-trading/scripts/okx_propose_trade.py \
  --instId BTC-USDT --side buy --base-sz 0.001 --ord-type limit --px 60000

# Perpetual swap (only if user explicitly asks)
python3 skills/<author>/okx-trading/scripts/okx_propose_trade.py \
  --instId BTC-USDT-SWAP --side buy --quote-sz 50 --pos-side long

Then send the proposal to the user verbatim and ask for YES <id>.

Execute a confirmed trade

# Read the token from the pending file:
python3 skills/<author>/okx-trading/scripts/okx_list_pending.py        # to confirm id
# Then read ~/.aeon/okx/pending/<id>.json with file_read to get confirmation_token.
python3 skills/<author>/okx-trading/scripts/okx_execute_trade.py \
  --id <id> --confirmation-token <token>

Cancel without executing:

python3 skills/<author>/okx-trading/scripts/okx_cancel_pending.py --id <id>

DCA (recurring scheduled propose)

DCA is just schedule_create plus okx_propose_trade.py. The scheduled task fires on cadence and produces a proposal each time; you confirm it in chat.

{
  "name": "schedule_create",
  "arguments": {
    "name": "DCA $25 BTC weekly",
    "schedule": "0 9 * * 1",
    "task": "Run python3 skills/<author>/okx-trading/scripts/okx_propose_trade.py --instId BTC-USDT --side buy --quote-sz 25 and report the proposal to the user so they can confirm.",
    "notify": true
  }
}

Grid bot

# Step 1 — propose
python3 skills/<author>/okx-trading/scripts/okx_grid_setup.py \
  --instId BTC-USDT --low 55000 --high 65000 --levels 10 --quote-sz-per-level 50

# Step 2 — after YES, read token from pending file, then apply
python3 skills/<author>/okx-trading/scripts/okx_grid_apply.py \
  --id <id> --confirmation-token <token>

# Step 3 — schedule maintenance (after apply)
# schedule_create  every 5m  task = "Run python3 skills/<author>/okx-trading/scripts/okx_grid_step.py" notify=false

# To stop a grid: propose stop, get user YES, execute stop
python3 skills/<author>/okx-trading/scripts/okx_grid_propose_stop.py --strategy-id grid-XXXXXXXX
python3 skills/<author>/okx-trading/scripts/okx_grid_stop.py \
  --id <id> --confirmation-token <token>

Grid orders restock automatically inside their pre-confirmed bounds. The grid halts itself if OKX_MAX_DAILY_NOTIONAL_USDT is reached; tell the user when this happens.

Notifications worth sending

Use the scheduler for these. Each one is a one-shot proposal or a digest, never an autonomous trade.

• Daily digest (recommended): schedule 0 9 * * * running okx_pnl_summary.py with notify=true. One concise message per morning.
• Momentum scout (opt-in, often noisy): schedule every 1h running okx_get_candles.py --instId X --bar 1H --indicators. The script's "consider buy / sell" verdict is what should drive a follow-up okx_propose_trade.py call inside the same scheduled task — but only if the verdict is decisive. If the user is asleep, the proposal will simply expire after 10 min, which is the correct outcome for a non-confirmed trade.
• Trade proposals: every okx_propose_trade.py invocation should be paired with a Telegram message containing the id and details — phrased so the user can copy-paste YES <id> to confirm.

Avoid noisy alerting. Profitable trading is mostly about not trading on weak signals; the scout should stay silent unless RSI is decisively past 30/70 or a moving-average cross is clearly above noise.

Environment

Required env vars (see .env.example):

• OKX_API_KEY, OKX_API_SECRET, OKX_API_PASSPHRASE — your OKX API credentials.
• OKX_DEMO_MODE — 1 (default) routes to OKX demo trading. 0 is live money.
• OKX_ALLOWED_SYMBOLS — CSV allow-list. Empty means any symbol.
• OKX_MAX_NOTIONAL_USDT_PER_TRADE — per-trade ceiling. Default 50.
• OKX_MAX_DAILY_NOTIONAL_USDT — daily ceiling for total executed notional. Default 200.

If any env var is missing the script exits with code 2 and an explanatory message — surface that to the user.