
Non-custodial, policy-checked execution engine for Hyperliquid: CLI + MCP server for traders and AI
Non-custodial, policy-checked execution engine for Hyperliquid: CLI + MCP server for traders and AI agents. Try it keyless: uvx omx-hyperliquid --demo. Testnet-verified, pre-audit.
·
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.
| You worry about | What OMX does |
|---|---|
| Your keys | Signs only with a Hyperliquid API (agent) wallet you create in your own account; never asks for your main key or seed. The config holds the key file's path, not the key. No withdrawal or transfer code. |
| Limits | Every child order is checked locally: coin allowlist, liquidity and depth, price band and slippage, per-coin and account notional (resting orders included), leverage, daily loss, data age. The engine refuses any child the policy rejects. No MCP tool can change limits; they come from the config the daemon loaded. An agent that also has shell or file access as your OS user could edit that file, so run such agents under another OS user (trust boundary). |
| Human approval | An agent intent above approval_above_usd, or beyond the agent's daily budget, waits for you: omx approvals approve <id>, then a confirm code typed in the daemon's terminal. Pending approvals expire. |
| Stopping it | Any agent or human can trip the kill switch; it cancels resting OMX orders. Only a human can clear it (omx unkill). |
| Audit | Every decision goes to a hash-chained log; omx audit verify detects tampering. |
| Fees | Optional 1 bp builder fee, charged only after you approve it in your own wallet; --no-builder for none. See docs/FEES.md. |
Path: the keyless demo, then paper trading on live Hyperliquid books (also keyless), then testnet, then mainnet with small size.
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/plugin marketplace add Lumen-Founder/omx-hyperliquid-mcp, then /plugin install omx@omx.gemini extensions install https://github.com/Lumen-Founder/omx-hyperliquid-mcp.{"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 "[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; 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.
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 --paperAny 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.
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 clientomx 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.
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.
pip install omx-hyperliquid # PyPI; gives the `omx`, `omx-mcp` and `omx-hyperliquid` commandsFrom 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 testsThe 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.
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/.
secrets/hl_agent_testnet.key.python -m omx.cli --config omx.toml init --account 0xYOUR_MAIN_ADDRESS --key-path secrets/hl_agent_testnet.keyconfig.example.toml shows every field. Eligibility must be renewed every
eligibility_ttl_days (default and maximum 30): omx eligibility.python -m omx.cli --config omx.toml daemonstate_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 eligibility every 10 minutes and turns cancel-only
when the check fails. daemon --cancel-only starts without the check and
only cancels resting OMX orders (for an expired or blocked user).
Approvals, unkill, eligibility and audit repair sent to the daemon
are shown in its terminal with what they would do and the request id the
CLI printed; they run only after you type the confirm <code> line it
prints there. Keep that terminal interactive (a real console, not < NUL
or a pipe; see docs/SECURITY.md).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 and approvals approve need the
daemon; without it (heartbeat older than 5 s) they stop with a message
telling you to start omx daemon. After a daemon restart status of an
older intent answers unknown (check the audit log and the venue), never
rejected.python -m omx.cli --config omx.toml kill --reason "...".
It always writes the state_dir/KILL file first (no new orders from any
OMX process), then cancels resting OMX orders through the daemon, or, if no
daemon is running, through a one-shot cancel-only engine it builds for this
(no eligibility check). Either way it exits with code 3 and a WARNING if
the sweep failed or an order could not be cancelled.
--all cancels every open order on the account, not only OMX ones; the
scope is stored in the KILL file and honoured by the next daemon. Clearing
it (unkill) asks you to type I UNDERSTAND. submit prints the intent id;
after a timeout check it with status <id> and retry with --intent-id <id>
(the daemon refuses an id it already took).python -m omx.cli --config omx.toml mcp (usually started by
your MCP client, see docs/AGENTS.md). It holds no key and no engine and
needs the daemon running.Stopping the daemon (Ctrl+C) does not set the kill switch and cancels
nothing: resting OMX orders stay on the venue and sliced intents stop sending.
On the next start the engine cancels orphan OMX orders from the previous run.
To cancel immediately, use omx kill.
Other commands: cancel, approvals list|approve|reject, audit verify,
audit repair, fees, mcp, eligibility, approve-builder, doctor. audit verify tells a torn last
line from a crash (TRUNCATED_TAIL, exit 4) apart from tampering (BROKEN,
exit 3); audit repair moves only a torn tail aside, after you type
REPAIR AUDIT.
Every child order passes all of these before it can leave your machine:
state_dir; any process can trip it; omx kill also cancels resting OMX orders)omx audit verify)Plus a per-child notional cap, reduce-only checks, and for AI agents: an
on/off switch, an agent coin subset, a per-intent human-approval threshold, a
daily agent notional budget, approvals that expire, and no ability to unkill
or change limits. See docs/SECURITY.md, docs/FEES.md, docs/AGENTS.md.
OMX is open source (MIT) and costs nothing to install or run. The maintainers
are paid through an optional Hyperliquid builder fee on mainnet fills. When omx/config.py names a default builder for the network
(DEFAULT_BUILDER), omx init sets it at 1 bp (0.01 % of filled notional).
--no-builder sends no builder code, --fee-tenths-bps sets a lower fee, and
--builder-address uses your own. Nothing is charged until you approve the
fee from your own wallet (omx approve-builder), and you can revoke it at any
time. omx fees shows the exact rate and the exact max rate you would
approve, before you approve anything. Details in docs/FEES.md.
Enforcement. With [builder] address and fee_tenths_bps > 0 set, the
engine itself attaches {"b": address, "f": fee} to every order it sends.
Intents (CLI, MCP, approvals) have no builder field, so no caller can set or
remove it; a child order carrying any other builder is refused. The builder
address must differ from the account and from the agent wallet. The daemon
reads maxBuilderFee for (account, builder) at start and every 10 minutes
(every 60 s while blocked). While the approved maximum is below the configured
fee it is in BUILDER_NOT_APPROVED: new intents are refused with that reason
and the hint omx approve-builder; working intents finish or can be
cancelled; omx kill always works.
Approve in your browser, no key in 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%It serves one page on 127.0.0.1 (random port and path) and opens your
browser (--no-browser only prints the URL; --timeout-s stops it, default
900). The page uses your browser wallet (window.ethereum): it checks that the
selected account is account_address, asks the wallet to sign
HyperliquidTransaction:ApproveBuilderFee, sends the signed approval from the
browser straight to Hyperliquid's /exchange and re-reads maxBuilderFee.
OMX's Python process never receives a key or the signature.
Check the setup: python -m omx.cli --config omx.toml doctor prints
OK / FAIL (with the fix) / SKIP for: config, key file, agent address (never the
key), endpoint, account exists, account mode, account value, agent approved for
the account, builder approval vs configured fee, builder account value >= 100
USDC, builder account mode, eligibility, daemon running. It only reads /info,
and only when you run it.
Account modes: OMX reads the account's Hyperliquid userAbstraction at
start and every 10 minutes. Standard accounts (disabled / default) use the
perp account value as equity. Unified accounts (unifiedAccount, the default
for users) keep one USDC balance in the spot clearinghouse, so OMX takes equity
from the spot USDC total. The docs do not say whether total already holds
the open positions' unrealized P&L; a testnet measurement (2026-11-05, 9 of 9
intervals: total moved with the unrealized P&L to 1e-6) shows it does, so the
equity is total itself. Positions always come from the
perp clearinghouse state. portfolioMargin, dexAbstraction or an unreadable
mode refuse new intents with ACCOUNT_MODE_UNSUPPORTED (kill and cancels still
work). Switching to Manual / Standard is optional; builder addresses must be
standard to accrue fees. python tools/measure_account_mode.py --config omx.toml --samples 10 --interval 30 (read-only, no key) prints both candidate equities
and, with an open position whose P&L moves, which one the venue uses.
Test wallets: python tools/new_test_wallet.py --out secrets/testnet_builder.key
creates a new throwaway key (never overwrites a file, restricts it to your
user) and prints only its address. Use it for test wallets only (a testnet
builder, a Base Sepolia payer), never for real funds.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/omx-hyperliquid-mcp to learn what the "Omx Hyperliquid Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
claude mcp add omx -- uvx omx-hyperliquid # Claude Code
claude mcp add omx-paper -- uvx omx-hyperliquid --paperpip install omx-hyperliquidThis server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/omx-hyperliquid-mcp)Nothing comparable is listed yet.
v0.1.8v0.1.8: native TWAP route, execution receiptsRelease notesv0.1.7v0.1.7: new repository nameRelease notesv0.1.6v0.1.6: omx setup and omx mcp-configRelease notesv0.1.5v0.1.5: paper trading on live Hyperliquid booksRelease notesv0.1.4v0.1.4: keyless by default, one-click installsRelease notesv0.1.3v0.1.3: keyless demo modeRelease notesv0.1.2OMX v0.1.2Release notesv0.1.1OMX v0.1.1Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "omx-hyperliquid-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.