pathiel-agent v2.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/09b4b3e3b88d925c.

---
name: pathiel-agent
description: Use when operating, maintaining, or debugging pathiel — the headless Hyperliquid trading desk Claude trades through its MCP server. Covers place_bracket/bracket_sweep/close_position, the risk-profile sizing path, MCP tool wiring, and Hyperliquid order-placement gotchas.
version: 2.0.0
author: Pathiel Agent
license: MIT
metadata:
  pathiel:
    tags: [trading, hyperliquid, mcp, quant]
    related_skills: [hyperliquid-agent-wallets]
    homepage: https://github.com/Julian-dev28/pathiel
---

# Pathiel Trading Desk

`pathiel` is a **headless Hyperliquid trading desk** (operator decision,
2026-10-23): Claude is the only trader on the wallet, placing every trade
through the **MCP server** (`scripts/pathiel-mcp-server.py`, registered in
`~/.pathiel/config.yaml` under `mcp_servers.pathiel`) — `place_bracket`,
`bracket_sweep`, `close_position`. There is no autonomous scan/research/
execute engine any more: the old scan→research→execute pipeline, its
trigger config, TA filter, risk gates, DSL exit loop, and the seven
strategy books it used to run are all retired. See
`docs/overhaul/HEADLESS_2026-10-23.md` for the wave-1 (strategy-book)
retirement and its wave-2 addendum (the engine itself) for the full history,
and `.claude/skills/oil-tick/SKILL.md` for the 15-minute loop Claude
actually runs today.

Repo: `/Users/julian_dev/Documents/code/pathiel`. The user may work on
dirty local branches and switch deploy branches between sessions. **Commit/push
only when the user asks, and never push directly to another branch without
explicit confirmation.**

## How a trade happens now

1. **Read the call.** `desk_brief {desk}` (oil is primary) for the desk's
   current thesis, or `desk_refresh` to force a new one. `risk_limits` /
   `risk_size_trade` for what the account may trade and how big — size
   every trade with `risk_size_trade`, never by hand.
2. **Place it.** `place_bracket {coin, entry_px, stop_px, tp_px}` — one
   entry with an exact stop and target. It sizes through
   `services/risk/size.py`'s `size_trade()` against the operator's saved
   risk profile, checks the stop against liquidation
   (`pathiel.agents.bracket.check_leverage`), and refuses under the 1.5R
   minimum or when a position/entry already exists on the coin.
3. **Housekeep.** `bracket_sweep {coin}` after every close: cancels the
   stranded sibling order left by a fired stop/target and confirms an open
   position is covered by a stop.
4. **Close.** `close_position {coin}` — market-closes with `reduce_only`,
   cancels the coin's remaining SL/TP bracket, and reports the realized
   PnL. Implemented in `pathiel/agents/bracket.py`'s `close_position()`
   (moved there from the retired `executor.close_position_market`,
   2026-10-23 wave 2).

Full tool list and safety annotations: `docs/overhaul/MCP.md`
(59 tools, generated by `scripts/mcp_tool_table.py` — regenerate it after
any tool change, never hand-edit).

## Running the server

Use `scripts/restart.sh` as the canonical process manager:

```bash
scripts/restart.sh              # restart server + log rotator
scripts/restart.sh server       # restart FastAPI server only
scripts/restart.sh stop         # stop both, don't start
scripts/restart.sh status       # show what's running
```

Logs land in `logs/server.log`. The MCP server
(`scripts/pathiel-mcp-server.py`) is intentionally NOT managed by
restart.sh — it's a transient stdio process respawned by the MCP client
on each tool call. If MCP code is stale: `pkill -f pathiel-mcp-server.py`
and the next tool call respawns it fresh.

Manual foreground launch is only for debugging: `python -m pathiel.server`.

There is no trading loop or scheduler process any more (both retired
2026-10-23, wave 2, with the rest of the autonomous engine) — only the
dashboard/API server and the log rotator run as standing processes.

## Risk sizing

Every trade sizes through `services/risk/size.py`'s `size_trade()`:
`notional = (equity × risk_per_trade_pct) / stop_distance`, clamped by the
operator's saved risk profile (`risk_limits` MCP tool / `/api/risk/*`) and
the coin's exchange max leverage. Leverage is already baked into the
notional — `position_notional = trade_notional`, never
`trade_notional × leverage` again. `pathiel.agents.bracket.min_tradable_equity`
is the structural floor below which the exchange can't clear a $10 order at
all; `services.risk.books.main_engine_spec` is the one `BookSpec` the
feasibility check (`risk_limits`/`risk_size_trade`/`place_bracket`) prices
against — there is no per-book roster any more.

## Asset-class / dex toggles

`.agent-config.json` carries:

