# How markets work


Source: https://docs.stxapp.io/concepts/how-markets-work/

Every market on the STX exchange is a **binary outcome contract**: it either resolves yes
or no. When a market resolves, every outstanding contract settles at either the market's
`max_price` or at $0. The market's
`description` field is the definitive statement of what constitutes a "yes" result:

```json
{
  "description": "Contracts for this market settle into $1 if the Boston Red Sox beats the New York Yankees by at least 1.5 runs and $0 if they do not.",
  "market_id": "becf9bf9-e2ff-4b50-879b-46054ad5c69a",
  "short_title": "NYY @ BOS -1.5"
}
```

**Buying** a contract means you believe the outcome described will happen. **Selling** means
you believe it won't. You are always trading against other participants on the exchange, not
against STX.

---

## Prices

Prices are **dollar amounts sent as strings**. A price of `"0.45"` means $0.45, and
an order price takes at most two decimal places. The spread between the best
available bid and offer represents the current market consensus.

The REST API writes every money field this way, and quantities as decimal strings:

```json
{
  "max_price": "1.0000",
  "bids":   [{"quantity": "566.00", "price": "0.5300"}],
  "offers": [{"quantity": "3636.00", "price": "0.6700"}]
}
```

The order book channel, `market:<market_id>`, sends those levels in dollars too but in
its own abbreviated shape. `order_book_update` carries `ob.b` and `ob.o`, and each level
is `{p, q, l, tc, tl}` (price, contracts, liquidity, and the cumulative contracts and
liquidity through that level), with every value a **JSON number, not a string**:

```json
{"ob": {"b": [{"p": 0.53, "q": 566,  "l": 299.98,  "tc": 566,  "tl": 299.98}],
        "o": [{"p": 0.67, "q": 3636, "l": 2436.12, "tc": 3636, "tl": 2436.12}]}}
```

The `markets` and `market_updates` channels are different again: their `bids[].price`
and `offers[].price` are in **cents** (`53`), not dollars. All three formats side by
side are in [Mapping markets](/concepts/market-shape/#money-on-the-wire).

Over REST a book price can go straight into an order: `"0.5300"` from `bids` is a valid
`price`. Only the `markets` and `market_updates` channels need converting from cents.

The `max_price` field on a market is the settlement value for a winning contract, in dollars.
It is also the reference point for calculating sell-order liability (see
[Understanding Positions](/concepts/positions/)).

Read `max_price` from each market rather than assuming it. New markets settle at $1, so
`max_price` is `"1.0000"` and a contract trades between $0.01 and $0.99, but older markets
carry other values and one environment can hold both. An order priced at or above a
market's `max_price` is rejected.

---

## Market Status

| Status | Meaning |
|--------|---------|
| `scheduled` | Created; no orders accepted yet |
| `pre_open` | Accepts limit orders ahead of open; no trades yet |
| `open` | Orders can be placed and matched |
| `closed` | The result is known; no new orders, and resting orders are cancelled |
| `resulted` | Result confirmed; settlements generated |
| `cancelled` | Cancelled; no new orders, and resting orders are cancelled |
| `voided` | Cancellation confirmed; void settlements generated |

A response can also read `suspended`, which is not a stored status: an `open` or
`pre_open` market that is not trading right now. `archived` is a separate boolean field,
not a status. See [Market and order status](/concepts/market-status/) for the full
detail.

---

## Querying Markets

Use the [`GET /api/v1/markets`](/api/rest/markets/list-markets/) query to fetch current markets.
It is signed like every other `/api/v1` route, and heavily cached, so you can call it
frequently; it is designed to handle high query rates.

For a price display or market screener, see
[List markets](/api/rest/markets/list-markets/) for the request, response and a runnable curl.

The best bid and offer are enough to estimate the implied probability of the outcome. For
example, on a market whose `max_price` is `"1.0000"`, a best bid of `"0.5700"` and a best
offer of `"0.6000"` mean the market is trading at 57 to 60 cents, roughly a 57 to 60%
probability of the "yes" outcome.

---

## Real-Time Updates

Querying `GET /api/v1/markets` gives you a snapshot. To receive live price and status changes without
polling, subscribe to the [`markets`](/websockets/channels/markets/) WebSocket channel,
which pushes only the changed fields whenever a market is updated.