OMX for Hyperliquid

OMX：AI エージェント向け Hyperliquid 執行（MCP）

OMX は、Hyperliquid の無期限先物向けのノンカストディアルな執行エンジンです。ご自身のマシン上で動作し、注文意図（成行、指値、TWAP、POV、チェイス、または有効にした場合は Hyperliquid 独自の TWAP）を子注文に変換して、各子注文を設定した事前取引ポリシーに照らして確認し、すべての判断をハッシュチェーン形式の監査ログに記録します。コマンドラインと MCP サーバーを使って、人間または AI エージェントが設定された制限内で操作できます。

OMX は、取引実績や利益について何ら保証しません。安全策を備えた執行基盤です。

懸念事項	OMX の対応
キー	ご自身のアカウントで作成した Hyperliquid API（エージェント）ウォレットを使って署名します。メインキーやシードを求めることはありません。設定にはキーそのものではなく、キーファイルのパスを保存します。出金や送金のコードはありません。
制限	すべての子注文をローカルで確認します。対象コインの許可リスト、流動性と板の厚さ、価格帯とスリッページ、コインごとおよび口座全体の想定元本（未約定注文を含む）、レバレッジ、日次損失、データの経過時間を確認します。エンジンはポリシーで拒否された子注文をすべて拒否します。制限を変更できる MCP ツールはありません。制限はデーモンが読み込んだ設定から適用されます。OS ユーザーとしてシェルやファイルにもアクセスできるエージェントは、そのファイルを編集できるため、そのようなエージェントは別の OS ユーザーで実行してください（信頼境界）。
人間による承認	エージェントの意図が approval_above_usd を超える場合、またはエージェントの日次予算を超える場合は、ユーザーの承認を待ちます。omx approvals approve <id> を実行し、デーモンのターミナルに確認コードを入力してください。保留中の承認は期限切れになります。
停止	エージェントも人間もキルスイッチを作動させられます。作動すると、未約定の OMX 注文が取り消されます。解除できるのは人間だけです（omx unkill）。
監査	すべての判断をハッシュチェーン形式のログに記録します。omx audit verify を実行すると改ざんを検出できます。
手数料	オプションの 1 bp のビルダー手数料です。ご自身のウォレットで承認した後にのみ課金されます。手数料が不要な場合は --no-builder を指定してください。docs/FEES.md を参照してください。

手順：キー不要のデモから始め、キー不要のまま Hyperliquid のライブ板でペーパートレードを行い、次にテストネット、最後に少額でメインネットを利用します。

今すぐ試す：キーもアカウントも不要です

ワンクリックで、デモモードの MCP サーバーをインストールします（独立したプロセスで動作するシミュレーション上の取引所です。実際の取引は行われません）。

または、次の 1 行でインストールできます。

claude mcp add omx -- uvx omx-hyperliquid          # Claude Code
codex mcp add omx -- uvx omx-hyperliquid           # OpenAI Codex CLI
gemini mcp add omx uvx omx-hyperliquid             # Gemini CLI

• Claude Code プラグイン：/plugin marketplace add Lumen-Founder/omx-hyperliquid-mcp を実行し、続けて /plugin install omx@omx を実行します。
• Gemini CLI 拡張機能：gemini extensions install https://github.com/Lumen-Founder/omx-hyperliquid-mcp。
• その他の MCP クライアント（Claude Desktop、Cline、Windsurf、Zed、JetBrains など）： {"mcpServers": {"omx": {"command": "uvx", "args": ["omx-hyperliquid"]}}}。 Claude Desktop では claude_desktop_config.json に設定します（Settings > Developer > Edit Config；Windows %APPDATA%\Claude\、macOS ~/Library/Application Support/Claude/）。 Cursor では ~/.cursor/mcp.json に設定します。"[email protected]" を指定すると、バージョンを固定できます。
• uv がインストールされていない場合：Windows：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"； macOS / Linux：curl -LsSf https://astral.sh/uv/install.sh | sh を実行し、新しいターミナルを開きます。または、 pip install omx-hyperliquid を実行し、コマンドとして omx-hyperliquid を使用します。

--config、OMX_CONFIG、./omx.toml のいずれも指定されていない場合、omx-hyperliquid は デモを実行します（--demo を指定すると強制的にデモになります）。エンジン、ポリシーチェック、承認しきい値、 エージェントの予算、キルスイッチ、監査ログには実際のコードが使われます。価格は ランダムウォークモデルに基づいており、Hyperliquid のデータではありません。すべての応答に "demo": true が含まれます。 状態は一時ディレクトリに保存され、終了時に削除されます。指定した設定ファイルが 存在しない場合はエラーとなり、黙ってデモモードに切り替わることはありません。

