Aicoin

AiCoin

Crypto data & trading toolkit powered by AiCoin Open API.

Version: 1.6.0 | Last Updated: 2026-03-05

🚨 CRITICAL RULES - READ FIRST

FREQTRADE OPERATIONS:

• ✅ ALWAYS use node scripts/ft-deploy.mjs deploy for deployment
• ✅ ALWAYS use node scripts/ft-deploy.mjs backtest for backtesting
• ❌ NEVER use Docker commands
• ❌ NEVER manually run freqtrade commands
• ❌ NEVER write custom Python scripts for Freqtrade

TRADING SAFETY:

• ❌ NEVER place orders without explicit user confirmation
• ❌ NEVER auto-adjust order parameters
• ✅ ALWAYS show order preview and ask "确认下单？" first

Data Sources: AiCoin aggregates data from 200+ exchanges. Price data is real-time, K-lines updated every second, funding rates every 8h.

Supported Exchanges for Trading: Binance, OKX, Bybit, Bitget, Gate.io, HTX, KuCoin, MEXC, Coinbase (requires API keys in .env).

Quick Start Examples:

# Check BTC price
node scripts/coin.mjs coin_ticker '{"coin_list":"bitcoin"}'

# Get 1h K-line
node scripts/market.mjs kline '{"symbol":"btcusdt:okex","period":"3600","size":"10"}'

# Check balance (requires exchange API keys)
node scripts/exchange.mjs balance '{"exchange":"okx"}'

Performance Tips:

• Batch queries: coin_ticker supports multiple coins → faster than separate calls
• Reduce API calls: Check balance once, reuse result for multiple calculations
• Use appropriate timeframes: Don't fetch 1000 candles when 10 is enough

Quick Reference — Most Common Commands

Run all scripts from the aicoin skill directory. Use exec tool, NOT process. API keys are pre-configured. Do NOT ask the user for keys. Do NOT run env/printenv. Do NOT use curl, web_fetch, or browser for crypto data. Always use these scripts. 🚨 TRADING SAFETY: NEVER place orders without user confirmation. ALWAYS show order details and ask "确认下单？" FIRST. NEVER auto-adjust order size or parameters. ⚡ PERFORMANCE: Use batch queries when possible. coin_ticker supports multiple coins in one call (e.g., "coin_list":"bitcoin,ethereum,solana").

Symbol shortcuts: BTC, ETH, SOL, DOGE, XRP auto-resolve to AiCoin format (e.g. btcswapusdt:binance) in coin.mjs. For exchange.mjs, use CCXT format: BTC/USDT, BTC/USDT:USDT (swap).

Chinese Slang Recognition: Understand common crypto slang: 大饼=BTC, 姨太=ETH, 狗狗=DOGE, 瑞波=XRP, 索拉纳=SOL, 做多=long, 做空=short, 爆仓=liquidation, 合约=futures/swap.

Common Errors & Solutions:

• Error: Invalid symbol → Check symbol format (AiCoin: btcusdt:okex, CCXT: BTC/USDT)
• Error: Insufficient balance → Check balance first with exchange.mjs balance, don't auto-adjust order size
• Error: API key invalid → Keys are in .env, never pass inline. Check if user configured exchange keys.
• Timeout → Freqtrade operations may take 5+ minutes, increase timeout or use ft-deploy.mjs which handles this
• Rate limit exceeded → Wait 1-2 seconds between requests. Use batch queries when possible to reduce API calls.
• Script not found → Ensure you're in the aicoin skill directory. Use exec tool with full path to script.

Response Format Best Practices:

• Use tables for structured data (prices, K-lines, balances)
• Include units (USDT, BTC, %) and directions (📈/📉) for clarity
• For analysis: show data first, then interpretation
• Keep responses concise - users can ask for details if needed
• Always fetch fresh data - NEVER use cached or memorized prices
• Timestamps: API returns UTC, convert to user's timezone if needed (default: show UTC+8 for Chinese users)
• Language: Always reply in the same language as the user. If the user writes in Chinese, ALL text (titles, headings, analysis, labels) MUST be in Chinese. Never mix English headings into a Chinese response.

Coin Recommendation Best Practices:

• When the user asks for coin picks WITHOUT specifying a sector, recommend across MULTIPLE sectors (AI, DeFi, L2, Meme, Infrastructure, etc.) for diversification
• Only focus on a single sector when the user explicitly requests it (e.g., "AI赛道", "DeFi概念")
• Use hot_coins with different keys (defi, gamefi, web, newcoin, market) to discover coins across sectors, don't just pick from one category
• Always include reasoning for each pick: why THIS coin, why NOW (momentum, volume spike, whale activity, news catalyst, etc.)

