MCP server

Unhedged,
in your chat

Connect Claude, Codex, or Cursor to Unhedged prediction markets with the Model Context Protocol (MCP). Research markets, track your positions, and trade with scoped API keys.

Create a key

Run this command in your terminal.

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

Replace the key placeholder before connecting.

Full setup instructions

01 / Setup

Connect your client

AI client

Requires Node.js 20+ and npx on the computer running the server. Replace the key placeholder if you have not entered one above.

01

Create an API key

Start with read access. Add trading permissions when you need them.

Research only

  • market:read
  • portfolio:read
  • bet:read
  • order:read
  • balance:read
Create a key

02

Add to Claude Code

Run this command in your terminal.

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

03

Check the connection

Open a new Claude Code session, type /mcp, and look for unhedged.

Check a BTC market in Claude Code

02 / Capabilities

What you can ask

Research

“Which open markets cover the next Counter-Strike major, and what are the implied probabilities?”

search_markets

Portfolio

“Summarise my positions, my available and locked balance, and where my risk is concentrated.”

get_portfolio

Trading

“Buy 50 shares of MLBB finals YES at 62 cents, then show me the fill.”

place_order

Tools behind the answers

37 tools

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.

Combo workflows and permissions

Retail: create a combo, request a quote, inspect it, accept or cancel, then reconcile the fill and positions. Acceptance needs order:place and order:read; cancellation needs order:cancel; positions need portfolio:read. ACCEPTED is not a completed trade. The process tracks pending BUY spend until confirmed execution or non-execution.

Makers need MARKET_MAKER or SUPER_ADMIN, order:read, and order:place. The combo-quoting skill uses await_combo_quote_events and post_combo_quote. Confirmation runs in the process; confirm_combo_quote is only a retry after confirmError within the remaining three-second window. Capped maker quotes require full quantity and reserve the larger cash side. Retail uses the combo-trading skill and REST reconciliation.

Read the combo contract and examples
Explore markets Find live questions, understand the rules, and compare activity. No market scope needed
  • Check combo availability

    Read global combo availability; category and leg eligibility still apply.

    get_combo_config Public endpoint
  • Read a combo

    Read a combo and its selected outcomes.

    get_combo Public endpoint
  • Find group combos

    Page through combos containing a child of a market group.

    list_group_combos Public endpoint
  • Read public book depth

    Snapshot bid/ask levels best price first, with truncation and receipt-time metadata.

    get_order_book Public endpoint
  • Find markets

    Find active and ended markets by asset, sport, topic, or tag. Request resolved markets for history.

    search_markets Public endpoint
  • Read a market

    Check the outcomes, close time, and resolution rule.

    get_market Public endpoint
  • Compare market activity

    See implied probabilities, volume, and bet activity.

    get_market_stats Public endpoint
Understand your account Review your balance, positions, bets, and open orders. Read scopes on your key
  • Read quotes and confirmed fills

    Read quotes, request status, and fill; reconcile pending retail session spend.

    list_combo_quotes order:read
  • Read funded combo positions

    Read gross long/short claims, including zero-net positions; settled claims disappear.

    get_combo_positions portfolio:read
  • Read every active position

    Page through active and ended positions, including fractional contracts.

    list_positions portfolio:read
  • Read settled positions

    Page through resolved or voided positions.

    list_position_history portfolio:read
  • Read executed trades

    Reconcile fills, signed fees, and independently paginated complete-set burns.

    list_trades order:read
  • Recover client order IDs

    Look up retained client IDs for accepted orders, including closed orders.

    list_order_aliases order:read
  • Check your balance

    See spendable and locked USD, plus held CC.

    get_balance balance:read
  • Review your positions

    See position exposure, performance, and recent payouts.

    get_portfolio portfolio:read
  • Review your pool bets

    See your pool bets and whether they are open or settled.

    list_bets bet:read
  • Review open orders

    See open order book orders across your account or one market.

    list_orders order:read