次に、エージェントに ETH の価格提示、小規模な TWAP のプレビューと発注（たとえば、10 秒間で 5 回に分けて 0.1 ETH を買う）を依頼し、order_status を done になるまで確認してください。1,000 USD を超えるインテントは approval_id を返して人による承認を待ちます。デモには承認手順がないため、注文は保留状態のまま期限切れになります。 kill_switch の実行後は、新しい注文がすべて拒否されます。実際の利用では、人間だけが omx unkill で解除できます（I UNDERSTAND と入力する必要があります）。デモには unkill がないため、状態をリセットするにはサーバーを再起動してください。

Hyperliquid のライブ注文板でのペーパートレード

omx-hyperliquid --paper（または omx-mcp --paper、omx paper）を実行すると、Hyperliquid メインネットの公開注文板をリアルタイムで参照し、約定をシミュレーションして同じツールを利用できます。キー、アカウント、設定、デーモンは不要です。公開市場データ（/info l2Book、allMids、metaAndAssetCtxs）の読み取りのみを行い、注文への署名や送信は一切行いません。ペーパーアカウントの初期残高は 10,000 USD です（変更するには --paper-equity 2500 を指定します）。テイカー注文は Hyperliquid の基本手数料ティア（テイカー 0.045 %、メイカー 0.015 %）で実際の注文板をたどり、未約定注文は注文板がその価格を通過した場合にのみ約定します。また、Hyperliquid の 10 USD の最低注文額を含む、デフォルトのポリシー制限が適用されます。すべての応答には "paper": true が含まれます。約定はモデルによるものであり、Hyperliquid のマッチングエンジンによるものではありません。docs/PAPER.md を参照してください。

claude mcp add omx-paper -- uvx omx-hyperliquid --paper

その他のクライアントの場合：{"command": "uvx", "args": ["omx-hyperliquid", "--paper"]}。

Codex CLI はデフォルトでサーバーの起動を 10 s 待機します。また、uvx の初回実行時には依存関係がダウンロードされます。タイムアウトする場合は、~/.codex/config.toml の [mcp_servers.omx] の下に startup_timeout_sec = 60 を追加してください。

自分のアカウントを設定する

pip install omx-hyperliquid        # or: uv tool install omx-hyperliquid
omx setup                          # one guided terminal session, testnet first
omx --config <path printed by setup> daemon     # in its own terminal, keep it open
omx mcp-config                     # prints the settings for your MCP client

omx setup は、ネットワーク（まずテストネット）、メインアカウントの公開アドレス、API ウォレットキー（非表示のプロンプトに入力して自分だけが読み取れるファイルに保存するか、すでに保存してあるキーファイルを指定します）、利用資格に関する質問、エージェントの制限、ビルダーフィーの選択、読み取り専用のチェックの順に案内します。メインウォレットのキーやシードフレーズを尋ねることはなく、アドレスがメインアカウントと一致するキーは拒否します。omx mcp-config は、設定ファイルの絶対パスを入力した状態で、Claude Code、Codex、Gemini、VS Code、Cursor、Claude Desktop 用の設定を出力します。各手順を手動で行う方法については、docs/SETUP.md とクイックスタートを参照してください。

エージェントフレームワーク：omx-integrations には、OpenAI Agents SDK、LangChain、Claude Agent SDK、PydanticAI、CrewAI のコピーして実行できるサンプルがあります。各サンプルは、各フレームワーク独自の MCP クライアントを使ってこのサーバーで検証済みです（デフォルトはデモモード）。

ステータス（v0.1.8）： 1.0 以前のバージョンです。（エージェントの意図 → ポリシー → ビルダーコード付き署名済み注文 → 約定 → キルスイッチ → 監査検証）という一連の処理は、Hyperliquid テストネットでエンドツーエンドに実行済みです。ネイティブ TWAP ルート（v0.1.8、デフォルトでは無効）と約定レシートは、ローカルシミュレーターおよび記録済みの取引所応答に対してテスト済みですが、テストネットではまだテストされていません。OMX は外部のセキュリティ監査を受けていません。 まずテストネットで始め、その後、少額でメインネットを利用してください。MIT ライセンスで提供され、保証はありません。

