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

# MCP Server

> Connect AI assistants to Limitless for market discovery, portfolio reads, and browser-approved trading via the remote MCP server

Limitless runs a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI assistants direct, tool-based access to the exchange. An assistant connected to the server can browse and search markets, read orderbooks, check your balance and positions, and propose orders. **You approve every order proposal in your browser** before anything is submitted.

**Server URL:**

```
https://api.limitless.exchange/mcp
```

The server uses the Streamable HTTP transport with plain JSON responses and OAuth 2.1 authorization.

<Note>
  This is the **trading** MCP server. It is separate from the docs MCP server at `https://docs.limitless.exchange/mcp`, which only exposes this documentation as searchable context. Connect both if you want an assistant that can look up API docs and act on the exchange.
</Note>

## How authorization works

The server implements OAuth 2.1 with the standard discovery flow, so any MCP client with remote server support can connect without pre-registered credentials:

1. The client discovers the OAuth endpoints from `https://api.limitless.exchange/.well-known/oauth-protected-resource`.
2. The client registers itself automatically via dynamic client registration. The server accepts only public clients with PKCE (`S256`).
3. Your browser opens a Limitless consent page. Log in with your Limitless account and approve the connection.
4. The client exchanges the authorization code for an access token with the `trading` scope. That is the only scope the server issues.

Access tokens expire after one hour. Clients refresh them automatically; refresh tokens are single-use and rotated on every refresh.

Tokens are scoped to your selected Limitless Wallet. Every tool response that touches funds includes a `walletContext` object identifying that wallet. This keeps the assistant from confusing it with your login or embedded wallet.

## Connect an assistant

Any MCP client that supports remote servers with OAuth works. For example, with Claude Code:

```bash theme={null}
claude mcp add --transport http limitless https://api.limitless.exchange/mcp
```

Or in a JSON-based MCP client configuration:

```json theme={null}
{
  "mcpServers": {
    "limitless": {
      "url": "https://api.limitless.exchange/mcp"
    }
  }
}
```

On first use, the client walks you through the browser login and consent flow described above.

## Available tools

### Market discovery

These tools work for any authenticated connection:

| Tool                     | What it does                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_market_categories` | Lists the same market categories used by Limitless navigation. Returns category paths for use with `list_markets`.                                                  |
| `list_markets`           | Lists active markets, paginated. Accepts an optional `categoryPath` (from `list_market_categories`) and a `categoryFilter` for narrower browsing within a category. |
| `search_markets`         | Semantic search over markets.                                                                                                                                       |
| `get_market`             | One market by slug: title, status, deadline, YES/NO position ids, and trading rules.                                                                                |
| `get_market_group`       | A market group by slug with its visible child markets. Orders must target a child market slug, never the group slug.                                                |
| `get_orderbook`          | Point-in-time orderbook snapshot: best bid, best ask, spread, last trade price, and liquidity-reward settings.                                                      |

To browse by category, the assistant first calls `list_market_categories`, then passes a returned path (for example `/sport`) as `categoryPath` to `list_markets`. Category responses include `categoryFilters` (filter groups with option values) that can be passed back as `categoryFilter` to narrow results further.

### Portfolio reads

| Tool                 | What it does                                                                                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_wallet_balance` | USDC balance of your selected Limitless Wallet, the collateral committed to open BUY orders, and the amount available for new BUY orders.                  |
| `get_positions`      | Cached position snapshot across wallets linked to your account. `marketValue` and `unrealizedPnl` use reference prices and are not live executable quotes. |
| `get_open_orders`    | Your open (LIVE) orders across all markets, cursor-paginated, with the `makerAddress` that placed each order.                                              |
| `get_trade_history`  | Your trade history with explicit BUY/SELL sides, cursor-paginated, with an optional market filter.                                                         |

### Trading

| Tool                 | What it does                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `place_orders`       | Proposes 1–10 limit orders for a single browser approval. Nothing is submitted until you approve. |
| `check_order_status` | Polls the outcome of a `place_orders` approval: `pending`, `approved`, `rejected`, or `expired`.  |
| `cancel_order`       | Cancels one of your open orders by id.                                                            |
| `cancel_all_orders`  | Cancels all your open orders in one market.                                                       |

## Order approval flow

The server is non-custodial. The assistant never holds your keys and cannot sign or submit orders on its own. `place_orders` only creates a proposal:

1. The assistant calls `place_orders` with up to 10 limit orders. Each order specifies a market slug, side (`BUY`/`SELL`), outcome index (`0` = YES, `1` = NO), a limit price between 0 and 1, shares, and an order type (`GTC` or `FAK`). Each order must be worth at least \$1 (price × shares).
2. The server validates the orders, attaches a fee preview per order, and returns an `approvalUrl` on `limitless.exchange`. The proposal expires after 600 seconds.
3. You open the approval URL in your browser, log in with your own Limitless session, review the exact orders and fee previews, and approve or reject them. Approval requires your browser session. The assistant's token cannot approve its own proposal.
4. On approval, your wallet signs and submits the orders. The assistant polls `check_order_status` with the returned `state` to learn the outcome.

Fee previews show a worst-case taker scenario (`ifTaker`) calculated as a full taker fill at the limit price, and for GTC orders also a maker scenario (`ifMaker`). These are conditional scenarios, not predictions. Actual fees are calculated per fill.

<Warning>
  Order cancellation does not require a browser approval. `cancel_order` and `cancel_all_orders` execute immediately with the connection's `trading` scope.
</Warning>

## Response conventions

* Token and collateral amounts are raw integer strings. Format them with each market's `collateralToken.decimals` (USDC uses 6). Prices are decimals between 0 and 1.
* List and search responses default to `orderableOnly: true`. Markets have an `orderable` flag; groups have `hasOrderableMarkets` instead, and their child markets come from `get_market_group`.
* Position snapshots are cached and can lag recent fills, transfers, or redemptions.
* Orderbook midpoints are arithmetic and not executable prices.

## Related pages

* [Build a Trading Agent](/developers/build-a-trading-agent) for a full agent built on the REST API and SDKs
* [Authentication](/developers/authentication) for API keys used outside of MCP
* [Fees](/user-guide/fees) for the fee schedule behind the previews