Pathiel

AI trading agent for Hyperliquid perps: bracket orders with an exact stop and target, risk sizing, account reads, oil and metals desk briefs. Read-only without a key.

Documentation

pathiel

An AI trading agent for Hyperliquid: Claude trades perps from Claude Code, with an exact stop and target on every order.

Claude Code plugin pathiel MCP server – quality and maintenance score on Glama Listed on mcpservers.org Version 0.7.1 MCP server CI License: MIT

Real money. A public install runs on Hyperliquid mainnet. With no key it only reads; once you add a key, orders are real. Read Before you trade first. Practice on testnet with one line: PATHIEL_NETWORK=testnet.

What it does

pathiel is a free, open-source Hyperliquid MCP server and Claude Code plugin: 30 tools that read Hyperliquid perpetual futures (perps) markets and your account, and place orders, from Claude Code, Claude Desktop, Cursor or any MCP client. Every trade is one bracket order: an entry, a stop-loss and a take-profit target, sized from your risk profile (3x and 1% of equity per trade by default). Desk briefs for crude oil (Brent and WTI) and metals (gold and silver) on Hyperliquid's HIP-3 markets give Claude a written call to trade from; nothing trades unless you ask.

Install in 30 seconds

In Claude Code:

/plugin marketplace add Julian-dev28/pathiel
/plugin install pathiel@pathiel
/pathiel:setup

From a shell instead:

claude plugin marketplace add Julian-dev28/pathiel
claude plugin install pathiel@pathiel

Claude Code v2.1.275 or later also takes the first two lines as one: /plugin install pathiel --marketplace Julian-dev28/pathiel. If Claude Code says Run /reload-plugins to apply, do that, then run /pathiel:setup.

/pathiel:setup shows the network and the risks, builds a private Python environment, creates ~/.pathiel/.env.local (mode 600) for your keys, seeds the default risk profile, checks the install without printing any key, and connects the MCP server. The steps are in commands/setup.md.

You need Claude Code, Python 3.11 or later, and for trading a Hyperliquid account and a browser wallet (or an API wallet you make in the Hyperliquid app). Reading markets needs no account. docs/GETTING_STARTED.md walks through the account setup.

Other MCP clients

Cursor, Claude Desktop, Pathiel Agent and any other MCP client register the launcher scripts/pathiel-mcp from a clone as the server command, or run the published container (amd64 and arm64). It is listed in the official MCP registry as io.github.Julian-dev28/pathiel.

docker run -i --rm --user "$(id -u):$(id -g)" -v "$HOME/.pathiel:/data" \
  ghcr.io/julian-dev28/pathiel-mcp:0.7.1

To build it yourself: docker build -f Dockerfile.mcp -t pathiel-mcp .

Both are the public install: keys and config come from ~/.pathiel, with the same default network, profile and fee rules as the plugin. Starting scripts/pathiel-mcp-server.py directly, or accepting the repo .mcp.json when you open a clone in Claude Code, is the maintainer path (see Maintainer setup).

First prompts to try

Paste these into Claude Code once /mcp shows pathiel connected.

you typewhat answers
What's the oil desk's call right now?get_desk_brief: direction, entry, stop, target, the R it pays, and "Your size"
Show me BTC's order book and funding.get_order_book, get_market
What's my balance and what's open?get_account, get_positions
What are my risk limits?get_risk_limits
Size a long on gold with the stop under today's low.size_trade
Dry-run that as a bracket.place_bracket with dry_run: true: judged and sized, nothing sent
Place it.place_bracket: live money, Claude Code asks you first
Run one oil desk tick./pathiel:desk-tick oil: brief, sweep, levels, one decision

What Claude can do

scripts/pathiel-mcp-server.py lists 30 tools over stdio to a plugin install: one tool per job, verb_noun names (contracts/mcp_public). The maintainer's own checkout lists the 60 only, the operator set the live desks use. Every older tool name still answers when called; it is just no longer listed. The full table, generated from the server's own tool lists, is docs/overhaul/MCP.md.

grouptoolsnames
Market data (no key)5get_market, list_markets, get_candles, get_order_book, get_funding_regime
Account reads4get_account, get_positions, get_orders, get_history
Risk and sizing2get_risk_limits, size_trade
Orders (live money)7place_bracket, set_stop (tighter only), set_target, cancel_order, close_position, set_leverage, sweep_brackets
Desks5list_desks, get_desk_brief, refresh_desk, submit_desk_call, get_desk_record
Setup4get_status, get_config, update_config, connect_wallet (approve an API wallet with one signature)
Research pool3get_pool_status, join_pool, leave_pool

get_account, get_positions, get_orders and get_history take an address to read any other wallet, and only read it. The server signs with one key, yours, so it has no path to place, close or resize an order on any other account.

The oil desk is the one active desk on a fresh install. It trades Brent (xyz:BRENTOIL) on mainnet, and WTI (xyz:CL) on testnet, where Brent is not listed. The metals desk (gold, silver) is registered and off by default; get_desk_brief still reads it. The rules each bracket must pass are in docs/strategy/OIL_RULES.md.