利用資格

Hyperliquid の利用規約に基づき、米国、カナダのオンタリオ州、制裁対象地域に居住、所在、設立されている、または登録事務所を置いている個人や法人、ならびに制裁対象地域の市民は OMX を利用できません。VPN やプロキシの利用、または虚偽の居住地申告によってこれを回避することは規約違反です。OMX にはブロックを回避する方法はありません。OMX は結果市場を提供しません。omx eligibility はこれらの質問を行い、回答により利用がブロックされる場合は取引を拒否します。保存するのは国・地域コードと「はい／いいえ」の回答のみです。

非カストディアルモデル

• 資金はご自身の Hyperliquid アカウントに置かれます。OMX には出金や送金を行うコードパスはありません。
• ご自身のアカウントで API／エージェントウォレットを作成します。このウォレットでは注文の発注とキャンセルはできますが、出金はできません。OMX が署名に使うのは、そのキーのみです。
• OMX がメインウォレットのキーやシードフレーズを尋ねることはありません。ビルダーフィーの承認（該当する場合）は、ご自身のウォレットでご自身が署名します。
• 設定にはエージェントキーのファイルのパス、または環境変数名のみが保存され、キー自体は保存されません。秘密鍵のような形式の値を含む設定は拒否されます。コマンドライン引数についても同様です。

インストール

pip install omx-hyperliquid          # PyPI; gives the `omx`, `omx-mcp` and `omx-hyperliquid` commands

チェックアウトから実行する場合（開発、テスト）：

python -m venv .venv
.venv/Scripts/python -m pip install -e ".[test]"   # Windows; .venv/bin/python elsewhere
.venv/Scripts/python -m pytest -q tests

以下のコマンドも、チェックアウトから python -m omx.cli ... として実行できます。 Python 3.11 以降が必要です（tomllib；開発環境は 3.12）。MCP サーバーは 公式の mcp Python SDK 2.x を使用します。Hyperliquid の実環境では、署名用に eth_account も必要です。

クイックスタート（テストネット）

OMX は、単一の長時間稼働プロセス omx daemon として実行されます。このプロセスがエンジン（Hyperliquid と通信し、エージェントキーを保持する唯一のもの）、監査ログライター、承認エグゼキューターを管理します。CLI と MCP サーバーは、state_dir/ipc/ 内のファイルを介してデーモンと通信する軽量なクライアントです。

1. app.hyperliquid-testnet.xyz（API ページ）でエージェントウォレットを作成し、自分のユーザーだけが読み取れるファイル（例：secrets/hl_agent_testnet.key）にキーを保存します。
2. 設定を記述し、適格性に関する質問に回答します：

   python -m omx.cli --config omx.toml init --account 0xYOUR_MAIN_ADDRESS --key-path secrets/hl_agent_testnet.key
   

   config.example.toml にすべてのフィールドが記載されています。適格性は eligibility_ttl_days ごとに更新する必要があります（デフォルトおよび最大値は 30）：omx eligibility。
3. 専用のターミナルでデーモンを起動し、取引中は実行したままにします：

   python -m omx.cli --config omx.toml daemon
   

   200 ms ごとに、処理中のすべてのインテントをステップ実行します（TWAP／POV／チェイスのスライスは、実行中のみ送信されます）。state_dir ごとに実行できるデーモンは 1 つだけで、アカウントごとにも 1 つだけです（アカウント単位のロックは %LOCALAPPDATA%\omx\locks、または設定の lock_dir にあります）。有効な適格性証明がない場合は起動を拒否します。取引に回避手段はありません。適格性を 10 分ごとに再確認し、確認に失敗するとキャンセル専用モードに切り替わります。daemon --cancel-only は確認なしで起動し、休止中の OMX 注文のみをキャンセルします（期限切れまたはブロックされたユーザー向け）。 デーモンに送信された承認、unkill、eligibility、audit repair は、実行内容と CLI が表示したリクエスト ID とともに、デーモンのターミナルに表示されます。そこに表示された confirm <code> の行を入力した場合にのみ実行されます。そのターミナルは対話可能な状態にしておいてください（実際のコンソールを使い、< NUL やパイプは使用しないでください。docs/SECURITY.md を参照）。
