binance-onchain-copy-trader

Binance オンチェーンコピートレーダー

コピートレードパイプラインのひな型です。このスキルは戦略を提供しません。 提供するのは、機能の一覧、イベントの契約、構成の骨組み、そして3つの戦略フックです。戦略そのものは、ご自身で構築し、磨き上げてください。

最初にお読みください

このスキルに記載されているすべてのリスク管理、ポジション管理方式、パラメーター値は、あくまで提案および例です。必須ではなく、安全性を保証するものでも、投資助言でもありません。

• このひな型が保証するのは、設定したチェックを実行することだけです。それらのチェックが資金を守るのに十分であることは保証しません。予算上限、損切り幅、流動性の下限は、すべてご自身で選択してください。広めに設定する、設定しない、あるいはハニーポットのブロックを無効にするなど、指示どおりにひな型は動作します。
• 同梱の3つのフックは、パイプラインが動作することを示す最小限のリファレンス実装です。推奨戦略ではなく、期待収益がプラスであることを示す根拠もありません。そのままライブで実行することは、検証されていない戦略に実資金を投入することを意味します。
• オンチェーン取引は取り消せません。自動戦略は、予期しない市場状況、プラットフォームの挙動の変化、またはこのひな型の不具合によって損失を生じさせる可能性があります。リスクはご自身で負うことになります。
• 推奨手順：意味のある期間 dry-run を実行する → events.jsonl を読み、自分のベースラインを作成する → 全額失っても許容できる金額で live に切り替える → そこから調整する。

依存関係

現在の環境で次のスキルを利用できることを確認してください。このスキルは全体を調整するだけで、基盤となる機能はすべて各スキルから提供されます。

スキル	提供する機能	ここでの用途
binance-agentic-wallet	ウォレット、成行注文、指値注文、クォータ、チェーン情報	wallet market-order limit-order
binance-wallet-tracker	アドレス監視、リアルタイムプッシュ、グループ管理	tracker ws tracker token/tx tracker group/address
↳	接続のライフサイクルとシグナルフィールドの null 許容性のセクションが含まれている必要があります。このスキルの接続監視の分割と、初回プッシュのフィールドに関する前提は、それらに直接依存します	—
binance-leaderboard	トレーダーランキング、アドレススコアリング、保有者検索	leaderboard query/analyze/alpha-radar
binance-trading-signal	スマートマネーシグナル、カスタム戦略、バックテスト	signal list signal strategy signal backtest
query-token-audit	トークンセキュリティ監査	監査 HTTP エンドポイント
query-token-info	(任意) ライブのトークン価格と市場データ	イベントに価格情報が含まれず、フックがライブ価格を必要とする場合のみ

確認：

baw --version
baw cli-check --required-version "$(grep -m1 requiredCliVersion SKILL.md | tr -dc '0-9.')" --json
#   ↑ the frontmatter `requiredCliVersion` is the single source of truth for the version floor.
#     Below it, `tracker ws --duration 0` has no keepalive and no reconnect, and the scaffold
#     refuses to start.

いずれか1つでも不足していると、対応する段階が無効になります。binance-leaderboard がなければ、アドレスを体系的に選ぶ方法がありません。binance-trading-signal がなければ、カスタムシグナル戦略を作成できません。query-token-audit がなければ監査データがなく、hard_gate は通過させるか拒否するかを判断するために require_audit にフォールバックします。

インストール元：https://github.com/binance/binance-skills-hub

はじめに

何もない状態から、スコア付きのドライランを実行するまでの手順です。各手順から、以下の該当セクションを参照してください。

順序に注意してください。 戦略の作成は最初のドライランの後であり、前ではありません。これは意図的です。このひな型の前提は、しきい値はご自身のデータから導き出すべきであり、最初の実行前にはそのデータがないということです。そのため、最初の実行では同梱のリファレンスフックを変更せずに使います。それらが優れているからではなく、より良いものを作成するために必要なデータセットを生成するからです。

1 · 環境の確認 →「起動前チェック」を参照 ウォレットが CONNECTED であること、対象チェーンが market-order と limit-order の両方に対応していること、クォートトークンとガスの残高が十分であることを確認してください。limit-order を利用できないチェーンでは、オンチェーンの保護注文を発注できません。続行する前に、その点を了承してください。 2 · トリガーソースを選択する →「トリガーソース」を参照 アドレスの購読、シグナルの購読、または両方を選択します。これによって、次にソースを選ぶ方法が決まります。

3 · ソースを選択する

• アドレスソース：候補を探すには leaderboard query を、各候補の6次元スコアを確認するには leaderboard analyze を実行します（ここでは follow_friendly が最も関連性の高い次元です）。次に、アドレスを1行に1つずつ addrs.txt に書き込みます。コメントには # を使い、最大100件です。
• シグナルソース：公式ストラテジーを閲覧するには signal explore を、自分のストラテジーを作成するには signal strategy create を、購読するには signal strategy follow を実行します。または、--smy を使い、設定なしでプラットフォーム独自の判断に任せることもできます。

ソートの次元は候補の集団の性質を大きく変えます（--sort-by は 0=PnL、20=勝率、30=取引量、50=取引回数 …）。また、個々の次元は飽和することがあります。たとえば短期間では、多くのアドレスが勝率100%で同率になる場合があります。同率を解消するために、独自の副次的な基準を追加してください。

4 · 設定を書く →「設定」を参照 初回実行時に $COPYTRADER_HOME（既定値は ~/.local/copytrader）へ空のテンプレートが書き込まれ、必須項目がすべて入力されるまで起動が拒否されます。不足している項目はすべて正確に一覧表示されます。仕組みのパラメーター（予算／1取引あたりのサイズ／同時実行数／ガスの下限値）は、フックに渡される policy とは別です。mode は dry-run のままにしてください。

ここで設定する値は推測で補う既定値ではなく、判断して決めるものです。特に budget_usd は、全額を失っても許容できる金額にしてください。この金額はステップ9で確認を求められます。

5 · 同梱のフックを変更せずにドライランする

cd <skill-dir>/scripts && python3 copytrader.py

まだフックを編集しないでください。同梱のフックはほとんど何もフィルタリングしません（方向と鮮度のみ）。そのためストラテジーとしては不十分ですが、観測手段としては優れています。幅広いサンプルを通過させることで、除外を始める前にストリームに実際に何が含まれているかを確認できます。

