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

# Market lifecycle

> How an XO market moves through Pending, Active, Paused, Resolved, Voided, and Closed.

Every market on XO is in one of six states. The state determines whether you can place orders, whether existing orders rest, and whether payouts are claimable.

## States

| Status     | Order entry    | Resting orders           | What it means                                                                                  |
| ---------- | -------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
| `Pending`  | Rejected (422) | None yet                 | Market created on-chain but not yet activated.                                                 |
| `Active`   | Accepted       | Match normally           | Normal trading.                                                                                |
| `Paused`   | Rejected (422) | **Retained**             | Transient hold. Matching is frozen but orders stay on the book; market can resume to `Active`. |
| `Resolved` | Rejected (422) | All cancelled atomically | Winning outcome recorded; positions are claimable.                                             |
| `Voided`   | Rejected (422) | All cancelled atomically | Market invalidated; positions refund pro-rata.                                                 |
| `Closed`   | Rejected (422) | All cancelled atomically | Market closed without resolution.                                                              |

`Resolved`, `Voided`, and `Closed` are **terminal**. `Paused` is **transient** — orders stick around.

## Transitions you'll see in production

```
Pending ──► Active ──► Paused ◄──► Active
                │
                ├─► Resolved   (winner recorded)
                ├─► Voided     (market invalidated)
                └─► Closed     (closed without resolution)
```

When attempting to place an order against a non-`Active` market, the response is `422 Unprocessable Entity` with body `{"error": "market is not active (status: Pending)"}` (or `Paused`, `Resolved`, etc.).

## Order entry on a non-Active market

Order placement returns 422 with a stable error prefix:

```json theme={null}
{"error": "market is not active (status: Paused)"}
```

Substring-match on `"market is not active"` to detect this case generically across all non-Active statuses.

## WebSocket: MarketStatusChanged

The combined `/ws` channel emits a `market_status_changed` frame on every transition:

```json theme={null}
{
  "type": "market_status_changed",
  "market_id": "0x39a12d52b63969654926e095ddd96f5c459112714da03edca769aa58173c78fb",
  "old_status": "Active",
  "new_status": "Paused",
  "cancelled_orders": 0
}
```

`cancelled_orders` is non-zero only on terminal transitions (`Resolved`, `Voided`, `Closed`). On a `Paused` transition it's always `0` — Paused retains resting orders.

On terminal transitions, `/ws/user` subscribers also receive one `order/CANCELLATION` frame per cancelled order owned by the user, fanned out before the `market_status_changed` frame.

## Claimable positions

Once a market reaches `Resolved` or `Voided`, the user's positions become claimable. Query `GET /claimable?address=<addr>`:

```json theme={null}
{
  "address": "0xCAFE000000000000000000000000000000000A11",
  "claimable": [
    {
      "market_id": "0x39a12d52b63969654926e095ddd96f5c459112714da03edca769aa58173c78fb",
      "outcome": "Yes",
      "token_id": "26516164265702901957933644848127860370782874751279270726689263951695181556943",
      "balance": "50000000",
      "refund_reason": "resolved_winner"
    }
  ]
}
```

`refund_reason`:

* `resolved_winner` — Market resolved with a definite winner; this side won.
* `voided_refund` — Market was invalidated. Both YES and NO holders get pro-rata refunds; both sides appear here when held.

The actual redemption is an on-chain `ConditionalTokens.redeemPositions` call made by the smart account through the XO bundler; the orderbook does not move funds — it tells you what you can claim. See [Redeem positions](/guides/redeem-positions).

On-chain, payouts are reported when the market is **closed** (after the resolution period). `redeemPositions` reverts until `payoutDenominator(conditionId)` is non-zero, even if `/claimable` already lists the position.

## Pending → Active

Markets created on-chain through the protocol enter `Pending`. The matching engine activates them when the on-chain `MarketCreated` event is observed and any required setup completes. Once `Active`, the market is queryable via `/markets/{condition_id}` with `"active": true`.

A `Pending` market with token IDs visible in `/markets` is a normal intermediate state — not an error.