Hyperliquid API Walletの鍵が漏れたら｜署名の分け方とnonce管理

HyperliquidでAI取引エージェントを本番に出す前に、答えておきたい問いがあります。「API Walletの鍵が漏れたら、何ができてしまうか」です。

API Walletは、口座の代わりに注文へ署名するための鍵です。代わりに署名する仕組みであって、細かな権限を管理する仕組みではありません。そのため、この鍵が実行できる操作は、アプリ固有の「BTCだけ」「1回100 USDCまで」「reduce-onlyだけ」といった権限表にはなっていません。

API Walletを口座ごとに作る運用もあります。ただ、これはnonceがぶつからないようにするための工夫です。鍵の権限が一つのサブアカウントに自動で絞られるとは限りません。だから、漏れた鍵で何ができるかは、登録条件を確かめて見積もる必要があります。

もう一つ、避けたい失敗があります。注文を送ったのに、応答が返ってこない。そこで、新しいnonceで同じ注文を作り直して送ってしまうのです。タイムアウトしていても、取引所の側では注文が受け付けられていることがあります。その場合、作り直した注文で二重発注になります。

鍵そのものがアプリの権限表になっていない以上、制限は鍵を使う側で守らせます。そこで、署名処理（署名Worker）をAIや他の処理から切り離し、その中で口座・操作・金額・期限を確かめてから署名します。二重発注のほうは、nonceを署名者ごとに1か所で採番して保存し、結果が分からない要求は自動では送り直さずに止めることで防ぎます。

扱うのは儲け方ではなく、鍵・nonce・署名要求の守り方です。参照実装は公式ドキュメントと公式Python SDK 0.24.0をもとにし、初期値をテストネットとdry-runにしています。AI取引エージェントを本番で動かす連載のうち「鍵とnonce」の回で、API Walletとnonceの詳しい説明はここに集めています。全体の構成はHyperliquid AI取引エージェントの本番設計にまとめています。

鍵が漏れたら、何ができてしまうか

アプリ側で「この銘柄だけ」と権限表を決めていても、その内容は鍵そのものには伝わりません。API Walletが実行できる操作は、アプリの権限表とは別に決まっています。だから制限は、鍵を使う署名Workerの中で守らせます。

全体の流れは次のとおりです。AIは注文の意図を作るだけで、鍵には触れません。

AIが想定外の操作を作っても、署名Workerに届かなければ署名はされません。そこでWorkerが受け付けるのは、許可した形の注文意図だけにします。任意のactionや、署名対象のバイト列そのものは受け取りません。知らない項目が付いていれば拒否します。

そのうえで、次の項目を毎回同じ規則で確かめます。

• 銘柄、売買方向、注文額
• ポジション、日次損失、reduce_only
• client order ID、期限

AI・判定エンジン（Policy Engine）・署名Worker・運用者のそれぞれに何を許し、何を拒むかは、後半の「各担当の権限と資格情報」にまとめています。判定の順番や緊急停止の作り方は判定エンジンと緊急停止の記事で扱います。ここでは、判定を通った要求を署名Workerがどう受け、どう署名するかを見ていきます。

口座・API Wallet・サブアカウントは、どう違うか

3つを同じ「ウォレット」として扱わないことが出発点です。鍵を持つのはmaster accountとAPI Walletだけです。

サブアカウントで注文するときは、master側の署名者で署名します。そしてvaultAddressにサブアカウントのアドレスを指定します。この役割分担は公式のExchange endpointに明記されています。

それぞれを何ごとに作るかの目安は次のとおりです。

• master account：事業・所有者ごと
• API Wallet：戦略・環境・プロセスごと
• サブアカウント：戦略・顧客・リスクの区分ごと

取り違えやすいのが、口座の状態を読むときです。Nonces and API walletsとInfo endpointによると、Info APIにAPI Walletのアドレスを渡すと、口座の状態ではなく空の結果が返ります。これは典型的な誤りです。Info APIには、masterかサブアカウントの実アドレスを渡します。

