# Cancels & Refunds

## When a Match Can Be Cancelled

| State     | Can be cancelled? | By whom                                       |
| --------- | ----------------- | --------------------------------------------- |
| `waiting` | ✅ Yes             | Creator manually, or auto after 5 min         |
| `ready`   | ✅ Yes             | Either player manually (admin tool currently) |
| `playing` | ❌ No              | Match is in progress                          |
| `settled` | ❌ No              | Outcome already final                         |

## How Cancels Work

When a cancel triggers:

1. Server CAS-flips `status: 'waiting' → 'cancelled'` (or `ready → cancelled`)
2. The CAS guard ensures only ONE cancel can succeed — no double-refund possible
3. For each side that deposited: server calls `sendPayout()` to send the wager back on-chain
4. Notification dropped to each refunded player with the refund TX signature

## What If a Refund Fails?

Rare but possible (RPC blip, treasury balance momentarily low). When `sendPayout` fails:

* The match stays `cancelled` (state already flipped)
* A `[pvp/lobby sweep] REFUND FAILED` entry is logged with the wallet + amount + match\_id
* The refund needs **manual reconciliation** by ops — report it in the support topic on Telegram with your wallet address
* We **never double-pay** — the CAS guard + deposit-sig uniqueness make that structurally impossible

## Auto-Cancel for Stuck Matches

Currently:

* ✅ **`waiting` matches** (nobody joined) → auto-cancel + refund after 5 min via the lobby sweep
* ❌ **`ready` matches** (both deposited but never started) → NOT auto-cancelled yet. Manual cleanup via admin. If you're stuck in a `ready` match and the opponent ghosts, please report it in the support topic on Telegram with the match ID.

Post-beta this will be cron-automated.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snake-os.com/pvp-real-sol-wagering/cancels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.