CoinOS Trading

Critical Rules

1. NEVER place orders without explicit user confirmation.

   create_order

   returns a preview first. Show it, wait for "确认"/"yes", THEN re-run with

   "confirmed":"true"

   .
2. NEVER auto-adjust order parameters (size, leverage). If balance is insufficient, tell the user.
3. NEVER sell or close positions unless the user specifically asks.
4. NEVER write custom CCXT/Python code. ALL exchange operations MUST go through

   exchange.mjs

   .
5. NEVER run

   env

   or

   printenv

   — leaks API secrets.
6. Scripts auto-load

   .env

   — never pass credentials inline.

Quick Reference

node scripts/exchange.mjs balance '{"exchange":"okx"}'

node scripts/exchange.mjs ticker '{"exchange":"binance","symbol":"BTC/USDT"}'

node scripts/exchange.mjs orderbook '{"exchange":"binance","symbol":"BTC/USDT"}'

node scripts/exchange.mjs create_order '{"exchange":"okx","symbol":"BTC/USDT","type":"market","side":"buy","amount":0.001}'

node scripts/exchange.mjs positions '{"exchange":"okx","market_type":"swap"}'

node scripts/exchange.mjs set_leverage '{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"market_type":"swap"}'

node scripts/auto-trade.mjs setup '{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"capital_pct":0.5}'

BTC/USDT

BTC/USDT:USDT

Setup

.env

npm install

.env

1. Current working directory

2. ~/.openclaw/workspace/.env

3. ~/.openclaw/.env

CEX (Centralized Exchanges)

# Format: {EXCHANGE}_API_KEY / {EXCHANGE}_API_SECRET
# Supported: BINANCE, OKX, BYBIT, BITGET, GATE, HTX, KUCOIN, MEXC, COINBASE
BINANCE_API_KEY=xxx
BINANCE_API_SECRET=xxx

# OKX additionally needs passphrase:
OKX_API_KEY=xxx
OKX_API_SECRET=xxx
OKX_PASSWORD=your-passphrase

PROXY_URL=socks5://127.0.0.1:7890  # optional

Hyperliquid (DEX — wallet-based, NOT API key)

# Wallet address (0x...) — this is your public address, NOT an API key
HYPERLIQUID_API_KEY=0x1234...abcd
# Private key (0x...) — export from MetaMask/Rabby, or use HL Agent Wallet
HYPERLIQUID_API_SECRET=0xabcd...1234

1. HYPERLIQUID_API_KEY

   = your EVM wallet address (the 0x... shown in MetaMask/Rabby)

2. HYPERLIQUID_API_SECRET

   = private key. Two options:
   • Agent Wallet (recommended): On app.hyperliquid.xyz → Settings → Agent Wallet → Create. This gives a limited-permission key that can only trade (cannot withdraw).
   • Wallet private key: Export from MetaMask (Settings → Security → Export Private Key). Full permissions — use with caution.

BTC/USDC:USDC

ETH/USDC:USDC

Pre-Trade Checklist (MANDATORY)

1. markets

   — Get

   limits.amount.min

   and

   contractSize

   . NEVER guess minimums.

2. balance

   — Check available funds.
3. Convert units —

   amount

   differs between spot and futures:
   • Spot: amount = base currency (e.g., 0.01 = 0.01 BTC)
   • Futures: amount = contracts (e.g., 1 = 1 contract). Use

     contractSize

     to convert.
4. Confirm with user — Show coin, direction, quantity, estimated cost, leverage. Ask "确认下单？"

0.01

0.01 / 0.01 = 1

1

100 / price

(100 / price) / contractSize

Scripts

scripts/exchange.mjs — Exchange Operations (CCXT)

Public (no API key)

exchanges

markets

{"exchange":"binance","market_type":"swap","base":"BTC"}

ticker

{"exchange":"binance","symbol":"BTC/USDT"}

orderbook

{"exchange":"binance","symbol":"BTC/USDT"}

trades

{"exchange":"binance","symbol":"BTC/USDT"}

ohlcv

{"exchange":"binance","symbol":"BTC/USDT","timeframe":"1h"}

Account (API key required)

balance

{"exchange":"binance"}

positions

{"exchange":"binance","market_type":"swap"}

open_orders

{"exchange":"binance","symbol":"BTC/USDT"}

closed_orders

{"exchange":"binance","symbol":"BTC/USDT","limit":50}

my_trades

{"exchange":"binance","symbol":"BTC/USDT","limit":50}

fetch_order

{"exchange":"binance","symbol":"BTC/USDT","order_id":"xxx"}

Trading (API key required)

create_order

{"exchange":"okx","symbol":"BTC/USDT","type":"market","side":"buy","amount":0.001}

{"exchange":"okx","symbol":"BTC/USDT:USDT","type":"market","side":"buy","amount":1,"market_type":"swap"}

cancel_order

{"exchange":"okx","symbol":"BTC/USDT","order_id":"xxx"}

set_leverage

{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"market_type":"swap"}

set_margin_mode

{"exchange":"okx","symbol":"BTC/USDT:USDT","margin_mode":"cross","market_type":"swap"}

transfer

{"exchange":"binance","code":"USDT","amount":100,"from_account":"spot","to_account":"future"}

• Account names:

  spot

  ,

  future

  ,

  delivery

  ,

  margin

  ,

  funding

  (exact values).
• OKX unified account: Spot and derivatives share balance. No transfer needed. Error 58123 = unified account.
• Binance: Requires explicit transfer between spot/futures.

scripts/auto-trade.mjs — Automated Trading

~/.openclaw/workspace/aicoin-trade-config.json

setup

{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":20,"capital_pct":0.5,"stop_loss_pct":0.025,"take_profit_pct":0.05}

status

{}

open

{"direction":"long"}

{"direction":"short"}

close

{}

open

Automated Trading Workflow

1. Ask user: exchange, coin, capital, leverage

2. auto-trade.mjs setup

   with params

3. auto-trade.mjs status

   to verify
4. Set up OpenClaw cron:

openclaw cron add --name "BTC auto trade" --every 10m --session isolated \
  --message "Use aicoin-market to fetch data, analyze, then use aicoin-trading auto-trade.mjs open/close"

Cross-Skill References

Common Errors

• errorCode 304 / HTTP 403

  — Paid AiCoin feature. Do NOT retry. See below.

• Invalid symbol

  — Use CCXT format:

  BTC/USDT

  (spot),

  BTC/USDT:USDT

  (swap). Hyperliquid uses USDC:

  BTC/USDC:USDC

  .

• Insufficient balance

  — Check balance first, don't auto-adjust. Tell user.

• API key invalid

  — Keys in

  .env

  , never inline. Check if user configured exchange keys.

• Rate limit exceeded

  — Wait 1-2s between requests.
• OKX error 58123 — Unified account, no transfer needed between spot/futures.

Paid Feature Guide

1. What happened: This feature needs a paid AiCoin API subscription.
2. How to get a key: Visit https://www.aicoin.com/opendata to register and create an API key.
3. Tier options:

1. How to configure: Add to

   .env

   file:

AICOIN_ACCESS_KEY_ID=your-key-id
AICOIN_ACCESS_SECRET=your-secret

1. .env

   auto-loaded from: cwd →

   ~/.openclaw/workspace/.env

   →

   ~/.openclaw/.env

   . After configuring, the same script command will work.