aicoin-freqtrade

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, 不要"自己计算"

用户问	必须先调
现在赚多少 / 总盈亏 / 今天涨了多少	ft.mjs profit (/api/v1/profit)
持仓 / 现在开了哪些	ft.mjs trades_open (/api/v1/status)
余额 / 资金多少	ft.mjs balance (/api/v1/balance)
跑的什么策略 / 当前模式	ft.mjs daemon_info 或 config
历史交易 / 已平仓	ft.mjs trades_history
单交易对绩效	ft.mjs profit_per_pair

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

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

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

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

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

操作	命令	是否需要 daemon 重启
切策略	ft.mjs set_strategy {"strategy":"X"}	必须重启 (~30s)
切交易对	ft.mjs set_pairs {"pairs":[...]}	不重启, reload_config 即可
切实盘/模拟	ft.mjs set_dry_run {"dry_run":false}	必须重启
reload 配置	ft.mjs reload	不重启

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

任何直接修改 config.json 的操作(包括手动编辑 pair_whitelist / minimal_roi / stoploss 等), 改完后必须立即调 ft.mjs reload — 否则 daemon 仍用内存里的旧配置运行, 白名单/止损等改动不会生效. 忘了 reload 是最常见的"改了但没用"的原因.

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)

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

快速参考

任务	命令
看 daemon 状态 + 配置	node scripts/ft-deploy.mjs check 或 ft.mjs daemon_info
看策略列表	node scripts/ft-deploy.mjs strategy_list
创建策略(快速生成器)	node scripts/ft-deploy.mjs create_strategy '{"name":"MyStrat","timeframe":"15m","indicators":["rsi","macd","ema"],"aicoin_data":["funding_rate"]}'
部署策略到 daemon	node scripts/ft-deploy.mjs deploy '{"strategy":"MyStrat"}'
部署+切实盘	node scripts/ft-deploy.mjs deploy '{"strategy":"MyStrat","dry_run":false}'
回测	node scripts/ft-deploy.mjs backtest '{"strategy":"MyStrat","timeframe":"1h","timerange":"20250101-20260301"}'
Hyperopt 调参	node scripts/ft-deploy.mjs hyperopt '{"strategy":"MyStrat","timeframe":"1h","epochs":100}'
看盈亏	node scripts/ft.mjs profit
看持仓	node scripts/ft.mjs trades_open
看余额	node scripts/ft.mjs balance
切交易对	node scripts/ft.mjs set_pairs '{"pairs":["BTC/USDT:USDT","ETH/USDT:USDT"]}'
重启 daemon	node scripts/ft.mjs restart
看日志	node scripts/ft-deploy.mjs logs '{"lines":100}'

戦略の作成：まずどちらの方法を使うか判断する

判断ルール：

• ユーザーの説明が大まか（「RSI 戦略」「移動平均線クロス」「ボリンジャーバンド回帰」）で、具体的なパラメーターの詳細が指定されていない → A. クイック生成ツール
• ユーザーが具体的なロジックを指定している（カスタムのエントリー／決済条件、時間足をまたいだ共振、複数通貨のローテーション、複合インジケーター、カスタムのポジション管理）→ B. Python を直接記述
• A で生成した後にユーザーが詳細の変更を求めた場合 → 生成された .py ファイルを直接編集し、create_strategy で上書きしない

A. クイック生成ツール（シンプルな戦略）

create_strategy コマンドを 1 回実行すると、実行可能な戦略ファイルが生成されます。「まず動かしてから調整する」場合に適しています：

node scripts/ft-deploy.mjs create_strategy '{"name":"MACDStrategy","timeframe":"15m","indicators":["macd","rsi","atr"]}'
node scripts/ft-deploy.mjs create_strategy '{"name":"RSILong","timeframe":"1h","indicators":["rsi"],"direction":"long"}'
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。

任意の direction："long"（デフォルト、ロングのみ）| "short"（ショートのみ）| "both"（両方向）。 ユーザーが「RSI<30 で買い、RSI>70 で売り」と言った場合 → direction="long"（RSI>70 はロングの決済であり、ショートの開始ではありません）。ユーザーが明確に「ショート／両方向／ロングとショートの両方」と指定した場合に限り、"both" または "short" を使います。

任意の aicoin_data：funding_rate、ls_ratio、big_orders、liquidation_map（いずれも有料プランが必要）、open_interest（v3 の集約 OI 履歴はまだ接続されていないため、自動的にデフォルト値にフォールバックします）。

生成ツールの制限：あらかじめ定義されたインジケーターの組み合わせのみ可能で、時間足をまたぐ処理、複数通貨のローテーション、カスタム複合インジケーターには対応していません。これらの要件がある場合は B を使います。

