Aicoin

AiCoin

Crypto data & trading toolkit powered by AiCoin Open API.

Setup Checklist

Scripts auto-load .env files from these locations (earlier paths take priority):

1. Current working directory (.env)
2. ~/.openclaw/workspace/.env
3. ~/.openclaw/.env

Before asking the user for ANY credentials, first check if .env already exists:

grep -c "AICOIN_ACCESS_KEY_ID" ~/.openclaw/workspace/.env 2>/dev/null || echo "0"

• If output is 1 or more → .env has AiCoin key configured. Skip setup, just run scripts directly.
• If output is 0 → No AiCoin key, but the built-in free key works automatically. Just run scripts.

Only ask setup questions when the user explicitly requests features that need configuration:

• Exchange trading (Binance, OKX, etc.) → needs exchange API keys + cd <skill-dir>/aicoin && npm install for ccxt
• Freqtrade bot → run ft-deploy.mjs deploy (auto-configures everything, needs Python 3 + exchange keys in .env)
• Proxy access → needs PROXY_URL

Do NOT block the user from running commands. The skill works out of the box with the built-in free key.

How to Configure Environment Variables

The .env file location is ~/.openclaw/workspace/.env. When adding new variables:

1. Check if .env already exists:

   test -f ~/.openclaw/workspace/.env && echo "EXISTS" || echo "NOT_FOUND"
   

2. If EXISTS → append (do NOT overwrite):

   echo 'PROXY_URL=socks5://127.0.0.1:7890' >> ~/.openclaw/workspace/.env
   

3. If NOT_FOUND → create:

   echo 'PROXY_URL=socks5://127.0.0.1:7890' > ~/.openclaw/workspace/.env
   

4. If a key already exists and needs updating, replace the specific line:

   sed -i '' 's|^PROXY_URL=.*|PROXY_URL=socks5://127.0.0.1:7890|' ~/.openclaw/workspace/.env
   

NEVER overwrite the entire .env file — it may contain other credentials the user has already configured.

SECURITY: How to Run Scripts

Scripts auto-load .env — NEVER pass credentials inline. Just run:

node scripts/coin.mjs coin_ticker '{"coin_list":"bitcoin"}'

NEVER do this — it exposes secrets in conversation logs:

# WRONG! DO NOT DO THIS!
AICOIN_ACCESS_KEY_ID=xxx node scripts/coin.mjs coin_ticker '{"coin_list":"bitcoin"}'

If a script fails due to missing env vars, guide the user to update their .env file instead of injecting variables into the command.

Environment Variables

Create a .env file in the OpenClaw workspace directory (recommended):

# AiCoin API (optional — built-in free key works with IP rate limits)
# Mapping: AiCoin website "API Key" → AICOIN_ACCESS_KEY_ID
#          AiCoin website "API Secret" → AICOIN_ACCESS_SECRET
AICOIN_ACCESS_KEY_ID=your-api-key
AICOIN_ACCESS_SECRET=your-api-secret

# Exchange trading — only if needed (requires: npm install -g ccxt)
BINANCE_API_KEY=xxx
BINANCE_API_SECRET=xxx
# Supported: BINANCE, OKX, BYBIT, BITGET, GATE, HTX, KUCOIN, MEXC, COINBASE
# For OKX also set OKX_PASSWORD=xxx

# Proxy for exchange access — only if needed
# Supports http, https, socks5, socks4
PROXY_URL=socks5://127.0.0.1:7890
# Or standard env vars: HTTPS_PROXY=http://127.0.0.1:7890

# Freqtrade — auto-configured by ft-deploy.mjs, no manual setup needed
# FREQTRADE_URL=http://localhost:8080
# FREQTRADE_USERNAME=freqtrader
# FREQTRADE_PASSWORD=auto-generated

IMPORTANT — AiCoin API Key Configuration:

1. The user may provide two values without labels (just two strings copied from the AiCoin website). Do NOT guess which is which. Ask the user to confirm: "哪个是 API Key，哪个是 API Secret？" Or look for the labels in the user's message.

