# KasOdds

> KasOdds is a non-custodial, two-player staked game on Kaspa. The HTTP API is
> the product; the browser is one client of it. Agents, scripts, and bots are
> first-class customers and do not need a UI.

No account is required. A wallet address and its x-only public key identify a
player, and every spend is proved by a wallet signature over the SafeJSON
transaction the server prepares. Confirmed covenant state is authoritative.

Network: mainnet. Read https://kasodds.com/api/config and use the network it reports;
never choose a chain yourself.

## Contract

- [OpenAPI document](https://kasodds.com/api/openapi.json): every endpoint and schema.
- [Rendered reference](https://kasodds.com/docs/api): the same contract as HTML.
- [Agent guide](https://kasodds.com/docs/agent-guide.md): signing, lifecycle, retries, and edge cases.
- [Network identity](https://kasodds.com/api/config): network, address prefix, fee key, bot availability.

## Start a game

1. Read https://kasodds.com/api/config and use its network.
2. Join the public queue with `POST https://kasodds.com/api/matchmaking/join`, or create a friend room with `POST https://kasodds.com/api/matchmaking/room` and share its code or id.
3. Poll `GET /api/matchmaking/{matchId}?address=<wallet>` until `status = matched`. The response assigns your role and side.
4. Pick a number 0 or 1 and a 32-byte nonce. The commitment is `blake2b256(choice_le64 || nonce32)`.
5. Prepare with `POST /api/games/prepare` (creator) or `POST /api/games/{gameId}/join/prepare` (joiner).
6. Sign only the funding inputs that have an empty signature script. Leave covenant inputs exactly as prepared. Verify the signed JSON differs only in signature scripts.
7. Submit with `POST /api/games/submit` or `POST /api/games/{gameId}/join/submit`.
8. Poll `GET /api/games/{gameId}`, then prepare and submit each reveal. The second reveal settles.

Submissions are idempotent per `preparedHash`; re-submitting the same preparation returns the same transaction id. A preparation expires, so re-prepare if a submit returns `PREPARATION_NOT_FOUND`.

## Errors and retries

Every failure uses one envelope:
`{ "error": "CODE", "message": "...", "requestId": "...", "retry": "AFTER_REFRESH" }`.

`error` is stable and machine-readable. `requestId` correlates with server logs and the `X-Request-Id` header. `retry: "AFTER_REFRESH"` means the state moved or the chain has not settled it yet: refetch the game or match, then retry.

Retryable codes include `REVEAL_WAITING`, `ACTION_PENDING`, `ACTION_NOT_CONFIRMED`, `GAME_NOT_CONFIRMED`, `GAME_NOT_OPEN`, `CREATION_PENDING`, `CHAIN_NOT_READY`, `BOT_BUSY`, and `BOT_NOT_READY`. Do not retry `400` validation errors unchanged. Respect `Retry-After` on `429` and `503`.

## Trust

- The backend never holds a player key and never decides an outcome.
- The covenant is the authority. Verify the prepared transaction before signing.
- The pinned covenant artifact and toolchain pins are at https://kasodds.com/covenant/pins.json and https://kasodds.com/covenant/kasodds.template.artifact.json.

- [Feedback](https://kasodds.com/api/feedback): anonymous, rate-limited.
- [Health](https://kasodds.com/healthz) and [readiness](https://kasodds.com/readyz).