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

# Settlement

> Settlement flow, statuses, void conditions, and reconciliation

## Settlement Flow

Markets predict the **next round** — they are created during the current round's freeze time and settle when the target round ends.

Settlement happens in two phases:

1. **Live settlement** — During the target round. Some markets settle immediately when the triggering event occurs (e.g., `headshot_opening` is settled as soon as the first kill happens, `awp_kill` settles the moment an AWP kill is confirmed).

2. **End-of-round settlement** — When the target round ends, all remaining pending markets are settled based on the full round result.

```mermaid theme={null}
graph TD
    A["Round N freeze time<br/>Markets created for Round N+1"] --> B["Round N+1 starts<br/>Betting is open"]
    B --> C{"In-round event?"}
    C -->|"Kill / bomb / clutch"| D["Live settlement<br/>(definitive markets only)"]
    C -->|"Round N+1 ends"| E["End-of-round settlement<br/>(all remaining markets)"]
    D --> F["settled: won"]
    E --> G["settled: won / lost"]
    E --> H["voided: void"]
```

### Timing Example

| Time  | Event                                                                    |
| ----- | ------------------------------------------------------------------------ |
| T+0s  | Round 7 freeze — engine generates markets predicting **Round 8** events  |
| T+0s  | `<odds_change>` published — markets are active, betting opens            |
| T+2s  | Round 8 starts                                                           |
| T+5s  | First kill is a headshot → `headshot_opening` settled immediately (live) |
| T+8s  | AWP kill occurs → `awp_kill` settled immediately (live)                  |
| T+45s | Round 8 ends → all remaining markets settled (end-of-round)              |

## Settlement Statuses

| Status    | Result | Meaning                                      |
| --------- | ------ | -------------------------------------------- |
| `pending` | `null` | Market is open or suspended, not yet settled |
| `settled` | `won`  | The predicted event occurred — pay out       |
| `settled` | `lost` | The predicted event did not occur — bet lost |
| `voided`  | `void` | Market cancelled — return stakes to bettors  |

## Settled By

| Value    | Meaning                                        |
| -------- | ---------------------------------------------- |
| `engine` | Automatic settlement by the odds engine        |
| `system` | System-level action (e.g., match cancellation) |
| `admin`  | Manual settlement by back-office operator      |

## Void Conditions

Markets are voided when:

* The match is abandoned or cancelled mid-play
* A technical issue prevents reliable settlement
* An admin manually voids the market

<Warning>
  When a market is voided, operators **must** return all stakes to bettors. Voided markets have no winner or loser.
</Warning>

## Betstop Protocol

When a market is suspended (`suspended: true`), operators **MUST** immediately stop accepting new bets on that market.

### Suspension Triggers

| Trigger                | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| **Outcome determined** | First kill occurred → opening-kill markets suspended |
| **TTL expiry**         | Market exceeds its time-to-live window               |
| **Extreme odds**       | Odds exceed 40.0 (virtually impossible)              |
| **Round end**          | All round markets suspended, then settled            |
| **Manual**             | Admin suspends via back-office                       |

### Suspension Rules

<Note>
  Once a market is suspended, it **stays suspended** until settlement. It will not be reactivated. New markets for the next round are created independently.
</Note>

* A suspended market with `settlement_status: "pending"` will still be settled at round end
* The `suspended` field transitions: `false` → `true` (never back to `false`)

## Reconciliation

Use `GET /cs2/v1/settlements` with cursor-based pagination to reconcile settlements. Requires `cs2:markets:settlements` scope.
Each entry includes `market_offer_id` which you can look up against `GET /cs2/v1/matches/{id}` (`cs2:matches:read`) to retrieve the `event_id` for cross-referencing.

```python theme={null}
import requests
import time

API_KEY = "your-api-key"
BASE = "https://ticktock.bet/cs2/v1"
last_id = None

while True:
    params = {"limit": 100}
    if last_id:
        params["since_id"] = last_id

    resp = requests.get(
        f"{BASE}/settlements",
        headers={"X-API-Key": API_KEY},
        params=params,
    )
    entries = resp.json()["data"]

    for entry in entries:
        # entry["outcome"] is "won", "lost", or "void"
        process_settlement(entry)
        last_id = entry["id"]

    time.sleep(30)  # Poll every 30 seconds
```

**Settlement log entry fields:**

| Field             | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `id`              | Cursor value — pass as `since_id` on next poll                     |
| `market_offer_id` | The settled market UUID                                            |
| `previous_status` | Status before transition (e.g. `pending`)                          |
| `new_status`      | `settled` or `voided`                                              |
| `outcome`         | `won` / `lost` / `void` — use to grade bets                        |
| `settled_by`      | `engine` / `system` / `admin`                                      |
| `reason`          | Human-readable reason (for manual/system actions, null for engine) |
| `is_resettlement` | `true` when a previously settled market has been re-graded         |
| `created_at`      | ISO 8601 settlement timestamp                                      |

<Tip>
  To get the match event ID for a settled market: call `GET /cs2/v1/matches/{match_id}`. The `event_id` field lets you cross-reference any settled market against the same match in the messaging feed.
</Tip>

<Tip>
  Poll the settlement log periodically (every 30s) to catch any settlements that may have been missed due to AMQP disconnections.
</Tip>