コードの上でも、読み取りに使うaccount_addressと、書き込みに使うsigner_address・vault_addressは別の項目にします。同じ変数に詰め込むと、この取り違えが起きます。

nonceは、どう採番すれば重複しないか

Hyperliquidは署名者ごとに、値の大きい方から100個のnonceを覚えています。新しいnonceは、次の条件をすべて満たす必要があります。

• 覚えている100個の最小値より大きい
• 過去に使っていない値である
• ブロック時刻Tに対して(T - 2日, T + 1日)の範囲に入る

公式ドキュメントが勧めるのは、原子的なカウンタを現在のUnixミリ秒まで早送りできる作りです。

この条件は署名者ごとにかかります。複数のプロセスが同じ署名者で別々に採番すると、番号がぶつかります。まず考えるのは、署名者を共有しないことです。複数のエージェントのプロセスから、同じAPI Walletを直接使ってはいけません。公式が勧めるのは、取引プロセスごとにAPI Walletを作ることです。サブアカウントを並行して動かす場合も、master accountの下にサブアカウントごとのAPI Walletを作ります。

どうしても共有するなら、1つの署名者のnonceは1つのWorkerだけが採番します。手順は次のとおりです。

1. 全要求を、同じ永続化した待ち行列へ入れる。
2. 署名者ごとの担当権（リース）を、1つのWorkerだけが取る。
3. DBのトランザクションでmax(now_ms, last_nonce + 1)を保存し、コミットする。
4. コミットの後で署名する。
5. 再起動したときは、未完了の要求、監査ログ、Hyperliquidの注文状態を突き合わせてから再開する。

応答が失われても、注文は取引所に届いていることがあります。だから、新しいnonceで同じ注文を作り直してはいけません。

API Walletを入れ替えるときにも、nonceの落とし穴があります。次のどれかが起きると、そのAPI Walletとnonceの状態は消去（prune）されることがあります。

• API Walletの登録を解除した
• 期限が切れた
• 登録した口座の資金がなくなった

消去の後は、過去の署名済み操作が再利用（replay）され得ます。そのため公式ドキュメントは、失効したAPI Walletのアドレスを再利用しないよう強く勧めています。鍵を更新するときは新しい鍵ペアを作り、旧アドレスを二度と登録しないための台帳を残します。

応答が返ってこない注文は、どう扱うか

注文を送った後にAPIがタイムアウトしても、取引所の側では注文が受け付けられていることがあります。ここで送り直すと、二重発注になるおそれがあります。

参照実装では、タイムアウトやHTTPエラーの要求を「結果不明（UNKNOWN）」として保存します。再起動後に同じ要求が来ても、保存済みの結果不明を返すだけで、自動では送り直しません。

結果不明の要求は、client order ID、注文状態、WebSocketのユーザーイベントを見て確かめます。確かめるのは、読み取り専用の確認処理か運用者です。送っていないと確かめられない限り、同じ意図の注文を新しい要求として送りません。

WebSocketの切断、部分約定、注文状態の同期はWebSocket注文同期の記事で扱います。署名Workerの役目は、最終状態を推測せずに止まることです。

鍵はどこに保管し、どこに出してはいけないか

鍵の管理では、保管場所だけでなく「鍵がどこに出ていないか」まで確かめます。秘密情報ごとに見ていきます。

API Walletの秘密鍵

• 保管する場所：専用の秘密情報管理サービス・KMS、隔離したWorkerの実行環境だけ
• 出してはいけない場所：LLMへの指示文、リポジトリ、CIの出力、通常のアプリ、APM
• 更新のきっかけ：定期、担当者の交代、侵害の疑い、環境の廃止
• 失効の確かめ方：旧agentを登録解除し、アドレスの再利用を禁止する

Workerのサービス資格情報

