> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carboncopy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket MCP Capabilities Reference

> Canonical reference for public discovery, batched market data, auth wrappers, bridge, transaction building, relayer flows, prompts, and resources.

## Canonical tool surface

This page reflects the current canonical MCP surface asserted by the server smoke test on `main`.

The server is organized around a smaller set of wrapper-style entry points:

* `list_markets` selects listing shape and retrieval mode with `view` and `mode`
* market data is exposed through pluralized batch tools like `get_order_books` and `get_prices`
* auth flows are centered on `ensure_api_key`, `prepare_order`, `place_order`, `cancel_orders`, `get_rewards`, and `get_rewards_market_details`
* transaction building is unified under `build_transactions`
* relayer execution is unified under `relayer_execute`

## 1) Public market discovery

These tools work without credentials.

| Task                | Tools                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| Health check        | `health_check`                                                                                                |
| Market discovery    | `list_markets`, `get_market`                                                                                  |
| Event discovery     | `list_events`, `get_event`, `search`                                                                          |
| Batched market data | `get_order_books`, `get_prices`, `get_midpoints`, `get_spreads`, `get_last_trade_prices`, `get_price_history` |
| Trade-event lookup  | `get_market_trade_events`                                                                                     |
| Market metadata     | `get_fee_rate_bps`, `get_tick_size`, `get_neg_risk`, `calculate_market_price`                                 |

### `list_markets`

`list_markets` is the canonical listing entry point. It accepts:

* `view` to choose payload shape
* `mode` to choose listing mode
* `next_cursor` for pagination

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tool": "list_markets",
  "input": {
    "view": "simplified",
    "mode": "sampling"
  }
}
```

## 2) Batched market data

Use these tools when you already have one or more `token_id` values and want consistent batch responses.

| Tool                    | Purpose                                             |
| ----------------------- | --------------------------------------------------- |
| `get_order_books`       | Level-2 order book snapshots for `items[].token_id` |
| `get_prices`            | Best quotes for `items[].token_id` + `items[].side` |
| `get_midpoints`         | Neutral midpoint values by token                    |
| `get_spreads`           | Bid/ask spread values by token                      |
| `get_last_trade_prices` | Latest trade prices by token                        |
| `get_price_history`     | Historical pricing series for market/token inputs   |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tool": "get_prices",
  "input": {
    "items": [
      { "token_id": "<token_id>", "side": "BUY" },
      { "token_id": "<token_id>", "side": "SELL" }
    ]
  }
}
```

<Note>
  `items[].side` is required for side-aware tools like `get_prices`. Including `side` in other batched calls is still useful for a uniform workflow shape.
</Note>

## 3) Authenticated trading and account wrappers

These tools require configured Polymarket credentials.

| Task                    | Tools                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| L2 key bootstrap        | `ensure_api_key`, `get_api_keys`, `delete_api_key`                                                         |
| Read-only key lifecycle | `create_readonly_api_key`, `get_readonly_api_keys`, `validate_readonly_api_key`, `delete_readonly_api_key` |
| Account inspection      | `get_order`, `get_open_orders`, `get_user_trades`, `get_balance_allowance`                                 |
| Allowance mutation      | `update_balance_allowance`                                                                                 |
| Order preparation       | `prepare_order`                                                                                            |
| Order posting           | `place_order`                                                                                              |
| Order cancellation      | `cancel_orders`                                                                                            |
| Rewards                 | `get_rewards`, `get_rewards_market_details`                                                                |

### `prepare_order`

`prepare_order` prepares or signs an order locally without posting it.

* `kind: "limit"` expects `price` and `size`
* `kind: "market"` expects `amount`

### `place_order`

`place_order` is the canonical order-posting wrapper. It uses `source` to select the posting path:

* `source: "draft"` for create-and-post from a draft order
* `source: "signed"` for posting one pre-signed order
* `source: "signed_batch"` for posting a batch of pre-signed orders

`confirm: true` is required.

### `cancel_orders`

`cancel_orders` is the canonical cancellation wrapper. It uses:

* `mode: "ids"`
* `mode: "all"`
* `mode: "market"`

`confirm: true` is required.

### `get_rewards`

`get_rewards` uses a `scope` selector:

* `day`
* `total_day`
* `current`
* `percentages`
* `user_market_config`

Use `get_rewards_market_details` when you need market-specific reward details for a `condition_id`.

## 4) Bridge and transaction building

### Bridge tools

* `bridge_supported_assets`
* `bridge_create_deposit_addresses`
* `bridge_get_transaction_status`

### `build_transactions`

`build_transactions` is the canonical transaction-builder wrapper. Pass an `items` array where each item declares a `kind` plus its required fields.

Representative `kind` values include:

* `erc20_approval`, `erc1155_approval`, `erc20_transfer`, `eth_transfer`
* `withdraw_on_matic`
* `split_positions`, `merge_positions`, `redeem_positions`
* `buy_market_outcome`, `sell_market_outcome`
* `add_funding`, `remove_funding`
* `neg_risk_convert_positions`, `neg_risk_redeem_positions`
* `proxy_wallet_address`, `index_set`, `market_index`

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tool": "build_transactions",
  "input": {
    "items": [
      {
        "kind": "erc20_transfer",
        "token_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
        "recipient": "0x000000000000000000000000000000000000dEaD",
        "amount": "1000000"
      }
    ]
  }
}
```

## 5) Relayer and builder-relayer

Use these when transaction lifecycle tracking matters.

### Relayer tools

* `relayer_get_relay_address`
* `relayer_get_nonce`
* `relayer_get_relay_payload`
* `relayer_get_transactions`
* `relayer_execute`
* `relayer_deploy_safe`
* `relayer_poll_until_state`

`relayer_execute` is the canonical relayer execution wrapper. It accepts:

* `execution_type: "proxy" | "safe" | "manual"`
* `transactions`
* optional `metadata`
* optional `gas_limit` / `gas_price` for manual mode
* `confirm: true`

### Builder-relayer tools

* `builder_relayer_get_nonce`
* `builder_relayer_get_relay_payload`
* `builder_relayer_get_transactions`
* `builder_relayer_execute`
* `builder_relayer_deploy`
* `builder_relayer_get_deployed`
* `builder_relayer_poll_until_state`

## 6) Prompts and resources

### Prompts

| Prompt                | Purpose                                |
| --------------------- | -------------------------------------- |
| `market-analysis`     | Structured market-analysis workflow    |
| `portfolio-review`    | Portfolio and risk review workflow     |
| `execution-checklist` | Pre-trade execution readiness workflow |

### Resources

| URI                      | Purpose                                           |
| ------------------------ | ------------------------------------------------- |
| `polymarket://contracts` | Canonical Polygon contract registry               |
| `polymarket://status`    | Runtime/auth readiness with redacted secret state |
| `polymarket://endpoints` | Canonical REST endpoint registry                  |

### Resource template

| URI template                         | Purpose                                               |
| ------------------------------------ | ----------------------------------------------------- |
| `polymarket://markets/{conditionId}` | Market payload for a specific Polymarket condition ID |