- `enable_hip3` (default `true`) — includes HIP-3 perpDexes (xyz / vntl /
  km / ...) in market reads.
- `hip3_dex_allowlist` / `hip3_dex_blocklist` — which HIP-3 dexes
  `get_universe()` fetches at all (a cost control on market/desk reads, not
  a per-trade safety gate — Claude names the coin explicitly on every
  `place_bracket` call, so the discipline that used to be an autonomous
  allowlist refusal is now the oil-tick skill's own scope).
- `coin_allowlist` / `coin_blocklist` — bare-ticker majors restriction
  (`pathiel/agents/universe.py`), matched by bare ticker so one entry
  covers every venue prefix for the same underlying.

2026-10-23 (wave 2) dropped `enable_crypto` and every per-trade sizing/
gating knob the retired autonomous engine read (leverage, equity-fraction,
the confidence/volume/regime gates, `dsl_exit`, `runner_entry_gate`, ...) —
see `pathiel/agents/config_store.py`'s `DEFAULT_CONFIG` for the full list
of what left and why.

## AI Brain Providers

`ai_brain` stays — `services/thesis`'s desk-refresh research and
`services/trend_engine` both call `pathiel.agents.ai_brain.get_brain()`.
Valid providers: `openrouter` (default HTTP), `claude_cli`
(`claude -p --output-format json`), `codex_cli` (`codex exec --sandbox
read-only --ephemeral -`). Selector precedence: `AI_BRAIN_PROVIDER` env
var, then `.agent-config.json` → `ai_brain.provider`, then `openrouter`.

## State Files

Project state (all gitignored):
- `.agent-config.json` — mode (OFF/LIVE), AI brain provider, risk profile,
  HIP-3 dex allow/blocklist, coin allow/blocklist
- `.state/strategies/<desk>/{theses,trades}/` — every desk's thesis and
  trade journal (`services/strategies/journal.py`, `trades.py`) — the
  evidence base under every graded call; back it up (`scripts/
  backup_state.py`) the same way `.agent-memory.json`/`shadow_ledger` used
  to matter.
- `.state/capital_flows.jsonl` — deposits/withdrawals, for flow-neutral
  drawdown.
- `auth.db` — users, sessions, login nonces (`services/auth`).
- `logs/server.log` — the dashboard/API process log.

`.agent-memory.json`, `.dsl-state.json`, `.rebalancer_claims.json` and
`.state/shadow_ledger/` no longer exist — their writers
(`pathiel.agents.memory`, `dsl_exit`, `rebalancer_owned`'s claims registry,
`shadow_ledger`) are all retired.

## Hyperliquid gotchas

See `references/hyperliquid-gotchas.md` for order-placement gotchas
(decimals, tick size, the $10 minimum, client singletons, unified-account
equity). Still fully current — these are exchange facts, not bot-specific.

## MCP Server

`scripts/pathiel-mcp-server.py` (stdio, 59 tools) is registered the same
way it always was — see `references/mcp-config.md` for the config block
and tool-parameter table, `references/mcp-server.md` for server structure,
adding tools, and the audit invariant
(`scripts/audit_mcp_server.py` / `skills/pathiel-agent/scripts/
audit_mcp_server.py` — run before and after editing the server).

## Unified Accounts

On a Hyperliquid unified account the agent wallet signs orders while the
master account holds funds; `resolve_user_address()` picks
`HYPERLIQUID_MASTER_ADDRESS` first, else `HYPERLIQUID_WALLET_ADDRESS`.
Equity reads come from the master. For agent-wallet setup and the
`approveAgent` flow, see the `hyperliquid-agent-wallets` skill.

## HIP-3 Tokenized Equity / Commodity Perps

HIP-3 markets are namespaced as `<dex>:<symbol>` and live on separate
clearinghouses (`xyz`, `km`, `vntl`, `flx`, `hyna`, `abcd`, `cash`, `para`).
`fetch_account_state(..., include_hip3=True)` aggregates equity across
main + every HIP-3 dex. `place_bracket`/`close_position` check the target
dex's own balance before placing — a HIP-3 order on an underfunded dex is
refused, since agent wallets cannot transfer between dexes automatically.

## References

- `references/mcp-config.md` — MCP server config and tool list.
- `references/mcp-server.md` — server structure, adding tools, the audit invariant.
- `references/hyperliquid-gotchas.md` — order-placement gotchas (decimals, tick size, $10 min, singletons).
- `../../docs/overhaul/MCP.md` — the generated 59-tool table with safety annotations.
- `../../docs/overhaul/HEADLESS_2026-10-23.md` — the full headless-desk retirement history (wave 1: the strategy books; wave 2: the autonomous engine itself).
- `../oil-tick/SKILL.md` — the 15-minute loop Claude actually runs to trade the oil desk.