> ## 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 Trading API

> Trade prediction markets on private-company valuations, programmatically

SOAR runs prediction markets on the valuations of private companies — OpenAI,
Anthropic, SpaceX and the like. This API is how a program trades them: find markets,
read the book, place and cancel orders, and track positions.

<Note>
  **The venue trades paper money.** Balances and P\&L are real in the sense that they
  are consistently accounted for, and not real in the sense that you can withdraw
  them. Everything else — the matching, the fees, the settlement — behaves as it would
  with real money, because it is the same engine.
</Note>

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    A key to your first order in five minutes, in five `curl` commands.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    One header, two scopes, and why they do not nest.
  </Card>

  <Card title="Trade from an AI assistant" icon="plug" href="/mcp/overview">
    Connect Claude or ChatGPT to SOAR over MCP. No key to handle.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    The code vocabulary, what to retry, and `result_unknown`.
  </Card>
</CardGroup>

```bash theme={null}
curl -s "https://api.trysoar.com/v1/markets?q=anthropic" \
  -H "X-API-KEY: $SOAR_API_KEY"
```

Base URL is `https://api.trysoar.com/v1`. Every request carries exactly one
credential: an `X-API-KEY` header for an integration you write, or an OAuth bearer
token for an approved application. Never both.

## Three things to know before you write code

The API is ordinary REST; the market structure is not. These three facts cause most
first-integration bugs.

<AccordionGroup>
  <Accordion title="Markets come in ladders, not one-off questions" icon="stairs">
    Most markets are one rung of a **survival ladder** — a row of thresholds on the
    same company's valuation, each asking "is it worth more than \$T?". The rung prices
    together describe where the market thinks the valuation lands, so a view about a
    company is usually a trade on several rungs.

    [Survival ladders →](/concepts/survival-ladders)
  </Accordion>

  <Accordion title="One market has two outcomes, not two books" icon="scale-balanced">
    `yes` and `no` are two ways of naming a position in the same book: `buy no` at 40¢
    is the other side of `buy yes` at 60¢, and the two will trade against each other.
    Modelling them as separate markets halves the liquidity you can see.

    [Binary markets →](/concepts/binary-markets)
  </Accordion>

  <Accordion title="There are no short positions" icon="ban">
    Selling what you do not hold is a rejection, not a short. To take the bearish side
    you buy the opposite outcome. Positions are non-negative, always.

    [insufficient\_shares →](/api-reference/errors#insufficient-shares)
  </Accordion>
</AccordionGroup>

## The contract is machine-readable

```bash theme={null}
curl -s https://api.trysoar.com/v1/openapi.yaml
```

No key required. That is the OpenAPI 3.1 document for every endpoint here, and it is
the same file this site renders — so the docs, the playground, and the API cannot
disagree with each other.

If you are pointing an agent at this API, point it there.

## What you can do

| | |
| - | - |
| **Discover** | Search companies, list events and ladder rungs, read a market. |
| **Read the market** | Order book, recent trades, candles, or all three in one `snapshot` call. |
| **Trade** | Place, amend, and cancel orders. `gtc`, `ioc`, `fok`. |
| **Size in cash** | Spend a budget instead of counting shares — the engine sizes it against the book. |
| **Track** | Orders, fills, positions, and balance — keyset-paged. |

Full endpoint reference, with a playground that sends real requests, is in the **API
Reference** tab.

## Conventions

* **Prices are whole cents, 1–99.** Amounts are integer cents. Never a float.
* **Rates and valuations are decimal strings** — `"0.0700"` is 7%. A float64 loses
  precision at these valuations.
* **Ids are strings.** `order_id` exceeds what a JavaScript number holds exactly, so it
  is quoted; a client that parses it as a number will cancel orders that do not exist.
* **Enums are lower-case strings** — `yes`/`no`, `buy`/`sell`, `gtc`/`ioc`/`fok`.
* **Timestamps are RFC3339, UTC, `Z`-suffixed.**
* **Lists are keyset-paged** with `limit` and an opaque `cursor`. The cursor is the
  empty string on the last page — never absent.
* **Errors carry a `code`.** Branch on it; the message is free text.
  [Errors →](/api-reference/errors)


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