AiCoin Freqtrade

Freqtrade 策略 / 回测 / 部署 / 实时控制 — 跨 CoinClaw 三引擎自动适配。

关键原则(读完再动手)

一、CoinClaw 容器里 freqtrade 是常驻 daemon

OpenClaw / Hermes / Claude Code 三个引擎容器都通过 supervisord 把 freqtrade 起为常驻进程, 监听 127.0.0.1:8080, 默认跑 NoOpStrategy(空跑). 不要自己起 freqtrade 进程 — 会跟 daemon 抢端口, dashboard 立刻 offline.

正确流程是: 写策略文件 → 调 ft-deploy.mjs deploy {"strategy":"..."} → 脚本改 config + 重启 daemon. dashboard 会自动刷出新策略.

scripts/ft.mjs + scripts/ft-deploy.mjs 内置三引擎自动识别(lib/coinclaw-env.mjs), 路径 / auth / supervisord socket 都自动解析, agent 不用关心是哪个引擎.

二、永远先调 freqtrade REST API, 不要"自己计算"

dashboard 数字对齐规则(关键): 用户问"赚了多少"必须报告两个数字:

• 已平仓累计盈亏 = profit_closed_coin (USDT) — dashboard 顶栏的累计盈亏 = 这个
• 含浮动总盈亏 = profit_all_coin (USDT) — 已平仓 + 当前持仓的浮动盈亏

只调 /status 拿持仓浮动盈亏会漏掉已平仓部分, 导致跟 dashboard 数字不一致 — 用户立刻发现, 信任度归零.

三、切策略 / 切实盘 / 切交易对必须走脚本

config.json 是 daemon 启动时读一次, 手动改完不会自动生效. 必须用:

或者一次完成所有变更: ft-deploy.mjs deploy {"strategy":"X","pairs":["BTC/USDT:USDT"],"dry_run":false}.

chat 主动发起的高 stake 操作必须强 confirm(违反即错):

适用: 用户在 chat 里说"平掉"、"切实盘"、"卖了"、"开仓"等 — 通过 agent 调用 force_exit / force_enter / set_dry_run 的操作.

流程:

1. 先列预览: 动哪个 trade / pair / 当前盈亏 / 估算损益 / dry_run vs live / 余额状况
2. 明确等用户输"确认"或"yes" 才真调 force_exit / set_dry_run / force_enter
3. 即使用户语气笃定("平了","直接切"), 也必须先预览等确认

不需要 confirm 的:

• 查询类(查持仓 / 盈亏 / 状态) — 直接读
• freqtrade daemon 自己根据策略信号自动开/平仓 — 这是 daemon 本职工作, 用户切实盘那一刻就授权了, agent 不在这个链路里, 不要拦也不需要 confirm
• 非破坏性配置(set_pairs 加币对、reload) — 列改动表然后直接执行

违反规则的反例:

• ❌ 用户说"平掉", 你直接调 force_exit 平了真持仓 (K-Live-3 dogfood 抓到的真 bug)
• ❌ 用户说"切实盘", 你不列 .env key / 余额 / 风险就直接 set_dry_run {"dry_run":false}
• ✅ 用户说"平掉", 你列"持仓: BNB/USDT 0.05 +$1.07, 平这单吗? dry_run=true 模拟盘", 等用户确认

写策略 + 切策略 倾向分两轮(create_strategy 一轮, set_strategy 一轮). 不是技术限制,是 UX 选择:

1. 第一轮: 写完策略文件 → 告诉用户"已生成 X.py, 要切上去吗?"
2. 用户确认后第二轮: set_strategy 切策略 + 重启 daemon (~30s)

这样用户切策略前能 review 生成文件; daemon 重启 30s 期间用户对状态有预期, 不会误判 chat 卡死. 用户明确说"一气呵成做完"也可以单 turn 跑完两步, 但默认分轮.

四、Freqtrade 不支持网格策略 (grid)

用户问网格时直接说明限制 + 建议趋势跟踪 / 区间策略 / 网格回报模拟器替代. 不要硬写一个伪网格.

