casino/docs/API.md

# Quantum Arcade API

Everything the browser client does, it does over this API. There is no private
back channel — you can write a bot that plays exactly as well as a human, and
nothing in the protocol is reserved for the official client.

Base URL is wherever the server is listening, e.g. `http://arcade.lan:8080`.
All request and response bodies are JSON. Amounts are **millisatoshis**
(`1 sat = 1000 msat`) and always integers.

## Authentication

Identity is an ed25519 keypair. You prove ownership by signing a server-issued
challenge; there is no password and nothing to register.

### 1. Request a challenge

```
POST /api/auth/challenge
{ "pubkey": "<64 hex chars>" }

→ { "challenge": "<64 hex chars>" }
```

The challenge is single-use and expires after two minutes.

### 2. Sign it and verify

Sign the **raw 32 bytes** of the challenge (decode the hex first — do not sign
the hex string).

```
POST /api/auth/verify
{ "pubkey": "<hex>", "signature": "<128 hex chars>", "nickname": "botto" }

→ { "token": "<hex>", "balance_msat": 0 }
```

Pass the token on every subsequent request:

```
Authorization: Bearer <token>
```

Tokens live in memory, so a server restart signs everyone out. Just
re-authenticate — it costs two requests and no human interaction.

## Balance and history

```
GET /api/balance
→ { "balance_msat": 4500000 }
```

```
GET /api/history
→ { "entries": [
     { "Kind": "payout", "AmountMsat": 2500000,
       "BalanceBefore": 2000000, "BalanceAfter": 4500000,
       "RoundID": 412, "CreatedAt": "..." }
   ] }
```

Every balance change has exactly one entry explaining it. Nothing moves without
a record.

## Peer-to-peer transfers

```
POST /api/transfer
{ "to_pubkey": "<hex>", "amount_msat": 100000 }

→ { "balance_msat": 4400000 }
```

Instant and internal. Fails with 400 if you cannot cover it.

## Crash games

Three rooms share one engine: `rocket`, `orbital`, `tower`.

### Watch the state

```
GET /api/games
→ { "rooms": [ {
      "round_id": 412,
      "game": "rocket",
      "state": "betting_open",     // betting_open | locked | running | settled
      "tick": 0,
      "multiplier": "1.000000",
      "commitment": "<hex>",       // published before betting opens
      "server_seed": "<hex>",      // present only once settled
      "crash_point": "3.472190",   // present only once settled
      "players": [ { "nickname": "botto", "pubkey": "<hex>",
                     "stake_msat": 100000, "cashed_out": "2.500000",
                     "auto": true, "payout_msat": 250000 } ],
      "next_phase_in_seconds": 12.4
    } ] }
```

For a live feed instead of polling, open a WebSocket to `/ws/{game}` and you
will receive the same object on every tick.

### Place a bet

Only during `betting_open`, once per round.

```
POST /api/bet
{ "game": "rocket",
  "stake_msat": 100000,
  "nickname": "botto",
  "auto_cashout": 2.5 }        // optional; omit or 0 for no target

→ { "balance_msat": 4300000 }
```

The stake leaves your balance immediately. `auto_cashout` must be above 1.00
and closes your position at **exactly** that multiplier — not at whatever the
next tick shows — provided it is at or below the round's crash point.

Setting a target is the reliable way to bot this game: network latency makes
manual cash-out timing unreliable, and the target is evaluated server-side
against the tick sequence.

### Cash out manually

Only during `running`.

```
POST /api/cashout
{ "game": "rocket" }

→ { "cashed_out_at": "2.317445" }
```

Payment lands at settlement, a moment later.

## Scratch tickets

```
GET /api/scratch/catalog
→ { "tickets": [ {
      "id": "nebula-nine", "name": "Nebula Nine", "cells": 9,
      "rtp_bp": 9900,
      "odds": [ { "tier": "Double", "payout_bp": 20000,
                  "weight": 155000, "denominator": 1000000,
                  "one_in": 6 } ]
    } ] }
```

The odds table is generated from the same data that produces outcomes, so it
cannot drift from reality. `rtp_bp` is in basis points: 9900 is 99%.

