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

# SOAR over MCP

> Trade the venue from Claude or ChatGPT, without handling an API key

SOAR runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at
`https://mcp.trysoar.com/mcp`. Connect an MCP-aware assistant to it and the assistant
can search markets, read a ladder, check your portfolio, and place or cancel orders —
authenticated as you, over OAuth, with no key to copy or store.

<Note>
  **The venue trades paper money.** Balances and P\&L are consistently accounted for and
  cannot be withdrawn. Nothing you do here is a real financial transaction.
</Note>

If you are writing a program rather than driving one from a chat client, skip this and
use the [REST API](/quickstart) directly. MCP is the same venue behind a different
transport, not a second venue.

<Card title="Connect it" icon="plug" href="/mcp/connect">
  Claude, Claude Code, ChatGPT and Codex — the exact steps, and the scopes to grant.
</Card>

## What it can do

Eleven tools, split by whether they move anything.

| Tool | What it does |
| - | - |
| `soar_search_markets` | Search markets by company, grouped into ladders |
| `soar_get_ladder` | Read a ladder as a valuation distribution — band masses, quantiles |
| `soar_get_market` | One market, and your state in it |
| `soar_get_price_history` | OHLCV bars for a market |
| `soar_get_orders` | List your orders, or fetch one by id |
| `soar_get_fills` | Your fill history, priced for your own side |
| `soar_get_portfolio` | Balance, positions, marks, and P\&L |

| Tool | What it moves |
| - | - |
| `soar_place_order` | Places a limit order |
| `soar_amend_order` | Changes a resting order's price or size |
| `soar_cancel_order` | Cancels one known order |
| `soar_cancel_market_orders` | Cancels every resting order in a market or event |

The write tools appear only when your token carries a write scope, and your client
asks before each call. Both layers are described in [Connect](/mcp/connect#approval).

<Note>
  There is no streaming tool. SOAR's realtime feed authenticates with an API key or an
  app session, not with the OAuth token this server holds on your behalf — so there is
  nothing it can subscribe to for you. Ask again to refresh instead.
</Note>

## Why it exists

Everything here is reachable with `curl`. The server exists because a handful of fields
are correct-looking and wrong when read naively, and it would rather resolve them once
than let every assistant that connects rediscover them.

<AccordionGroup>
  <Accordion title="The price you paid is not the price that printed" icon="scale-balanced">
    A fill carries both. **`price_cents` is yours** — what you actually paid or
    received, and the field that reconciles against your cash. `tape_price_cents` is the
    public print both counterparties see.

    They differ by `100 − 2p`, which is 40¢ a share at a 30¢ print. Computing P\&L from
    the tape price is wrong silently, in the direction that looks plausible.

    [Binary markets →](/concepts/binary-markets#what-you-paid-and-what-printed)
  </Accordion>

  <Accordion title="A fresh covered pair looks like a loss and is not" icon="layer-group">
    Marks are liquidation-side — what you could sell out at right now. A `yes`+`no`
    pair you bought across the spread marks below the 100¢ it is guaranteed to pay at
    settlement, so it reads as a loss the moment you have it.

    `soar_get_portfolio` reports `covered_pairs_value_cents` next to the mark for exactly
    this reason. Read it before concluding you are underwater.
  </Accordion>

  <Accordion title="Errors say what to do, in a field you can branch on" icon="triangle-exclamation">
    Every failure carries a `code` and a `disposition`. Branch on those; the English
    `detail` is not contractual.

    | `disposition` | What it means |
    | - | - |
    | `terminal` | Fix the request. Retrying unchanged fails identically. |
    | `auth` | Reissue the token with the scope named. |
    | `retry_safe` | Nothing was sequenced. Retry freely. |
    | `retry_idempotent_only` | The write **may have committed**. |

    `retry_idempotent_only` is the one that costs money. It does not mean "nothing
    happened." Re-send with the *same* `client_order_id` — the venue deduplicates on it
    — or poll with `soar_get_orders`. Never retry with a fresh id.

    [`result_unknown` →](/api-reference/errors#result-unknown)
  </Accordion>

  <Accordion title="Tickers are opaque, and the dots are load-bearing" icon="hashtag">
    `ANTHROPIC-VALUATION-26Q3-1.05T` is one rung. Never sanitize a ticker, never split it
    on a hyphen, and never assemble one — read `event_ticker` and `series_ticker` off the
    response.

    [Survival ladders →](/concepts/survival-ladders#addressing-a-ladder)
  </Accordion>
</AccordionGroup>

## Ladders, in one call

Most markets are one rung of a **survival ladder** — a row of valuation thresholds on
the same company, where each price is the probability the valuation exceeds that
threshold. `soar_get_ladder` reads the row as a distribution: the gaps between adjacent
rungs are the probability mass in each band.

Rung prices must fall as strikes rise. When they do not, that is a real inefficiency,
and the tool names it rather than leaving you to spot it.

[Survival ladders →](/concepts/survival-ladders)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.