快速参考

两种创建策略的方式

A. 快速生成器(简单策略)

create_strategy 一条命令生成一个带选定 indicator + 可选 AiCoin 数据的策略文件:

node scripts/ft-deploy.mjs create_strategy '{"name":"MACDStrategy","timeframe":"15m","indicators":["macd","rsi","atr"]}'
node scripts/ft-deploy.mjs create_strategy '{"name":"WhaleStrat","timeframe":"15m","indicators":["rsi","macd"],"aicoin_data":["funding_rate","ls_ratio"]}'

可选 indicators: rsi, bb, ema, sma, macd, stochastic/kdj, atr, adx, cci, williams_r, vwap, ichimoku, volume_sma, obv.

可选 aicoin_data: funding_rate (基础版), ls_ratio (基础版), big_orders (标准版), open_interest (专业版), liquidation_map (高级版).

B. 自定义 Python 策略 (复杂逻辑)

直接写 .py 文件到 daemon 的 strategy 目录. 三引擎该目录不同, 从 daemon_info 拿或用 Write 工具写到下面任一路径(脚本会自动用 /api/v1/show_config 验证):

用 AiCoin Python SDK (aicoin_data.py, image build 时已复制到上面目录, 也由 create_strategy 兜底拷贝):

from aicoin_data import AiCoinData, ccxt_to_aicoin

ac = AiCoinData(cache_ttl=300)
symbol = ccxt_to_aicoin("BTC/USDT:USDT", "binance")  # → "btcswapusdt:binance"

# 免费版
ac.coin_ticker("bitcoin")
ac.kline(symbol, period="3600")
ac.hot_coins("market")

# 基础版 ($29/mo)
ac.funding_rate(symbol)
ac.funding_rate(symbol, weighted=True)
ac.ls_ratio()

# 标准版 ($79/mo)
ac.big_orders(symbol)
ac.agg_trades(symbol)

# 高级版 ($299/mo)
ac.liquidation_map(symbol, cycle="24h")

# 专业版 ($699/mo)
ac.open_interest("BTC", interval="15m")
ac.ai_analysis(["BTC"])

完整模板

from freqtrade.strategy import IStrategy, IntParameter, DecimalParameter
from pandas import DataFrame
import logging, time

logger = logging.getLogger(__name__)


