OMX for Hyperliquid

OMX：面向 AI Agent 的 Hyperliquid 执行（MCP）

OMX 是 Hyperliquid 永续合约的非托管执行引擎。它运行在你自己的机器上，将订单意图（市价、限价、TWAP、POV、追价，或启用后使用 Hyperliquid 自带的 TWAP）转换为子订单，根据你配置的交易前策略检查每笔子订单，并将每项决策写入哈希链审计日志。命令行和 MCP 服务可让人或 AI Agent 在这些限制范围内驱动它。

OMX 不对交易表现或利润作任何保证。它只是带有防护措施的执行基础设施。

你担心的事	OMX 的处理方式
你的密钥	仅使用你在自己账户中创建的 Hyperliquid API（Agent）钱包签名；绝不索要你的主密钥或助记词。配置中保存的是密钥文件的路径，而非密钥本身。不包含提款或转账代码。
限额	每笔子订单都会在本地检查：币种允许列表、流动性和深度、价格区间和滑点、单币种及账户名义价值（包括挂单）、杠杆、每日亏损、数据时效。引擎会拒绝任何不符合策略的子订单。MCP 工具无法更改限额；限额来自守护进程加载的配置。以你的操作系统用户身份运行的 Agent 若也拥有 shell 或文件访问权限，就可能编辑该文件，因此这类 Agent 应以另一个操作系统用户身份运行（信任边界）。
人工审批	Agent 意图超过 approval_above_usd，或超出 Agent 的每日预算时，需要等待你的审批：执行 omx approvals approve <id>，然后在守护进程的终端中输入确认码。待审批请求会过期。
停止运行	任何 Agent 或人都可以触发紧急停止开关；它会取消 OMX 的挂单。只有人可以解除该开关（omx unkill）。
审计	每项决策都会写入哈希链日志；omx audit verify 可检测篡改。
费用	可选的 1 bp 建造者费用，仅在你通过自己的钱包批准后才会收取；如需不收取费用，可使用 --no-builder。参见 docs/FEES.md。

使用路径：无密钥演示，然后在 Hyperliquid 实时订单簿上进行模拟交易（同样无需密钥），接着使用测试网，最后以小额资金使用主网。

立即试用：无需密钥，无需账户

点击一次即可在演示模式下安装 MCP 服务（在独立进程中模拟交易场所；无法进行真实交易）：

或者运行一行命令：

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 可强制启用）。引擎、策略检查、审批阈值、 Agent 预算、紧急停止开关和审计日志都使用真实代码；价格采用 随机游走模型，并非来自 Hyperliquid 的数据。每条回复都包含 "demo": true。 状态保存在临时目录中，并会在退出时删除。指定的配置文件不存在时会报错，绝不会静默进入演示模式。

然后让 Agent 报出 ETH 报价、预览一笔小额 TWAP 并提交订单（例如在 10 s 内分 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 钱包密钥（输入时会隐藏，并保存到仅你本人可读取的文件中；也可使用你已保存的密钥文件）、资格问题、Agent 限额、构建者费用选项，随后执行只读检查。它绝不会索要主钱包密钥或助记词，并会拒绝地址属于主账户的密钥。omx mcp-config 会打印 Claude Code、Codex、Gemini、VS Code、Cursor 或 Claude Desktop 的设置，并填入配置文件的绝对路径。请参阅 docs/SETUP.md，或按照快速开始手动完成每个步骤。

Agent 框架：omx-integrations 提供可复制运行的示例，涵盖 OpenAI Agents SDK、LangChain、Claude Agent SDK、PydanticAI 和 CrewAI；每个示例都使用相应框架自带的 MCP 客户端通过此服务验证（默认使用演示模式）。

状态（v0.1.8）： 尚未达到 1.0 版本。完整流程（Agent 意图 -> 策略 -> 带构建者代码的签名订单 -> 成交 -> 紧急停止开关 -> 审计验证）已在 Hyperliquid 测试网上端到端运行。原生 TWAP 路由（v0.1.8，默认关闭）和执行回执已通过本地模拟器及记录的交易所响应进行测试，尚未在测试网上测试。OMX 尚未经过外部安全审计。 请先在测试网上使用，再以小额在主网上使用。采用 MIT 许可证，不提供任何保证。