• 保管する場所：呼び出し元のワークロード識別情報・mTLS
• 出してはいけない場所：ブラウザ、共有チャット、URLのクエリ文字列
• 更新のきっかけ：短命で自動更新、呼び出し元の侵害
• 失効の確かめ方：旧識別情報で401になることと、監査ログを確かめる

master walletの鍵

• 保管する場所：通常のWorkerの外。API Walletの承認・失効専用の別の手段
• 出してはいけない場所：Botのホスト、LLM、テスト用の固定データ
• 更新のきっかけ：危殆化時は専用の手順書で対応する
• 失効の確かめ方：権限の移行と資金の保護を個別に確かめる

テストネット用のローカル鍵

• 保管する場所：隔離した開発端末、価値のない専用口座
• 出してはいけない場所：本番と同じ保管庫、公開リポジトリ
• 更新のきっかけ：演習の終了、漏えい、共有者の交代
• 失効の確かめ方：残高を不要にし、鍵を破棄し、テスト用の固定データから除く

テストネット用の鍵は、本番鍵と同じ保管庫・IAM（IDとアクセス権限の管理）・バックアップに混ぜません。本番の口座へも一度も承認しません。APM（アプリケーション性能監視）や例外通知にも、鍵・署名・認証ヘッダーを送らない設定になっているかを確かめます。

KMSやHSMを使えば、鍵は取り出せなくなります。それでも、Workerが任意のデータに署名できてしまう問題は残ります。また、KMS・HSMでは、Hyperliquidの署名方式に合っているかを確かめます。secp256k1（Hyperliquidが使う楕円曲線）への対応、ダイジェスト（署名する前のハッシュ値）の作り方、recovery値をSDKのテストベクタ（正解の入出力例）と突き合わせます。本番の署名鍵をHSMやMPCで守る全体の設計は本番署名鍵のHSM・MPC設計も参考になります。

鍵を入れ替えるときは、何をどの順でするか

新しい鍵を登録した時点では、旧鍵はまだ使える状態です。旧鍵で出した要求が残っていることもあります。旧鍵を止め、その要求の結果まで確かめて、はじめて入れ替えが終わります。

1. 新しいAPI Walletを新しいアドレスで作り、秘密鍵を秘密情報管理サービスへ登録する。
2. 新しいWorkerをテストネット・dry-runで起動し、署名者、口座、サブアカウント、判定ルールの版を突き合わせる。
3. 旧Workerへの投入を止める。担当権を持っている要求と、nonce確保済み（NONCE_RESERVED）・送信済み（SUBMITTED）の要求を洗い出す。
4. Hyperliquidの注文・約定・取消の状態と監査ログを突き合わせる。結果が確定しない要求は、運用者の保留にする。
5. master accountの別の管理手段から、旧API Walletを失効させる。旧アドレスは再利用禁止の台帳へ入れる。
6. 旧資格情報、実行環境、キャッシュ、クラッシュダンプ、バックアップへのアクセスを失効させる。旧鍵での要求が拒否されることを確かめる。
7. 新しいWorkerを小さい上限で有効にし、監視しながら通常の上限へ段階的に戻す。

鍵が漏れた・口座を取り違えたとき、まず何を止めるか

最初にするのは、送信を止めることです。そのうえで、署名者（鍵）の側と口座の側を別々に封じ込めます。

たとえばAPI Walletの鍵が漏れたら、待ち行列を止め、agentを失効させます。対象サブアカウントの未約定注文を取り消すかは、別の手段で判断します。nonceの競合や応答の欠落なら、新しいnonceで送り直さず、その署名者の待ち行列を保留にします。

事象ごとの「すぐ止めること・確かめること・再開の条件」は、後半の「事象ごとの封じ込め手順」の表にまとめています。

本番へ移してよいのは、どんな状態になったときか

ここまで見てきた事故は、鍵の漏えいだけではありません。二重発注や口座の取り違えも含めて防げることを、次の6つで確かめてから本番へ移します。

