Hyperliquid AI Botを本番へ移す手順｜少額から進める段階と中止の条件

ある取引チームのAI Botが、Hyperliquidのテストネットで予定したテストをすべて通しました。開発者は、そろそろ本番へ移したいと考えています。そこでリスク管理担当者が聞きました。「本番で注文の応答が返ってこなかったら、同じ注文を二度出したりしない？」「おかしいと気づいたとき、どこまで止められる？」

テストネットは、本番の流動性、相手の注文、混雑、約定のばらつき、資金の損失を再現しません。ですから、テストネットの合格だけでは、この問いに答えられません。本番へ移す前には、テストネットでの正常な動作に加えて、次の2つを確かめます。注文・約定・残高が取引所の記録と合っていること。そして、障害が起きたときに止められることです。

そのための手順が、段階投入です。実資金を扱う範囲をはっきりさせ、少額から一段ずつ進めます。段階ごとに「ここで止める」という中止の条件も用意します。

以下では、この取引チームが本番へ移す手順を、段階の順に追います。前提となる構成は次のとおりです。AIが出すのは、決まった形式の注文の案（注文意図）まで。判定ルールで機械的に検査する判定器（Policy/Risk Engine）と、切り離した署名の担当（署名Worker）が、検証と送信を受け持ちます。売買戦略や収益性は扱いません。

この話は、AI取引エージェントを本番で動かすための連載のうち「段階投入と実行・中止の判断」にあたります。全体の構成はHyperliquid AI取引エージェントの本番設計にまとめています。

テストネットで動いた＝本番で使える、ではない

Hyperliquidは、本番（mainnet）とテストネット（testnet）のそれぞれにREST・WebSocketのURLを用意しています。

テストネットで確かめられるのは、次のようなことです。署名、APIの入出力の形式、最小注文、注文と取消、購読と再接続、Bot内部の状態の移り方。損益や、自分の注文が相場に与える影響を、テストネットの結果から推し量ってはいけません。

そこで、テストネットの前後にも段階を設けます。段階ごとに確かめることと、次へ進む条件は次のとおりです。

冪等性とは、同じ要求が何度届いても1回分として扱われることです。各段階の送信先と、使う鍵・権限は次のとおりです。

• 単体・結合テスト：模擬応答・固定データ。鍵なし
• 過去データの再生：保存したイベント。鍵なし
• テストネット：api.hyperliquid-testnet.xyz。テストネット専用のAPI Wallet
• シャドー：本番の読み取り専用。署名Workerは無効
• カナリア：本番。権限を絞ったAPI Wallet
• 本番：api.hyperliquid.xyz。段階ごとの上限

過去データを再生して仮の約定を作るとき、保存した最良の気配値に触れたら約定、とみなすだけでは不十分です。再生では、板の中での順番、自分の注文で板が変わること、一部だけの約定、遅延、取消との競合を再現できないからです。

ですから再生の結果は、実績の見込みではなく、実装の不具合を見つけるために使います。手数料、funding（ポジションを持ち続けると定期的に払う・受け取る料金）、スリッページは多めに差し引き、結果にはsimulatedと明記します。

本番への送信は、7つの条件がそろわないと開かないようにする

AIの出力を、そのままSDKに渡すことはしません。流れは次のとおりです。

1. AIが、有効期限付きの注文意図を出す
2. 判定器が、銘柄、方向、価格、数量、古さ、ポジション、頻度を検査する
3. 承認された注文意図だけを署名Workerに渡す。Workerは安定したcloidを付けて送る

署名Workerは、秘密鍵をLLM、アプリのログ、監視に送るデータへ出しません。判定の順番と停止の設計は判定エンジンと緊急停止の記事で詳しく扱います。

本番への送信は、設定値を1つ書き換えただけでは開かないようにします。次の7つがすべて同時にそろうことを求めます。

1. 送信先のネットワークが本番になっている
2. 本番の有効化の設定がオンになっている
3. 期限内の、人による承認がある
4. 承認された段階が本番になっている
5. 上限の値がゼロより大きい
6. 監視の死活信号（heartbeat）が正常
7. 照合の差異がない

1つでも欠ければ、停止状態に移します。設定での書き方は、後半の「設定と注文意図の形式」に載せました。

金額の上限は、例をそのまま写さないでください。許容できる損失、異常に気づくまでの時間、止めるのにかかる時間から、自分たちで決めます。

応答がないときは、失敗ではなく「結果不明」として扱う

冒頭の「応答が返ってこなかったら？」への答えです。

