An AI trading agent for Hyperliquid: Claude trades perps from Claude Code, with an exact stop and target on every order.
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.
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.
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@pathielClaude 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.
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.1To 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).
Paste these into Claude Code once /mcp shows pathiel connected.
| you type | what 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 |
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.
| group | tools | names |
|---|---|---|
| Market data (no key) | 5 | get_market, list_markets, get_candles, get_order_book, get_funding_regime |
| Account reads | 4 | get_account, get_positions, get_orders, get_history |
| Risk and sizing | 2 | get_risk_limits, size_trade |
| Orders (live money) | 7 | place_bracket, set_stop (tighter only), set_target, cancel_order, close_position, set_leverage, sweep_brackets |
| Desks | 5 | list_desks, get_desk_brief, refresh_desk, submit_desk_call, get_desk_record |
| Setup | 4 | get_status, get_config, update_config, connect_wallet (approve an API wallet with one signature) |
| Research pool | 3 | get_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.
The mode follows from what is in ~/.pathiel/.env.local:
| you have | mode | what works |
|---|---|---|
| no key | read-only, mainnet (the default) data | every read tool; order tools answer that no key is configured |
| an API wallet key | mainnet (the default) | everything, with real money |
a key and PATHIEL_NETWORK=testnet |
testnet | everything, 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.
- An exact stop on every order.
place_bracketis 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 saysFILLED WITHOUT A STOPandsweep_bracketschecks 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_leveragerefuses above the cap. You change the profile withupdate_configor 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.
- Your main wallet's key never goes in pathiel. It is the one key that can withdraw. A public install refuses to trade with it, and no pathiel process loads it from the env file. On a Mac, keep it in the Keychain (how).
- Testnet when you want it.
PATHIEL_NETWORK=testnetin~/.pathiel/.env.localswitches 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/loopdesk tick trades only while your session runs it.
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.
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.
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.
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.
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.
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/
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.
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.
| doc | for |
|---|---|
| docs/GETTING_STARTED.md | account setup, permissions, prompts from first read to first trade |
| docs/BUILDER_FEE.md | the fee is waived; revoking a 0.4.0 approval; how it works if it returns |
| docs/strategy/OIL_RULES.md | the rules every oil bracket must pass, and what is not known |
| docs/overhaul/MCP.md | all 30 public tools, and the operator's 60 |
| docs/PRIVACY.md | the research pool: what is public, what is not, how to join, leave and come back |
| Scoreboard | the research pool's public, graded results |
| SECURITY.md | where keys live, what pathiel never does, how to report a problem |
| CONTRIBUTING.md | dev setup, the test gate, style rules |
| CHANGELOG.md | what changed per version |
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.jsonstartsscripts/pathiel-mcp-server.pydirectly, 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 registerscripts/pathiel-mcp. - Risk profile. The tracked config sets 20x, the whole equity per
position less the opening fee, one position. The rules
place_bracketenforces (2R minimum, stop inside half the distance to liquidation, one slot) hold on both paths. - Desk loop.
.claude/skills/desk-tick/SKILL.mdon/loop 15m /desk-tick oil.scripts/build_plugin_skill.pygenerates the plugin copies underskills/andagents/; the gate fails when a copy is stale. - Gate.
PATHIEL_STATE_DIR=$(mktemp -d) .venv/bin/python -m pytest -q, offline, run byscripts/hooks/pre-commit(scripts/install_hooks.shwires it in).scripts/mcp_tool_table.pyregenerates the tool table;.venv/bin/python scripts/mcp_smoke.pyis a live, read-only MCP smoke. - Keys.
scripts/preflight_secrets.pychecks the env file without printing it;docs/SECRETS.mdlists every secret and how to rotate it.
HYPERLIQUID_MASTER_PRIVATE_KEY can withdraw, and only treasury.py,
approve_api_wallet.py and approve_builder_fee.py sign with it. Keep it in
the Keychain (built into macOS, free, encrypted at rest), not in .env.local.
One command moves it there. It stores the key, reads it back to check,
and only then deletes the line from .env.local. It never prints the key,
and the key never appears in a process list or your shell history.
.venv/bin/python scripts/master_key_to_keychain.py --dry-run # what it would do
.venv/bin/python scripts/master_key_to_keychain.py # do itUse it for one run. The key reaches that one script and nothing else. The first time, macOS asks to allow access: "Allow" asks every time, "Always Allow" stops asking.
HYPERLIQUID_MASTER_PRIVATE_KEY="$(security find-generic-password -a "$USER" -s pathiel-master-key -w)" \
.venv/bin/python scripts/treasury.pyOr run any of the three without it and paste the key at its hidden prompt.
By hand, without the script:
security add-generic-password -a "$USER" -s pathiel-master-key -w # -w last: prompts, paste twice
security find-generic-password -a "$USER" -s pathiel-master-key # check: details, not the key
# then delete the HYPERLIQUID_MASTER_PRIVATE_KEY= line from .env.local
security delete-generic-password -a "$USER" -s pathiel-master-key # remove, when retiring the walletIt shows in the Keychain Access app, login keychain, as pathiel-master-key.
More: CONTRIBUTING.md for the code layout, SECURITY.md for the hardening checks.
MIT. See LICENSE.