6 · 配線が機能しているか確認する

tail -f $COPYTRADER_HOME/copytrader.log

以下を確認します。

• 起動ログの sources と policy が、意図した内容と一致している
• events.jsonl に書き込みが行われ、decision の分布が妥当である。除外理由は、意図したものになっていますか？
• 通過したイベントに lag_s、tax、audit_risk、liquidity、price の値がある。値が欠けている場合、上流の呼び出しで何も返されていません。
• conn_seq が急速に増加していない（頻繁な再接続は、ストリームが不安定であることを意味します）
• 最初の期間が経過した後、outcomes.jsonl にデータが入り始める
• ドライラン中、state.json の deployed が0のままである

このステップで確認するのはパイプラインであり、ストラテジーではありません。データを解釈する前に、ここで問題をすべて修正してください。

7 · ここでストラテジーを書く →「ストラテジーフック」と「資金を使わずに判断をスコアリングする」を参照 データセットができたら、scripts/copytrader.py の先頭にある ══ で区切られたブロック内の3つの関数、should_enter／size_position／exit_plan を編集します。

events.jsonl と outcomes.jsonl を key で結合し、その結果に基づいてしきい値を決めてください。追加するゲートはすべて、データを根拠として示せるものにしてください。また、decision の分布から、何が除外されたのかを正確に確認できる必要があります。フックが読み取るパラメーターは自由に決められます。config.json の policy セクションに設定すると、そのまま渡されます。

8 · 反復する フックを変更 → 再実行 → 再スコアリングします。これはすべてドライランで行えます。 それがドライランの目的です。結果のサンプリングには約定が必要ないため、実資金ではなく記録されたデータからストラテジーを評価できます。そうでなければ、有用なサンプル数を集めることが最もコストのかかる作業です。

早々に結論を出さないでください。スコアリング済みの判断がわずかしかなければ何もわかりません。また、1つか2つの外れ値に左右される平均値からも何もわかりません。

9 · ライブに切り替える mode を live に設定し、リスクにさらす金額を確認してください。ライブモードでは、確認ファイルに現在の budget_usd が記載されていない限り、起動は拒否されます。

echo <budget_usd> > $COPYTRADER_HOME/I_UNDERSTAND_THE_RISK

金額はオペレーターが確認する必要がありますが、確認後のファイル作成はエージェントが行えます。 このゲートの目的は、判断が下され、その判断がこの特定の金額についてなされたことを確認することです。人間がコマンドを入力したかどうかではありません。したがって、自然な流れは、エージェントが予算と全額を失った場合の意味を提示し、オペレーターが確認し、エージェントがファイルを作成して実行を開始することです。

単なる touch ではなく金額を指定する理由は、他の人のランタイムディレクトリをコピーしても引き継がれず、その金額は決定した人が設定する必要があり、後から budget_usd を引き上げると確認が無効になるためです。リスクにさらす金額が増えるなら、古い確認を使い回すのではなく、新たに判断する必要があります。

ここまでに、意味のあるサンプルが蓄積されるまでドライランを行い、直感ではなく outcomes.jsonl から判断を評価し、budget_usd の全額を失っても許容できると結論付けておく必要があります。

ドライランではポジションが記録されないため、予算と同時実行数のガードレールは一切作動しません。そのため、ドライランのパス数は、実際に本番で開くポジション数より多くなります。 ドライランのパス率を基準に本番のサイズを決めないでください。

機能マップ

パイプラインの各段階は、既存の機能に対応しています。以下の表は参照先の一覧です。パラメーターについては、各スキルのドキュメントと --help を正式な情報源として扱ってください。

ソースの選択 — アドレスソースにはアドレスを、シグナルソースには戦略を選ぶか構築します

機能	コマンド	返される内容	主なパラメーター
トレーダーのランキング	baw leaderboard query	アドレス · winRate · realizedPnl · realizedPnlPercent · totalVolume · totalTxCnt · buyTxCnt · tags · addressLabel	-c チェーン · -p 7d/30d/90d · -t ALL/KOL/MPC · --sort-by 0=PnL 20=勝率 30=取引量 50=取引数 60=アクティビティ 70=レート 80=トークン数 · --page · --size（≤20）
単一アドレスのスコア	baw leaderboard analyze	6次元スコア（勝率／安定性／ドローダウン／タグ／PnL／follow_friendly）とAIアーキタイプ	-c · -a アドレス · -p · --top-n（≤5000）
保有銘柄による逆引き	baw leaderboard alpha-radar	指定したトークンを保有するアドレス	-c · -t カンマ区切りのトークンアドレス · -m 最小ヒット数 · -p
トークンレベルのモニタリング	baw tracker token	最近のトークンアクティビティ	-c · -g グループ · --tag-type kol/smy · --token-size · --period 1m/5m/1h/4h/24h · --filter-risk
取引レベルのモニタリング	baw tracker tx	個々の取引	上記と同じ
フォロー中のアドレス	baw tracker follow	現在のフォローリスト（読み取り専用）	-c
グループ管理	baw tracker group / address	グループの作成、一括インポート、ラベル付け、紐付け	wallet-tracker のドキュメントを参照

トリガーソース — 同等の2つのリアルタイムサブスクリプション

どちらも baw tracker ws を経由し、レイテンシーも同程度の WebSocket プッシュです。違いは、何を確認する価値があるかを誰が決めるかです。アドレスソースではウォレットを指定し、シグナルソースではプラットフォーム（または構築した戦略）が決定します。どちらか一方だけで実行することも、両方同時に実行することもできます（sources: ["address","signal"]）。

A · アドレスのサブスクリプション — 監視するウォレットを選ぶと、そのすべての取引がプッシュされます

コマンド	イベントの意味
baw tracker ws --address-list <file> -c <chain>	指定したアドレスによるすべてのオンチェーン取引。アドレスは最大100件
baw tracker ws --address <addr> -c <chain>	単一のアドレス
baw tracker ws --following -c <chain>	現在のフォローリスト。ログインが必要で、ほかのフラグとは併用できません

• 選び方：leaderboard query/analyze/alpha-radar に加え、tracker group/address でグループを作成します
• イベントの粒度：取引ごとにイベントは1件。再プッシュはありません
• 方向：tradeSideCategory — 買い {11,19}、売り {21,29}
• チェーン：-c が適用されます。単一チェーンです
• エントリー価格：イベントには tokenPrice が含まれます（取引相手が実際に約定した価格）
• 配信レイテンシ：ご自身で測定してください。中央値は数秒程度ですが、長い遅延が発生する場合があります（P90は数分に達することがあります）。想定で決めつけず、イベントのタイムスタンプから実際のレイテンシを記録してください。