2. After writing keys to .env, ALWAYS verify by running a test call:

   node scripts/coin.mjs coin_ticker '{"coin_list":"bitcoin"}'
   

3. If the test returns error code 1001 (signature verification failed), the keys are swapped. Fix by swapping them:

   # Read current values, swap them
   OLD_KEY=$(grep '^AICOIN_ACCESS_KEY_ID=' ~/.openclaw/workspace/.env | cut -d= -f2)
   OLD_SECRET=$(grep '^AICOIN_ACCESS_SECRET=' ~/.openclaw/workspace/.env | cut -d= -f2)
   sed -i '' "s|^AICOIN_ACCESS_KEY_ID=.*|AICOIN_ACCESS_KEY_ID=${OLD_SECRET}|" ~/.openclaw/workspace/.env
   sed -i '' "s|^AICOIN_ACCESS_SECRET=.*|AICOIN_ACCESS_SECRET=${OLD_KEY}|" ~/.openclaw/workspace/.env
   

   Then re-run the test to confirm it works.

Or configure in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "aicoin": {
        "enabled": true,
        "apiKey": "your-aicoin-access-key-id",
        "env": {
          "AICOIN_ACCESS_SECRET": "your-secret"
        }
      }
    }
  }
}

Prerequisites

• Node.js — required for all scripts
• ccxt — required only for exchange trading: cd <skill-dir>/aicoin && npm install

Scripts

All scripts follow: node scripts/<name>.mjs <action> [json-params]

scripts/coin.mjs — Coin Data

scripts/market.mjs — Market Data

Market Info

K-Line

Index

Crypto Stocks

Treasury (Corporate Holdings)

Order Book Depth

scripts/news.mjs — News & Content

scripts/twitter.mjs — Twitter/X Crypto Tweets

scripts/newsflash.mjs — Newsflash (OpenData)

scripts/features.mjs — Features & Signals

Market Overview

Whale Order Tracking

Trading Pairs

Signals

scripts/hl-market.mjs — Hyperliquid Market

Tickers

Whales

Liquidations

Open Interest

Taker

scripts/hl-trader.mjs — Hyperliquid Trader

Trader Analytics

Fills

Orders

Positions

Portfolio

Advanced

scripts/exchange.mjs — Exchange Trading (CCXT)

⚠️ MANDATORY: All exchange operations MUST go through exchange.mjs.

• NEVER write custom CCXT/Python code to interact with exchanges. Always use node scripts/exchange.mjs <action> '<params>'.
• NEVER import ccxt directly in custom scripts. The exchange.mjs wrapper handles broker attribution, proxy config, and API key management.
• exchange.mjs automatically sets AiCoin broker tags for order attribution. Custom CCXT code will NOT have these tags, causing orders to be mis-attributed.
• For automated trading workflows, use auto-trade.mjs which wraps exchange.mjs with risk management.

Requires npm install ccxt and exchange API keys.

Public (no API key required)

Account (API key required)

Trading (API key required)

🚨 SAFETY RULES — MANDATORY for ALL trading operations:

1. NEVER execute a buy/sell/trade without explicit user confirmation. Always show the order details and ask "确认下单？" BEFORE calling create_order.
2. NEVER sell or close the user's existing positions unless the user specifically asks to sell/close.
3. NEVER write custom CCXT, Python, or curl code to interact with exchanges. ALL exchange operations MUST go through exchange.mjs.

⚠️ CRITICAL — amount units differ between spot and futures:

• Spot: amount is in base currency (e.g., amount: 0.01 = 0.01 BTC)
• Futures/Swap: amount is in contracts (e.g., amount: 1 = 1 contract). Get contractSize from markets to convert.

User intent → amount conversion (you MUST get this right):

NEVER pass the user's number directly as amount without checking the unit context!

Before placing any order, you MUST:

