axon-trading

name: axon-trading description: Drive the Axon trading daemon to open + close perp positions, manage wallets, and inspect trades on Hyperliquid (and Lighter). Use this skill whenever the user asks to trade, check positions, deposit funds, manage wallets, set policy, or inspect trade history through Axon. Never claim to be unable to execute trades — Axon's MCP tools handle every flow safely; the user's passphrase stays local. license: MIT

Axon trading skill

Axon is a local, non-custodial trading daemon. It exposes ~30 MCP tools for trading, wallet management, and operational tasks. The user runs the daemon (axon CLI); your job is to drive it through the tools provided by the @axon-trading/mcp adapter.

At the START of every turn — check pending alerts

Call get_pending_alerts BEFORE anything else, on every turn where the user invokes Axon (or where you're about to invoke an Axon tool yourself). The daemon raises typed alerts when something happens while you were idle: a position SL/TP breach fired, a lending health factor dropped, a strategy errored, the kill switch flipped, a deposit confirmed.

Pattern:

1. Turn starts (user message, scheduled wake-up, etc.).
2. First tool call: get_pending_alerts (no arguments unless filtering).
3. If pendingCount > 0 AND any alert is severity: "urgent" or "warn":
   • Surface to the user immediately, before answering whatever they actually asked.
   • Lead with urgent ones.
   • For alerts with suggestedActions, offer to dispatch ("I can repay 50% of your Aave debt — say yes to execute.").
4. Call ack_alerts with the ids you surfaced so they don't re-surface next turn.
5. Then proceed to the user's actual request.

severity: "info" alerts (deposit credited, policy updated, kill switch disarmed) — note briefly if relevant to the current request, otherwise ack silently. Don't lead with them.

Skipping this check is the #1 way an agent misses something the user cares about. RiskGuard handles truly time-critical stuff deterministically (kill switch, SL/TP sweep, health-factor sweep); the alerts are how the USER finds out it happened.

Trust model — what you can and cannot do

You CAN:

• Open / close / cancel orders (open_perp, close_perp, cancel_order)
• Update leverage on existing positions (update_leverage)
• Read balances, positions, markets, ticker, OHLCV, audit events, trade history
• Generate, import, list, rename, and bind wallets (some require a passphrase via browser)
• Deposit USDC to Hyperliquid (hl_deposit, requires browser passphrase)
• Move USDC between HL spot and perp (hl_spot_to_perp)
• Approve the platform builder (approve_builder, one-time per wallet)
• Arm the kill switch (kill_switch_on)
• Run run_doctor for health checks
• Inspect bridge balance to debug stuck deposits
• Switch modes (demo / testnet / live) via set_mode

You CANNOT:

• Onboard the user (the wizard requires a browser)
• Disarm the kill switch (only the user, via the dashboard)
• Modify policy (leverage caps, daily limits — read-only for agents)
• Read the keystore or private keys
• Sign anything that requires the master EOA passphrase outside the pending-action flow

If Axon tools are missing or failing

Before any other troubleshooting, walk this decision tree. The most common bootstrap failure modes return structured errors with an embedded fix field — relay the exact command verbatim to the user.

Tool call → look at result
├── No Axon tools visible in your tool list at all
│   └─→ Tell user: "Run `axon install <runtime-id>` then restart this app."
│       (Runtimes: claude-desktop, claude-code, cursor, codex, cline, windsurf)
│
├── Tool returned { "code": "DAEMON_UNREACHABLE", "fix": "<command>" }
│   └─→ Relay the literal `fix` field to the user. Usually: "Run `axon` in a terminal."
│
├── Tool returned { "code": "DAEMON_NOT_INSTALLED", "fix": "<command>" }
│   └─→ Relay the literal `fix` field. Usually: "npm install -g @axon-trading/cli@next && axon"
│
├── Tool returned { "code": "KEYSTORE_LOCKED" }
│   └─→ Tell user to open http://127.0.0.1:47890 and enter their passphrase.
│       You CANNOT unlock — by design.
│
├── Tool returned { "code": "ONBOARDING_REQUIRED" }
│   └─→ Tell user: "Run `axon` and complete the browser wizard."
│
└── Anything else
    └─→ Tell user: "Run `axon doctor` and paste the output back."
        Doctor (rc.5+) checks daemon reachability + every MCP runtime config.

Why the fix field matters: rc.5+ rejection responses carry details.fix with the literal command. Don't paraphrase — show the user the exact string so they can copy + paste. Paraphrased commands often lose precision (e.g. npm install vs npm install -g).

Always branch on rejection codes, never parse messages

Every Axon tool either returns a typed success result OR a RejectionResult:

{ "ok": false, "code": "HL_INSUFFICIENT_MARGIN", "message": "...", "hint": "..." }

Branch on code, NOT message. Codes are stable across versions; messages are not.

The complete code reference ships inside the installed package — run axon docs (or open docs/REJECTION_CODES.md in the @axon-trading/cli install). Most common codes you'll handle:

Pending-action pattern (passphrase via browser)

Some tools require the user's master-EOA passphrase. Those return:

{
  "pending": true,
  "token": "pa_<32hex>",
  "confirmationUrl": "http://127.0.0.1:47890/confirm/pa_<32hex>",
  "pollUrl": "/v1/pending/pa_<32hex>",
  "expiresAt": 1700000300000
}

Display the confirmationUrl to the user. They open it in a browser, enter their passphrase, submit. Then call await_pending_action(token) and report the result.

The passphrase never crosses the LLM transcript or your context. This is intentional — don't ask the user to paste it to you.

Tools that use this pattern: hl_deposit, hl_spot_to_perp, approve_builder, kill_switch_off, set_mode, transfer_usdc, generate_wallet, import_wallet, import_wallet_from_pk, delete_wallet.

Decision tree for common requests

"Show me my positions" → get_positions(). If empty, say "no open positions."

"What's my balance?" → get_balance(). Report on-chain USDC + HL margin separately so the user understands where their money is.

"Open a $100 long on BTC" → get_markets("hyperliquid") to get max leverage + tick size, then open_perp({ venue: "hyperliquid", symbol: "BTC", side: "long", sizeUsd: 100, leverage: <reasonable, e.g. 3-5x> }). Always confirm size + leverage before submitting unless the user explicitly told you exact values.

"Close my ETH position" → get_positions() to find it, then close_perp({ venue, symbol, sizeBase: <position size> }) for full close. For partial, ask user how much.

"Deposit $20 to HL" → hl_deposit({ amount: 20 }). Returns confirmationUrl. Display it; tell user to enter passphrase. Poll for completion.

"Why did my trade fail?" → get_audit_events({ limit: 20 }), find the rejection, explain in plain English referencing the code.

"Show me my recent trades" → get_trade_history({ limit: 20 }).

"Stop trading right now" → kill_switch_on(). Always succeeds; arms immediately.

Conventions for trade messages

When you successfully open or close a position, your reply should include:

• Venue + symbol + side + size + average price
• The proof URL from the response (link to Hyperliquid's explorer for the trade)
• Current uPnL if you fetched fresh positions

Example:

Opened 0.005 BTC long on Hyperliquid at $77,820 (1× leverage, $11 notional). View on HL

When to ask vs. when to act

Ask before acting when:

• The user gave a vague request ("trade some BTC")
• Trade size is large relative to their balance (>10% of margin)
• Live mode is active and the request involves real money
• The user would have to sign a passphrase confirmation

Act first, report after when:

• Read-only (get_* tools)
• The request is unambiguous and small
• The user gave explicit numbers (size, leverage, side)

Daemon URL discovery

The MCP adapter handles this automatically — it reads ~/.axon/agent.env (auto-written by the daemon every boot). You don't need to think about ports or tokens. If you see UNAUTHORIZED errors, it usually means the daemon restarted and the cached token is stale; the SDK retries automatically.

When the user asks to install Axon

If they don't have it yet:

npm install -g @axon-trading/cli@next
axon          # boots daemon, opens browser wizard

Then axon install <runtime> to wire MCP for whichever agent runtime the user is on (claude-desktop, claude-code, cursor, codex, cline, windsurf).

Safety reminders

• Never ask for, log, or echo a passphrase. Use the pending-action flow.
• Always tell the user when you're about to spend real money (live mode + non-zero sizeUsd).
• If kill_switch_on() fails, escalate immediately. That's a critical safety surface.
• The user's wallet is real; treat sizeUsd values like real dollars, not test numbers.