B · シグナルのサブスクリプション — プラットフォームまたは独自の戦略が判断し、その結果をプッシュします

コマンド	イベントの意味
baw tracker ws --smy	スマートマネーのシグナル（複数アドレスのコンセンサス）。全チェーン対象。-c は効果がありません
baw tracker ws --kol -c <chain>	KOL レベルのイベント
baw tracker ws --wallet BSC,SOL,BASE,ETH	チェーンレベルのウォレットアクティビティ。チェーンはカンマ区切りで指定します

• 選び方：公式戦略を調べるには signal explore、カスタム戦略（meme-rush / fomo-call）の作成やサブスクリプションには signal strategy create/follow、バックテストには signal backtest を使用します
• イベントの粒度：同じ signalId が状態の更新とともに繰り返しプッシュされます — 1つのシグナルにつき数十回から数百回程度です。「これが新しいシグナルか」を判断するには、signalId で重複排除する必要があります
• シグナル専用フィールド：smartMoneyCount（一致したスマートマネーアドレス数） · exitRate（すでに退出した割合） · maxGain · status
• status の意味：valid/active は有効 · timeout は期限切れ（トリガーから120分後に1回プッシュ） · outDecline · exitRate
• チェーン：全チェーンのイベントがプッシュされます。chainId でご自身でフィルタリングしてください
• エントリー価格：currentPrice（多くの場合 null）または alertPrice（トリガー時点の過去の価格 — 現在取引可能な価格ではありません）
• 配信レイテンシ：ご自身で測定し、測定方法にも注意してください — signalId ごとに最小の遅延を取得し、実際の初回プッシュのみを数える必要があります。そうしないと、再プッシュによって「シグナルの現在の経過時間」が「レイテンシ」として扱われ、結果が桁違いに大きくなります。

どちらを選ぶか

	アドレスソース	シグナルソース
何を監視するかを決める人	あなた（アドレスを選択）	プラットフォームの判定／独自の戦略
1つのイベントの意味	ある人の1回の取引	複数のアドレス間のコンセンサス
対象範囲	100アドレスの上限に制約されます	プラットフォーム全体、全チェーン
重複排除	不要	必要（signalId による）
タイムスタンプフィールド	ts	signalTriggerTime
イベント密度	選択したアドレスの活動状況と数によって異なります	プラットフォームの判定によって異なり、チェーン間で偏りがあります — 1つのチェーンをサブスクライブすると、イベントが長時間発生しない場合があります

共通パラメーター：--duration <sec>（0 または省略 = 無制限）。スキャフォールドでは各ソースが1つの読み取りスレッドを使用します。イベントは norm_address() / norm_signal() で正規化され、単一のキューに統合されます。

シグナルの照会と戦略管理（REST、プッシュではありません）

スマートマネーシグナルのリアルタイム経路は、上の表にある tracker ws --smy です。このグループは、バックフィル、フィルタリング、カスタム戦略の作成、バックテストに使用する REST による照会と戦略管理です。レイテンシとは関係ありません。

機能	コマンド	主なパラメーター
シグナルフィード（バックフィル）	baw signal list	-c チェーン · -s all/user/meme/smart-money · --time-range 5m/1h/24h（signalTriggerTime でフィルタリング） · --sort-by time/maxGain · -n（≤100）
カスタム戦略	baw signal strategy create/update/delete/follow/unfollow/list/list-followed	-c · -t meme-rush/fomo-call · --job-id · --config
バックテスト	baw signal backtest list/detail/retry/schedule	--interval 4H/6H/12H/24H/OFF
バックテストクレジット	baw signal credits	—
公式戦略一覧	baw signal explore	—

signal list は、tracker ws --smy がプッシュするものと同じソースのフィールドを返します（signalId の値は一致します）が、どちらかがもう一方を完全に包含するわけではありません。

リスク管理と実行

以下の機能は利用可能なツールです。どのように組み合わせるかは、フックと設定によって決まります。このスキルでは、特定のチェックを義務付けていません。指定したチェックが適切なタイミングで実行されることのみを保証します。

機能	コマンド／エンドポイント
トークン監査	POST https://web3.binance.com/bapi/defi/v1/public/wallet-direct/security/token/audit、本文 {binanceChainId, contractAddress, requestId}。hasResult isSupported riskLevel extraInfo.buyTax/sellTax riskItems[].details[].isHit を返します
マーケットデータ	GET .../buw/wallet/market/token/dynamic/info/ai?chainId=&contractAddress= → price liquidity holders volume24h
見積もり	baw market-order quote --fromTokenQty --fromToken --toToken --binanceChainId --slippage
成行注文	baw market-order swap（同じパラメーターに --mev --gasLevel を追加）→ orderId を返します
注文照会	baw market-order list → status toTokenActualQty txHash
指値注文	baw limit-order buy/sell --triggerPrice --fromTokenQty --fromToken --toToken --binanceChainId --slippage --mev --gasLevel
キャンセル／一覧	baw limit-order cancel --strategyId · baw limit-order list
ガードレールの確認項目	baw wallet balance · left-quota · tx-lock · settings · chains

イベントスキーマ

どちらのソースも、norm_address()／norm_signal() によって正規化され、1 つの構造になります。フックが受け取るのは常にこの構造です。

{
  "src":   "address" | "signal",
  "key":   dedupe key (address stream = txHash; signal stream = "sig:" + signalId),
  "ca":    token contract address,
  "token": token name,
  "price": entry reference price (address stream = counterparty fill price `tokenPrice`;
           signal stream = `currentPrice` or `alertPrice`),
  "ts":    event time (epoch seconds) — time.time() - ts is the delivery latency,
  "chain": chain ID,
  "side":  11/19 = buy, 21/29 = sell (always 11 on the signal stream),
  "who":   source identity (address stream = wallet label; signal stream = "SMY×N"),
  "usd":   USD size of the counterparty's trade,
  "risk":  tokenRiskLevel,
  "top10": top-10 holder concentration,
  "tags":  token tag array,
  "extra": source-specific fields
}

extra の内容はソースによって異なります。

