Back to Details

aicoin-trading

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CoinOS Trading

CoinOS Trading

Exchange trading toolkit powered by AiCoin Open API. Buy, sell, manage positions across 9 major exchanges.
Version: 1.0.0
由AiCoin Open API提供支持的交易所交易工具包，可在9大主流交易所完成买入、卖出、持仓管理操作。
版本： 1.0.0

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.
  1. 未获得用户明确确认前绝对不要下单。 
    create_order
    会首先返回订单预览，向用户展示预览内容，等待用户回复"确认"/"yes"后，再传入
    "confirmed":"true"
    重新执行。
  2. 绝对不要自动调整订单参数（下单数量、杠杆倍数）。如果余额不足，请直接告知用户。
  3. 绝对不要主动卖出或平仓除非用户明确提出相关要求。
  4. 绝对不要编写自定义CCXT/Python代码。 所有交易所操作必须通过
    exchange.mjs
    执行。
  5. 绝对不要运行
    env
    或
    printenv
    命令    ——会泄露API密钥信息。
  6. 脚本会自动加载
    .env
    配置    ——永远不要在行内传入凭证信息。

Quick Reference

快速参考

TaskCommand
Balance
node scripts/exchange.mjs balance '{"exchange":"okx"}'
Ticker
node scripts/exchange.mjs ticker '{"exchange":"binance","symbol":"BTC/USDT"}'
Orderbook
node scripts/exchange.mjs orderbook '{"exchange":"binance","symbol":"BTC/USDT"}'
Buy (preview)
node scripts/exchange.mjs create_order '{"exchange":"okx","symbol":"BTC/USDT","type":"market","side":"buy","amount":0.001}'
Positions
node scripts/exchange.mjs positions '{"exchange":"okx","market_type":"swap"}'
Set leverage
node scripts/exchange.mjs set_leverage '{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"market_type":"swap"}'
Auto-trade setup
node scripts/auto-trade.mjs setup '{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"capital_pct":0.5}'
Supported Exchanges: Binance, OKX, Bybit, Bitget, Gate.io, HTX, KuCoin, MEXC, Coinbase, Hyperliquid.
Symbol format: CCXT format — 
BTC/USDT
(spot), 
BTC/USDT:USDT
(swap/futures).
操作命令
查询余额
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}'
支持的交易所： Binance、OKX、Bybit、Bitget、Gate.io、HTX、KuCoin、MEXC、Coinbase、Hyperliquid。
交易对格式： 遵循CCXT格式 —— 
BTC/USDT
（现货）、
BTC/USDT:USDT
（永续/交割合约）。

Setup

配置说明

Requires exchange API keys in 
.env
and ccxt installed (
npm install
in this skill directory).
.env
locations (auto-loaded, first found wins):
  1. Current working directory
  2. ~/.openclaw/workspace/.env
  3. ~/.openclaw/.env
需要在
.env
文件中配置交易所API密钥，并且安装ccxt依赖（在当前skill目录下执行
npm install
）。
.env
文件加载优先级（自动加载，先找到的生效）：
  1. 当前工作目录
  2. ~/.openclaw/workspace/.env
  3. ~/.openclaw/.env

CEX (Centralized Exchanges)

中心化交易所（CEX）配置

All CEX use the same pattern — go to exchange API management page, create API key:
ExchangeAPI Key Management URL
Binancehttps://www.binance.com/en/my/settings/api-management
OKXhttps://www.okx.com/account/my-api
Bybithttps://www.bybit.com/app/user/api-management
Bitgethttps://www.bitget.com/account/newapi
Gate.iohttps://www.gate.io/myaccount/apikeys
HTXhttps://www.htx.com/en-us/apikey/
KuCoinhttps://www.kucoin.com/account/api
MEXChttps://www.mexc.com/user/openapi
Coinbasehttps://www.coinbase.com/settings/api
undefined
所有中心化交易所的配置逻辑一致——前往交易所API管理页面，创建API密钥：
交易所API密钥管理页面地址
Binancehttps://www.binance.com/en/my/settings/api-management
OKXhttps://www.okx.com/account/my-api
Bybithttps://www.bybit.com/app/user/api-management
Bitgethttps://www.bitget.com/account/newapi
Gate.iohttps://www.gate.io/myaccount/apikeys
HTXhttps://www.htx.com/en-us/apikey/
KuCoinhttps://www.kucoin.com/account/api
MEXChttps://www.mexc.com/user/openapi
Coinbasehttps://www.coinbase.com/settings/api
undefined