Setup Checklist

✅ Good News: The skill works out of the box! 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 into the aicoin skill directory and run npm install for ccxt
• Freqtrade bot → MUST use node scripts/ft-deploy.mjs deploy (auto-configures everything, needs Python 3.11+ + exchange keys in .env). NEVER manually configure Freqtrade, NEVER use Docker, NEVER write custom install scripts.
• 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"}'

Additional security rules:

• NEVER run env, printenv, or env | grep — leaks gateway tokens and API secrets into session logs
• NEVER use curl to call exchange REST APIs directly (Binance, OKX, etc.) — use exchange.mjs which handles auth, broker tags, and proxy
• NEVER use web_fetch, web_search, or browser for crypto data — always use the scripts in this skill
• NEVER fabricate or guess data from memory — always fetch real-time data via scripts

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. Run npm install in the aicoin skill directory to 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. create_order returns a preview by default. Show the preview to the user, wait for them to say "确认" / "yes" / "go ahead", THEN re-run with "confirmed":"true". Do NOT add confirmed=true on the first call.
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.
4. NEVER auto-adjust order parameters (size, leverage, etc.) without asking the user first. If balance is insufficient, tell the user and let them decide.
5. ALWAYS verify order details before confirmation: Show coin, direction (buy/sell/long/short), quantity, estimated cost, and ask "确认下单？"

⚠️ 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
7. Show clear summary: Coin, Direction, Quantity, Est. Cost, Leverage (if applicable)

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:

• Account names MUST use these exact values: spot, future, delivery, margin, funding. Do NOT use futures, usdm, coinm, or other aliases — they may cause errors.
• 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

🚨 CRITICAL: For ALL Freqtrade operations (deploy, backtest, update), ALWAYS use ft-deploy.mjs. NEVER manually run freqtrade commands, NEVER write custom Python scripts, NEVER use Docker.

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.

AiCoin-powered strategies (auto-installed on deploy, use AiCoin data in live/dry-run mode, fall back to technical indicators in backtest):

• FundingRateStrategy — Exploit extreme funding rates for mean reversion (Basic tier)
• WhaleFollowStrategy — Follow whale order flow + contrarian L/S ratio (Normal tier)
• LiquidationHunterStrategy — Profit from liquidation cascades (Premium tier)

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

🚨 CRITICAL: When user asks to deploy/setup Freqtrade, ALWAYS use ft-deploy.mjs. NEVER manually configure, NEVER use Docker, NEVER write custom scripts.

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 → MUST use ft-deploy.mjs backtest (does NOT require Freqtrade to be running). NEVER write custom Python backtest scripts, NEVER manually run freqtrade commands.
• 写策略 / write strategy → FIRST read an existing template (e.g. FundingRateStrategy.py), then write .py based on it. See "Writing Custom Strategies with AiCoin Data" below.
• 量化策略 / 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.

Writing Custom Strategies with AiCoin Data

🚨 BEFORE writing ANY strategy, ALWAYS read an existing template first:

cat ~/.freqtrade/user_data/strategies/FundingRateStrategy.py

Copy the pattern exactly. Do NOT invent your own approach.

Required strategy structure:

class MyStrategy(IStrategy):
    INTERFACE_VERSION = 3          # MUST be 3
    timeframe = '15m'
    can_short = True               # MUST set for short trading
    minimal_roi = {"0": 0.05}
    stoploss = -0.05

    def populate_indicators(self, dataframe, metadata):
        # ... compute indicators ...
        # AiCoin data (live/dry_run only):
        if self.dp and self.dp.runmode.value in ('live', 'dry_run'):
            self._update_data(metadata)
        return dataframe

    def populate_entry_trend(self, dataframe, metadata):   # NO 's' at end!
        # ... entry logic ...
        return dataframe

    def populate_exit_trend(self, dataframe, metadata):    # NO 's' at end!
        # ... exit logic ...
        return dataframe

⚠️ Common mistakes (NEVER do these):

• ❌ populate_entry_trends → ✅ populate_entry_trend (no 's')
• ❌ populate_exit_trades → ✅ populate_exit_trend
• ❌ for x in self.param.range → ✅ self.param.value (single value, not loop)
• ❌ Missing INTERFACE_VERSION = 3 or `can_shor

…(truncated)