ソース	extra の内容
アドレス	addr
シグナル	signalId status smy（コンセンサス数）exitRate liq entry_liq holders is_alpha launch_ms mcap sig_seq

生のプッシュフィールドの全項目（正規化の際に除外されるものも含む）については、binance-wallet-tracker のフィールド一覧を参照してください。必要に応じて norm_* 関数を拡張し、より多くのフィールドを extra に含めます。

シグナルストリーム：初回配信と再配信でのフィールドの利用可能性

ストラテジーを書く前に、必ず確認してください。 --smy はイベントストリームではなく状態ストリームです。同じ signalId が存続期間中に繰り返し配信され、初回配信と再配信では含まれるフィールドが異なります。判定は初回配信時に行う必要があるため、ストラテジーで使用できるのは初回配信に含まれるフィールドだけです。

正式な定義は、binance-wallet-tracker/references/cli.md の Signal field nullability セクションにあります。以下の表は、組み立てレイヤーでのフィールドの扱いを示しています。

フィールド	初回配信	エントリー判断に使用可能か
signalId ticker chainId contractAddress	含まれる	はい
signalTriggerTime	含まれる	はい — 配信の鮮度の計算に使用します
alertPrice alertMarketCap	含まれる	はい（ただし、取引可能な価格ではなく、トリガー時点の過去の価格です）
alertLiquidity entryLiquidity	含まれる	はい
top10 holders smartMoneyCount isAlpha launchTime	含まれる	はい
status	通常は null	いいえ — 注 1 を参照してください
exitRate maxGain currentPrice	通常は null	いいえ — 注 2 を参照してください

注：

1. status によるゲートで拒否してよいのは、明示的に不正な値だけです。値がない場合は通過させてください。 初回配信時の status は通常 null です（ライフサイクル状態の timeout ／ outDecline ／ exitRate が設定されるのは後続の配信です）。if st not in ("valid","active") と書くと、正規の初回配信のほとんどが気づかないうちに除外されます。しかも、「このチェーンにはシグナルがない」という症状と見分けがつかないため、原因の診断が非常に困難になります。 正しい形式は次のとおりです。

   if st is not None and st not in ("valid", "active"):
       return False, f"status={st}"
   

2. エントリー条件に exitRate ／ maxGain ／ currentPrice を使用しないでください。 これらはシグナル発生後の推移を示すものであり、初回配信時にはサーバーがまだ計算していません。これらのフィールドに対するしきい値ゲートは初回配信時には決して作動せず、ライフサイクルの途中で購読を開始した古いシグナルを誤って判定するだけです。代わりに、決済ロジックや事後の相関分析に使用してください。これらのフィールドは引き続き完全な形で events.jsonl に書き込まれます。

3. 取引可能な価格であるかのように、alertPrice を基準に注文を出さないでください。 これはトリガー時点の過去の価格です。配信遅延と組み合わせて約定価格として使用すると、約定できない注文を記録することになります。このひな形では、これはフックに渡す参照価格としてのみ扱います。一方、保護注文のトリガーは、usd / actual filled quantity で算出した実際のエントリー価格から常に導出します。この2つを混同しないでください。フックでリアルタイムの価格が必要な場合は、市場データ（query-token-info）を照会し、取得できない場合はスキップしてください。

4. 流動性のために市場データを呼び出す必要はありません。alertLiquidity は初回配信に含まれており、新規ローンチされたトークンは市場データにインデックスがないことが多いため、イベント独自のフィールドより信頼性が低くなります。また、シグナルソースではすでに流動性によるフィルタリングが行われているため、シグナルストリームに流動性の下限を設定しても、ほとんど効果はありません。フィルタリングの役割を期待しないでください。

5. 期限切れの再配信は、status ではなく鮮度ゲートで検出してください。 status=timeout の期限切れ通知は、トリガーから常に T+120min に届きます。status は含まれますが、signalTriggerTime は古い値です。この2つのゲートは互いを補完します。status は明示的な不正値を検出し、鮮度ゲートは時間的に古くなったものをすべて検出します。

組み立て構造

ws_reader(source)          one thread per source; timestamps and enqueues only, never blocks
      ↓ queue
worker × N
      ↓
  norm_* ─────────────► normalized event `ev`
      ↓
  should_enter(ev, ctx)    ← hook ①  ctx.audit / liquidity are still None here
      ↓ pass
  gate_ok()                mechanism guardrails: budget / positions / gas / tx-lock / quota / STOP
      ↓
  audit() ∥ token_market()  fetch audit and market data concurrently, completing ctx
      ↓
  hard_gate(ctx)            mechanism-forced check: audit has a result + honeypot (configurable)
      ↓
  should_enter(ev, ctx)    ← hook ① again, now with audit and liquidity
      ↓ pass
  size_position(ev, ctx)   ← hook ②  returns a USD amount
      ↓
  market-order swap → actual_qty() reads toTokenActualQty from market-order list
      ↓
  exit_plan(ev, ctx, entry, qty) ← hook ③  returns [(trigger_price, qty, slippage), ...]
      ↓
  place_protection()        places limit-order sells in the returned order
      ↓
  reconcile()               periodic: once any protective order fills, re-place against the
                            actual remaining balance

このような構成にしている理由

パイプラインには、インターフェースの契約に基づく、一見すると分かりにくい選択が3つあります。変更する前に、契約が現在も成り立っていることを確認してください。

選択	前提となる契約
約定数量はウォレット残高のポーリングではなく、market-order list から取得する	market-order swap が返すのは orderId であり、txHash も約定数量も返さない。数量は market-order list の toTokenActualQty にあります
exit_plan で損切りを指定できる	limit-order sell は市場価格を下回る triggerPrice を受け付け、その場合、即時に約定せず status: WORKING のままになります
ws_reader はプロセスレベルでのみ再起動する	接続レベルの処理は tracker ws --duration 0 に組み込まれています（PING によるキープアライブ＋自動再接続＋バックオフ）。必要な CLI バージョンはフロントマターの requiredCliVersion に記載されています。binance-wallet-tracker の Connection lifecycle セクションでは、呼び出し側で二重の処理を追加しないよう明示されています。外側でローテーションすると正常な接続が切断され、外側のウォッチドッグを使うと、CLI がすでにバックオフしている再接続を中断してしまいます

