okx-pro

# OKX Pro 🟧 专业 OKX 交易所交易技能 - 全球领先的加密货币合约交易所。 ## 🚀 Quick Start ### Setup Credentials Save to `~/.openclaw/credentials/okx.json`: ```json { "apiKey": "YOUR_API_KEY", "secretKey": "YOUR_SECRET_KEY", "passphrase": "YOUR_PASSPHRASE" } ``` ### Environment Variables (alternative) ```bash export OKX_API_KEY="your_api_key" export OKX_SECRET="your_secret_key" export OKX_PASSPHRASE="your_passphrase" ``` --- # 📖 技术文档 | Technical Documentation ## 中文文档 ### 1. 概述 OKX Pro 是一个完整的 OKX 交易所集成技能，支持： - 现货交易 (Spot Trading) - 合约交易 (Futures Trading) - U本位合约 / 币本位合约 - 杠杆交易 (Leverage Trading) - 止盈止损 (Take Profit / Stop Loss) - 仓位管理 (Position Management) ### 2. API 版本 本技能使用 OKX V5 API： - 基础URL: `https://www.okx.com` - 所有请求需要签名认证 ### 3. 支持的交易对 | 交易对 | 说明 | |--------|------| | BTC-USDT | BTC 现货 | | ETH-USDT | ETH 现货 | | BTC-USDT-SWAP | BTC U本位永续合约 | | ETH-USDT-SWAP | ETH U本位永续合约 | | BTC-USD-SWAP | BTC 币本位永续合约 | ### 4. 交易参数 | 参数 | 说明 | 示例 | |------|------|------| | instId | 交易对ID | BTC-USDT-SWAP | | tdMode | 仓位模式 | cross(全仓) / isolated(逐仓) | | side | 交易方向 | buy / sell | | ordType | 订单类型 | market / limit / conditional | | sz | 数量 | 0.001 | | px | 价格 | 50000 | | SL | 止损 | slTriggerPx | | TP | 止盈 | tpTriggerPx | ### 5. 订单类型详解 #### 市价单 (Market Order) 立即以市场价成交 ```json {"instId":"BTC-USDT-SWAP","tdMode":"cross","side":"buy","ordType":"market","sz":"0.001"} ``` #### 限价单 (Limit Order) 指定价格成交 ```json {"instId":"BTC-USDT-SWAP","tdMode":"cross","side":"buy","ordType":"limit","sz":"0.001","px":"50000"} ``` #### 条件单 (Conditional Order) 止盈止损订单 ```json { "instId": "BTC-USDT-SWAP", "tdMode": "cross", "side": "sell", "ordType": "conditional", "sz": "0.001", "slTriggerPx": "45000", "slOrdPx": "-1" } ``` ### 6. 止盈止损详解 - `slTriggerPx`: 止损触发价格 - `slOrdPx`: 止损订单价格 (-1 = 市价) - `tpTriggerPx`: 止盈触发价格 - `tpOrdPx`: 止盈订单价格 ### 7. 仓位管理 | 操作 | API | |------|-----| | 查询仓位 | GET /api/v5/position/positions | | 设置杠杆 | POST /api/v5/account/set-leverage | | 追加保证金 | POST /api/v5/account/increase-margin | | 减少保证金 | POST /api/v5/account/decrease-margin | ### 8. 风险控制 ⚠️ 安全规则： 1. 杠杆不超过10x（新手建议2-3x） 2. 始终设置止损 3. 大额订单先确认 4. 测试网验证后再实盘 --- ## English Documentation ### 1. Overview OKX Pro provides complete OKX exchange integration: - Spot Trading - Futures Trading (U-Margin / Coin-Margin) - Leverage Trading - Take Profit / Stop Loss - Position Management ### 2. API Version Uses OKX V5 API: - Base URL: `https://www.okx.com` - All requests require signature authentication ### 3. Supported Trading Pairs | Pair | Description | |------|-------------| | BTC-USDT | BTC Spot | | ETH-USDT | ETH Spot | | BTC-USDT-SWAP | BTC USDT-Margin Perpetual | | ETH-USDT-SWAP | ETH USDT-Margin Perpetual | ### 4. Trading Parameters | Parameter | Description | Example | |-----------|-------------|---------| | instId | Instrument ID | BTC-USDT-SWAP | | tdMode | Trade Mode | cross / isolated | | side | Order Side | buy / sell | | ordType | Order Type | market / limit / conditional | | sz | Size | 0.001 | | px | Price | 50000 | ### 5. Order Types #### Market Order Execute immediately at market price ```json {"instId":"BTC-USDT-SWAP","tdMode":"cross","side":"buy","ordType":"market","sz":"0.001"} ``` #### Limit Order Execute at specified price ```json {"instId":"BTC-USDT-SWAP","tdMode":"cross","side":"buy","ordType":"limit","sz":"0.001","px":"50000"} ``` #### Conditional Order Stop loss / Take profit orders ```json { "instId": "BTC-USDT-SWAP", "tdMode": "cross", "side": "sell", "ordType": "conditional", "sz": "0.001", "slTriggerPx": "45000", "slOrdPx": "-1" } ``` ### 6. Stop Loss / Take Profit - `slTriggerPx`: Stop loss trigger price - `slOrdPx`: Stop loss order price (-1 = market) - `tpTriggerPx`: Take profit trigger price - `tpOrdPx`: Take profit order price ### 7. Position Management | Operation | API | |-----------|-----| | Get Positions | GET /api/v5/position/positions | | Set Leverage | POST /api/v5/account/set-leverage | | Increase Margin | POST /api/v5/account/increase-margin | | Decrease Margin | POST /api/v5/account/decrease-margin | ### 8. Risk Control ⚠️ Safety Rules: 1. Leverage max 10x (beginners: 2-3x) 2. Always set stop loss 3. Confirm large orders 4. Test on demo trading first --- ## 🔐 Signature Helper ```bash # 生成 OKX 签名的函数 okx_sign() { local method="$1" local request_path="$2" local body="$3" local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z") local message="${timestamp}${method}${request_path}${body}" local signature=$(echo -n "$message" | openssl dgst -sha256 -hmac "$OKX_SECRET" | cut -d' ' -f2) echo "$signature" } okx_request() { local method="$1" local endpoint="$2" local body="$3" local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z") local signature=$(okx_sign "$method" "$endpoint" "$body") curl -s -X "$method" "https://www.okx.com$endpoint" \ -H "Content-Type: application/json" \ -H "OKX-ACCESS-KEY: $OKX_API_KEY" \ -H "OKX-ACCESS-SIGN: $signature" \ -H "OKX-ACCESS-TIMESTAMP: $timestamp" \ -H "OKX-ACCESS-PASSPHRASE: $OKX_PASSPHRASE" \ -d "$body" } ``` ## 📊 Basic Queries ### Check Balance ```bash okx_request "GET" "/api/v5/account/balance" '' ``` ### Get Current Price ```bash curl -s "https://www.okx.com/api/v5/market/ticker?instId=BTC-USDT" | jq '.data[0]' ``` ### Get All Positions ```bash okx_request "GET" "/api/v5/position/positions" '' ``` ## ⚡ Futures Trading ### Open LONG Position (Buy) ```bash INST_ID="BTC-USDT-SWAP" SZ="0.001" TD_MODE="cross" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"$TD_MODE\",\"side\":\"buy\",\"ordType\":\"market\",\"sz\":\"$SZ\"}" ``` ### Open SHORT Position (Sell) ```bash INST_ID="BTC-USDT-SWAP" SZ="0.001" TD_MODE="cross" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"$TD_MODE\",\"side\":\"sell\",\"ordType\":\"market\",\"sz\":\"$SZ\"}" ``` ### Set Stop Loss ```bash INST_ID="BTC-USDT-SWAP" SZ="0.001" STOP_PRICE="75000" TD_MODE="cross" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"$TD_MODE\",\"side\":\"sell\",\"ordType\":\"conditional\",\"sz\":\"$SZ\",\"slTriggerPx\":\"$STOP_PRICE\",\"slOrdPx\":\"-1\"}" ``` ### Set Take Profit ```bash INST_ID="BTC-USDT-SWAP" SZ="0.001" TP_PRICE="85000" TD_MODE="cross" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"$TD_MODE\",\"side\":\"sell\",\"ordType\":\"conditional\",\"sz\":\"$SZ\",\"tpTriggerPx\":\"$TP_PRICE\",\"tpOrdPx\":\"-1\"}" ``` ### Close Position (Market) ```bash INST_ID="BTC-USDT-SWAP" SZ="0.001" TD_MODE="cross" okx_request "POST" "/api/v5/trade/close-position" "{\"instId\":\"$INST_ID\",\"mgnMode\":\"cross\",\"posSide\":\"long\"}" ``` ### Set Leverage ```bash INST_ID="BTC-USDT-SWAP" LEVERAGE="10" TD_MODE="cross" okx_request "POST" "/api/v5/account/set-leverage" "{\"instId\":\"$INST_ID\",\"lever\":\"$LEVERAGE\",\"mgnMode\":\"$TD_MODE\"}" ``` ## 📈 Spot Trading ### Buy (Market) ```bash INST_ID="BTC-USDT" SZ="0.001" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"cash\",\"side\":\"buy\",\"ordType\":\"market\",\"sz\":\"$SZ\"}" ``` ### Sell (Market) ```bash INST_ID="BTC-USDT" SZ="0.001" okx_request "POST" "/api/v5/trade/order" "{\"instId\":\"$INST_ID\",\"tdMode\":\"cash\",\"side\":\"sell\",\"ordType\":\"market\",\"sz\":\"$SZ\"}" ``` ## 🔧 Utilities ### View Open Orders ```bash okx_request "GET" "/api/v5/trade/orders-pending" '' ``` ### Cancel Order ```bash INST_ID="BTC-USDT-SWAP" ORD_ID="123456789" okx_request "POST" "/api/v5/trade/cancel-order" "{\"instId\":\"$INST_ID\",\"ordId\":\"$ORD_ID\"}" ``` ### View Trade History ```bash okx_request "GET" "/api/v5/trade/fills" '' ``` ## 📋 Popular Pairs | InstID | Description | |--------|-------------| | BTC-USDT | Bitcoin U本位合约 | | ETH-USDT | Ethereum U本位合约 | | SOL-USDT | Solana U本位合约 | | XRP-USDT | XRP U本位合约 | | DOGE-USDT | Dogecoin U本位合约 | | BTC-USDT-SWAP | 永续合约 | | ETH-USDT-SWAP | ETH 永续合约 | ## ⚠️ Safety Rules 1. **ALWAYS** verify position before closing 2. **ALWAYS** set Stop Loss on leveraged trades 3. **NEVER** use leverage higher than 10x without experience 4. **VERIFY** pair and quantity before executing 5. **CONFIRM** with user before executing large orders 6. **注意**：U本位合约用 USDT 计价，币本位用 USD/BTC 计价 ## 🔗 Links - [API Documentation](https://www.okx.com/docs-v5/) - [Create Account](https://www.okx.com/) - [Testnet](https://www.okx.com/market/trade/demo)