• 戦略・環境・サブアカウントごとに署名者と資金の上限が別になっていて、事故の影響範囲を説明できる。
• AIの出力は型付きの注文意図だけ。判定エンジンと署名Workerの二段階で、同じ重要な条件を確かめる。
• nonceの採番、要求の台帳、待ち行列、監査ログが永続化され、再起動の試験を通る。
• タイムアウト、レート制限、部分約定、WebSocket切断で二重発注しない。結果不明（UNKNOWN）になったら運用者へ止められる。
• 明示的な設定、独立した承認、低い初期上限、緊急停止、鍵更新の演習がそろうまで、本番は閉じたままになっている。
• 秘密鍵、署名、認証ヘッダーが、LLM、CI、ログ、APM、例外通知、問い合わせチケットに出ていないことを検査済み。

段階的に本番へ移す手順と、実行・中止の条件はテストネット検証と段階投入の手順で扱います。

実装する人向けの詳細

ここからは、署名Workerを実際に組むときの材料です。権限表、JSONの形、状態遷移、コード、テストの順に見ていきます。実装全体とpytestは署名Workerの参照実装（ZIP）から取得できます。参照実装はPython 3.11、FastAPI、公式SDK 0.24.0を固定し、初期値をテストネット・dry-runにしています。

各担当の権限と資格情報

鍵を使えるのは署名Workerだけです。AIと判定エンジンは、秘密鍵を一度も参照しません。

署名Workerが受け取るJSONの形を決め、それ以外は受け付けない

