> ## 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.
# Quickstart
> From a new key to your first order and back out, in five commands
Five commands: get a key, find a market, orient, place an order, cancel it and check
your balance. You need a SOAR account and `curl`. Nothing to install.
Every response below is real output from running these exact commands.
## 1. Create a key
Sign in to SOAR and create an API key with the `read` and `trade` scopes. You need
both — [scopes do not nest](/api-reference/authentication#scopes), and a `trade`-only
key cannot read back the order it just placed.
The key is shown once. Save it:
```bash theme={null}
export SOAR_API_KEY="soar_sk_…"
```
Full details, including the 10-key limit and how to revoke:
[Authentication](/api-reference/authentication#creating-a-key).
## 2. Find something to trade
```bash theme={null}
curl -s "https://api.trysoar.com/v1/markets?q=anthropic&limit=3" \
-H "X-API-KEY: $SOAR_API_KEY"
```
```json theme={null}
{
"markets": [
{
"ticker": "ANTHROPIC-VALUATION-26Q3-1.05T",
"market_id": "edec0c7b-925e-482f-b029-6815f86e78ef",
"event_ticker": "ANTHROPIC-VALUATION-26Q3",
"name": "> $1.05T",
"description": "Resolves YES if Anthropic's valuation exceeds $1.05T by end of Q3 2026.",
"state": "active",
"min_price": 1,
"max_price": 99,
"tick_size": 1,
"strike_value": "1050000000000",
"strike_unit": "usd",
"maker_fee_rate": "0",
"taker_fee_rate": "0.0007",
"last_price": 76,
"created_at": "2026-06-30T05:51:42.077000000Z"
}
],
"cursor": ""
}
```
That is one rung of a ladder. To see the whole ladder at once, ask for its event:
```bash theme={null}
curl -s "https://api.trysoar.com/v1/events/ANTHROPIC-VALUATION-26Q3" \
-H "X-API-KEY: $SOAR_API_KEY"
```
Note `strike_value` and the fee rates are **decimal strings**, not numbers — at these
magnitudes a float would lose precision. And `cursor` is the empty string because this
is the last page; it is never absent.
## 3. Orient in one call
`snapshot` returns the market, the book, the last trade, the stats, and *your* position
and resting orders in it — everything a decision needs, in one round trip.
```bash theme={null}
curl -s "https://api.trysoar.com/v1/markets/ANTHROPIC-VALUATION-26Q3-1.05T/snapshot" \
-H "X-API-KEY: $SOAR_API_KEY"
```
```json theme={null}
{
"market": { "ticker": "ANTHROPIC-VALUATION-26Q3-1.05T", "last_price": 76, "state": "active" },
"orderbook": {
"as_of": "2026-08-04T03:32:39.968000000Z",
"bids": [ { "price": 76, "size": 5423 }, { "price": 75, "size": 5254 } ],
"asks": [ { "price": 78, "size": 5428 } ]
},
"last_trade": {
"trade_id": "t_owpg72smx3pem",
"price": 76,
"qty": 20,
"created_at": "2026-08-04T03:32:39.968000000Z"
},
"stats": { "volume_usd": "4336308.00000000000000000000", "last_price": 76 },
"positions": [],
"resting_orders": []
}
```
Best bid 76¢, best ask 78¢. `positions` and `resting_orders` are empty arrays because
this account holds nothing here yet — empty collections are always `[]`, never `null`.
`trade_id` is **opaque**: use it to deduplicate, never to sort. Order by `created_at`.
## 4. Place an order
A `gtc` buy at 3¢ — far below the bid, so it rests instead of trading. Exactly what
you want the first time.
```bash theme={null}
curl -s -X POST "https://api.trysoar.com/v1/orders" \
-H "X-API-KEY: $SOAR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"ticker": "ANTHROPIC-VALUATION-26Q3-1.05T",
"outcome": "yes",
"side": "buy",
"price": 3,
"qty": 1,
"time_in_force": "gtc",
"client_order_id": "my-first-order-1"
}'
```
```json theme={null}
{
"order_id": "4112819884627358272",
"client_order_id": "my-first-order-1",
"ticker": "ANTHROPIC-VALUATION-26Q3-1.05T",
"event_ticker": "ANTHROPIC-VALUATION-26Q3",
"outcome": "yes",
"side": "buy",
"price": 3,
"qty": 1,
"remaining_qty": 1,
"filled_qty": 0,
"status": "open",
"time_in_force": "gtc",
"created_at": "2026-08-04T03:33:53.993183584Z",
"updated_at": "2026-08-04T03:33:53.993183584Z"
}
```
**That `status` is already the real outcome, not an acknowledgement.** Matching
happened before the response came back. `open` means nothing traded and the order is
resting; had it crossed, you would have `filled` or `partially_filled` here.
An `ioc` order that finds no liquidity comes back `canceled` — there is nothing to
wait for. [Order lifecycle →](/concepts/order-lifecycle)
Two fields to handle carefully:
* **`order_id` is a string of digits.** It exceeds what a JavaScript number represents
exactly. Parse it as a number and you will eventually cancel an order that does not
exist.
* **`client_order_id` is yours**, unique among your own orders. Re-sending the same one
returns the existing order rather than creating a second — which is what makes a
retry safe when a write returns `503 result_unknown`.
[Read that before going live →](/api-reference/errors#result-unknown)
You can watch that dedup work right here: run this command twice unchanged and the
second response is the *same* `order_id` as the first, in whatever state that order
has reached. Use a fresh `client_order_id` when you actually want a second order.
## 5. Cancel it, and check your balance
While the order rests, its collateral is held. Check first:
```bash theme={null}
curl -s "https://api.trysoar.com/v1/portfolio/balance" \
-H "X-API-KEY: $SOAR_API_KEY"
```
```json theme={null}
{
"available_cents": 4999996,
"reserved_cents": 4,
"total_cents": 5000000
}
```
Four cents reserved for a 1-share buy at 3¢: the 3¢ you bid plus the 1¢ fee that trade
would incur. The venue reserves what the order could cost you, not just the price.
Now cancel it, using the `order_id` **from your own step 4 response** — the one below
is from this transcript and is long since canceled:
```bash theme={null}
export ORDER_ID="4112819884627358272"
curl -s -X DELETE "https://api.trysoar.com/v1/orders/$ORDER_ID" \
-H "X-API-KEY: $SOAR_API_KEY"
```
```json theme={null}
{
"order": {
"order_id": "4112819884627358272",
"status": "canceled",
"remaining_qty": 1,
"filled_qty": 0,
"reserved_cents": 0
},
"reduced_by": 1
}
```
`reduced_by` is the quantity the cancel actually pulled off the book — 1, the whole
order. Had part of it filled while your request was in flight, this would be smaller,
and that number is the truth rather than what you assumed you were canceling.
```bash theme={null}
curl -s "https://api.trysoar.com/v1/portfolio/balance" \
-H "X-API-KEY: $SOAR_API_KEY"
```
```json theme={null}
{
"available_cents": 5000000,
"reserved_cents": 0,
"total_cents": 5000000
}
```
`reserved_cents` is back to zero and `available_cents` is whole again: the collateral is
released the moment the cancel is acknowledged. All amounts are integer cents —
`5000000` is \$50,000.
## What next
Why five rung prices describe a whole valuation distribution.
Why `buy no` and `sell yes` are the same order, and why there are no shorts.
The code vocabulary, what to retry, and `result_unknown`.
Every endpoint, with a playground that sends real requests.
Testing against staging instead? Same paths, different host:
`https://api.staging.trysoar.com/v1`. Keys are per-environment.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.