読み取り値の解釈に影響する選択が、ほかに2つあります。ws_reader は conn_uptime_s を記録するため、サーバー側の遅延と再接続後のリプレイを区別できます。また、到着時刻が後続イベントで累積的に膨らむのを防ぐため、リーダースレッドではブロッキング呼び出しを行いません。

戦略フック

3つのフックは戦略を記述する場所です。リポジトリに含まれているのは、パイプラインを動作させるための例にすぎません。そこにある判断やしきい値はすべて、ご自身の分析結果に基づくものに置き換えてください。

3つの関数は scripts/copytrader.py の先頭にあり、メカニズム層がこれらに触れることはありません。シグネチャは次のとおりです。

should_enter(ev, ctx) -> (bool, reason)
size_position(ev, ctx) -> float            # USD; the mechanism layer then clamps to
                                           # min(value, position_usd, remaining budget)
exit_plan(ev, ctx, entry_price, qty) -> [(trigger_price, sell_qty, slippage_pct), ...]

ctx の内容：

キー	意味
audit	監査レスポンス（最初のフック呼び出し時は None）
liquidity	市場データから取得した流動性（最初の呼び出し時は None。シグナルストリームでは extra.liq にフォールバックできます）
price	エントリーの基準価格
positions	現在のポジション辞書
deployed	これまでに投入した USD 額
cfg	設定全体
policy	config.json の policy セクション。そのまま渡され、メカニズム層がキーを解釈することはありません

should_enter は2回呼び出されます。1回目は監査と市場データに何も使う前で（イベント自体のフィールドのみ利用可能）、2回目は両方の準備ができた後です。1回目には低コストな判断を、監査データが必要な判断は2回目に記述してください。

ヘルパー：audit_tax(a) は、監査レスポンスから buyTax + sellTax を取り出します。

メカニズムのガードレール

**2つの異なる事柄です。**ガードレールを実行するのはメカニズム層の役割であり、フックで回避することはできません。一方、値とスイッチを決めるのはユーザーです。

	誰が決めるか	注記
チェックを実行するタイミングと実行者	スキャフォールド	例：「エントリーのたびに予算をチェックする」は無効化できません
チェックで使うしきい値と、有効にするかどうか	ユーザー	budget_usd の値や、block_honeypot を有効のままにするかどうかなど。スキャフォールドは設定の内容に従って実行します
チェックを通過した後に何をいくら買い、どう手仕舞うか	フック	メカニズム層は上限を適用するだけで、銘柄を選びません

したがって、以下は推奨するガードレールであり、安全を保証するものではありません。budget_usd: 1000000 とし、ハニーポットブロックを無効にした設定でも、問題なく実行されます。

ガードレール一覧

項目	動作
予算	累積運用額が budget_usd を超えることはありません。size_position の戻り値は上限値で制限されます
1回の取引	position_usd を超えることはありません
同時実行	max_positions を超えることはありません
ガス	ネイティブ残高が gas_floor_native を下回ると、新規注文を停止します。残高を読み取れない場合も停止します
シリアライズ	tx-lock が LOCKED を報告している間は、注文を出しません
クォータ	left-quota が不足している場合は、注文を出しません
同一トークン	すでに保有しているトークンは、再度購入しません
単一インスタンス	pidfile ロックを使用します。2つ目のプロセスは直ちに終了します
ゲート	STOP は新規エントリーを停止します（既存の保護注文には影響しません）。KILL はプロセスを終了します
モード	mode: dry-run では、注文リクエストを一切発行しません
ライブ実行の確認	mode: live は、$COPYTRADER_HOME/I_UNDERSTAND_THE_RISK に現在の budget_usd が記載されていない場合、起動を拒否します。ランタイムディレクトリをコピーしても引き継がれず、予算を引き上げると無効になります

mode を dry-run から live に切り替えるには、特定の金額についてオペレーターが明示的に決定する必要があります。このスキャフォールドは、設定の編集だけを信用せず、上記の確認ファイルによってそれを徹底します。オペレーターが金額を確認した後、エージェントがファイルを作成できます。

接続監視の分担

接続レベルの管理は CLI、プロセスレベルの管理はこのスキャフォールドが担当します。 両方で管理しないでください。

レイヤー	担当	動作
接続	CLI	tracker ws --duration 0 には、30秒ごとのアプリケーションレベルの PING、onclose 時の自動再接続と再 SUBSCRIBE、指数バックオフ（プッシュを受信するたびにリセット）が組み込まれています
プロセス	このスキャフォールド	子プロセスが実際に終了した場合にのみ再起動します（固定の短い待機時間 proc_restart_sec）。また、state["stream_alarm"] を書き込みます

両方を重ねてはならない理由は、binance-wallet-tracker の 接続ライフサイクル セクションに明記されています。

• 外側の「アクティブローテーション」によって、CLI が正常に維持している接続が定期的に切断されます
• 外側の「無通信ウォッチドッグ」によって、CLI がバックオフ中の子プロセスが強制終了され、保留中の再接続が中断されます
• 2段階のバックオフが重なると、実際の再接続間隔が予測できなくなります

--duration N > 0 は動作が異なります。切断時にエラーとなり、再接続しない単一の接続です。単発のサンプリングに使用し、長時間稼働するプロセスには使用しないでください。

バージョンの下限は厳守してください。 組み込みのキープアライブは、このスキャフォールドの前提条件です。必要な CLI バージョンより古い場合、--duration 0 ではキープアライブも再接続も行われず、このスキャフォールドには接続レベルの再接続機能もありません。そのまま実行すると、最初の切断後に永久に無通信となり、それは市場が静かな状態と区別できません。起動時のチェックでバージョンを検証し、条件を満たさない場合は起動を拒否します。必要なバージョンは frontmatter の requiredCliVersion です。スクリプト内の CLI_MIN もこれに一致します。

適切なフィールドで生存状態を確認する

state["last_push_ms"] が生存状態を示します。再プッシュも含め、プッシュのたびに更新されます。

last_event_ms は使用しないでください。 これは重複排除後に書き込まれるため、新しい signalId が届いたかどうかだけを反映します。シグナルストリームが30分間静かでも、まったく正常です。このフィールドを生存確認に使うと、通常の静かな時間を誤って障害と判定します。

利益確定時のボーナス枠（state.bonus_slots） — 推奨設定。無効化できます