Format: {EXCHANGE}_API_KEY / {EXCHANGE}_API_SECRET

配置格式：{EXCHANGE}_API_KEY / {EXCHANGE}_API_SECRET

Supported: BINANCE, OKX, BYBIT, BITGET, GATE, HTX, KUCOIN, MEXC, COINBASE

支持的交易所变量名：BINANCE, OKX, BYBIT, BITGET, GATE, HTX, KUCOIN, MEXC, COINBASE

BINANCE_API_KEY=xxx BINANCE_API_SECRET=xxx
BINANCE_API_KEY=xxx BINANCE_API_SECRET=xxx

OKX additionally needs passphrase:

OKX额外需要配置passphrase

OKX_API_KEY=xxx OKX_API_SECRET=xxx OKX_PASSWORD=your-passphrase
PROXY_URL=socks5://127.0.0.1:7890 # optional
undefined
OKX_API_KEY=xxx OKX_API_SECRET=xxx OKX_PASSWORD=your-passphrase
PROXY_URL=socks5://127.0.0.1:7890 # 可选配置
undefined

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

Hyperliquid（去中心化交易所DEX —— 基于钱包验证，无需API密钥）

Hyperliquid is a DEX. There is NO API key page. Authentication uses your wallet address + private key.
undefined
Hyperliquid是去中心化交易所，没有API密钥管理页面，使用钱包地址 + 私钥完成身份验证。
undefined

Wallet address (0x...) — this is your public address, NOT an API key

钱包地址（0x开头）—— 是你的公开地址，不是API密钥

HYPERLIQUID_API_KEY=0x1234...abcd
HYPERLIQUID_API_KEY=0x1234...abcd

Private key (0x...) — export from MetaMask/Rabby, or use HL Agent Wallet

私钥（0x开头）—— 从MetaMask/Rabby导出，或者使用HL Agent Wallet

HYPERLIQUID_API_SECRET=0xabcd...1234

**How to get these:**
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.

**Symbol format**: Hyperliquid uses USDC, not USDT: `BTC/USDC:USDC`, `ETH/USDC:USDC`.
HYPERLIQUID_API_SECRET=0xabcd...1234

**获取方式：**
1. `HYPERLIQUID_API_KEY` = 你的EVM钱包地址（MetaMask/Rabby中显示的0x开头地址）
2. `HYPERLIQUID_API_SECRET` = 私钥，有两种获取方式：
   - **Agent Wallet（推荐）**：打开app.hyperliquid.xyz → 设置 → Agent Wallet → 创建，生成的是有限权限密钥，仅可用于交易，无法提现。
   - **钱包私钥**：从MetaMask导出（设置 → 安全与隐私 → 导出私钥），拥有完整权限，请谨慎使用。

**交易对格式**: Hyperliquid使用USDC作为计价货币，而非USDT，例如：`BTC/USDC:USDC`、`ETH/USDC:USDC`。

Pre-Trade Checklist (MANDATORY)

交易前检查清单（强制执行）

Before placing ANY order:
  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 "确认下单？"