Trade and manage orders Place or replace pool bets and order-book orders, including batch place/replace. Trading scopes on your key
  • Build a combo

    Get or create a definition from 2–32 eligible outcome legs. Creates no trade.

    get_or_create_combo order:place
  • Request a combo quote

    Open a full-quantity BUY or SELL RFQ. SELL requires unreserved long inventory.

    request_combo_quote order:place
  • Cancel an open combo RFQ

    Cancel only OPEN requests. ACCEPTED requests must be reconciled through confirmation or expiry.

    cancel_combo_quote_request order:cancel
  • Accept a combo quote

    Reserve BUY cost and accept. AWAITING_CONFIRMATION and UNKNOWN are not fills; background REST reads reconcile the result.

    accept_combo_quote order:place, order:read
  • Preview execution and fees

    Estimate fills, fees, and execution prices without placing an order.

    quote_order order:read
  • Watch account fills

    Read account events; reconnects and dropped events require reconciliation.

    await_order_events order:read
  • Start disconnect protection

    Start account-wide protection with automatic heartbeats; requires admin enablement.

    start_order_session order:cancel
  • Inspect disconnect protection

    Read this process’s session state and last successful heartbeat.

    get_order_session Public endpoint
  • Stop disconnect protection

    Stop this session; may cancel account-wide orders. New submissions require reconnect.

    stop_order_session order:cancel
  • Place a pool bet

    Commit a USD amount to an outcome in a pool market.

    place_bet bet:place
  • Place an order

    Submit a limit, market, stop loss, or take profit order (optional clientOrderId).

    place_order order:place
  • Batch-place orders

    Place 1–32 non-Market orders on one market in one request (legs may fill; one write rate unit).

    batch_place_orders order:place
  • Cancel orders

    Cancel by orderIds and/or clientOrderIds, or cancel-all when both lists are empty.

    cancel_order order:cancel
  • Replace an open Limit order

    Replace or amend one open Limit order. quantity is a total fill limit; same-price decreases keep id/priority. Send postOnly: true on reductions.

    replace_order order:place, order:cancel
  • Batch-replace open Limit orders

    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.

    batch_replace_orders order:place, order:cancel
Withdraw funds Send CC on Canton or USDC on Ethereum. Separate withdrawal scope
  • Request a withdrawal

    Send funds out as CC on Canton or USDC on Ethereum.

    request_withdrawal balance:withdraw
Market maker terms Check your live fees, rebates, rate limits, and exposure. Market maker role
  • Check market maker terms

    Read your fee tier, rebates, limits, and exposure.

    get_market_maker_profile portfolio:read
  • Await combo RFQ events

    Hold the combo-quotes WebSocket. This process confirms your last-look accepts.

    await_combo_quote_events order:read
  • Post a combo quote

    Post a price (and optional quantity) against an open combo quote request. Reposting replaces this maker's previous OPEN quote.

    post_combo_quote order:place
  • Confirm a combo quote

    Retry confirm only if in-process last-look set confirmError. Accept still has a 3s server window.

    confirm_combo_quote order:place

03 / Permissions

Choose your permissions

Research only

Read markets, positions, and balances.

  • market:read
  • portfolio:read
  • bet:read
  • order:read
  • balance:read

Research and trading

Read your account, place bets and orders, and cancel open orders.

  • market:read
  • portfolio:read
  • bet:read
  • bet:place
  • order:read
  • order:place
  • order:cancel
  • balance:read

Trading and withdrawals

Trade and send funds out of your account.

  • market:read
  • portfolio:read
  • bet:read
  • bet:place
  • order:read
  • order:place
  • order:cancel
  • balance:read
  • balance:withdraw

Cap the session

UNHEDGED_MAX_SPEND_PER_SESSION caps bet stakes, buy orders, retail combo BUY commitments, and maker combo collateral in USD. Confirmed retail non-execution releases reservations; uncertain outcomes retain them. Buy budgets that include fees count in full; other fees and withdrawals are excluded. The cap resets when the MCP server restarts.

Optional environment variables
UNHEDGED_MAX_SPEND_PER_SESSION 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.

04 / Links

Go deeper

Teach it the rules

A guide to sizing, fills, fees, and failed requests.

Open as Markdown