送信した後にタイムアウトしても、注文は取引所に届いているかもしれません。新しいIDで送り直すと、二重発注になりえます。そこで、その注文は「失敗」ではなく「結果不明」とします。

結果不明の注文は、送り直す前に、同じcloidで注文の状態を照会します。未約定注文と約定も突き合わせ、受け付けられていないと確かめてから次の処理に進みます。

WebSocketにも注意が要ります。購読の直後にスナップショットが送られてくることがあり、同じ情報が重なって届きます。また、60秒間こちらから何も送らない接続は、サーバーに閉じられます。

重複の除き方、再接続、照合までの設計はWebSocket注文同期の記事で、状態遷移表とDBの形まで含めて詳しく書いています。ここでは、各段階でその動きを試し、次へ進む条件に入れることに絞ります。

12のテストで何を確かめるか

テストは、入れる条件と期待する結果を前もって一覧にしておきます。

テストごとの「合格の証跡」は、後半に載せました。

テストネットでも、実際に注文を出すテストは人の承認を得てから行います。承認では、どの口座で・どの銘柄を・いくらまで・いつ・どうなったら取り消すかを決めます。

自動テスト（CI）で毎回走らせるのは、模擬応答・過去データの再生・dry-runまでです。テストネットでの実注文と本番は、人が手で起動するジョブに分けておきます。

監視では、注文の成功率より「記録が合っているか」「止められるか」を見る

見張る信号ごとに、警告の目安と、重大なときに自動で起きることを決めます。

p99は、平時の値の99%が収まる水準です。運用者がそれぞれで確かめることは、後半に載せました。

閾値は、固定の値を写しません。シャドー段階で得た値の分布と、損失が進む速さから決めます。SLOの候補には、たとえば次のようなものがあります。

• 注文意図の99.9%を期限内に判定
• 受け付けられた注文の100%をcloidで追跡
• 重大アラートの100%を当番へ届け、受領を確認
• 照合差異がある間の新規送信0件

取引所の公開上限（レート制限）も、いっぱいまで使う設計にはしません。照会と緊急の取消のための余力を残します。具体的な上限値は後半の表にまとめました。

段階ごと・プロセスごとに別の鍵を使う

API Walletは署名だけに使います。口座情報の照会には、masterまたはサブアカウントの実際のアドレスを渡します。API Walletのアドレスで照会すると、空の結果が返ります。

nonce（署名ごとに付ける、重複させない番号）は、署名者ごとに管理されます。そのため、1つのAPI Walletを複数のプロセスやサブアカウントで共有せず、プロセスごとに別のAPI Walletを割り当てます。失効させたAPI Walletのアドレスは、使い回しません。

段階投入では、「各段階で別のAPI Walletを使い、前の段階の鍵を本番に持ち込まない」ことを確認項目にします。nonceの有効範囲、失効時の注意、鍵の保管と更新の手順はAPI Walletと署名Workerの記事にまとめています。

次に進むか止めるかは、段階ごとに記録を残して承認する

1. 変更を固定する：コミット、依存パッケージの版、設定のハッシュ、モデルの版、判定ルールの版、対象の口座・銘柄を記録する。
2. テスト一覧を通す：正常系とT01〜T12を実行し、未解決の失敗を0件にする。
3. 照合する：注文、約定、ポジション、残高、手数料・funding、監査ログを、同じ基準時刻で一致させる。
4. 運用の演習をする：当番が呼び出しを受け、送信停止、全取消、鍵の失効、スナップショット取得、復旧の判断まで実際に行う。
5. 承認を得る：開発者以外の運用・リスクの責任者が、上限と観測期間を含む段階を、期限付きで承認する。
6. 一度に一つだけ変える：金額、銘柄の追加、頻度、ポジションの上限を、同時に広げない。

次のどれかに当てはまったら、先へ進まず中止します（no-go）。

• 結果不明の注文が残っている、照合の差異がある
• 監査ログが欠けている、巻き戻しを試していない
• 鍵を共有している、本番用の関門を迂回している
• 重大アラートが届いていない、説明のつかない拒否が増えている
• 承認の期限が切れた、承認後にコミットが変わった

止めた後にやること：注文の取消の先にある手順

全注文を取り消しただけでは、復旧は終わりません。次の順で進めます。

