@trade-mutex/mcp

Trade Mutex with an AI agent. This is a local MCP server for the Mutex Trading API. It has two modes, chosen by the prefix of the key you give it:

| Key | Mode | The agent can | The agent cannot | | --- | --- | --- | --- | | mtx_bot_… | Bot mode | Trade the one account the key trades through /v1: an API bot's sub-account or your vault. Preview, place, modify, cancel; read positions, fills, market data. | Deposit, withdraw, swap, transfer, or touch anything outside that account. | | mtx_agent_… | User mode | Act as you: trade your own perp account (preview, place, modify, cancel, leverage, OCO exits), read your balances, positions, orders and trade history, show your deposit address, withdraw to your own linked wallets, signed by a key that lives only on your machine, and deposit into a vault and withdraw from it: a vault of kind perp takes money from your Perp account or Funding balance and pays it back to the Perp account, one of kind spot takes it from your Funding or Spot balance and pays it back to the Funding balance. | Withdraw anywhere else (the api and the signer both refuse), add / remove / replace a linked wallet (no tool exists and the api refuses agent sessions), or make, change, close or trade a vault (no tool exists; a vault trades in bot mode, with its own key). |

Bot mode is the sanctioned way to try an agent: the bot balance is the whole downside (see Safe start). User mode is for an agent you already trust with your account.

Setup (bot mode)

1. Create a bot and fund it small

In the Mutex web app, create a bot with the AI Agent + API template (no strategy params, you drive it). Fund it and press Execute. 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.

2. Generate its trading key

Open Settings > API. Each API bot that is armed, running or paused has a Bot trading key panel there. Generate the key. It is shown once, so copy it (mtx_bot_…).

A vault of kind perp has a trading key of its own (one of kind spot has none): the lead trader makes it on the vault's Settings tab, and it is listed in Settings > API too. It trades that vault and nothing else, and it ends when the vault closes. Each order on a vault is for its depositors too, and a withdrawal from the vault makes every position and every resting order that is not reduce-only smaller, so an order can change size or order_id by itself.

3. Add the server to your agent

The server runs via npx (Node 20 or newer), 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" }
    }
  }
}

| Env var | Purpose | | --- | --- | | MUTEX_API_KEY | Your mtx_bot_… (bot mode) or mtx_agent_… (user mode) key. Required for everything except public market data. | | MUTEX_API_BASE | Override the base URL. Bot mode defaults to https://trade.mutex.trade (staging https://stage-trade.mutex.money); user mode to https://api.mutex.trade (staging https://stage-money-api.mutex.money). | | MUTEX_SIGNER_KEY_FILE | User mode only: where the local signing key lives. Default ~/.config/mutex/agent-signer.json, created with mode 0600 on first run (Windows does not enforce file modes: the file inherits the folder's permissions, keep them to your own account). |

4. Give the agent the know-how

Paste SYSTEM_PROMPT.md into your agent's system prompt. 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.

Setup (user mode)

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.

1. In the Mutex web app open Settings > Agents, turn Agent access on and generate an agent key (mtx_agent_…, shown once). One key is live per account; to rotate, revoke it first, then generate a new one.
2. Put it in the MCP config above as MUTEX_API_KEY and start the server once. On first run it generates a secp256k1 signing key at MUTEX_SIGNER_KEY_FILE (default ~/.config/mutex/agent-signer.json, mode 0600). The private key never leaves that file and is never printed.
3. Only if the agent should withdraw: ask it for mutex_signer_address and paste the address into Settings > Agents as the Agent signing key, pick how long it stays valid (at most 90 days) and press Authorize. Your linked wallet signs that approval, so have it at hand. Until you do, mutex_withdraw is refused and everything else still works.
4. Paste SYSTEM_PROMPT.md into the agent, as in bot mode.

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 refusal copy is returned to the agent as-is.
• The agent can never add or remove a wallet. Every linked-wallet and delegate route answers 403 to an agent session, and this 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.

The signing key is a file on the machine that runs the server. Treat it like an SSH key: back it up if you want to keep the authorization across machines, delete it (and revoke the address) if the machine is lost. It authorizes, it does not confirm: the server signs whatever payout challenge the api issues for a mutex_withdraw call, with no prompt on your machine. What bounds a withdrawal is the destination (your linked wallets), enforced by the api and the signer, not where the key lives.

Worked example

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, 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 bot in 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: revoke the agent key in Settings > Agents.

Tools

Public market data is available in both modes: get_markets and get_candles. Bot mode reads them from /v1/markets and /v1/candles on the trade host; user mode reads /markets and /candles on the api host (which serves no /v1) and returns the same fields.

Bot mode (mtx_bot_…)

| Tool | Does | | --- | --- | | get_markets | List markets (or one) with fees and limits. | | get_candles | OHLCV history. | | get_account | The account's balance: equity, available, margin, uPnL. | | get_positions | Open positions. | | get_orders | List orders (or fetch one by id). | | get_fills | Fill history. | | preview_order | Pre-trade fill/fee/margin quote, no side effects. | | place_order | Place an order; echoes estimate and resulting state. | | modify_order | Reprice or resize a resting order (a stop or take-profit keeps its trigger); echoes state. | | cancel_order | Cancel one or all; echoes state. | | set_leverage | Set per-symbol leverage. | | create_post | Post on the key owner's profile: title, body, image link, a share card, tagged assets with entry, stop loss and take profit. | | delete_post | Delete one of the owner's posts. |