class MyStrategy(IStrategy):
    INTERFACE_VERSION = 3
    timeframe = '15m'
    can_short = True

    minimal_roi = {"0": 0.05, "60": 0.03, "120": 0.01}
    stoploss = -0.05
    trailing_stop = True
    trailing_stop_positive = 0.02
    trailing_stop_positive_offset = 0.03

    rsi_buy = IntParameter(20, 40, default=30, space='buy')
    rsi_sell = IntParameter(60, 80, default=70, space='sell')

    _ac_funding_rate = 0.0
    _ac_last_update = 0.0

    def populate_indicators(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        # RSI
        delta = dataframe['close'].diff()
        gain = delta.clip(lower=0).rolling(window=14).mean()
        loss = (-delta.clip(upper=0)).rolling(window=14).mean()
        rs = gain / loss
        dataframe['rsi'] = 100 - (100 / (1 + rs))

        # AiCoin 数据 (live/dry_run only, backtest 用默认值 0.0)
        dataframe['funding_rate'] = 0.0
        if self.dp and self.dp.runmode.value in ('live', 'dry_run'):
            now = time.time()
            if now - self._ac_last_update > 300:
                self._update_aicoin_data(metadata)
                self._ac_last_update = now
            dataframe.iloc[-1, dataframe.columns.get_loc('funding_rate')] = self._ac_funding_rate

        return dataframe

    def _update_aicoin_data(self, metadata: dict):
        try:
            import sys, os
            _sd = os.path.dirname(os.path.abspath(__file__))
            if _sd not in sys.path:
                sys.path.insert(0, _sd)
            from aicoin_data import AiCoinData, ccxt_to_aicoin
            ac = AiCoinData(cache_ttl=300)
            pair = metadata.get('pair', 'BTC/USDT:USDT')
            exchange = self.config.get('exchange', {}).get('name', 'binance')
            symbol = ccxt_to_aicoin(pair, exchange)
            data = ac.funding_rate(symbol, weighted=True, limit='5')
            items = data.get('data', [])
            if isinstance(items, list) and items:
                self._ac_funding_rate = float(items[0].get('close', 0)) * 100
        except Exception as e:
            logger.warning(f"AiCoin data error: {e}")

    def populate_entry_trend(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        dataframe.loc[
            (dataframe['rsi'] < self.rsi_buy.value) &
            (dataframe['volume'] > 0),
            'enter_long'] = 1
        dataframe.loc[
            (dataframe['rsi'] > self.rsi_sell.value) &
            (dataframe['volume'] > 0),
            'enter_short'] = 1
        return dataframe

    def populate_exit_trend(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        dataframe.loc[(dataframe['rsi'] > 70), 'exit_long'] = 1
        dataframe.loc[(dataframe['rsi'] < 30), 'exit_short'] = 1
        return dataframe

写完后用 deploy {"strategy":"MyStrategy"} 让 daemon 切到这个策略.

AiCoin 数据集成模式

回测注意事项

AiCoin 实时数据不在历史区间内可用. 回测时:

• AiCoin 列用默认值 (funding_rate=0.0, ls_ratio=0.5, whale_signal=0.0)
• 回测结果只反映技术指标部分
• live/dry_run 跑的时候才用真实 AiCoin 数据, 表现应该比回测好

向用户报告回测结果时必须主动说明这点, 不要让用户以为回测包含了 AiCoin 信号.

脚本 API

scripts/ft-deploy.mjs — 策略 / 回测 / 部署

scripts/ft.mjs — 实时控制 (REST + 配置变更)

scripts/ft-dev.mjs — 调试 (回测 / 蜡烛 / 策略详情)

backtest_start / backtest_status / backtest_history / candles_live / candles_analyzed / strategy_list / strategy_get / whitelist / blacklist 等.

环境变量与认证

.env 自动加载顺序:

• coinclaw 容器内: /workspace/.env (Hermes/CC) 或 /home/node/.openclaw/workspace/.env (OpenClaw)
• host 模式: cwd → ~/.openclaw/workspace/.env → ~/.openclaw/.env

freqtrade REST 认证: freqtrade-api.mjs 自动从容器内 .ft_api_pass 文件读密码, agent 不用配 FREQTRADE_USERNAME / FREQTRADE_PASSWORD. 用户也可以通过 .env 覆盖.

交易所 key 在 web UI 的 EnvSection 里配置, 写到 .env 后 entrypoint 会自动 patch 进 freqtrade config.json. agent 不要直接读 .env 给用户看交易所 key.

AiCoin Open API key (用于策略集成 AiCoin 数据):

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

付费功能引导

返回 304 / 403 时 不要重试, 直接告诉用户:

获取地址: https://www.aicoin.com/opendata

跨 skill 引用

常见 pitfall

• 不要 cat /workspace/.ft_api_pass 把内部 daemon 密码贴到 chat — 直接用 ft.mjs 调 REST, 脚本内部读密码不会泄漏.
• 不要在 chat 里 echo 用户的交易所 key — 这些是高敏数据, 引导用户去 EnvSection 配置.
• 不要自己心算 RSI / MACD / EMA — freqtrade 算出的值跟你心算结果会差, 用 ft-dev.mjs candles_analyzed 拿 daemon 的真实指标.
• 不要"先 stop daemon 再 freqtrade trade ... &" — 那是绕过 supervisord, 下次 dashboard 看到的还是老的 daemon 状态. 必须用 set_strategy / deploy / restart.
• 回测拿不到 AiCoin 数据是正常的 — 不要造假 CSV 喂回测, 直接告诉用户回测只反映技术指标. 见根 AGENTS.md 的"数据准确性铁则".