4. 別のターミナルで、まずドライランを実行し、その後に送信します：

   python -m omx.cli --config omx.toml preview ETH buy 0.05 --algo twap --duration-s 300 --slices 5
   python -m omx.cli --config omx.toml submit  ETH buy 0.05 --algo twap --duration-s 300 --slices 5
   python -m omx.cli --config omx.toml status <intent_id>
   

   preview、submit、status、cancel、approvals approve にはデーモンが必要です。デーモンが起動していない場合（ハートビートが 5 秒より古い場合）、omx daemon の起動を促すメッセージを表示して停止します。デーモン再起動後、古いインテントに対する status の応答は unknown です（監査ログと取引所を確認してください）。rejected にはなりません。
5. すべてを一度に停止するには：python -m omx.cli --config omx.toml kill --reason "..."。 まず必ず state_dir/KILL ファイルを書き込みます（OMX のどのプロセスも新しい注文を出せなくなります）。その後、デーモン経由で休止中の OMX 注文をキャンセルします。デーモンが起動していない場合は、この処理用に一時的なキャンセル専用エンジンを構築してキャンセルします（適格性の確認なし）。いずれの場合も、キャンセル処理に失敗した場合、またはキャンセルできない注文があった場合は、終了コード 3 と WARNING を返します。 --all は OMX の注文だけでなく、アカウント上のすべてのオープン注文をキャンセルします。対象範囲は KILL ファイルに保存され、次回のデーモン起動時にも適用されます。これを解除する（unkill）には、I UNDERSTAND の入力が必要です。submit はインテント ID を表示します。タイムアウト後は status <id> で確認し、--intent-id <id> を指定して再試行してください（デーモンはすでに受け取った ID を拒否します）。
6. AI エージェント：python -m omx.cli --config omx.toml mcp（通常は MCP クライアントによって起動されます。docs/AGENTS.md を参照）。キーもエンジンも保持せず、デーモンの起動が必要です。

デーモンを停止（Ctrl+C）しても、キルスイッチは設定されず、何もキャンセルされません。休止中の OMX 注文は取引所に残り、スライスされたインテントの送信は停止します。次回の起動時に、エンジンは前回の実行で残された OMX 注文をキャンセルします。 すぐにキャンセルするには、omx kill を使用してください。

その他のコマンド：cancel、approvals list|approve|reject、audit verify、 audit repair、fees、mcp、eligibility、approve-builder、doctor。audit verify は、最後の行の破損をクラッシュによるもの（TRUNCATED_TAIL、終了コード 4）か、改ざんによるもの（BROKEN、終了コード 3）か判別して報告します。audit repair は、REPAIR AUDIT と入力した後、破損した末尾部分のみを別の場所に移動します。

制御

すべての子注文は、マシンから送信される前に以下のすべてのチェックを通過します。

1. コインの許可リスト
2. 流動性の下限（24 時間の取引名目額）とミッド価格付近の板の厚さ
3. ミッド価格に対する価格帯、意図の指値価格、意図ごとのスリッページ上限
4. コインごとの最悪ケース名目額（ポジションと同じ側のすべての未約定注文）
5. アカウント全体の最悪ケース名目額
6. エクイティに対する最悪ケースのレバレッジ
7. 1 日の損失上限（入金と出金は損益から除外）
8. マーケットデータの鮮度
9. キルスイッチ（state_dir 内のファイル。どのプロセスからでも作動させられます。omx kill は未約定の OMX 注文もキャンセルします）
10. ハッシュチェーン監査ログ（omx audit verify）

さらに、子注文ごとの名目額上限、リデュースオンリーのチェック、AI エージェント向けのオン／オフスイッチ、エージェントが取引できるコインのサブセット、意図ごとの人間による承認しきい値、1 日あたりのエージェント名目額予算、有効期限付きの承認があり、キルスイッチを解除したり、上限を変更したりする機能はありません。docs/SECURITY.md、docs/FEES.md、docs/AGENTS.md を参照してください。

ビルダー手数料

OMX はオープンソース（MIT）で、インストールや実行に費用はかかりません。メンテナーは、メインネットでの約定に対する任意の Hyperliquid ビルダー手数料によって報酬を受け取ります。ネットワークのデフォルトビルダーが omx/config.py（DEFAULT_BUILDER）で指定されている場合、omx init は手数料を 1 bp（約定時の想定元本の 0.01 %）に設定します。 --no-builder を指定するとビルダーコードは送信されず、--fee-tenths-bps で手数料を低く設定でき、--builder-address で自分のアドレスを使用できます。ご自身のウォレットから手数料を承認する（omx approve-builder）まで、料金は発生しません。また、いつでも承認を取り消せます。omx fees を実行すると、承認前に、承認対象となる正確な手数料率と最大手数料率が表示されます。詳しくは docs/FEES.md をご覧ください。