これはポジション管理の考え方の一例であり、推奨ではありません。「利益確定できたなら、現在の相場状況で戦略が機能しているため、エクスポージャーを増やせる」という前提に基づいています。この前提はトレンド相場では機能しますが、レンジ相場ではドローダウンを拡大させます。これを使わない場合は、position_usdがbudget_usdを割り切れる値になるようにし、このフィールドは無視してください。

利益確定で決済した場合、position_usd 1枠分の許容枠を追加します。

position ceiling = max_positions + bonus_slots
capital ceiling  = budget_usd    + bonus_slots × position_usd

損失を出した決済では何も追加されません。受取額を特定できない場合（proceeds is None）も何も追加されません。これはフェイルクローズの設計です。推測に基づいてリスクを拡大するより、許容枠を追加しないほうが安全です。受取額は、約定トランザクションのオンチェーン受取額から読み取ります。

同一トークンのクールダウン（policy.same_token_cooldown_h） — 推奨デフォルトは24時間。変更・無効化できます

クールダウン期間中、同じコントラクトアドレスを買うのは最初のシグナルのみです。「現在保有しているか」だけでは不十分です。ポジションを決済すると、同じトークンに対する後続のシグナルが再び有効になってしまいます（1つのトークンから1日に複数の異なるsignalIdが発生することがあります）。クールダウンの起点はポジション状態とは別に、state.json.ca_last[ca]に記録されます。

設定

$COPYTRADER_HOME/config.json（デフォルトは ~/.local/copytrader）。初回実行時に 完全に空のテンプレートが生成されます。

リソースのガードレールと戦略パラメーターにはデフォルト値がありません。いずれかが欠けていると起動を拒否します。 損切り幅や1取引あたりのサイズなどの値は、自分で判断した結果でなければならず、 そのままコピーするものではありません。考えたこともない損切り幅は、考えたこともない ポジションサイズと同じくらい危険です。そのため、このひな型は起動しない方を選びます。 例外は mode だけです。指定がない場合は dry-run となるため、設定漏れによってライブ取引が始まることはありません。

必須（メカニズム層）

キー	意味	決め方
chain	チェーン ID	現在サポートされている一覧は baw wallet chains --json で確認できます
quote_token	クオートトークンのコントラクトアドレス	そのチェーン上のステーブルコインを指定します。小文字で指定する必要があります
sources	トリガーソース	["address"] / ["signal"] / 両方
budget_usd	累積投資上限	再投資は行われず、単調増加します。全額を失っても問題ないか判断してください
position_usd	1取引あたりのサイズ	損切り幅と合わせて、1取引あたりの最大損失を決定します
max_positions	同時保有ポジションの上限	budget_usd と合わせて総エクスポージャーを制限します
gas_floor_native	ネイティブトークンの下限	これを下回ると新規ポジションの開始を停止します。残高を読み取れない場合も停止します

必須（戦略パラメーター。リファレンスフックが読み取ります）

policy セクションはフックにそのまま渡され、メカニズム層はキーを解釈しません。フックを置き換えると、この表の内容も変わります。リファレンス実装では以下が必要です。

キー	意味
follow_sides	アドレスストリームで追跡する tradeSideCategory の値
max_event_age_sec	配信の鮮度の上限（秒）
sl_mult / tp_mult	損切り／利確のトリガー = エントリー価格 × この値
tp_fraction	利確時に売却するポジションの割合
buy_slippage / sl_slippage / tp_slippage	各段階のスリッページ許容度（%）。損切りのスリッページ許容度は利確より広くする必要があります。暴落時に約定できない損切りは、保護になりません

デフォルト値あり（資金の安全性に影響しない配線設定）

mode（dry-run） · address_list（addrs.txt） · reconcile_sec · proc_restart_sec · workers · outcome_horizons_min（[5, 15, 60]。結果のサンプリングを無効にするには [] を設定します）

任意

policy.block_honeypot（デフォルトは true。無効化は推奨されません） · policy.require_audit · policy.enrich_srcs · policy.same_token_cooldown_h · policy.min_liquidity_usd · policy.block_risk_levels · policy.max_sell_tax_pct · policy.max_commit_ratio

まずしばらく dry-run を実行し、events.jsonl の decision の分布を確認して、 各ゲートが実際に何を拒否しているのかを把握してから、live に移行するか判断してください。

プラットフォームの動作に関する注意事項

cli-check が実際に返すもの

baw cli-check --required-version X --json では、success が示すのはコマンドが実行されたことだけで、常に true です。バージョンが条件を満たしているかどうかは data.needUpdateCli にあります。

{"success": true, "data": {"currentCliVersion": "x.y.z", "needUpdateCli": true}}

success を「バージョンに問題がない」という意味で扱うと、バージョンゲートは役に立ちません。コマンドは常に「成功」するため、ゲートも常に通過してしまいます。正しくは data.needUpdateCli === false を確認してください。

チェーンによってアドレスの大文字・小文字の扱いが異なります

CLI に渡すすべてのコントラクトアドレスを小文字にしてください。 チェーンによってアドレス形式の検証の厳しさが異なります。EIP-55 の大文字・小文字混在を受け付けるチェーンもあれば、明確に拒否するチェーンもあります。

[20003002] Invalid fromToken address

この違いは文書化されておらず、エラーも「形式が違う」ではなく「アドレスが無効」と表示されるため、トークンの設定を間違えたように見えます。

危険なのは、その見え方です。そのレッグのすべての注文が失敗しますが、「何も約定しない」状態は、あらゆる稼働状況メトリクスにおいて「このチェーンにはシグナルがない」状態とまったく同じに見えます。失敗した注文を明示的にカウントしないと、長期間気づかないおそれがあります。そのため、構築するレポートには state["buy_fails"] と最新のエラーを含めてください。

資金を使わずに判断を評価する

events.jsonl だけでは、判断が適切だったかどうかはわかりません。記録されるのは判断であり、その結果ではないためです。そのため、ポジションを開く判断に至ったものはすべて（何も購入しないドライランも含めて）、outcome_horizons_min の時点で価格を再取得するようスケジュールされ、その結果が outcomes.jsonl に追記されます。

{"key":"sig:…","ca":"0x…","token":"…","src":"signal","horizon_min":15,
 "t0_ms":…,"entry":0.0123,"price":0.0141,"ret_pct":14.63,"sampled_ms":…}

key で結合すると、各判断の特徴量と将来リターンを含む 1 行を取得できます。