资格

根据 Hyperliquid 使用条款，OMX 不适用于居住、位于、注册成立或设有注册办事处于美国、加拿大安大略省或受制裁地区的个人或实体，也不适用于受制裁地区的公民。使用 VPN 或代理，或提供虚假的居住地声明来规避限制，均属违约；OMX 不提供任何绕过限制的方式。OMX 不提供结果市场。omx eligibility 会询问这些问题，并在答案触发限制时拒绝交易；它只存储国家/地区代码以及是/否答案。

非托管模式

• 你的资金始终留在你自己的 Hyperliquid 账户中。OMX 不包含提取或转账代码路径。
• 你在自己的账户中创建 API / Agent 钱包。它可以下单和撤单，但不能提取资金。OMX 只使用该密钥签名。
• OMX 绝不会索要你的主钱包密钥或助记词。构建者费用授权（如有）由你在自己的钱包中签署。
• 配置中保存的是 Agent 密钥文件的路径或环境变量名称，而不是密钥本身。任何包含类似私钥内容的配置都会被拒绝，类似的命令行参数也会被拒绝。

安装

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 通信并持有 Agent 密钥的组件）、审计日志写入器和审批执行器。CLI 和 MCP 服务是轻量客户端，通过 state_dir/ipc/ 中的文件与其通信。

1. 在 app.hyperliquid-testnet.xyz（API 页面）创建 Agent 钱包，并将其密钥保存在只有你的用户才能读取的文件中，例如 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 只能运行一个守护进程，每个账户也只能运行一个守护进程（使用 %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 s），这些命令会停止并提示你启动 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 Agent：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. Coin 白名单
2. 流动性下限（24 h 成交名义金额）和中间价附近的挂单深度
3. 相对于中间价的价格区间、意图限价、每个意图的滑点上限
4. 每种 Coin 的最坏情况名义金额（持仓加上所有同方向挂单）
5. 账户整体最坏情况名义金额
6. 相对于权益的最坏情况杠杆
7. 每日亏损限额（存款和取款不计入盈亏）
8. 市场数据时效性
9. 紧急停止开关（位于 state_dir 中的文件；任何进程都可以触发；omx kill 还会取消挂单中的 OMX 订单）
10. 哈希链式审计日志（omx audit verify）

此外，还包括每笔子订单的名义金额上限、仅减仓检查，以及针对 AI Agent 的开关、Agent 可交易 Coin 子集、每个意图的人为审批阈值、Agent 每日名义金额预算、会过期的审批，以及无法解除紧急停止或更改限额的限制。请参阅 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、审批）不包含构建者字段，因此调用方无法设置或移除该字段；携带其他构建者的子订单会被拒绝。构建者地址必须与账户地址和 Agent 钱包地址不同。守护进程会在启动时及每 10 分钟读取一次 (account, builder) 的 maxBuilderFee（受阻期间每 60 秒读取一次）。如果已批准的最高费率低于配置的费用，系统将进入 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 上提供一个页面（使用随机端口和路径），并打开你的浏览器（--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：配置、密钥文件、Agent 地址（绝不读取密钥）、端点、账户是否存在、账户模式、账户价值、Agent 是否已获准使用该账户、构建者批准额度与配置费用是否匹配、构建者账户价值是否 >= 100 USDC、构建者账户模式、资格，以及守护进程是否运行。它只读取 /info，且仅在你运行命令时读取。

账户模式： OMX 会在启动时及每 10 分钟读取一次账户的 Hyperliquid userAbstraction。标准账户（disabled / default）使用永续合约账户价值作为权益。统一账户（unifiedAccount，用户的默认模式）在现货清算所保留一笔 USDC 余额，因此 OMX 会将现货 USDC 的 total 作为权益。文档没有说明 total 是否已包含未平仓头寸的未实现盈亏；测试网测量结果（2026-11-05，9 个区间中有 9 个区间的 total 随未实现盈亏变化，精度为 1e-6）表明它已包含，因此权益就是 total 本身。头寸始终取自永续合约清算所状态。对于 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 付款方），切勿用于真实资金。