Before you trade

Networks and modes

The mode follows from what is in ~/.pathiel/.env.local:

you havemodewhat works
no keyread-only, mainnet (the default) dataevery read tool; order tools answer that no key is configured
an API wallet keymainnet (the default)everything, with real money
a key and PATHIEL_NETWORK=testnettestneteverything, with test funds; the oil desk trades WTI (xyz:CL)

Connect your wallet is the quick way to a key: /pathiel:setup (or asking Claude to connect your wallet) runs connect_wallet. It makes a new API wallet key on your machine and opens a local page where your browser wallet approves it with one signature, on the network you run. The key goes into ~/.pathiel/.env.local (mode 600) and nowhere else: it can trade, never withdraw, and your main key never leaves the wallet. Pasting an API wallet from the Hyperliquid app by hand still works.

State (theses, journals, caches) is kept per network, so testnet and mainnet never share it. Testnet needs its own API wallet, created and approved in the testnet app. How to create one, step by step: Connect your Hyperliquid account. The network is read once when the server starts: after editing the env file, reconnect pathiel in /mcp.

How the safety works

  • An exact stop on every order. place_bracket is the one entry path: entry, stop and target together. It refuses a bracket that pays under 2R, and a stop that sits outside half the distance to liquidation. A market entry fills first and its stop goes on right after; if the venue refuses that stop, the output says FILLED WITHOUT A STOP and sweep_brackets checks every open position for one.
  • Default profile: 3x, 1%, one position. At most 3x leverage, 1% of equity at the stop per trade (up to 2% only when the venue's minimum order size forces it), one position at a time. set_leverage refuses above the cap. You change the profile with update_config or in ~/.pathiel/.agent-config.json; nothing raises it for you.
  • Read-only without a key. No key, no orders. The API wallet key can trade and can never withdraw.
  • Testnet when you want it. PATHIEL_NETWORK=testnet in ~/.pathiel/.env.local switches to test funds.
  • Claude Code asks before each live-money call. The seven order tools, and update_config, are marked destructive, so Claude Code asks you before each call unless you allow the tool for good. Nothing runs in the background: no bot, no scheduler. The /loop desk tick trades only while your session runs it.

Builder fee

None. pathiel is free: no order it places carries a Hyperliquid builder fee, so you pay only Hyperliquid's own trading fee. There is nothing to approve.

If a fee ever comes back

It would ship as a new version with the rate in the changelog, and it could not touch your orders on its own: Hyperliquid charges a builder fee only after you approve that exact rate with your master wallet, and rejects any order whose builder fee is above the max you approved. Hyperliquid caps a perp builder fee at 0.1%. If you approved the 0.01% fee of pathiel 0.4.0, it is no longer charged; docs/BUILDER_FEE.md shows how to revoke it anyway.

Risk

Leveraged perps can lose the whole account, fast. The default profile limits how much one trade can lose at its stop; it does not limit gaps, slippage or a run of losses. The profile's daily loss figure is shown, not enforced. There is no demonstrated edge and no return is promised. This is software, not financial advice. You decide every trade and carry its result.

Restricted jurisdictions

Hyperliquid's terms bar use from restricted jurisdictions, including by US persons. The current list is in Hyperliquid's terms. pathiel does not check where you are; staying within the rules where you live is on you.

Your data

pathiel runs on your computer and the project runs no server, so nothing is sent to the maintainer. No analytics, no telemetry. What does leave your machine:

  • Hyperliquid API (api.hyperliquid.xyz, or the testnet API): market and account reads, the orders you ask for, the API wallet approval you sign.
  • Public data feeds the desk briefs read: EIA, FRED, CFTC, Congress and the Federal Register, prediction markets and news. An optional API key for one of them goes only to that feed.
  • GitHub, only if you join the research pool: the signed statement you submit as a pull request.

Keys, theses, the desk journal and your config stay in ~/.pathiel. Details: docs/PRIVACY.md.

Research pool (opt-in)

pathiel can grade your trades alongside everyone else's. You register your Hyperliquid address with one signed statement; you upload nothing, since pathiel only reads fills Hyperliquid already makes public. From the time you join, your public fills on the pool coins (xyz:BRENTOIL, xyz:CL, xyz:SILVER, xyz:GOLD) are graded with the same harness the project runs on its own trades, and published on a public scoreboard at least 24 hours late.

What you get: your own graded report (fluke or edge on your trades, with ranges, through get_pool_status with report: true), and pool-level stats on which desks and setups hold up across members.

What it is not: not a fee waiver, since pathiel charges no fee to anyone, member or not, and joining never changes what you pay. No payout, refund or reward is ever tied to your returns. Not a copy-trading feed: results are published at least 24 hours late, never live. No edge is demonstrated by joining, or by anything the pool's stats show.

Run /pathiel:share to join or leave. It shows you the exact statement before it signs anything, and the pull request it opens for you.

Scoreboard: https://julian-dev28.github.io/pathiel/scoreboard/

Privacy

What is public: your account address (shortened, with an explorer link), the date you joined, your closed and graded trade counts, your graded row (win rate, mean result in R, a label, a luck score), and pool totals that include your trades. What is never public: anything closed in the last 24 hours, any open position, single trades, prices, sizes, dollar results, account value, leverage, or any key.

Leaving is one more signed statement, or a request in a GitHub issue with no signature. Coming back takes a new signed join; only trades after the new join count, and deleting a leave file never brings an account back on its own.

Full details, including the exact text you sign: docs/PRIVACY.md.

FAQ

How do I connect Claude to Hyperliquid? Install pathiel as a Claude Code plugin with the three lines in Install in 30 seconds. Market data works at once with no key; add an API wallet key to ~/.pathiel/.env.local to trade. Claude Desktop, Cursor and other MCP clients use the launcher or the container described in Other MCP clients. No Anthropic API key is needed: the one model step, the desk thesis behind refresh_desk, runs through your local Claude Code CLI.

Is pathiel a Hyperliquid trading bot? No, and it never trades on its own. It is an MCP server that gives Claude tools: Claude places an order when you ask for one in the session, and Claude Code asks before each live-money call. /loop 15m /pathiel:desk-tick oil re-prompts Claude on a timer, only while that session stays open.

Can it withdraw my money? No. pathiel signs with an API wallet, which Hyperliquid lets trade and never withdraw. Your master key is never stored, and pathiel needs it for nothing: the only script that takes it revokes a builder fee approval, at a hidden prompt in your own terminal.

Does pathiel charge a fee? No. Orders carry no builder fee; you pay Hyperliquid's own trading fee only.

How do I practice without real money? Add PATHIEL_NETWORK=testnet to ~/.pathiel/.env.local, create an API wallet in the testnet app (app.hyperliquid-testnet.xyz), and reconnect pathiel in /mcp. The oil desk trades WTI (xyz:CL) there.

Is there an edge? None is demonstrated. The desk briefs are a structured, written call with levels, not a forecast. get_desk_record grades every call in the open.

How do I remove it? Revoke the API wallet in the Hyperliquid app (More, API), then claude plugin uninstall pathiel@pathiel and delete ~/.pathiel if you want the keys and state gone.

Docs

docfor
docs/GETTING_STARTED.mdaccount setup, permissions, prompts from first read to first trade
docs/BUILDER_FEE.mdthe fee is waived; revoking a 0.4.0 approval; how it works if it returns
docs/strategy/OIL_RULES.mdthe rules every oil bracket must pass, and what is not known
docs/overhaul/MCP.mdall 30 public tools, and the operator's 60
docs/PRIVACY.mdthe research pool: what is public, what is not, how to join, leave and come back
Scoreboardthe research pool's public, graded results
SECURITY.mdwhere keys live, what pathiel never does, how to report a problem
CONTRIBUTING.mddev setup, the test gate, style rules
CHANGELOG.mdwhat changed per version

Maintainer setup

Maintainer path: this runs mainnet with the tracked repo config (20x, whole-equity sizing). It is not the public install.

This is how the maintainer runs pathiel on his own account, from a checkout. It is not the public install and its numbers are not the defaults.

git clone https://github.com/Julian-dev28/pathiel
cd pathiel
cp .env.local.example .env.local
scripts/restart.sh          # FastAPI Desk page on http://localhost:8000/ and the log rotator
scripts/restart.sh status
  • MCP server. The repo .mcp.json starts scripts/pathiel-mcp-server.py directly, with no install marker, so it runs mainnet on the tracked .agent-config.json. Opening a clone in Claude Code offers that server; accepting it is the maintainer path, not the public install. Other clients that want the public path register scripts/pathiel-mcp.
  • Risk profile. The tracked config sets 20x, the whole equity per position less the opening fee, one position. The rules place_bracket enforces (2R minimum, stop inside half the distance to liquidation, one slot) hold on both paths.
  • Desk loop. .claude/skills/desk-tick/SKILL.md on /loop 15m /desk-tick oil. scripts/build_plugin_skill.py generates the plugin copies under skills/ and agents/; the gate fails when a copy is stale.
  • Gate. PATHIEL_STATE_DIR=$(mktemp -d) .venv/bin/python -m pytest -q, offline, run by scripts/hooks/pre-commit (scripts/install_hooks.sh wires it in). scripts/mcp_tool_table.py regenerates the tool table; .venv/bin/python scripts/mcp_smoke.py is a live, read-only MCP smoke.
  • Keys. scripts/preflight_secrets.py checks the env file without printing it; docs/SECRETS.md lists every secret and how to rotate it.

More: CONTRIBUTING.md for the code layout, SECURITY.md for the hardening checks.

License

MIT. See LICENSE.