# Unhedged MCP agent guide

You are connected to Unhedged, a prediction-markets platform, through its MCP
server. This file is the contract for how to act on the account you were given.
Read the units and lifecycle sections before placing anything.

Package: `@unhedged/mcp` | API: `https://api.unhedged.gg` | API reference: /docs/api

Combo tools require @unhedged/mcp 0.3.0 or later. The 0.2.0 release has no combo tools. This catalog describes the 0.3.2 source; confirm that version is published before installing it, or build the matching source checkout.

## Connecting

For Claude Desktop, Cursor, Claude Code, or Codex, run
`npx @unhedged/mcp init` to set up the client. The server talks to `https://api.unhedged.gg`.

### Interactive setup

```
npx @unhedged/mcp init
```

### Claude Code

```
claude mcp add unhedged --scope user --transport stdio \
  --env UNHEDGED_API_KEY='ak_your_key_here' \
  -- npx -y @unhedged/mcp
```

### Codex CLI

```
codex mcp add unhedged \
  --env UNHEDGED_API_KEY='ak_your_key_here' \
  -- npx -y @unhedged/mcp
```

### Claude Desktop or Cursor config

```
{
  "mcpServers": {
    "unhedged": {
      "command": "npx",
      "args": [
        "-y",
        "@unhedged/mcp"
      ],
      "env": {
        "UNHEDGED_API_KEY": "ak_your_key_here"
      }
    }
  }
}
```

### Claude Desktop

In the Claude desktop app, open Settings > Developer > Edit Config. Merge the entry below into claude_desktop_config.json, keeping any existing servers.

Node.js 20+ and npx must be available on the computer running the client. Replace the API key placeholder with your Unhedged key.

```json
{
  "mcpServers": {
    "unhedged": {
      "command": "npx",
      "args": ["-y", "@unhedged/mcp"],
      "env": { "UNHEDGED_API_KEY": "ak_your_key_here" }
    }
  }
}
```

Fully quit and reopen Claude Desktop. Check that Unhedged tools appear in a new chat, then try this prompt.

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

[Claude Desktop MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers)

### Cursor

Merge this entry into ~/.cursor/mcp.json in your home directory to make Unhedged available across projects. Keep any existing servers.

Node.js 20+ and npx must be available on the computer running the client. Replace the API key placeholder with your Unhedged key.

```json
{
  "mcpServers": {
    "unhedged": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@unhedged/mcp"],
      "env": { "UNHEDGED_API_KEY": "ak_your_key_here" }
    }
  }
}
```

Enable unhedged in Cursor's MCP settings. Start an Agent chat and try this prompt using Unhedged tools.

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