User saysSpot amountSwap amount (OKX BTC, contractSize=0.01)
"0.01 BTC"
0.01
0.01 / 0.01 = 1
(1 contract)
"1张合约"N/A
1
"100U"
100 / price
(100 / price) / contractSize
在提交任何订单之前：
  1. 调用
    markets
    接口     —— 获取
    limits.amount.min
    （最小下单数量）和
    contractSize
    （合约面值），绝对不要猜测最小下单限制。
  2. 调用
    balance
    接口     —— 检查可用资金是否充足。
  3. 单位转换 —— 现货和合约的
    amount
    参数计数方式不同：
    • 现货：amount = 标的货币数量（例如0.01代表0.01 BTC）
    • 合约：amount = 合约张数（例如1代表1张合约），使用
      contractSize
      进行单位转换。
  4. 向用户确认 —— 展示交易币种、方向、数量、预估成本、杠杆信息，询问用户"确认下单？"
用户表述现货amount值永续合约amount值（OKX BTC，contractSize=0.01）
"买0.01 BTC"
0.01
0.01 / 0.01 = 1
（1张合约）
"买1张合约"不适用
1
"买100U的BTC"
100 / 当前价格
(100 / 当前价格) / contractSize

Scripts

脚本说明

scripts/exchange.mjs — Exchange Operations (CCXT)

scripts/exchange.mjs —— 交易所操作（基于CCXT）

Public (no API key)

公开接口（无需API密钥）

ActionDescriptionParams
exchanges
Supported exchangesNone
markets
Market list
{"exchange":"binance","market_type":"swap","base":"BTC"}
ticker
Real-time ticker
{"exchange":"binance","symbol":"BTC/USDT"}
orderbook
Order book
{"exchange":"binance","symbol":"BTC/USDT"}
trades
Recent trades
{"exchange":"binance","symbol":"BTC/USDT"}
ohlcv
OHLCV candles
{"exchange":"binance","symbol":"BTC/USDT","timeframe":"1h"}
操作说明参数
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
查询K线数据
{"exchange":"binance","symbol":"BTC/USDT","timeframe":"1h"}

Account (API key required)

账户接口（需要API密钥）

ActionDescriptionParams
balance
Account balance
{"exchange":"binance"}
positions
Open positions
{"exchange":"binance","market_type":"swap"}
open_orders
Open orders
{"exchange":"binance","symbol":"BTC/USDT"}
closed_orders
Order history
{"exchange":"binance","symbol":"BTC/USDT","limit":50}
my_trades
Trade history
{"exchange":"binance","symbol":"BTC/USDT","limit":50}
fetch_order
Order by ID
{"exchange":"binance","symbol":"BTC/USDT","order_id":"xxx"}
操作说明参数
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
根据订单ID查询订单信息
{"exchange":"binance","symbol":"BTC/USDT","order_id":"xxx"}

Trading (API key required)

交易接口（需要API密钥）