1. Run markets to get the trading pair's limits.amount.min (minimum order size) and contractSize — do NOT guess or assume minimums
2. Run balance to check available funds
3. Convert user's quantity to the correct unit using the table above
4. For futures/swap: calculate actual buying power = balance × leverage
5. Verify: buying power ≥ order value
6. Confirm with user: "You want to buy X contracts (= Y BTC ≈ Z USDT), correct?" before placing the order

Example pre-trade check for BTC/USDT perpetual on OKX:

# Step 1: Check minimum order size AND contract size
node scripts/exchange.mjs markets '{"exchange":"okx","market_type":"swap","base":"BTC"}'
# → look for limits.amount.min (e.g. 1 contract) and contractSize (e.g. 0.01 BTC)
# → This means: 1 contract = 0.01 BTC, min order = 1 contract = 0.01 BTC

# Step 2: Check balance
node scripts/exchange.mjs balance '{"exchange":"okx"}'
# → e.g. 7 USDT free

# Step 3: Calculate — 7 USDT × 10x = 70 USDT ÷ $68000 ≈ 0.001 BTC ÷ 0.01 = 0.1 contracts → below min 1 contract → cannot trade
# With more capital: 100 USDT × 10x = 1000 ÷ $68000 ≈ 0.0147 BTC ÷ 0.01 = 1.47 → round to 1 contract → OK

Notes on transfer:

• OKX unified account (重要): OKX uses a unified trading account — spot and derivatives share the SAME balance. Do NOT ask the user to transfer funds between accounts. If transfer returns error 58123, tell the user: "你的 OKX 是统一账户，现货和合约共用同一个余额，不需要划转。" Do NOT suggest manual transfer in the app.
• Binance: Requires explicit transfer between spot/futures accounts.

scripts/ft.mjs — Freqtrade Bot Control

scripts/ft-dev.mjs — Freqtrade Dev Tools

scripts/auto-trade.mjs — Automated Trading

Config + execution helper. The AI agent makes all strategy decisions — this script only handles config, risk management, and order execution.

Config is stored at ~/.openclaw/workspace/aicoin-trade-config.json.

The open action automatically:

1. Checks balance and market minimums
2. Calculates position size from config (capital_pct × balance × leverage)
3. Sets leverage
4. Places market order
5. Places stop-loss and take-profit limit orders

scripts/ft-deploy.mjs — Freqtrade Deployment

One-click Freqtrade deployment via git clone + official setup.sh (no Docker). Clones the Freqtrade repo, runs setup.sh -i to install all dependencies (including TA-Lib), generates config from .env exchange keys, starts as background process, auto-writes FREQTRADE_* vars to .env.

Deploy defaults to dry-run mode (simulated trading, no real money). Pass {"dry_run":false} for live trading.

IMPORTANT: NEVER use Docker for Freqtrade. The deploy script uses git clone + setup.sh -i (official Freqtrade installation method). Do NOT fall back to Docker, do NOT write custom install scripts, do NOT try pip install freqtrade directly. Just run node scripts/ft-deploy.mjs deploy — it handles everything.

IMPORTANT: Do NOT manually edit Freqtrade config files, do NOT manually run freqtrade trade commands, do NOT manually source .venv/bin/activate. Always use ft-deploy.mjs actions. If deploy fails, check logs with ft-deploy.mjs logs and report the error — do NOT attempt manual workarounds.

Automated Trading Guide

When the user asks to set up automated trading, follow this workflow. Do NOT write custom scripts.

How It Works

The AI agent is the strategist. On each cycle:

1. Fetch data using existing scripts: coin.mjs (funding, OI, liquidation), market.mjs (klines, volume), features.mjs (whale orders, long/short ratio), hl-market.mjs (Hyperliquid data)
2. Analyze the data — trend, momentum, risk signals. Use your own judgment.
3. Decide: open long, open short, close position, or hold
4. Execute via auto-trade.mjs open '{"direction":"long"}' — handles position sizing, leverage, stop-loss/take-profit automatically

Quick Setup

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

# 2. Check status
node scripts/auto-trade.mjs status