[Cursor MCP documentation](https://cursor.com/docs/mcp)

### Gemini CLI

Merge this entry into ~/.gemini/settings.json in your home directory. Keep your existing settings and any other entries under mcpServers.

Node.js 20+ and npx must be available on the computer running the client. Replace the API key placeholder with your Unhedged key.

```json
{
  "mcpServers": {
    "unhedged": {
      "command": "npx",
      "args": ["-y", "@unhedged/mcp"],
      "env": { "UNHEDGED_API_KEY": "ak_your_key_here" }
    }
  }
}
```

Run gemini and type /mcp to check that unhedged is connected. Then try this prompt.

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

[Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/)

### GitHub Copilot (VS Code)

Merge this entry into ~/.copilot/mcp-config.json, keeping existing servers. If COPILOT_HOME is set, use that directory instead.

Node.js 20+ and npx must be available on the computer running the client. Replace the API key placeholder with your Unhedged key.

```json
{
  "mcpServers": {
    "unhedged": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@unhedged/mcp"],
      "env": { "UNHEDGED_API_KEY": "ak_your_key_here" }
    }
  }
}
```

Run MCP: List Servers in VS Code and start unhedged. In Copilot Chat, select Agent mode, enable Unhedged tools, and try this prompt.

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

[GitHub Copilot (VS Code) MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

### Grok Bot

Create an Unhedged API key with the Research only scopes below.
Add a custom MCP server in Grok Bot, choose Command, and enter the fields below. Requires Node.js 20+ and npx on the Bot's computer.

```text
Name: unhedged
Server type: Command
Command: npx
Arguments: -y @unhedged/mcp

Environment variable:
UNHEDGED_API_KEY=ak_your_key_here
```

Set UNHEDGED_API_KEY in the server's environment configuration. Keep the key out of the command, arguments, and chat.

In your own Grok Bot chat, ask it to list the Unhedged tools. Then try this research prompt and check that it returns a market, its rules, and its closing time.

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

For Team Bots, Command servers with environment variables work only in the owner's own chat. Shared team access requires a Remote HTTPS MCP server. The Unhedged package currently provides a Command server only.

[Grok Bot MCP documentation](https://docs.x.ai/grok-bot/team-bots#plugins)

## Tools and scopes

Most tools use REST. `get_order_book` reads the public market gateway;
`await_order_events` and `await_combo_quote_events` read authenticated
API WebSocket events. `get_order_session` reads local process state, and
`start_order_session` manages REST heartbeats in the background. A tool only works when the
API key carries its scope, so a failure that looks like a permissions error
usually means the key was minted without that scope.

| Tool | Scope required | Effect | What it does |
| --- | --- | --- | --- |
| `get_combo_config` | none | read-only | Read global combo availability; category and leg eligibility still apply. |
| `get_or_create_combo` | `order:place` | changes trading state | Get or create a definition from 2–32 eligible outcome legs. Creates no trade. |
| `get_combo` | none | read-only | Read a combo and its selected outcomes. |
| `list_group_combos` | none | read-only | Page through combos containing a child of a market group. |
| `request_combo_quote` | `order:place` | changes trading state | Open a full-quantity BUY or SELL RFQ. SELL requires unreserved long inventory. |
| `list_combo_quotes` | `order:read` | read-only | Read quotes, request status, and fill; reconcile pending retail session spend. |
| `cancel_combo_quote_request` | `order:cancel` | changes trading state | Cancel only OPEN requests. ACCEPTED requests must be reconciled through confirmation or expiry. |
| `accept_combo_quote` | `order:place, order:read` | changes trading state | Reserve BUY cost and accept. AWAITING_CONFIRMATION and UNKNOWN are not fills; background REST reads reconcile the result. |
| `get_combo_positions` | `portfolio:read` | read-only | Read gross long/short claims, including zero-net positions; settled claims disappear. |
| `get_order_book` | none | read-only | Snapshot bid/ask levels best price first, with truncation and receipt-time metadata. |
| `quote_order` | `order:read` | read-only | Estimate fills, fees, and execution prices without placing an order. |
| `list_positions` | `portfolio:read` | read-only | Page through active and ended positions, including fractional contracts. |
| `list_position_history` | `portfolio:read` | read-only | Page through resolved or voided positions. |
| `list_trades` | `order:read` | read-only | Reconcile fills, signed fees, and independently paginated complete-set burns. |
| `list_order_aliases` | `order:read` | read-only | Look up retained client IDs for accepted orders, including closed orders. |
| `await_order_events` | `order:read` | read-only | Read account events; reconnects and dropped events require reconciliation. |
| `start_order_session` | `order:cancel` | changes trading state | Start account-wide protection with automatic heartbeats; requires admin enablement. |
| `get_order_session` | none | read-only | Read this process’s session state and last successful heartbeat. |
| `stop_order_session` | `order:cancel` | changes trading state | Stop this session; may cancel account-wide orders. New submissions require reconnect. |
| `search_markets` | none | read-only | Find active and ended markets by asset, sport, topic, or tag. Request resolved markets for history. |
| `get_market` | none | read-only | Check the outcomes, close time, and resolution rule. |
| `get_market_stats` | none | read-only | See implied probabilities, volume, and bet activity. |
| `get_balance` | `balance:read` | read-only | See spendable and locked USD, plus held CC. |
| `get_portfolio` | `portfolio:read` | read-only | See position exposure, performance, and recent payouts. |
| `list_bets` | `bet:read` | read-only | See your pool bets and whether they are open or settled. |
| `place_bet` | `bet:place` | changes trading state | Commit a USD amount to an outcome in a pool market. |
| `list_orders` | `order:read` | read-only | See open order book orders across your account or one market. |
| `place_order` | `order:place` | changes trading state | Submit a limit, market, stop loss, or take profit order (optional clientOrderId). |
| `batch_place_orders` | `order:place` | changes trading state | Place 1–32 non-Market orders on one market in one request (legs may fill; one write rate unit). |
| `cancel_order` | `order:cancel` | changes trading state | Cancel by orderIds and/or clientOrderIds, or cancel-all when both lists are empty. |
| `replace_order` | `order:place, order:cancel` | changes trading state | Replace or amend one open Limit order. quantity is a total fill limit; same-price decreases keep id/priority. Send postOnly: true on reductions. |
| `batch_replace_orders` | `order:place, order:cancel` | changes trading state | Replace or amend 1–32 open Limit orders (quantity is a total fill limit). Commits even if a leg fails; HTTP 400 when any failed. |
| `request_withdrawal` | `balance:withdraw` | changes trading state | Send funds out as CC on Canton or USDC on Ethereum. |
| `get_market_maker_profile` | `portfolio:read` | read-only | Read your fee tier, rebates, limits, and exposure. |
| `await_combo_quote_events` | `order:read` | read-only | Hold the combo-quotes WebSocket. This process confirms your last-look accepts. |
| `post_combo_quote` | `order:place` | changes trading state | Post a price (and optional quantity) against an open combo quote request. Reposting replaces this maker's previous OPEN quote. |
| `confirm_combo_quote` | `order:place` | changes trading state | Retry confirm only if in-process last-look set confirmError. Accept still has a 3s server window. |

## Retail combo workflow

Combo tools require the version described above. Use `get_combo_config`, then
`get_or_create_combo` with one outcome per eligible market (2–32 legs, at most
one child per event). Public `get_combo` and `list_group_combos` inspect definitions.
Category policy and the global flag must allow the trade. The backend rechecks
eligibility at every trading step. Decimal strings support up to 10 places.

1. `request_combo_quote` with comboId, BUY/SELL, and full quantity. Save request.id.
   SELL requires unreserved gross longs; it cannot open a short. Creation requires
   order:place. A new call creates a new RFQ; do not retry ambiguous creations blindly.
2. `list_combo_quotes` with requestId (order:read). Read quote prices and expiry.
3. After user authorization, `accept_combo_quote` with requestId and quoteId
   (order:place plus order:read), or `cancel_combo_quote_request` while OPEN
   (order:cancel). Acceptance reserves server-verified BUY cost before POST.
4. `list_combo_quotes` until state is FILLED with fill, EXPIRED, or CANCELLED.
   AWAITING_CONFIRMATION and UNKNOWN are never a completed trade. Accepted requests
   cannot be cancelled. Confirmed fills may have an empty quotes array.
5. `get_combo_positions` (portfolio:read) shows funded claims. Gross longShares
   and shortShares matter even when net shares are zero; settled claims disappear.

Requests last at most 60s, quotes 30s, and maker confirmation 3s, all capped at the
earliest leg cutoff. The retail process polls pending outcomes in the background.
It retains spend on ambiguous HTTP errors or OPEN reads after an uncertain accept,
commits once on a fill, and releases only on confirmed non-execution. SELL proceeds
never replenish the cap. State and cap reset on process restart; reconcile saved
request IDs before trading again. Retail uses REST and needs no maker feed.

Example tool sequence (IDs are illustrative):

```json
{"tool":"get_or_create_combo","arguments":{"legs":[{"marketId":"market_a","outcomeIndex":0},{"marketId":"market_b","outcomeIndex":1}]}}
{"tool":"request_combo_quote","arguments":{"comboId":"combo_1","side":"BUY","quantity":"10"}}
{"tool":"list_combo_quotes","arguments":{"requestId":"request_1"}}
{"tool":"accept_combo_quote","arguments":{"requestId":"request_1","quoteId":"quote_1"}}
{"tool":"list_combo_quotes","arguments":{"requestId":"request_1"}}
{"tool":"get_combo_positions","arguments":{}}
```

## Maker combo workflow

Requires MARKET_MAKER or SUPER_ADMIN, order:read for the authenticated socket,
and order:place for posting/confirmation. `await_combo_quote_events` subscribes
to the shared maker feed (up to 100 OPEN RFQs replayed, no accepted replay).
`post_combo_quote` quotes the full request quantity; a new quote replaces this
maker's OPEN quote. Under a session cap, supply quantity explicitly: the process
reserves the larger of buyer cash and seller mint collateral. Confirm attempts
commit that maker reservation for the rest of the session, even on uncertainty.

On private `combo_quote_accepted`, the **process** immediately confirms; the
model must not race the 3-second window. `confirm_combo_quote` is only a retry
after `confirmError`, while the window remains. Independent accepts confirm
concurrently. A reconnect does not replay pending confirmations. Quoting hides
requester identity; counterparties appear on the confirmed fill. For minting,
buyer cash plus seller collateral equals $1 per share. Settlement pays longs
the product of resolved/void leg values and shorts the remainder; voids do not
necessarily refund the original price. See /docs/api#combo-lifecycle for exact rules.

## Units and money

- **USD amounts.** Bets are denominated in USD. The platform balance is a USD
  figure with a CC reference for display and delivery.
- **Share quantities.** Order-book orders are sized in contracts, passed as
  `quantity` with exactly two decimal places (minimum `"0.01"`), or in USD
  notional, passed as `quoteQuantity` with exactly two decimal places.
  Fractional contracts are supported. Pass exactly one of the two, never both.
- **Order prices.** `price` is a decimal string with exactly two decimal
  places, strictly between 0 and 1 for Limit orders. Market orders accept an optional
  execution bound in [0,1]: maximum buy price or minimum sell price. It is a
  probability, not a percentage:
  `0.62`, not `62`. Stop and take-profit orders use the same bounds for
  `triggerPrice`.
- **Outcome labels.** Pass the label exactly as returned by
  `get_market`, for example `YES` or `"$95k - $100k"`. Approximate
  labels are rejected.
- **Balances.** `get_balance` reports available and locked amounts.
  Locked funds are already committed to open orders; available funds are what a
  new order can still use.
- **Fees are risk-shaped and assessed per fill.** Order-book fees apply when
  shares trade, not when an order is accepted. One fill costs
  `shares_filled x execution_price x (1 - execution_price) x rate`. The
  `price x (1 - price)` term is what makes the fee risk-shaped: it peaks at
  0.50 and shrinks toward zero as the price approaches 0 or 1, so the rate is
  never a flat percentage of trade value.
- **A multi-fill order pays this per fill**, each at that fill's own execution
  price. Never compute a single fee from the order's limit price and present it
  as the cost — report fees from the fills that actually happened.
- **Rebates and locks differ.** A negative rate is a rebate that lowers what the
  fill costs. It does not lower the balance locked when a bid is placed: the
  placement lock never goes below zero. A resting order also keeps the maker
  rate it was placed with, even if the tier changes later.
- **Direction of the fee.** Buying costs the share value plus the fee. Selling
  returns the share value minus the fee. Read the live schedule at /fees
  or, for market makers, from `get_market_maker_profile`.

## Bets and orders are different markets

- **Parimutuel bets** (`place_bet`) contribute to a pool. Your payout
  depends on the final split of that pool, so the return is not fixed at the
  moment you bet.
- **Order-book orders** (`place_order` / `batch_place_orders`) trade at a price against
  resting orders. Use them only on order-book markets; parimutuel markets have
  no order book and `list_orders` returns nothing for them.

Do not describe a parimutuel bet as a fill at a price, and do not describe an
order-book order as a pool contribution.

## Accepted is not executed

Placing an order returns an order record with an engine-assigned ID, a status,
and any fills that happened immediately. An accepted order is not a completed
trade.

- A **market order** usually fills immediately, possibly across several resting
  orders.
- A **limit order** may rest on the book unfilled, fill later, fill in several
  pieces, or never fill.
- A **partial fill** means only part of the quantity traded. Only the filled
  part changes your balance and positions; the remainder is still working.
- **Cancelling** stops the unfilled remainder. It does not reverse fills that
  already happened, and it does not return funds already spent on those fills.

Never tell the user a position was opened, closed, or hedged until you have read
the resulting positions or fills back.

## Execution previews and live events

Use `get_order_book` for public depth and `quote_order` for estimated fills
and account-specific fees. Neither reserves liquidity. Receipt timestamps do
not establish source freshness. Submit the same price bound with the order.
For Market/Limit bids with `quoteQuantity`, `budgetIncludesFees: true`
enforces an all-in budget at execution, including actual fees and resting fee
reserve. `postOnly: true` rejects taking liquidity; set it on each Limit
placement or replacement because it is not inherited.

Call `await_order_events` before trading to establish the account feed. On
`reconciliationRequired`, reconnect, or overflow, refresh orders, positions,
fills/burns, and balance. This feed has no replay and is not complete history. Reconcile periodically even
without a gap flag; only locally detected gaps are flagged.
Fill identity is market_id + trade_id + order_id. Portfolio pages may be cached
and change during pagination; reconcile again after concurrent trading.

## Permissions and limits

You have exactly the authority of the API key you were started with. There is
no separate agent permission system.

| Key profile | Scopes to grant |
| --- | --- |
| Research only | `market:read`, `portfolio:read`, `bet:read`, `order:read`, `balance:read` |
| Research and trading | `market:read`, `portfolio:read`, `bet:read`, `bet:place`, `order:read`, `order:place`, `order:cancel`, `balance:read` |
| Trading and withdrawals | `market:read`, `portfolio:read`, `bet:read`, `bet:place`, `order:read`, `order:place`, `order:cancel`, `balance:read`, `balance:withdraw` |

Users set your trading authority by minting a key with a narrower scope set and
by adding limits in the server environment:

| Variable | Requirement | Meaning |
| --- | --- | --- |
| `UNHEDGED_API_KEY` | required | Bearer token in the form ak_... . The scopes on the key decide which tools work. |
| `UNHEDGED_MAX_SPEND_PER_SESSION` | optional | Caps bet stakes, buy placements, and incremental bid replace notional (above remaining open lock) in USD. Counts full fee-inclusive buy budgets, pending/filled retail combo BUY cost, and worst-side maker combo collateral. Retail non-execution releases reservations; ambiguous outcomes retain them. Other fees and withdrawals are excluded. Resets on restart. Default: `unset`. |

## Withdrawals are separate

Permission to trade never implies permission to withdraw. `balance:withdraw`
is off unless it was explicitly granted, and it lets you move funds off the
platform to a destination you supply. Ethereum withdrawals also need
`balance:read`, because the fee quote is a separate authenticated request.

If a user asks you to withdraw and the tool returns a permissions error, stop
and explain which scope is missing. Do not attempt workarounds.

## Spend cap

`UNHEDGED_MAX_SPEND_PER_SESSION` caps cumulative bet stakes and buy-order
notional in USD. Fees and withdrawals are normally excluded. For a buy using
`budgetIncludesFees`, the full supplied all-in budget is conservatively
reserved against the session cap.

- The cap lives in the server process and **resets when the process restarts**.
  It is a session rail, not an account limit.
- It is additive to whatever the platform enforces; it does not replace balance
  or risk limits.
- When the backend definitively rejects a call with a 4xx response, the
  reservation is released. Ambiguous failures keep it reserved, which can make
  the cap stricter than the money actually spent. Soft no-spend outcomes
  (`{ err }`, unchanged replace — single or batch — and zero-fill
  `InternalCancel`) also release that reservation.
- If the notional cannot be estimated locally, the tool refuses the order rather
  than guessing. Supplying `quoteQuantity`, or a limit order with an explicit
  price and quantity, keeps the order inside the cap.
- Replacements consult the open source order first. Ask replacements do not
  count; bid replacements reserve only the incremental estimated notional
  above the source's **remaining** lock (original size minus fills). If the
  source side or exposure cannot be determined, replace tools refuse.

## Client order IDs

Optional tags for open order-book orders. Requests use `clientOrderId` /
`clientOrderIds`; order objects expose `client_order_id`.

| Rule | Detail |
| --- | --- |
| Validation | Optional on place. 1–64 characters from `[A-Za-z0-9._:-]`. Case is preserved. Absent is fine; invalid values are rejected. |
| Scope | Unique among **open** orders per balance and market. Shared across outcomes and every API key on that balance — not a per-strategy namespace. |
| Lifetime | After an order closes, the same string may name a later open order. That does **not** make placement retries safe. |
| Cancel | `orderIds` and `clientOrderIds` are a union. Both empty = cancel-all on that market. Numeric ids and client ids are best-effort (continue after soft failures such as unresolved client ids; partial success returns `dropped` + `err`). |
| Replace | Exactly one of `orderId` / `clientOrderId` per leg. Omit `replacementClientOrderId` to inherit. A client-id-only change to an unoccupied alias returns unchanged and keeps the old alias; a colliding alias is rejected. Use `batch_replace_orders` (or `POST /orders/replace/batch`) for multi-leg refreshes — the transaction commits even if a leg fails; HTTP 400 when any leg failed. |
| List recovery | `list_orders` without `marketId`, follow every `nextCursor` (default 100, max 500). Pending conditionals are included while open. |
| Terminal fills | Trade history has numeric order ids only. Missing from open orders does **not** prove a timed-out place never executed. |

**Unsafe replay example:** you place 2 contracts with `clientOrderId: "intent-1"`.
The request times out, but the order already filled. Placing again with the same
id can buy 2 more contracts. Treat a timeout as unknown: recover open orders and
fills before submitting anything new.

## Bot restart recovery

1. Before each mutation, persist the payload, client id, and any local operation
   key in durable storage.
2. After a crash, authenticate and pause new trading while recovering.
3. Page `list_orders` account-wide until `nextCursor` is null. Recover both
   numeric `id` and `client_order_id`, including pending conditionals.
4. Page `list_positions` for complete active inventory; read `get_balance`.
   Use `list_trades` for fills and burns and `list_order_aliases` for retained
   client IDs. Join aliases by market_id + order_id, observing retention and
   coverage limits. Use `list_position_history` for settled positions.
5. Leave unresolved submissions as unknown. Do not mint a fresh client id and
   place again solely because the first acknowledgement was lost.
6. Resume only when you can explain every open order and your exposure. Other
   strategies on the same balance share the client-id namespace — do not cancel
   every listed order as if it belonged to one bot.

## Cancel-on-disconnect (API-key bots)

`start_order_session` explicitly starts account-wide protection and sends
heartbeats every 30 seconds. Use `get_order_session` for local status and
`stop_order_session` for cleanup. New submissions pause while a heartbeat is
overdue or awaiting acknowledgment (`heartbeating`), including after process
suspension. Heartbeat failures halt automatic heartbeats
and block new MCP order submissions until cleanup and a successful
`start_order_session`. After a managed session stops, placements and
replacements remain blocked until `start_order_session` successfully reconnects.
Cancellation can still be pending after disconnect succeeds; waiting out the
grace period does not unblock submissions. Protection follows the MCP process,
not model activity; it is not a per-strategy kill switch.

Stopping or closing MCP blocks new submissions immediately, keeps healthy
heartbeats running while pending order mutations finish, and then disconnects.
`get_order_session` includes `pendingSubmissions`. Ambiguous order outcomes
block further trading. If a pending order times out during cleanup, or MCP closes
after an earlier ambiguous submission, heartbeats stop and disconnect is deferred
to server-side expiry. Reconcile orders/fills before calling
`stop_order_session` again; expiry alone does not prove cancellation.

| Condition | Behaviour |
| --- | --- |
| Enablement | Admin flag on the user plus API-key session registration. |
| Heartbeats | Default TTL 90s; send a heartbeat about every 30s. A 10s sweeper and 5s grace affect timing. |
| Multiple sessions | Cancel starts only after the last session for that balance ends; another live session keeps orders open. |
| Scope | Cancels that balance's open orders across active markets, not only one strategy's ids. |
| Engine restart | In-memory sessions disappear; resting orders remain. Reconnect. |
| Reconnection | Can stop pending dispatch but cannot retract cancellations already sent to the engine. |

## After an ambiguous failure

MCP mutations are never retried automatically. The server generates a fresh
idempotency key (the `Idempotency-Key` header) for each call, so calling a
tool again creates a **new request**, not a replay of the original. The API can
replay a completed successful response for the same key for up to 60 seconds on
`POST`, `PUT`, and `PATCH` requests. It does not reserve a key while the
first request is in flight, so simultaneous requests may both execute. The
cache does not cover `DELETE` requests such as `cancel_order`.

When a call fails with a timeout, a network error, or a 5xx response, the
outcome is unknown. Before submitting anything again:

1. Check `list_bets` for bets and `list_orders` for open orders (follow every
   `nextCursor`). A filled order will not appear in the open-order list. The
   portfolio is a bounded preview, and a balance alone cannot identify a
   transaction. Reusing a closed `clientOrderId` is not proof the first place
   failed.
2. For fills, page `list_trades` and `list_order_aliases`; join by market_id
   + order_id. Trade and burn cursors are independent: continue each non-null
   cursor, omit the exhausted stream, and stop when both are exhausted.
   Withdrawal history still requires the account transaction history on Unhedged.
3. Report what you found. If the outcome remains uncertain, stop and ask the
   user; an empty list is not proof that the operation failed.

## Secrets

The API key belongs in the client's server configuration, never in a prompt,
chat message, screenshot, recording, or shared config example. If you are asked
to repeat a key back, refuse and point the user at /account/api-keys. Use
`ak_your_key_here` in any example you write.

## Example prompts

Research:

> Find an active BTC Up or Down market using Unhedged MCP. What makes Up win, and when does it close?

> Which open markets cover the next Counter-Strike major, and what are the
> current implied probabilities for each outcome?

Portfolio review:

> Summarise my Unhedged positions, my available and locked balance, and which
> markets carry the most concentration risk.

Order management:

> Show my open orders, cancel everything resting more than 10% away from the
> current price on the MLBB market, and report the balance change afterwards.

## Skills

The server ships markdown workflows as MCP prompts. Clients that expose prompts
surface them as slash commands.

- `combo-trading` — Build a retail combo, request quotes, accept or cancel, and reconcile confirmed fills and session spend.
- `market-research` — Find markets for a topic and summarise odds, volume, and resolution rules. Read-only.
- `place-hedged-position` — Size and place a hedged position across multiple outcomes within a budget, confirming before it commits.
- `portfolio-review` — Read-only summary of holdings, profit and loss, win rate, and concentration.
- `cash-out` — Close open orders, sell order-book positions at market, and prepare a withdrawal.
- `market-maker-workflow` — Quote both sides of an order book around a chosen fair value and refresh as the market moves.
- `market-creator-assistant` — Draft a market with outcomes, resolution rules, and metadata, then guide submission.
- `combo-quoting` — Quote cross-event combos as an authorized market maker while respecting collateral and session spend limits.
