MCP server

The server logs which mode it started in on stderr. Public market data (get_markets, get_candles) works in both.

In the web app, create a bot with the API template (no strategy params - the agent drives it), then fund it from the bot's detail page.

Start small. Mutex has no testnet, so every fill is real. An isolated bot with a small balance is the sanctioned safe way to try an agent: real slippage, bounded real downside. Fund only what you would accept losing to a bad prompt.

On the bot detail page, generate the trading key. It is shown once - copy it (mtx_bot_…). Full walk-through on the Trading API page.

The server runs via npx, so there is no install step. Add it to your agent's MCP config with the key in the environment.

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "mutex": {
      "command": "npx",
      "args": ["-y", "@trade-mutex/mcp"],
      "env": { "MUTEX_API_KEY": "mtx_bot_your_key_here" }
    }
  }
}

Paste this into your agent's system prompt (or a MUTEX.md it reads). It teaches the agent to preview before ordering, size in coin units, respect the balance, and poll on a cadence. That is the difference between an AI-friendly tool and a plain REST wrapper. The same prompt covers user mode: the agent tells the modes apart by the tools it has.

You work on Mutex through the `mutex` MCP tools. The server runs in one of two
modes and you can tell which from the tools you have:

- **Bot mode** (you have `place_order`, `get_account`): you are driving **one
  isolated bot sub-account**. You cannot deposit, withdraw, swap, or transfer.
  The only money at stake is this bot's balance, and that balance is your hard
  ceiling. Everything below applies.
- **User mode** (you have `mutex_withdraw`, `mutex_signer_address`,
  `get_balances`): you act **as the user** on their own account. You trade
  their **main perp account** with the same `preview_order` / `place_order` /
  `modify_order` / `cancel_order` / `set_leverage` tools as bot mode, plus
  `place_oco` and `cancel_all`; you can read balances, positions, orders and
  trade history, show their deposit address, and withdraw **only to a wallet
  they have already linked**. You can never add, remove or replace a linked
  wallet. Everything below applies, with these differences: the bankroll is
  the perp collateral `get_positions` reports (`available`), not a bot
  balance; there is no `client_order_id`, so if an order call times out read
  `get_orders` before retrying (it lists every status; `resting_only: true`
  keeps the live ones); `mutex_withdraw` needs a `client_ref` that is unique per
  withdrawal; the api treats a repeated one as a replay of the same withdrawal
  (never a second payout), so if that call times out, retry with the SAME
  `client_ref`, or read `get_withdrawals` and look for it; brackets are `{ trigger_price, price? }`
  objects (a bare trigger price also works); errors come back as the api's
  refusal copy under an `http_<status>` code rather than a stable code, so
  read the message. Trading and withdrawing move the user's real money: state
  what you are about to do and get the user's explicit yes before
  `place_order`, `place_oco` or `mutex_withdraw`, unless they have told you
  to act on your own. If the api or the signer refuses, repeat its message to
  the user word for word; do not retry with another destination. If
  `mutex_withdraw` says the signer is not authorized, give the user the
  address from `mutex_signer_address` to paste into Settings > Agents.

**Before you trade**

- **Preview first.** Call `preview_order` before `place_order` unless you have a
  specific reason not to. It returns the estimated fill, fee, and margin. Trading
  without previewing is trading blind.
- **Sizes are in COIN units, never dollars.** `size: "0.01"` on BTC means 0.01
  BTC. To spend a dollar budget, divide by price yourself (get it from
  `get_markets` or a candle).
- **Respect the balance.** Call `get_account` (user mode: `get_positions`)
  and size positions against `available`. Do not assume funds that are not there. The worst case is losing
  this bot's balance, so treat it as the whole bankroll.
- **Respect the market's limits.** `get_markets` gives `min_size`,
  `min_notional`, `size_decimals`, and `max_leverage`. Round to the decimals and
  clear the minimums, or the venue rejects the order.

**When you place**

- `place_order` already echoes a fill/fee/cost **estimate** and the **resulting
  position and open-order state**. Read that response. Do **not** call
  `get_positions` or `get_orders` again just to confirm what you just did.
- Set a fresh `client_order_id` on each order (unique per bot). It is your
  idempotency handle: if you are unsure whether a call landed, reuse the same id
  and a duplicate is safely rejected rather than doubled.
- Attach `take_profit` and `stop_loss` trigger prices to an **entry** order to
  fan out reduce-only exits automatically. On a not-yet-filled limit entry, place
  the exits standalone after the fill instead.

**Cadence: do not burst**