適用の仕組み。 [builder] address と fee_tenths_bps > 0 が設定されている場合、エンジン自体が送信するすべての注文に {"b": address, "f": fee} を付加します。インテント（CLI、MCP、承認）にはビルダーフィールドがないため、呼び出し元がこれを設定または削除することはできません。別のビルダーを含む子注文は拒否されます。ビルダーアドレスはアカウントおよびエージェントウォレットと異なる必要があります。デーモンは起動時と 10 分ごと（ブロック中は 60 秒ごと）に、(account, builder) の maxBuilderFee を読み取ります。承認済みの最大値が設定済みの手数料を下回る間は、状態が BUILDER_NOT_APPROVED になります。この状態では、新しいインテントはその理由とヒント omx approve-builder を示して拒否されます。実行中のインテントは完了するか、キャンセルできます。omx kill は常に動作します。

OMX にキーを渡さず、ブラウザーで承認する：

python -m omx.cli --config omx.toml approve-builder                       # approves the configured fee
python -m omx.cli --config omx.toml approve-builder --max-fee-rate 0.02%  # a higher maximum
python -m omx.cli --config omx.toml approve-builder --revoke              # maxFeeRate 0%

127.0.0.1 上で 1 ページを配信し（ポートとパスはランダム）、ブラウザーを開きます（--no-browser を指定すると URL のみが表示され、--timeout-s でタイムアウトを設定できます。デフォルトは 900 です）。このページはブラウザーウォレット（window.ethereum）を使用します。選択中のアカウントが account_address であることを確認し、ウォレットに HyperliquidTransaction:ApproveBuilderFee への署名を求め、署名済みの承認をブラウザーから Hyperliquid の /exchange に直接送信して、maxBuilderFee を再度読み取ります。OMX の Python プロセスがキーや署名を受け取ることはありません。

セットアップの確認： python -m omx.cli --config omx.toml doctor を実行すると、次の項目について OK／FAIL（修正方法を表示）／SKIP が表示されます：設定、キーファイル、エージェントアドレス（キーは表示されません）、エンドポイント、アカウントの存在、アカウントモード、アカウントの価値、アカウントに対するエージェントの承認、設定済み手数料とビルダー承認の比較、ビルダーアカウントの価値が 100 USDC 以上であること、ビルダーアカウントモード、適格性、デーモンの実行状態。このコマンドは、実行時に限り /info を読み取ります。

アカウントモード： OMX は起動時と 10 分ごとに、アカウントの Hyperliquid userAbstraction を読み取ります。標準アカウント（disabled／default）では、perp アカウントの価値をエクイティとして使用します。統合アカウント（unifiedAccount、ユーザーのデフォルト）では、1 つの USDC 残高が spot clearinghouse に保管されるため、OMX は spot USDC の total をエクイティとして使用します。ドキュメントには、total にオープンポジションの未実現損益がすでに含まれるかどうかは記載されていません。テストネットでの測定（2026-11-05、9 区間中 9 区間で total が未実現損益とともに 1e-6 まで変動）では含まれることが確認されたため、エクイティには total 自体を使用します。ポジションは常に perp clearinghouse の状態から取得します。portfolioMargin、dexAbstraction、または読み取れないモードの場合、新しいインテントは ACCOUNT_MODE_UNSUPPORTED で拒否されます（kill とキャンセルは引き続き動作します）。Manual／Standard への切り替えは任意です。手数料を獲得するには、ビルダーアドレスが標準アカウントである必要があります。python tools/measure_account_mode.py --config omx.toml --samples 10 --interval 30 を実行すると（読み取り専用、キー不要）、両方の候補エクイティが表示されます。また、損益が変動するオープンポジションがある場合は、取引所がどちらを使用しているかも表示されます。

テスト用ウォレット： python tools/new_test_wallet.py --out secrets/testnet_builder.key を実行すると、新しい使い捨てキーが作成されます（ファイルを上書きせず、所有ユーザーのみにアクセスを制限します）。表示されるのはアドレスのみです。これはテスト用ウォレット（テストネットのビルダー、Base Sepolia の支払い元）にのみ使用し、実際の資金には使用しないでください。