python3 - <<'EOF'
import json, collections
ev = {}
for l in open("events.jsonl"):
    r = json.loads(l)
    if r.get("decision") in ("DRY_RUN", "OPENED"): ev[r["key"]] = r
by = collections.defaultdict(dict)
for l in open("outcomes.jsonl"):
    o = json.loads(l)
    if o["key"] in ev and o.get("ret_pct") is not None:
        by[o["key"]][o["horizon_min"]] = o["ret_pct"]
print(f"{len(by)} scored decisions")
for h in sorted({h for d in by.values() for h in d}):
    v = sorted(d[h] for d in by.values() if h in d)
    if v:
        n = len(v)
        print(f"  {h:>3}min  n={n:<4} median {v[n//2]:+7.1f}%  "
              f"win rate {sum(1 for x in v if x > 0)/n*100:.0f}%")
EOF

そこから、検証する特徴量（liquidity、top10、tax、smy、audit_risk、launch_ms に基づくトークン年齢など）ごとに分割して、分布を比較してください。

これらの数値は、その性質を踏まえて読み取ってください。

• これは評価価格であり、約定価格ではありません。 スリッページ、手数料、トークン税、ガス代は考慮されず、その価格で実際にポジションを決済できたかどうかも確認されません。戦略で獲得できた可能性のある利益の上限として扱ってください。
• 各時間軸の値はある瞬間の値であり、価格推移ではありません。 60 分後に +40% だったとしても、その間にストップロスに達しなかったとは限りません。複数の時間軸をまとめて確認し、その間にストップロスに達していれば実際の結果はまったく異なることを念頭に置いてください。
• すべては依然としてサンプル数に左右されます。 評価された判断がわずかしかなければ、何もわかりません。また、平均値が 1 つか 2 つの外れ値に左右されている場合も、何もわかりません。平均値ではなく、中央値と分布を確認してください。
• たとえば障害のあとなど、かなり遅れて取得されたサンプルには sampled_late のマークが付き、系列にひそかに含められることはありません。

独自のベースラインを構築し、他者の数値を使わないでください

以下の数値は、プラットフォームの変更、チェーン、トークンの種類、時間帯によって変動するため、ハードコードされた値はすぐに古くなります。スキャフォールドは、独自のベースラインを測定できるよう、これらすべてを正確に events.jsonl / orders.jsonl に記録します。

測定項目	方法	測定時の落とし穴
配信レイテンシ	lag_s = 到着時刻 − イベント時刻	シグナルストリームでは、signalId ごとに最小のラグを取り、実際の初回プッシュだけを数えてください（テスト：lag が秒単位）。再プッシュをすべて独立した観測値として扱うと、「シグナルの現在の経過時間」をレイテンシとして扱うことになり、桁違いの値になる場合があります
レイテンシの原因	conn_uptime_s を使って、「サーバーが遅かった」のか「再接続してリプレイを受信したばかり」なのかを切り分けます	このフィールドがなければ、原因を特定できず、混在した数値しか得られません
実行時間	latency_ms のステップごとの計測値	読み取りスレッドがブロッキング呼び出しを行うと、処理時間が後続イベントの測定レイテンシに累積されます
監査／市場データの網羅率	hasResult と px_src の分布	新規ローンチされたトークンは市場データでインデックス未登録の場合が多く、網羅率はトークンの経過時間と強く相関します。そのため、すべての経過時間のデータを一緒にまとめても意味がありません
取引あたりのガス代	取引前後のネイティブ残高の差 ÷ 取引数	指値注文の発注とキャンセルにもガス代がかかります。スワップだけを数えると、ポジションのライフサイクル全体のコストを過小評価します
トークン品質特徴量の予測力	events.jsonl の top10／tags／liquidity／tax／audit_risk を結果と相関させます	**サンプルサイズ。**約定数が一桁では、期待値について何も分かりません。リターンが1件か2件の取引に集中している場合、平均値は意味を持ちません

直感でトークン品質のしきい値を設定しないでください。 税金タグやトップ10保有者の 集中度などの指標は、新規ローンチされたトークンでは直感に反して異なる分布になることが よくあります。感覚で設定したしきい値は、正当な候補の大半を除外し、その過剰な除外は 「シグナルがない」状態とまったく同じように見えるため、気付きにくくなります。 まず記録し、次にテストし、最後にフィルターを適用してください。

事前チェック

チェーンの対応状況、クオートトークンの許可リスト、注文クォータはプラットフォームの進化に伴って変わるため、ハードコードされた表に頼らないでください。 各起動の前に現在の状態を照会し、その結果から利用可能なものを判断してください。

baw wallet status --json                    # must be CONNECTED
baw wallet chains --json                    # which chains are supported right now
baw wallet settings --json                  # daily limit / tradeAllTokens / abnormalTxnHandling
baw wallet left-quota --json                # remaining quota today
baw wallet balance --binanceChainId <c> --json   # quote-token and native (gas) balances

# Does the target chain support what you need? Probe with a quote — it prices a route without
# placing anything on-chain.
baw market-order quote --fromTokenQty 1 --fromToken <quote> --toToken <any token> --binanceChainId <c> --json
baw limit-order list --binanceChainId <c> --json     # does the chain answer for limit orders at all

limit-order が動作するかどうかで、オンチェーンの保護注文を発注できるかどうかが決まります — 対応していないチェーンでは、プロセスが稼働し続けることだけが保護の頼りになります。上記のどちらのプローブも、発注が成功することを証明するものではありません。証明となるのは最初の実際の保護注文です。WORKING に到達するのを確認するまでは、そのチェーンを未検証として扱い、保護なしでも保有できる最小のポジションサイズで始めてください。

エラーコード：1001001 チェーンまたは操作が未対応 · 1001002 パラメーターが無効 · 100 サーバーエラー（未接続のチェーンでは「流動性なし」として表れる場合もあるため、1001001 と区別してください）。

各依存関係のコマンドとパラメーターについては、そのスキルのドキュメントと --help が正式な情報源です。このドキュメントでは、機能一覧を重複して掲載しません。

実行

cd <skill-dir>/scripts && python3 copytrader.py            # foreground
nohup python3 -u copytrader.py >> runner.log 2>&1 & disown  # long-running