1. 宣言する：インシデントIDを発行し、新しい注文意図の作成と、署名待ちの列への取り込みを止める。AIだけを止めるのではなく、実行Worker側で断る。
2. 注文を封じ込める：未約定注文を別の手段で照会し、対象の口座・銘柄を確かめて、全取消か限定取消を行う。タイムアウトは結果不明として照会し直す。
3. 鍵を失効させる：侵害の疑いがあればAPI Walletを解除し、署名サービスのトークン・セッションも失効させる。旧アドレスは使い回さない。
4. 状態を保全する：設定、コミット、注文意図、cloid・oid（取引所が付ける注文ID）、応答、WebSocketのイベント、約定、未約定注文、ポジション、残高、時刻、運用者の操作を、書き換えられない場所へ保存する。
5. データを復旧する：最後に整合していたスナップショットからイベントを再生し、重複を除く。取引所の現在値と三者で照合する。手元のDBだけを正として上書きしない。
6. 原因を取り除く：同じ入力で失敗を再現するテストを足し、dry-run、再生、テストネットの順に通す。
7. 段階的に再開する：読み取り専用、シャドー、カナリアへ戻り、新しい鍵・承認・上限で観測期間をやり直す。
8. 振り返りを残す：気づけた信号、見逃した信号、判断の経緯、利用者・資金への影響、恒久対策の担当者と期限を残す。

24時間運用では、役割を分けます。一次・二次の当番、インシデントの指揮者、鍵の失効担当、対外連絡担当です。

運用者の権限も、読み取り、停止、取消、鍵管理、本番の有効化、ログ管理に分けます。停止は速く、再開と上限の拡大は複数人の承認で行います。監査ログを消す権限は、Botにも日常の運用者にも与えません。

投入前のチェックリスト

• ネットワーク、接続先URL、口座アドレス、API Walletが同じ環境を指し、本番の初期値が無効になっている。
• AI出力の形式、Policy/Risk Engine、署名Worker、監査ログがプロセスと権限の上で分かれている。
• cloidと注文意図IDが安定し、タイムアウト・重複・再起動でも二重発注しない。
• 未約定注文、約定、ポジション、残高を独立に照会し、差異があれば止まる。
• レート制限、再接続、死活信号、スナップショット、欠落分の補完を試験した。
• 金額、銘柄、頻度、ポジション、累計損失の上限と、承認の期限が設定されている。
• 全取消、限定取消、鍵の失効、運用者の手動介入を、別の担当者が演習した。
• 重大アラートの配送・受領・代わりの連絡手段と、監査ログの保全を確認した。
• 実行・中止の証跡に、コミット、設定のハッシュ、テスト結果、承認者、観測期間がある。
• 巻き戻し後はシャドーから再開する手順があり、本番を直接再開しない。

開発チームが実装する詳細

ここからは、さきほどの取引チームで仕組みを実装する開発者・SRE向けに、設定の形式、状態、テストの証跡、上限値、参照実装を示します。

設定と注文意図の形式

network: testnet
mode: dry_run
mainnet_enabled: false
symbols: [BTC]
limits:
  max_order_notional_usd: 25       # 例。自社のリスク許容度で決める
  max_position_notional_usd: 50
  max_orders_per_minute: 6
  max_intent_age_ms: 1500
guards:
  require_human_approval: true
  halt_on_reconciliation_break: true
  halt_on_market_data_stale_ms: 3000
release:
  approved_stage: testnet
  approval_id: CHANGE-REQUIRED
  expires_at: 2099-01-01T00:00:00Z

前半の7つの条件は、設定では次のように表します。①network=mainnet、②mainnet_enabled=true、③期限内の人間の承認、④approved_stage=mainnet、⑤ゼロより大きい上限、⑥監視の死活信号（heartbeat）が正常、⑦照合差異なし。1つでも欠ければHALTEDへ移します。

{
  "intent_id": "01J...",
  "created_at_ms": 1786615000000,
  "expires_at_ms": 1786615001500,
  "symbol": "BTC",
  "side": "buy",
  "order_type": "limit",
  "time_in_force": "Gtc",
  "size": "0.001",
  "limit_price": "10000.0",
  "reduce_only": false,
  "reason_code": "MODEL_SIGNAL_V3",
  "model_version": "sha256:..."
}

Hyperliquidの指値注文は、有効期間の種類としてGTC、IOC、ALOを区別します。cloidは任意の128ビットの16進文字列です。タイムアウトしたら、同じcloidをorderStatusで照会します。

API応答、orderUpdates、userFills、未約定注文、ポジション・残高は、別々の観測として保存します。

注文の状態と規則

states:
  - PROPOSED
  - POLICY_ACCEPTED
  - SUBMITTING
  - ACKNOWLEDGED
  - OPEN
  - PARTIALLY_FILLED
  - FILLED
  - CANCEL_PENDING
  - CANCELED
  - REJECTED
  - UNKNOWN
  - HALTED