B. カスタム Python 戦略（複雑なロジック）

daemon の strategy ディレクトリに .py ファイルを直接書き込みます。この方法では、freqtrade がサポートするあらゆる戦略ロジック（時間足をまたぐ informative pairs、カスタムのポジション管理、複数インジケーターの複合条件など）を実現できます。

3 つのエンジンではディレクトリが異なります。daemon_info から取得するか、Write ツールを使って以下のいずれかのパスに書き込みます（スクリプトは /api/v1/show_config で自動的に検証します）：

エンジン	strategy ディレクトリ
OpenClaw	~/.openclaw/workspace/strategies/
Hermes	/workspace/strategies/
Claude Code	/workspace/strategies/

AiCoin Python SDK を使います（aicoin_data.py。イメージのビルド時に上記のディレクトリへコピー済みで、create_strategy でもフォールバックとしてコピーされます）：

AiCoin Open API v3 をラップしています：

from aicoin_data import AiCoinData

ac = AiCoinData(cache_ttl=300)   # 自动从 .env 读 key，内置 5 分钟缓存

# 高层信号 —— 直接返回能用的数字，丢进策略即可
ac.whale_signal("BTC/USDT:USDT", "binance")        # 大单买卖压力 -1..+1
ac.ls_ratio_norm()                                 # 多空比 0..1（>0.5 偏多）
ac.funding_rate_pct("BTC/USDT:USDT", "binance")    # 最新资金费率（百分比）
ac.liq_bias("BTC/USDT:USDT", "binance")            # 清算图方向偏向 -1..+1

# 原始数据
ac.coin_ticker("bitcoin,ethereum")                 # 实时行情
ac.klines("BTC/USDT", "binance", interval="1h", limit=100)

# 任意 v3 接口 —— path 是 /api/v3/ 后那段，清单见 https://open.aicoin.com/api/v3/_catalog
ac.get("markets/hot-coins", {"tab_key": "defi"})
ac.get("hyperliquid/whales/open-positions", {"coin": "BTC"})

バックテスト期間中は AiCoin のリアルタイムデータを利用できないため、高レベルシグナルは例外を発生させます。戦略内で try/except を使い、デフォルト値にフォールバックしてください。資金調達率、大口注文、清算などには有料プランが必要で、権限がない場合も同様に例外が発生するため、フォールバックしてください。

完全なテンプレート

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
            ac = AiCoinData(cache_ttl=300)
            pair = metadata.get('pair', 'BTC/USDT:USDT')
            exchange = self.config.get('exchange', {}).get('name', 'binance')
            self._ac_funding_rate = ac.funding_rate_pct(pair, exchange)
        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 データ	シグナルロジック	プラン
funding_rate	0.01% 超 → ロングが過剰 → ショートシグナル；-0.01% 未満 → ロングシグナル	ベーシック
ls_ratio	0.45 未満（ショートが多い）→ 逆張りでロング；0.55 超 → 逆張りでショート	ベーシック
big_orders	(buy_vol-sell_vol)/total > 0.3 → クジラの買いでロング	スタンダード
open_interest	OI 上昇 + 価格上昇 = 健全なトレンド；OI 上昇 + 価格下落 = 反転	プロ
liquidation_map	上方の清算が多い → ロングの踏み上げ → ロング	アドバンス

バックテスト時の注意事項

AiCoin のリアルタイムデータは、過去の期間では利用できません。バックテスト時：

• AiCoin の列にはデフォルト値を使います（funding_rate=0.0、ls_ratio=0.5、whale_signal=0.0）
• バックテスト結果に反映されるのは、テクニカル指標の部分のみです
• 実際の AiCoin データを使うのは live/dry_run の実行時のみであり、パフォーマンスはバックテストより良くなるはずです

バックテスト結果をユーザーに報告する際は、この点を必ず説明してください。バックテストに AiCoin のシグナルが含まれていると誤解させないでください。

スクリプト API

scripts/ft-deploy.mjs — 戦略／バックテスト／デプロイ