アクション	コマンド
新しいポジションの開始を停止する	touch ~/.local/copytrader/STOP
プロセスを終了する	touch ~/.local/copytrader/KILL
リスク額を確認する（mode: live の実行前に必須）	echo <budget_usd> > ~/.local/copytrader/I_UNDERSTAND_THE_RISK
ライブ実行のゲートを復元する	rm ~/.local/copytrader/I_UNDERSTAND_THE_RISK

プロセスを終了しても、すでにオンチェーンにある保護注文はキャンセルされません。キャンセルするには、明示的に baw limit-order cancel を実行する必要があります。

データファイル（~/.local/copytrader/）：

ファイル	内容
events.jsonl	各イベントにつき1行。判断内容とすべての入力を記録します — 戦略が下した判断
outcomes.jsonl	開始されるはずだった各判断について、各時間軸で価格を再取得した値を記録します — 判断がどれほど適切だったか。key で events.jsonl と結合します
orders.jsonl	注文・指値注文・キャンセルのログ
state.json	ポジション、投入資本、処理済みキー
copytrader.log	時系列ログ

events.jsonl の診断フィールド：lag_s（配信遅延）・conn_uptime_s（イベント到着時点で接続が安定していた時間 — サーバー側の遅延と再接続後の再生を切り分けるために使用します）・conn_seq（接続番号）・replay（イベントがこの接続より前のものかどうか）・latency_ms（ステップごとのタイミング）・decision（通過、または却下理由）・tax audit_risk liquidity top10 px_src。

このデーモンには外部スーパーバイザーがありません。 独自の稼働監視を設定してください。プロセスが稼働しているか、state.json.last_push_ms が進んでいるか（last_event_ms ではありません。これは重複排除の後に書き込まれ、新しい signalId のみを反映するため、シグナルストリームが30分ほど静かな状態は正常です）、conn_seq がどれくらいの速さで増加しているか、baw wallet status が引き続き CONNECTED か、baw limit-order list のアクティブな注文数が state.json のポジション数と一致しているかを確認してください。

既知の制限事項

これらはスキャフォールドに固有の性質であり、今後対応すべき項目の一覧ではありません。本番稼働する前に、これらを受け入れられることを確認してください。

制限事項	詳細
戦略上の優位性はまったくありません	同梱されている3つのフックは、パイプラインが動作することを実証するための最小限のリファレンス実装です。推奨される戦略ではなく、期待値を示す根拠もありません。 戦略を考えるのはあなたです
ガードレールは安全性を保証しません	スキャフォールドは、設定したチェックを実行しますが、それらが十分かどうかは判断しません。しきい値を緩く設定したり、オプションのブロックを無効にしたりしても、その設定どおりに動作します。リスク管理の有効性を決めるのは設定値であり、このスキルではありません
構造上、相手より後手になります	プッシュの遅延、判断、注文にかかる時間の分だけ、あなたの約定は必ずコピー対象より遅くなります。相手が発行者であったり、非公開の執行経路を使っていたりする場合、その利益は再現できず、損失だけがそのままコピーされます
保護されない時間帯があります	買い注文の約定から保護注文の発注までには時間がかかり、決済とAPIの往復通信によって所要時間が決まります。その間、ポジションは下落リスクから保護されません。この時間帯をなくすことはできず、短縮することしかできません
一部約定後は数量がずれていきます	保護注文が一部でも約定すると、残りの注文数量は残りのポジションと一致しなくなります。照合スレッドは実際の残高に基づいて注文を再発注しますが、照合間隔中にプロセスが終了すると、過剰な数量の注文が残ります
ストップロス注文では流動性の低いトークンを救えません	注文を発注できることと、注文が約定することは同じではありません。このような極端なリスクに対応する手段は流動性の下限であり、ストップロス注文ではありません
ドライランは本番稼働と同等ではありません	ドライランではポジションを記録しないため、予算と同時実行数のガードレールは発動せず、通過件数は必然的に本番稼働で建てられる件数より多くなります。ドライランの通過率から本番稼働時の約定頻度を推定しないでください
プロセス終了後に自動復旧することはありません	スキャフォールドは、子プロセスが終了するとそのプロセスを再起動しますが、スキャフォールド自体が終了しても、外部の監視プロセスによる再起動はありません。 プロセスレベルの監視（launchd / systemd / コンテナの再起動ポリシー）は、ご自身で設定してください
レイテンシが測定するのは「プラットフォーム上の記録から配信まで」です	イベントのタイムスタンプとオンチェーンのブロック時刻との関係は定義されていません。イベント時刻がすでにチェーンに遅れている場合、実際のエンドツーエンドのレイテンシは測定値より大きくなります
失敗した注文でも、1日のクォータを消費する場合があります	クォータを消費する場合と、消費しない場合の両方が確認されています。1日の上限に余裕がある間は問題になりませんが、クォータが厳しい場合、失敗した注文は無料だと想定しないでください

免責事項

これは足場となるものであり、取引製品ではありません。また、独自の戦略は備えていません。

• 同梱されているフックは、パイプラインが動作することを示すために提供される、最小限のリファレンス実装です。期待値がプラスであることを示す根拠はなく、推奨するものでもありません。
• このスキルに含まれるリスク管理、ポジション管理の仕組み、およびパラメーター値はすべて、安全策ではなく提案です。この足場は、設定したチェックを実行しますが、それらのチェックが十分かどうかは判断しません。また、恣意的に広いしきい値や、無効にされた任意の保護機能にもそのまま従います。
• **ここに記載されている内容は、投資、金融、または取引に関する助言ではありません。**この足場を使って構築した戦略が利益を上げることや、損失を回避することを保証するものではありません。
• オンチェーントランザクションは取り消せません。自動取引では、予期しなかった市場状況、プラットフォームやプロトコルの動作変更、このソフトウェアの欠陥、または作成した戦略の欠陥により、資金を失う可能性があります。コピー取引には構造上の不利もあります。あなたの約定は常にコピー対象の相手より遅くなり、その相手が発行者である場合や、非公開の執行経路を利用している場合、その利益は再現できない一方で、損失は再現されます。
• このソフトウェアは現状のまま、いかなる種類の保証もなく、明示的にも黙示的にも提供されます。法律で認められる最大限の範囲において、本ソフトウェアの使用から生じるいかなる損失または損害についても、責任を負いません。
• 実行する内容、選択するパラメーター、適用される法律および規制の遵守、ならびに投入する資金については、すべてあなた自身が責任を負います。

budget_usd に設定した金額全額を失う覚悟がない場合は、mode を live に切り替えないでください。