ActionDescriptionParams
create_order
Place orderSpot: 
{"exchange":"okx","symbol":"BTC/USDT","type":"market","side":"buy","amount":0.001}
Swap: 
{"exchange":"okx","symbol":"BTC/USDT:USDT","type":"market","side":"buy","amount":1,"market_type":"swap"}
cancel_order
Cancel order
{"exchange":"okx","symbol":"BTC/USDT","order_id":"xxx"}
set_leverage
Set leverage
{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":10,"market_type":"swap"}
set_margin_mode
Margin mode
{"exchange":"okx","symbol":"BTC/USDT:USDT","margin_mode":"cross","market_type":"swap"}
transfer
Transfer funds
{"exchange":"binance","code":"USDT","amount":100,"from_account":"spot","to_account":"future"}
Transfer notes:
  • 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.
操作说明参数
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"}
资金划转说明：
  • 账户名称可选值：
    spot
    （现货账户）、
    future
    （合约账户）、
    delivery
    （交割账户）、
    margin
    （杠杆账户）、
    funding
    （资金账户），必须使用以上 exact 值。
  • OKX统一账户：现货和衍生品账户共享余额，无需划转。报错58123代表是统一账户，无需执行划转操作。
  • Binance：需要手动在现货和合约账户之间划转资金。

scripts/auto-trade.mjs — Automated Trading

scripts/auto-trade.mjs —— 自动交易

Config stored at 
~/.openclaw/workspace/aicoin-trade-config.json
.
ActionDescriptionParams
setup
Save trading config
{"exchange":"okx","symbol":"BTC/USDT:USDT","leverage":20,"capital_pct":0.5,"stop_loss_pct":0.025,"take_profit_pct":0.05}
status
Config + balance + positions
{}
open
Open position
{"direction":"long"}
or 
{"direction":"short"}
close
Close position + cancel orders
{}
The 
open
action automatically: checks balance, calculates position size (capital_pct x balance x leverage), sets leverage, places market order, sets SL/TP.
配置文件存储在
~/.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:
bash
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"
  1. 询问用户：交易所、交易币种、投入资金、杠杆倍数
  2. 调用
    auto-trade.mjs setup
    传入对应参数完成配置
  3. 调用
    auto-trade.mjs status
    验证配置是否正确
  4. 配置OpenClaw定时任务：
bash
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

跨skill引用

NeedUse
Prices, K-lines, news, signalsaicoin-market
Freqtrade strategies/backtestaicoin-freqtrade
Hyperliquid whale trackingaicoin-hyperliquid
需求使用的skill
价格、K线、新闻、交易信号aicoin-market
Freqtrade策略/回测aicoin-freqtrade
Hyperliquid巨鲸追踪aicoin-hyperliquid

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.
  • errorCode 304 / HTTP 403
    —— 该功能是AiCoin付费功能，不要重试，参考下方说明处理。
  • Invalid symbol
    —— 请使用CCXT格式的交易对：
    BTC/USDT
    （现货）、
    BTC/USDT:USDT
    （永续合约），Hyperliquid使用USDC计价：
    BTC/USDC:USDC
    。
  • Insufficient balance
    —— 先查询余额，不要自动调整下单数量，直接告知用户余额不足。
  • API key invalid
    —— 密钥配置在
    .env
    文件中，不要在行内传入，检查用户是否正确配置了交易所密钥。
  • Rate limit exceeded
    —— 两次请求之间等待1-2秒再重试。
  • OKX报错58123 —— 是统一账户，现货和合约账户之间无需划转资金。

Paid Feature Guide

付费功能说明

When a script returns 304 or 403: Do NOT retry. Tell the user:
  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:
TierPriceHighlights
Free$0Prices, K-lines, trending coins
Basic$29/mo+ Funding rate, L/S ratio, news
Standard$79/mo+ Whale orders, signals, grayscale
Advanced$299/mo+ Liquidation map, indicator K-lines, depth
Professional$699/moAll endpoints: AI analysis, OI, stocks
  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.
当脚本返回304或403错误时：不要重试，告知用户以下内容：
  1. 发生了什么：该功能需要订阅AiCoin API付费套餐。
  2. 如何获取密钥：访问https://www.aicoin.com/opendata注册账号并创建API密钥。
  3. 套餐选项：
套餐等级价格核心权益
免费版$0价格查询、K线数据、热门币种榜单
基础版$29/月额外支持资金费率、多空比、新闻查询
标准版$79/月额外支持巨鲸订单、交易信号、灰度持仓数据
高级版$299/月额外支持爆仓地图、指标K线、深度数据
专业版$699/月支持所有接口：AI分析、未平仓合约数据、股票数据
  1. 如何配置：在
    .env
    文件中添加以下配置：
AICOIN_ACCESS_KEY_ID=your-key-id
AICOIN_ACCESS_SECRET=your-secret
  1. .env
    文件加载顺序：当前工作目录 → 
    ~/.openclaw/workspace/.env
    → 
    ~/.openclaw/.env
    。配置完成后，重新执行原脚本命令即可正常使用。