User mode (mtx_agent_…)

| Tool | Calls | Does | | --- | --- | --- | | mutex_signer_address | local | The signing key's address, for Settings > Agents. Never the private key. | | get_balances | GET /balances | Your ledger accounts; the perp row is read live. | | get_positions | GET /positions | Main perp account: collateral, available, positions, as_of. | | get_orders | GET /orders | Orders, newest first, every status; resting_only: true keeps the live ones. Rows carry symbol. Keyset before. | | get_fills | GET /episodes | Trade history: one row per closed position episode (the api keeps no fill-grained user feed). | | mutex_deposit_address | GET/POST /deposits/address | Your deposit address on ethereum or solana, minted on first ask. | | get_withdrawals | GET /withdrawals | Your withdrawals, newest first: state, amount, destination, client_ref, tx_hash. The agent reads it before retrying a timed-out mutex_withdraw. | | mutex_withdraw | GET /withdrawals, then POST /withdrawals/challenge and POST /withdrawals | Withdraw amount USDC (or swap to asset) to destination, one of your linked wallets. The challenge is requested with signer_network: "ethereum", its typed data is signed locally, verbatim, and the 0x-hex signature rides the withdrawal. client_ref (required, unique per withdrawal) is the idempotency handle: a repeated one returns the existing withdrawal (checked here first, and again by the api), so a retry after a timeout can never pay twice. | | preview_order | POST /orders/preview | Fees, margin and worst-case fill for a market or limit order. Pure read. | | place_order | POST /orders/market, /orders/limit, /orders/stop, /orders/take-profit by type | Place on your main perp account. market and limit take inline take_profit / stop_loss brackets (a trigger price, or { trigger_price, price } for a limit exit); stop_loss[_limit] and take_profit[_limit] are standalone conditionals. Echoes positions + resting orders. | | place_oco | POST /orders/oco | Linked take-profit + stop-loss exit pair on a position (one leg's fill cancels the other), both reduce-only; omit size for the whole position. | | modify_order | POST /orders/:id/modify | Reprice or resize a resting order in place. A stop or take-profit keeps its trigger: its size changes, and a limit variant's limit price. | | cancel_order | POST /orders/:id/cancel | Cancel one order. | | cancel_all | POST /orders/cancel-all | Cancel every resting order, or one market's with symbol. | | set_leverage | POST /positions/:market_index/leverage | Per-market leverage, capped by the market maximum. | | mutex_vault_list | GET /vaults | The listed vaults with their public numbers and your share in each; sort by equity, age, return_30d, max_drawdown or depositors. | | mutex_vault_get | GET /vaults/:id | One vault, its state, and mine, your share in it. | | mutex_vault_mine | GET /vaults/mine | Every vault you lead (closed ones too) and every vault you hold a share in. | | mutex_vault_deposit | POST /vaults/:id/deposit | Deposit amount USDC: into a vault of kind perp from your Perp account, or from Funding with source: funding; into one of kind spot from your Funding balance, or from your Spot balance with source: spot. client_ref (required, unique per deposit) is the idempotency handle: a repeat with the same amount answers the first deposit and moves nothing. | | mutex_vault_withdraw_preview | POST /vaults/:id/withdraw/preview | An estimate of a withdrawal of amount or all: the payout and the profit share. Nothing is stored. | | mutex_vault_withdraw | POST /vaults/:id/withdraw | Withdraw amount or all to your Perp account from a vault of kind perp, to your Funding balance from one of kind spot. It is pending until it is paid and has no cancel. client_ref is required, as on a deposit. | | create_post | POST /posts | Post on your profile, the same post the app writes. | | delete_post | DELETE /posts/:id | Delete one of your posts. |

The trading tools take the same inputs as their bot-mode twins (symbol, coin-unit size, string-or-number decimals). The user routes address a market by market_index, so symbol is resolved through the public GET /markets list; an unknown symbol is refused locally and nothing is sent. Order placement is rate-limited per user (60/min) by the api; a refusal comes back with the api's copy word for word, and a vault refusal with its stable code (no_room, under_minimum, ...) in front of it. There is no separate bot to pause: revoke the agent key in Settings > Agents to stop the agent, and cancel_all still works while trading is halted platform-wide.

Safe start

• 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. With a vault's key the same holds for the vault: it can lose the vault's money, the depositors' share included, and it reaches nothing else. To stop it, delete the vault's key; Mutex can stop the vault's trading too.

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 you linked, and it can never change which wallets those are. The destination is bounded, the value is not: the agent picks the amount and the asset it arrives as, and a swap into a thin token can lose most of the value to slippage on the way to your own wallet. Nothing on your machine asks you before the signing key signs. Keep the signing key's authorization short, and revoke the agent key in Settings > Agents to stop the agent.

The vault tools add one path: a hijacked agent can deposit your money into a vault, where another person trades it. That reaches no further than trading your main account already does, and a vault withdrawal comes back only to your Perp account or your Funding balance. This server has no tool that makes, changes, closes or trades a vault, but the agent key itself can make, change, trade and close your own vault on the api. Two acts cannot be undone and the key can do both: a close, and a lower profit share.