OMX for Hyperliquid

OMX: Hyperliquid execution for AI agents (MCP)

OMX is a non-custodial execution engine for Hyperliquid perpetuals. It runs on your own machine, turns an order intent (market, limit, TWAP, POV, chase, or Hyperliquid's own TWAP when you turn it on) into child orders, checks every child against a pre-trade policy you configure, and writes every decision to a hash-chained audit log. A command line and an MCP server let a human or an AI agent drive it inside those limits.

OMX makes no claim about trading performance or profit. It is execution plumbing with guard rails.

Path: the keyless demo, then paper trading on live Hyperliquid books (also keyless), then testnet, then mainnet with small size.

Try it now: no key, no account

One click installs the MCP server in demo mode (a simulated venue in its own process; nothing real can be traded):

Or one line:

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: /plugin marketplace add Lumen-Founder/omx-hyperliquid-mcp, then /plugin install omx@omx.
• Gemini CLI extension: gemini extensions install https://github.com/Lumen-Founder/omx-hyperliquid-mcp.
• Any other MCP client (Claude Desktop, Cline, Windsurf, Zed, JetBrains, ...): {"mcpServers": {"omx": {"command": "uvx", "args": ["omx-hyperliquid"]}}}. Claude Desktop keeps it in claude_desktop_config.json (Settings > Developer > Edit Config; Windows %APPDATA%\Claude\, macOS ~/Library/Application Support/Claude/); Cursor in ~/.cursor/mcp.json. Pin a version with "omx-hyperliquid@0.1.8".
• No 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; then open a new terminal. Or pip install omx-hyperliquid and use omx-hyperliquid as the command.

With no --config, no OMX_CONFIG and no ./omx.toml, omx-hyperliquid runs the demo (--demo forces it). The engine, policy checks, approval threshold, agent budget, kill switch and audit log are the real code; prices are a random-walk model, not Hyperliquid data. Every answer carries "demo": true. State lives in a temporary directory that is deleted on exit. A config that is named but missing is an error, never a silent demo.

Then ask the agent to quote ETH, preview a small TWAP and submit it (for example buy 0.1 ETH over 10 s in 5 slices), and poll order_status until it is done. An intent above 1,000 USD returns an approval_id and waits for a human; the demo has no approval step, so it stays pending and expires. After kill_switch every new order is refused. In real use only a human clears it, with omx unkill (it asks you to type I UNDERSTAND); the demo has no unkill, so restart the server to start fresh.

Paper trading on live Hyperliquid books

omx-hyperliquid --paper (or omx-mcp --paper, omx paper) runs the same tools with simulated fills against Hyperliquid mainnet's live public order books. No key, no account, no config, no daemon: it only reads public market data (/info l2Book, allMids, metaAndAssetCtxs) and never signs or sends an order. The paper account starts at 10,000 USD (--paper-equity 2500 to change it); taker orders walk the real book at Hyperliquid's base-tier fees (0.045 % taker, 0.015 % maker), resting orders fill only when the book trades through their price, and the default policy limits apply (including Hyperliquid's 10 USD minimum order). Every answer carries "paper": true. Fills are a model, not Hyperliquid's matching engine; see docs/PAPER.md.

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

Any other client: {"command": "uvx", "args": ["omx-hyperliquid", "--paper"]}.

Codex CLI waits 10 s for a server to start by default, and the first uvx run downloads the dependencies; if it times out, add startup_timeout_sec = 60 under [mcp_servers.omx] in ~/.codex/config.toml.

Set up your own account

pip install omx-hyperliquid        # or: uv tool install omx-hyperliquid

omx setup # one guided terminal session, testnet first omx --config daemon # in its own terminal, keep it open omx mcp-config # prints the settings for your MCP client

omx setup walks you through the network (testnet first), your main account's public address, an API wallet key (typed into a hidden prompt and saved to a file only your user can read, or a key file you already saved), the eligibility questions, agent limits, the builder-fee choice, then read-only checks. It never asks for your main wallet key or seed phrase, and refuses a key whose address is your main account. omx mcp-config prints the settings for Claude Code, Codex, Gemini, VS Code, Cursor or Claude Desktop, filled in with your config's absolute path. See docs/SETUP.md and the Quick start for each step by hand.

Agent frameworks: omx-integrations has copy-and-run examples for the OpenAI Agents SDK, LangChain, the Claude Agent SDK, PydanticAI and CrewAI, each checked against this server with the framework's own MCP client (demo mode by default).

Status (v0.1.8): pre-1.0. The full path (agent intent -> policy -> signed order with a builder code -> fill -> kill switch -> audit verify) has been run end to end on Hyperliquid testnet. The native TWAP route (v0.1.8, off by default) and execution receipts are tested against the local simulator and recorded exchange answers, not yet on testnet. OMX has not had an external security audit. Start on testnet, then mainnet with small size. MIT licensed, no warranty.

Eligibility

OMX is not available to persons or entities residing, located, incorporated or with a registered office in the United States, Ontario (Canada) or sanctioned territories, nor to citizens of sanctioned territories, per the Hyperliquid Terms of Use. Using a VPN or proxy, or a false residency statement, to get around this is a breach; OMX offers no way around a block. OMX does not offer outcome markets. omx eligibility asks these questions and refuses to trade when the answer is blocked; it stores only country/region codes and yes/no answers.

Non-custodial model

• Your funds stay in your own Hyperliquid account. OMX has no withdrawal or transfer code path.
• You create an API / agent wallet in your own account. It can place and cancel orders but cannot withdraw. OMX signs with that key only.
• OMX never asks for your MAIN wallet key or seed phrase. The builder-fee approval (if any) is signed by you in your own wallet.
• The config holds the agent key's file PATH or env var NAME, never the key. A config containing anything shaped like a private key is rejected, and so is a command-line argument shaped like one.

Install

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

From a checkout (development, tests):

python -m venv .venv

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

The commands below also work as python -m omx.cli ... from a checkout. Requires Python 3.11+ (tomllib; developed on 3.12). The MCP server uses the official mcp Python SDK 2.x. The live Hyperliquid venue also needs eth_account for signing.

Quick start (testnet)

OMX runs as one long-lived process, omx daemon, which owns the engine (the only thing that talks to Hyperliquid and holds the agent key), the audit-log writer and the approval executor. The CLI and the MCP server are thin clients that talk to it through files in state_dir/ipc/.

1. Create an agent wallet at app.hyperliquid-testnet.xyz (API page) and save its key in a file only your user can read, e.g. secrets/hl_agent_testnet.key.
2. Write the config and answer the eligibility questions:

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

config.example.toml shows every field. Eligibility must be renewed every eligibility_ttl_days (default and maximum 30): omx eligibility.

1. Start the daemon in its own terminal and leave it running while you trade:

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

It steps every working intent every 200 ms (TWAP/POV/chase slices are sent only while it runs). Only one daemon can run per state_dir, and only one per account (a per-account lock in %LOCALAPPDATA%\omx\locks, or lock_dir in the config). It refuses to start without a valid eligibility attestation; there is no bypass for trading. It re-checks eligib