rules:
  timeout_after_submit: UNKNOWN
  unknown_action: query_by_cloid_then_reconcile
  duplicate_event: ignore_if_event_key_seen
  websocket_gap: pause_submit_then_snapshot_and_backfill
  reconciliation_break: HALTED
terminal: [FILLED, CANCELED, REJECTED]

SUBMITTINGの後のタイムアウトはUNKNOWNとし、再送の前に注文状態・未約定注文・約定を照合します。

テストごとの合格の証跡

• T01：監査ログ、秘密情報の検査結果
• T02：重複排除の件数、送信ログ
• T03：状態履歴、orderStatusの結果
• T04：欠落区間、再購読の応答、差異0
• T05：イベントキー、無視した件数
• T06：再試行回数、待ち行列の滞留時間
• T07：HALTED、秘密情報へのアクセスログ
• T08：取引所の呼び出し0件
• T09：作成時刻、判定時刻
• T10：復旧レポート
• T11：スナップショットの差分、インシデントID
• T12：設定検証の結果

監視の信号ごとに運用者が確かめること

• 注文・約定・ポジションの照合差異：cloid、oid、約定、ポジションのスナップショット
• UNKNOWNの注文：orderStatusと未約定注文
• 市場データの経過時間：最後のイベント、時計のずれ
• 拒否率：取引所側・判定側の理由別の内訳
• WebSocket再接続：接続、購読、スナップショット
• 監査ログの欠損：待ち行列、保存先、ハッシュ連鎖（記録を前の記録のハッシュでつなぎ、改ざんに気づけるようにしたもの）

Hyperliquidの公開上限

2026年9月24日時点の公開上限は次のとおりです。

そのまま検証できる最小の参照実装

以下の参照実装は、秘密鍵を読み込まず、注文も送りません。pytestで次のことを確認できます。

• 安定したcloidの生成
• 注文意図の古さ・銘柄・注文額・ポジションの上限
• 本番用の多段の関門

署名とSDKの実行は、別のサービスとして実装してください。

段階投入の関門の参照実装（ZIP）をダウンロード

unzip hyperliquid-ai-bot-release-guard-reference.zip
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pytest -q
# expected: 4 passed

実運用では、SDKのInfo(constants.TESTNET_API_URL, skip_ws=True)などをテストネット専用のプロセスに組み込みます。秘密鍵は、設定ファイル、LLMへの指示文、CIのログに置きません。秘密情報の管理サービスから、署名Workerだけへ短時間だけ渡します。テストネットの実注文も、人の明示的な承認なしには実行しません。

関連する記事

AIの提案から署名・送信までの全体像はHyperliquid AI取引エージェントの本番設計が起点です。個別の設計は、判定の順番と緊急停止を判定エンジンと緊急停止、鍵とnonceをAPI Walletの安全な署名設計、注文状態の同期をWebSocket注文同期で扱います。Hyperliquidそのものの仕組みはHyperliquidの仕組み、データの取り方はHyperliquid API・RPC・データ基盤が基礎になります。

XTELAができること

私たちは、AI出力の形式、判定ルール、署名の分離、監視、検証環境をつなぎ、テストネットからシャドー・カナリアを経て本番へ進める段階投入の仕組みを設計・実装します。貴社のBotに合わせた中止条件とテスト一覧を作り、PoCから運用開始後の見直しまで一緒に進めます。売買戦略や投資判断は私たちの仕事の範囲に含みません。段階投入の設計を相談したい場合はお問い合わせからご連絡ください。

主要参考資料

• Hyperliquid Docs: API（本番・テストネットのURL、2026年9月24日確認）
• Nonces and API wallets（API Wallet、nonce、失効時の扱い）
• Exchange endpoint（注文、TIF、cloid）
• Info endpoint（orderStatus、口座状態）
• WebSocket（接続URL、再接続）
• WebSocket subscriptions（orderUpdates、userFills、スナップショット）
• Timeouts and heartbeats（60秒、ping/pong）
• Rate limits and user limits（IP・アドレス・WebSocketの上限、2026年9月24日確認）
• Hyperliquid公式Python SDK v0.24.0（2026年9月24日時点の最新リリース）

資料の確認日と注意

公式ドキュメントの仕様（URL、上限値、nonce、WebSocket）は2026年9月24日に確認し直しました。SDK例は、2026年9月24日時点の最新リリースhyperliquid-python-sdk==0.24.0を基準にしています。ここで示したのは技術・運用設計の一般情報で、投資助言ではありません。API仕様や上限は変わるため、投入時点の公式資料で確かめてください。