```
POST /api/scratch/play
{ "ticket_id": "nebula-nine", "stake_msat": 10000 }

→ { "outcome": { "tier_name": "Double", "payout_bp": 20000,
                 "payout_msat": 20000, "roll": 481203,
                 "cells": [2,5,2,0,2,4,1,3,5] },
    "proof": { "commitment": "...", "server_seed": "...",
               "participants": ["..."], "nonce": 91,
               "round_seed": "..." },
    "balance_msat": 4310000 }
```

Resolves immediately. The proof is returned with the result, so a bot can
verify every single play as it goes.

## Verification

```
GET /api/verify/{roundID}
→ { "round_id": 412, "game": "rocket", "nonce": 412,
    "commitment": "<hex>", "server_seed": "<hex>",
    "client_seed": "<hex>", "crash_point": 14914127396,
    "participants": ["<hex>", "<hex>"] }
```

Returns 409 while a round is still open — the seed stays sealed until
settlement, otherwise you could compute the outcome before betting closed.

To check it yourself:

1. `SHA256(server_seed)` must equal `commitment`.
2. `client_seed` must equal `SHA256(` each participant pubkey, each prefixed by
   its 4-byte big-endian length, concatenated in join order `)`.
3. The round seed is `HMAC-SHA256(server_seed, client_seed || uint64be(nonce))`.
4. `crash_point` is derived from that seed. It is Q32.32 fixed-point: divide by
   2³² to get the multiplier.

## Health

```
GET /api/health
→ { "status": "ok", "ledger_sum_msat": 0 }
```

`ledger_sum_msat` sums every account. Because each transaction balances to
zero, it must always be zero. Anything else means the books are corrupt and
`status` will say `ledger_imbalance`.

## Errors

Failures return the appropriate status with `{ "error": "..." }`. Common cases:

| Status | Meaning |
|---|---|
| 400 | Bad request, insufficient funds, betting closed, already in this round |
| 401 | Missing or unknown token |
| 404 | No such game or ticket |
| 409 | Round has not settled; the seed is still sealed |

## A complete bot

Plays every rocket round with a 2× target and verifies each result.

```python
import time, requests
from nacl.signing import SigningKey   # pip install pynacl

BASE = "http://arcade.lan:8080"
key  = SigningKey.generate()          # persist this to keep your balance
pub  = key.verify_key.encode().hex()

chal = requests.post(f"{BASE}/api/auth/challenge", json={"pubkey": pub}).json()
sig  = key.sign(bytes.fromhex(chal["challenge"])).signature.hex()
tok  = requests.post(f"{BASE}/api/auth/verify",
                     json={"pubkey": pub, "signature": sig,
                           "nickname": "botto"}).json()["token"]
S = requests.Session()
S.headers["Authorization"] = f"Bearer {tok}"

seen = None
while True:
    room = next(r for r in S.get(f"{BASE}/api/games").json()["rooms"]
                if r["game"] == "rocket")

    if room["state"] == "betting_open" and room["round_id"] != seen:
        r = S.post(f"{BASE}/api/bet", json={
            "game": "rocket", "stake_msat": 10_000,
            "auto_cashout": 2.0, "nickname": "botto"})
        if r.ok:
            seen = room["round_id"]
            print(f"round {seen}: in, balance {r.json()['balance_msat']}")

    if room["state"] == "settled" and room.get("server_seed"):
        print(f"  crashed at {room['crash_point']}")

    time.sleep(1)
```

Verifying a settled round, using only published values:

```python
import hashlib, hmac, struct

def verify(round_id):
    r = requests.get(f"{BASE}/api/verify/{round_id}").json()
    seed = bytes.fromhex(r["server_seed"])

    assert hashlib.sha256(seed).hexdigest() == r["commitment"], "bad commitment"

    h = hashlib.sha256()
    for p in r["participants"]:
        pk = bytes.fromhex(p)
        h.update(struct.pack(">I", len(pk)) + pk)
    assert h.hexdigest() == r["client_seed"], "bad client seed"

    round_seed = hmac.new(seed,
                          bytes.fromhex(r["client_seed"]) +
                          struct.pack(">Q", r["nonce"]),
                          hashlib.sha256).digest()
    print("verified:", round_seed.hex(),
          "crash", r["crash_point"] / 2**32)
```

## Rate and fairness notes

There is no rate limiting, because this runs on a private network among people
who know each other. If you point it at a hostile network, add some.

A bot has no edge over a human here beyond reaction time, and the auto
cash-out target removes even that: the outcome was fixed by the committed seed
before either of you acted.