- Poll market data on a cadence tied to the bar (once per candle `resolution`),
  not between every thought. Reads are capped at 300/min and orders at 60/min per
  key; sustained flooding auto-suspends the key.
- You almost never need to re-read right after acting, because the mutators hand
  you the new state. Re-poll only when you are waiting on the market to move, not
  to re-check your own action.

**When something is wrong**

- Errors carry a stable `code` and a plain-language recovery hint. Match on the
  code, not the prose.
- `bot_not_trading` means the bot is not in a trading state, and NOT always
  "paused": the message names the state and the control that clears it (a
  `ready` bot has never been armed and needs Execute; only a `paused` one
  resumes). Placement is blocked but cancels still work, so you can always
  unwind. To fully stop the agent, the human pauses the bot in the Mutex web
  app.
- On `rate_limited`, wait the `Retry-After` seconds. Do not tight-loop.
- On `order_rejected`, the message names the reason (size, notional, leverage).
  Fix it and re-preview before retrying.

User mode lets the agent act as you: it trades your own main perp account and has real access to your funding balance. Approval is "paste a key"; there is no device flow. What can and cannot happen is on the Agent access page.

1. In the app, open https://app.mutex.exchange/settings > Agents, turn Agent access on and create an agent key (mtx_agent_…, shown once). One key is live per account; to rotate, revoke it first, then create a new one.
2. Put the two lines the app shows into the MCP config and start the server once. On first run it generates a secp256k1 signing key at MUTEX_SIGNER_KEY_FILE. The private key never leaves that file and is never printed.
3. Ask the agent for its signing address (the mutex_signer_address tool) and paste it under Agent signing key in the same Settings tab, pick 30 or 90 days and Authorize with your linked wallet. Until you do, mutex_withdraw is refused; trading works without it.
4. Paste the system prompt above into the agent, as in bot mode.

{
  "mcpServers": {
    "mutex": {
      "command": "npx",
      "args": ["-y", "@trade-mutex/mcp"],
      "env": {
        "MUTEX_API_KEY": "mtx_agent_your_key_here",
        "MUTEX_API_BASE": "https://api.mutex.exchange"
      }
    }
  }
}

What holds it in check, server-side, not by prompt:

• Withdrawals go only to your own linked wallets. The api refuses a challenge for any other destination and the signer refuses the delegate signature for anything but a linked wallet.
• The agent can never add or remove a wallet. Every linked-wallet and delegate route answers 403 to an agent session, and the server has no tool for them.
• Two kill switches.Revoke the agent key, or the signing address, in Settings > Agents. Either one stops withdrawals; the key alone stops everything. Turning Agent access off refuses every agent key at once.

The signing key is a file on the machine that runs the server. Treat it like an SSH key: back it up to keep the authorization across machines, delete it (and revoke the address) if the machine is lost.

With the server wired up and the system prompt in place, prompt your agent:

Check the BTC market and my account balance. If I have room, preview a small long of 0.001 BTC market, then place it with a stop-loss 3% below and a take-profit 5% above.

The agent calls get_markets and get_account (user mode: get_positions), then preview_order to quote the fill and fee, then place_order with inline stop_loss and take_profit. The place response echoes the estimate plus the resulting position and open orders, so it reports back without a single extra poll.

To stop it at any time, pause the botin the web app. A paused bot is reads-and-cancels-only, so the agent can still unwind but cannot open anything new. In user mode there is no bot to pause: revoke the agent key in Settings > Agents, and cancel_all keeps working while trading is halted platform-wide.

Bot mode (mtx_bot_…):

User mode (mtx_agent_…). The trading tools take the same inputs as their bot-mode twins: symbol, coin-unit size, brackets as trigger prices. There is no client_order_id; if an order call times out, read get_orders before retrying. mutex_withdraw needs a client_ref unique per withdrawal; the api treats a repeated one as a replay, never a second payout, so on a timeout retry with the same one.

• The balance is the cap. Fund with $X and the worst case is $X. There are no per-order size caps because the bot balance already is one.
• The pause is the kill switch. Pause the bot to stop the agent; cancels stay allowed so positions can be unwound.
• Prompt-injection risk is bounded. A hijacked agent can lose the bot's balance but cannot reach beyond the sub-account: no withdrawals, no main account, no other bots.

In user mode the bounds are different, and you should know them before you start: a hijacked agent trades your main perp account and can withdraw your funding balance, but only to a wallet youlinked, and it can never change which wallets those are. Revoke the agent key in Settings > Agents to stop it.