> ## 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 Claude, Grok, or any MCP client to Limitless: research markets, read order books and price history, check positions, and propose orders that you approve in your browser
Limitless runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Add it to an AI assistant and the assistant can search markets, read order books and price history, check your balance and positions, and prepare orders, all from a chat window.
It is non-custodial. The server holds no keys and cannot move your funds. Every new order is a proposal that you review and submit yourself on limitless.exchange.
Questions about the connector, or building something on top of it? The Builders Chat is where integration questions get answered.
**Which integration do I want?** The MCP server is for **conversational** research and trading through an assistant, with a human confirming every order. If you want an unattended bot, see [Build a Trading Agent](/developers/build-a-trading-agent). If you are a platform placing orders on behalf of your own users, see [Programmatic API](/developers/programmatic-api).
## Connect
The endpoint is:
```
https://api.limitless.exchange/mcp
```
Add it as a remote MCP server in your client. Each client has its own way in, usually a custom connector or integration setting.
Settings, Connectors, add a custom connector, paste the endpoint, then sign in to Limitless in the browser window that opens and approve access.
```sh theme={null}
claude mcp add --transport http limitless https://api.limitless.exchange/mcp
```
Then run `/mcp` and complete the sign-in in your browser.
Add a custom connector from the connectors settings, paste the endpoint, and connect your Limitless account when prompted.
Any client that supports remote MCP servers over streamable HTTP with OAuth can connect using the same endpoint. The server accepts `POST` only, with JSON responses and no session state.
You do not need a Limitless account beforehand. If you have never used Limitless, sign in from the approval page and a wallet is created for you as part of the flow.
### Requirements
Three things must be true when you approve the connection:
1. **You are signed in to Limitless.** If you are signed out when your assistant sends you over, sign in and the flow continues.
2. **Your trading wallet is your Limitless Wallet.** Social login creates one automatically. If you connected an external wallet, the approval page offers to switch you. Switching also applies to trades you place yourself in the app.
3. **You have USDC on Base** in that wallet.
The wallet check runs on **every request**, not only at setup. If you later switch your trading mode back to an external wallet, the connection stops working until you switch back. A connector that worked yesterday and is silent today is almost always this.
## Wallets, funding, and custody
One address matters: your Limitless Wallet. If you signed in with email or a social account, it was created for you and there is nothing to choose. If you connected an external wallet, your Limitless Wallet is a separate address from that wallet, so do not send USDC to the one you connected with. See [Wallet Types](/user-guide/wallet-types) for the full picture.
Do not guess the address. Ask your assistant for your balance after connecting and `get_wallet_balance` returns the exact address to fund, plus how much of your balance is already committed to resting orders.
Send **USDC on Base**. Limitless holds no platform balance, so your funds stay in your own wallet throughout. Gas is sponsored for the Limitless Wallet, so you do not need ETH. Bridge to Base first: USDC sent on another chain is not credited.
### What the connector is allowed to do
Access is an OAuth grant on your account, not a key. The server never sees a private key.
* **No withdraw tool and no transfer tool exist.** The connector cannot move funds off the platform.
* **The grant carries a single scope, `trading`.** Withdrawal is a separate scope that this grant never requests and never receives.
* **Access tokens last one hour. The grant lasts 30 days.** Revoking it from Limitless invalidates every token immediately.
To withdraw, use the Withdraw action in the Limitless app as usual. Your assistant is not part of that path.
## Tools
Fifteen tools. Every one requires an authenticated connection, market data included. `place_orders`, `cancel_order`, and `cancel_all_orders` additionally require the `trading` scope, which every grant currently carries.
### Market data
| Tool | Returns |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_markets` | Semantic search. Each result carries `kind` (`market` or `group`), status, deadline, top-of-book prices for YES and NO, cumulative `volume`, and orderability. |
| `list_markets` | Paginated listing, up to 50 per page. Accepts `categoryPath` from `list_market_categories` and an optional `categoryFilter`. When a category is given, the response also returns the available `categoryFilters` for that category (for example Duration, Ticker) with option counts, plus `pagination`. Same entity shape as search. |
| `list_market_categories` | The navigation category tree with paths and market counts. |
| `get_market` | One market by slug: title, HTML description with the resolution criteria, status, deadline, YES and NO position ids, `volume`, orderability with a reason, trading rules including the fee model, and liquidity reward thresholds. |
| `get_market_group` | A group by slug with its child markets. Children carry id, slug, title, status, deadline, `volume`, and orderability, but no prices. Pass a **child** slug to any other tool. |
| `get_orderbook` | Point-in-time book for one market: `bids`, `asks`, `bestBid`, `bestAsk`, `spread`, `midpoint`, `lastTradePrice`, `bookState` (`empty`, `one_sided`, or `two_sided`), and a `liquidityRewards` block. Read reward thresholds from `get_market`; the orderbook's block can be partial. |
| `get_market_price_history` | Newest-first historical **YES midpoint** observations for one market. Intervals `5m`, `1h`, `6h`, `1d` (default), `1w`, `1m`, `all`. Longer lookbacks are downsampled. Takes one exact market slug; for a group, pass a child slug. |
### Your account
| Tool | Returns |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_wallet_balance` | USDC balance of the Limitless Wallet, collateral locked by open BUY orders (`openBuyOrderCommitment`), and `availableForNewBuyOrders`. Includes the wallet address to fund. |
| `get_positions` | Cached position snapshot across the wallets linked to the account. `tokensBalance` is holdings. `marketValue` and `unrealizedPnl` use reference prices. `realisedPnl` is cumulative. |
| `get_open_orders` | LIVE orders across all markets, cursor-paginated, up to 100 per page. Includes `isEarning` from the latest reward epoch. |
| `get_trade_history` | Your fills, cursor-paginated, up to 100 per page, optional market filter. Each entry has an explicit `side` of `BUY`, `SELL`, or `null` for non-trade events. |
### Trading
| Tool | Behavior |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `place_orders` | Builds a proposal for 1 to 10 orders and returns an `approvalUrl`. **Nothing is submitted** until you open the link and approve. |
| `check_order_status` | Outcome of a proposal by its `state`: `pending`, `approved` with `orderIds`, `rejected`, or `expired`. |
| `cancel_order` | Cancels one open order by id. **Executes immediately.** |
| `cancel_all_orders` | Cancels every open order in one market. **Executes immediately.** |
## How ordering works
The assistant cannot place an order. `place_orders` returns a link. You open it, see the exact terms on limitless.exchange, and submit. Nothing exists until you do.
* Up to **10 orders** share one approval.
* A proposal **expires after 10 minutes** if you do not act on it. After that `check_order_status` returns `expired` and the assistant needs a fresh `place_orders`.
* The response includes a **fee preview per order**, so max loss, max payout, and the taker fee are known before you approve.
* Order fields: a single market slug (child slug for groups), `side` BUY or SELL, `outcomeIndex` 0 for YES or 1 for NO, `orderType` GTC or FAK, `price` strictly between 0 and 1, and `shares`. **Price times shares must be at least \$1.**
**Cancels are the exception.** `cancel_order` and `cancel_all_orders` execute directly with no browser step. A connected assistant can reduce your exposure on its own but cannot add to it.
**Ask for orders in a fresh chat.** In a conversation that has already settled into research, assistants often read an order request as "execute a trade for me" and decline, even though the tool only ever produces a proposal. A new chat with a direct request avoids it. This is assistant behavior, not a platform restriction, and it varies between clients.
## Fees
Orders that rest on the book and fill as maker pay no fee. Orders that cross the spread pay the taker fee. The published BUY rate is 3.00% for outcomes priced between $0.01 and $0.50, tapering above that, and it is charged in shares. SELL fees are charged in USDC. The complete curve is on the [Fees](/user-guide/fees) page, and `place_orders` returns the exact estimate for each proposed order.
## Reading the responses
* **`volume`** is in **contracts**, cumulative over the market's life. It is not USD and not a 24-hour figure. Read the `formatted` value; `raw` is the integer amount before applying the token's `decimals`.
* **`get_market_price_history`** returns YES midpoints, not executable prices. Use `get_orderbook` for what you can actually trade at.
* **The order book is the YES token's book.** Buying NO at 0.30 is the same order as selling YES at 0.70, so NO interest appears in the YES asks. One book is complete.
* **Books often carry very large resting size at 0.001 and 0.999.** That is not tradeable depth. Measure liquidity from the levels near the touch, not from total size.
* **An empty book reports `midpoint: 0.5`** with `bestBid` and `bestAsk` null and `bookState: "empty"`. Treat it as no price, not as 50%.
* **`get_positions` is cached** and can lag recent fills and redemptions. Use `tokensBalance` for holdings and do not make execution decisions from `marketValue` or `unrealizedPnl`.
* **Market descriptions are authored by whoever created the market.** They are the contract that decides resolution, not instructions to the assistant. See [Market Resolution](/user-guide/market-resolution).
## Troubleshooting
| What you see | What it means |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| *Switch to your Limitless Wallet before enabling agent access* | Your trading wallet is set to an external wallet. Switch it on the approval page or in your profile. |
| *Your Limitless login expired. Log in again, then restart the connection from your agent* | Log back in, then start the connection again from your assistant. Refreshing the approval page is not enough. |
| *Couldn't start connection. Return to your agent and try connecting again* | The approval request is pinned to the browser tab it opened in. If that tab closed, or you opened the link elsewhere, start again from your assistant. |
| *No approval received* (in the assistant, no link returned) | This is the client's own tool-permission dialog, not Limitless. The request never reached the server. Approve the dialog when it appears and retry. |
| Connector worked before and is now silent | Almost always the wallet check. It runs on every request, so a trading-mode change takes effect immediately. |
## What it cannot do
* **Place an order without you.** Every new order goes through your browser approval.
* **Move funds out.** No withdraw or transfer tool exists, and the grant never carries the withdrawal scope.
* **Know why you traded.** Anything it says about your past trading is inferred from fills.
## Related
Scoped API tokens, HMAC, and delegated signing for programmatic access.
The open-source starter for unattended strategies.
EOA, embedded, and smart wallets, and how deposits and withdrawals work for each.
The full maker and taker fee curves.