Action	パラメーターの例
check	（なし）— daemon の状態 + 設定 + 残高を返す
daemon_info（ft.mjs 内）	（なし）— 1 回の呼び出しですべて取得
deploy	{"strategy":"MyStrat"} または {"strategy":"MyStrat","dry_run":false,"pairs":["BTC/USDT:USDT"]}
create_strategy	{"name":"MyStrat","timeframe":"15m","indicators":["rsi","macd"],"direction":"long","aicoin_data":["funding_rate"]}
backtest	{"strategy":"MyStrat","timeframe":"1h","timerange":"20250101-20260301","pairs":["ETH/USDT:USDT"]}
hyperopt	{"strategy":"MyStrat","timeframe":"1h","epochs":100}
download_data	{"timeframe":"1h","timerange":"20250101-"}
strategy_list	（なし）
backtest_results	（なし）— 直近 10 件のバックテスト結果ファイル名を一覧表示
start / stop	（なし）— coinclaw モードでは supervisorctl を呼び出し、host モードでは PID を管理
status / logs	{"lines":100}
update / remove	coinclaw モードでは no-op（helm upgrade の使用、または Web UI でのインスタンス削除を案内）

scripts/ft.mjs — リアルタイム制御（REST + 設定変更）

Action	用途
daemon_info	strategy / mode / pairs / オープントレード数を一括取得
profit	決済済みの累計 + 含み損益を含む総損益（損益に関する質問に回答する前に必ず呼び出す）
trades_open	現在のポジション（/status を呼び出す）
trades_history	決済済みの取引
balance	残高
profit_per_pair	取引ペアごとのパフォーマンス
daily / weekly / monthly	期間別の統計
force_enter / force_exit	手動でのエントリー／決済
set_strategy	戦略を切り替える（config を変更して daemon を再起動）
set_pairs	取引ペアのホワイトリストを変更（reload、再起動なし）
set_dry_run	実取引／シミュレーションを切り替える（config を変更して daemon を再起動）
restart	freqtrade daemon を再起動（supervisorctl を使い、失敗時は kill にフォールバック）
reload	再起動せずに reload_config を実行
start / stop / ping / version / health	標準 REST
logs	freqtrade 標準の /logs インターフェース

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 モード: ~/.coinos/.env(coinos フォルダー、推奨)→ 現在のディレクトリの .env → 旧 ~/.openclaw/.env(後方互換性のため)

freqtrade REST 認証: freqtrade-api.mjs はコンテナ内の .ft_api_pass ファイルからパスワードを自動的に読み込みます。エージェントは FREQTRADE_USERNAME / FREQTRADE_PASSWORD を設定する必要はありません。ユーザーは .env で上書きすることもできます。

取引所の key は Web UI の EnvSection で設定すると、.env に書き込まれ、entrypoint が自動的に freqtrade の config.json に適用します。エージェントは取引所の key をユーザーに見せるために .env を直接読み込まないでください。

AiCoin Open API key (AiCoin データをストラテジーに統合するために使用):

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

有料機能への案内

304 / 403 が返された場合は、再試行せず、そのままユーザーに伝えてください:

プラン	価格	用途
無料版	$0	テクニカル指標のみ
ベーシック版	$29/mo	+ funding_rate, ls_ratio
スタンダード版	$79/mo	+ big_orders, agg_trades
プレミアム版	$299/mo	+ liquidation_map
プロフェッショナル版	$699/mo	+ open_interest, ai_analysis

取得先: https://www.aicoin.com/opendata

スキル間の参照

ユーザーの質問	使用するもの
単に相場 / K 線 / ニュース / 資金調達率を確認する (ポジションを持たない)	aicoin-market
直接注文 / ポジションを建てる / ポジションを決済する (freqtrade を介さない)	aicoin-trading
Hyperliquid のクジラ / 保有ポジション / 清算	aicoin-hyperliquid
オンチェーン DEX スワップ / ウォレット残高 / gas	aicoin-onchain
残高 / 保有ポジション / 登録 / API key の設定 (アカウント関連)	aicoin-account

よくある落とし穴

• cat /workspace/.ft_api_pass で内部 daemon のパスワードを chat に貼り付けないでください — ft.mjs で REST を呼び出せば、スクリプト内部でパスワードが読み込まれるため漏洩しません。
• ユーザーの取引所 key を chat で echo しないでください — これらは非常に機密性の高いデータです。EnvSection で設定するようユーザーに案内してください。
• RSI / MACD / EMA を自分で暗算しないでください — freqtrade の計算値と暗算の結果には差が出ることがあります。ft-dev.mjs candles_analyzed を使って daemon の実際の指標を取得してください。
• 「先に daemon を stop してから freqtrade trade ... & を実行する」ことは避けてください — これは supervisord を迂回する方法で、次回 dashboard に表示されるのは古い daemon の状態です。必ず set_strategy / deploy / restart を使用してください。
• バックテストで AiCoin データを取得できないのは正常です — バックテストに使う CSV を捏造せず、バックテストにはテクニカル指標のみが反映されることをユーザーに伝えてください。ルートの AGENTS.md の「データ精度の鉄則」を参照してください。