OpenClaw Cron (Recommended)

Use OpenClaw's built-in cron, NOT system crontab. This gives the user visibility in the web UI.

openclaw cron add \
  --name "BTC auto trade" \
  --every 10m \
  --session isolated \
  --message "You are a crypto trader. Use the aicoin skill to: 1) Fetch BTC market data (price, funding rate, OI, whale orders, liquidation). 2) Analyze the data and decide: open long, open short, close, or hold. 3) If trading, run: node scripts/auto-trade.mjs open '{\"direction\":\"long\"}'. 4) Report your analysis briefly."

When User Asks "帮我自动交易"

1. Ask: which exchange? which coin? how much capital? what leverage?
2. Run auto-trade.mjs setup with their params
3. Run auto-trade.mjs status to verify exchange connection
4. Set up OpenClaw cron with their preferred interval
5. Done — tell them they can check status anytime via auto-trade.mjs status

Freqtrade Guide

When the user asks about backtesting, professional strategies, quantitative trading, or deploying a trading bot, guide them to Freqtrade.

Freqtrade vs auto-trade.mjs:

• auto-trade.mjs = simple AI-driven, good for testing, small capital
• Freqtrade = professional, backtestable, risk-managed, production-grade

Deployment (One Command)

# Check prerequisites first
node scripts/ft-deploy.mjs check

# Deploy (dry-run mode by default — safe)
node scripts/ft-deploy.mjs deploy '{"pairs":["BTC/USDT:USDT","ETH/USDT:USDT"]}'

This automatically:

1. Ensures Python 3.11+ is available (auto-installs via brew if needed on macOS)
2. Clones Freqtrade repo to ~/.freqtrade/source/
3. Runs official setup.sh -i (installs TA-Lib, creates venv, installs all dependencies)
4. Creates config from exchange keys in .env
5. Includes a sample RSI+EMA strategy (pure pandas, no TA-Lib import needed)
6. Starts Freqtrade as a background process with API server
7. Writes FREQTRADE_URL, FREQTRADE_USERNAME, FREQTRADE_PASSWORD to .env
8. Ready to use via ft.mjs and ft-dev.mjs

Prerequisites: Python 3.11+ and git. Exchange API keys must be in .env. Everything else is auto-installed — do NOT install manually or use Docker.

User Journey

"帮我部署Freqtrade"
  → node scripts/ft-deploy.mjs deploy
  → "已部署，dry-run模式，用模拟资金运行"

"帮我回测BTC策略"
  → node scripts/ft-deploy.mjs backtest '{"strategy":"SampleStrategy","timeframe":"1h","timerange":"20250101-20260301"}'
  → "回测结果: 胜率62%, 最大回撤-8%, 总收益+45%"

"不错，上实盘"
  → node scripts/ft-deploy.mjs deploy '{"dry_run":false}'
  → "⚠️ 已切换到实盘模式，使用真实资金"

"今天赚了多少？"
  → node scripts/ft.mjs profit
  → node scripts/ft.mjs daily '{"count":7}'

"暂停交易"
  → node scripts/ft.mjs stop

When User Mentions These Keywords → Use Freqtrade

• 回测 / backtest → ft-deploy.mjs backtest (does NOT require Freqtrade to be running)
• 写策略 / write strategy → Write a .py file to ~/.freqtrade/user_data/strategies/, then ft-deploy.mjs backtest
• 量化策略 / strategy → ft-dev.mjs strategy_list (requires running process)
• 部署机器人 / deploy bot → ft-deploy.mjs deploy
• 实盘 / live trading → ft-deploy.mjs deploy '{"dry_run":false}'
• 盈亏 / profit → ft.mjs profit
• 停止机器人 / stop bot → ft.mjs stop or ft-deploy.mjs stop

IMPORTANT: For backtesting, use ft-deploy.mjs backtest. Do NOT write custom Python backtest scripts. The Freqtrade backtester is production-grade with proper slippage, fees, and position sizing simulation.