AIが生成した未知の操作をWorkerへ届けないために、入力の形式をadditionalProperties: falseにします。client_order_idとrequest_idは、再試行を追うための別々の識別子です。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "HyperliquidSigningRequestV1",
  "type": "object",
  "additionalProperties": false,
  "required": ["request_id","network","account_address","expires_at_ms","dry_run","order"],
  "properties": {
    "request_id": {"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},
    "network": {"enum":["testnet","mainnet"]},
    "account_address": {"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},
    "vault_address": {"type":["string","null"],"pattern":"^0x[0-9a-fA-F]{40}$"},
    "expires_at_ms": {"type":"integer"},
    "dry_run": {"type":"boolean","default":true},
    "order": {
      "type":"object","additionalProperties":false,
      "required":["asset","coin","is_buy","size","limit_price","reduce_only","tif","client_order_id"],
      "properties": {
        "asset":{"type":"integer","minimum":0}, "coin":{"type":"string","pattern":"^[A-Z0-9]{1,12}$"},
        "is_buy":{"type":"boolean"}, "size":{"type":"number","exclusiveMinimum":0},
        "limit_price":{"type":"number","exclusiveMinimum":0}, "reduce_only":{"type":"boolean"},
        "tif":{"enum":["Alo","Ioc","Gtc"]},
        "client_order_id":{"type":"string","pattern":"^0x[0-9a-f]{32}$"}
      }
    }
  }
}

応答は次の形です。

{
  "request_id": "req_01J...",
  "state": "DRY_RUN | SUBMITTED | REJECTED | UNKNOWN",
  "nonce": 1786616000000,
  "action_hash": "sha256:...",
  "exchange_response": null,
  "error": {"code":"EXCHANGE_RESULT_UNKNOWN","next_action":"RECONCILE_CLIENT_ORDER_ID_THEN_OPERATOR_HOLD"}
}

アドレスは、0xに続く40桁の16進数だけを受け付けます。Worker内では小文字にそろえます。3つのアドレスの意味は次のとおりです。

• account_address：資金・状態の持ち主
• vault_address：該当する場合のvault
• 秘密鍵から導く署名者：署名の主体

Workerは、署名者と口座の対応が事前に登録されているかも確かめます。見た目のアドレスだけで、責任の主体を取り違えないためです。

呼び出し元の確認には、mTLS（相互TLS認証）か署名付きのサービス識別情報を使います。参照実装は簡潔なHMAC（共有鍵によるメッセージ認証コード）の例です。タイムスタンプを30秒で失効させ、正規化した本文のハッシュを認証の対象にしています。ネットワークのアクセス制御や送信元IPだけでは足りません。共有された長寿命のBearerトークンだけでも足りません。

要求の状態遷移と、守るべき4つの約束

要求は次の状態をたどります。

states:
  RECEIVED:  {on_valid: POLICY_APPROVED, on_invalid: REJECTED}
  POLICY_APPROVED: {on_lease: NONCE_RESERVED, on_expiry: EXPIRED}
  NONCE_RESERVED: {on_sign: SIGNED, on_worker_crash: RECONCILE}
  SIGNED: {on_post: SUBMITTED, on_timeout: RECONCILE}
  SUBMITTED: {on_exchange_accept: ACCEPTED, on_unknown: RECONCILE}
  RECONCILE: {on_found: ACCEPTED, on_absent_and_safe: RETRY_SAME_REQUEST, on_ambiguous: OPERATOR_HOLD}
terminal: [ACCEPTED, REJECTED, EXPIRED]
invariants:
  - one signer has exactly one nonce allocator
  - request_id and body_hash are immutable
  - timeout never means not submitted
  - retry never allocates a new nonce before reconciliation

末尾のinvariantsは、どの状態でも破ってはいけない約束です。日本語にすると次の4つです。

1. 1つの署名者のnonceを採番するのは、1か所だけ。
2. request_idと本文のハッシュ（body_hash）は後から変えない。
3. タイムアウトは「送っていない」という意味ではない。
4. 突き合わせが終わるまで、再試行で新しいnonceを取らない。

最小実装：注文意図から署名までのコード

coinは表示用の名前なので、許可リストとしては信用しません。Workerが対象ネットワークの公式metaを取得し、無期限先物の銘柄の並び順からassetを割り出します。キャッシュは60秒以内のものだけを使います。

ネットワークをまたいだ古い対応表や、AIが示した番号をそのまま信用しないため、次のどれかに当たれば署名前に拒否します。

• metaが取れない
• 未知の銘柄である
• 入力のassetと一致しない

def allocate(signer: str, now_ms: int) -> int:
    db.execute("BEGIN IMMEDIATE")
    row = db.execute("SELECT value FROM nonce_state WHERE signer=?", (signer,)).fetchone()
    nonce = max(now_ms, row[0] + 1 if row else now_ms)
    db.execute("INSERT ... ON CONFLICT ...", (signer, nonce))
    db.execute("COMMIT")
    return nonce

wire = order_request_to_order_wire(validated_order, asset)
action = order_wires_to_order_action([wire])
signature = sign_l1_action(
    api_wallet, action, vault_address, nonce, expires_at_ms, network == "mainnet"
)
payload = {
    "action": action, "nonce": nonce, "signature": signature,
    "vaultAddress": vault_address, "expiresAfter": expires_at_ms,
}

expiresAfterは、公式SDKで一部のL1操作に対応しています。期限を過ぎた操作を取引所に拒否させる項目です。ただし期限は、nonceの永続化や重複防止の代わりにはなりません。

期限の短すぎにも注意が要ります。expiresAfterの期限切れで取り消された操作は、アドレスごとのレート制限を通常の5倍消費します（公式のExchange endpoint）。期限切れが続かないよう、公式のレート制限を監視します。レート制限にかかったときも、同じ要求を無制限に即時再送しません。

結果不明の保存のしかた

参照実装は送信前に、署名済み（SIGNED）の状態、nonce、操作のハッシュをSQLiteへ保存します。タイムアウトやHTTPエラーになったら、UNKNOWNとRECONCILE_CLIENT_ORDER_ID_THEN_OPERATOR_HOLDを確定として保存します。プロセスを作り直しても、この状態から復元されます。

事象ごとの封じ込め手順

どの事象でも、まず送信を止め、突き合わせが済むまで再開しません。

pytestとテストネットで、危ないときに止まるかを先に確かめる

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
export WORKER_AUTH_SECRET='test-only-value'
export ALLOWED_ACCOUNTS='0x1111111111111111111111111111111111111111'
export NONCE_DB='./nonce.sqlite3'
pytest -q
uvicorn app:app --host 127.0.0.1 --port 8081

添付のテストが確かめるのは、次の項目です。

• dry-runでは鍵を読まず、送信しない
• 期限切れ・注文額の上限超過・未知の項目・16進でないアドレス・coinとassetの不一致を拒否する
• 並列でnonceを割り当てても重複しない
• 同じ要求IDで本文を差し替えられない
• HTTPタイムアウト後にUNKNOWNを保存し、プロセスを作り直しても復元される

API Walletの失効、WebSocket切断、レート制限、部分約定は、取引所とストリームを含む結合テストで確かめます。この最小Workerは、UNKNOWNから自動で再送しません。

test_cases:
  - {id: dry_run_no_key, expect: "200 DRY_RUN; no signature; no network post"}
  - {id: expired_request, expect: "422; no nonce allocation"}
  - {id: unknown_field, expect: "422; additional property rejected"}
  - {id: policy_limit, expect: "403; no signature"}
  - {id: concurrent_nonce, expect: "all unique and monotonically allocated per signer"}
  - {id: post_timeout, expect: "RECONCILE; no automatic new-nonce resend"}
  - {id: worker_restart, expect: "unfinished requests restored from durable store"}
  - {id: mainnet_default, expect: "403 unless explicit enablement and dry_run=false"}

テストネットで実注文を出す場合も、人が口座、銘柄、数量、価格、取消の手順を確かめてから一度だけ実行します。テスト一式が自動で取引を起こすことはありません。

Workerを止めるときは、新規の受け付けを閉じます。待ち行列は処理し切るか保留にし、未完了の要求とnonceの状態をバックアップしてから終了します。

関連する記事

AIの提案から署名・送信までの全体像はHyperliquid AI取引エージェントの本番設計が起点です。同じ連載では、判定と停止を判定エンジンと緊急停止、注文状態の同期をWebSocket注文同期、本番への段階投入を本番移行の手順書で扱います。Hyperliquidそのものの仕組みはHyperliquidの仕組み、データの取り方はHyperliquid API・RPC・データ基盤を参照してください。

XTELAができること

私たちは、AIが出す注文意図の形式、Policy/Risk Engine、署名Workerの分離、nonceの台帳、鍵の更新と失効の手順を、テストネットで検証できる形で設計・実装します。貴社の口座とサブアカウントの構成から署名者の分け方を決め、監視と復旧の手順書まで一緒に作ります。取引や投資の判断は私たちの仕事の範囲に含みません。実装の相談はお問い合わせください。

参考資料

• Hyperliquid Docs: Nonces and API wallets（2026年9月24日確認）
• Hyperliquid Docs: Exchange endpoint（vaultAddress、expiresAfter。2026年9月24日確認）
• Hyperliquid Docs: Info endpoint（orderStatus、口座状態の照会）
• Hyperliquid Docs: Rate limits and user limits
• Hyperliquid Docs: WebSocket
• Hyperliquid Docs: WebSocket subscriptions
• Hyperliquid公式Python SDK 0.24.0

資料の確認日と注意

Hyperliquid公式ドキュメントは2026年9月24日に確認し直しました（nonceの条件、expiresAfterのレート制限の扱いを含む）。公式Python SDK 0.24.0は、commit 2fdb18f9517675ea03695a0962bd19eece9c83f0を2026年8月13日に確認し、0.24.0が最新であることを2026年9月24日に再確認しています。

鍵・nonce・署名要求の技術設計の解説で、取引・投資・法的な判断を代わりに行うものではありません。仕様は変わり得るため、実装時に公式ドキュメントで確かめてください。