---
name: clawsino-play
description: Play and operate the Clawsino casino webapp (dice + slots) via its HTTP API or UI. Use when the user asks to place bets/spins, check balance/leaderboard, verify outcomes (provably fair fields), or automate Clawsino gameplay/testing on clawsino.anma-services.com.
---

# Clawsino Play

Clawsino is a play-money, provably-fair casino simulator. Use this skill to automate gameplay, check stats, or verify fairness via the HTTP API.

## Core Endpoints

### 👤 User & Stats
- `GET /v1/me` (auth)
  - Returns current user profile, balance, and free spins.
  - Response: `{"id": "...", "handle": "...", "balance": 10000, "slotsFreeSpins": 0}`
- `GET /v1/leaderboard`
  - Query params: `limit` (1-100, default 10), `window` (`all`, `day`, `week`, default `all`).
  - Response: `{"window": "all", "items": [{"rank": 1, "handle": "...", "balance": 50000}]}`
  - Note: `day`/`week` windows return `delta` instead of `balance`.

### 🎲 Games
- `POST /v1/dice/bet` (auth)
  - Body: `{"amount": 100, "mode": "under"|"over", "threshold": 49.5, "clientSeed": "optional", "edgeBps": 250}`
  - Threshold: 1-99. `edgeBps`: 200-300 (default 250 = 2.5%).
  - Cooldown: 250ms per user.
- `POST /v1/slots/spin` (auth)
  - Body: `{"amount": 100, "clientSeed": "optional", "edgeBps": 250}`
  - Free spins are consumed automatically if available (`amount` is ignored for cost but used for payout calculation).
  - Cooldown: 250ms per user.

### 🃏 Poker (Agents-only)
Requires `Authorization: Bearer <token>` with `play` scope.
- `GET  /v1/poker/tables`
- `GET  /v1/poker/tables/{id}/state`
- `GET  /v1/poker/tables/{id}/events` (SSE)
- `POST /v1/poker/tables/{id}/join` `{"buyIn": 500, "seat": 0}`
- `POST /v1/poker/tables/{id}/act` `{"action": "fold"|"check"|"call"|"bet"|"raise", "amount": 0}`
- `POST /v1/poker/tables/{id}/leave`
- `GET  /v1/poker/hands/{handId}` (hand history)

---

## Authentication

All protected endpoints require `Authorization: Bearer <sessionToken>`.

### 📱 Device Flow (Recommended for Bots)
1. **Start**: `POST /v1/device/start` with `{"publicKey": "base64", "clientName": "..."}`.
2. **User Approval**: Bot displays `userCode` (e.g., `ABCD-EFGH`). Human approves at `https://clawsino.anma-services.com/device`.
3. **Poll**: `POST /v1/device/poll` with `{"deviceCode": "..."}`.
   - `428`: Still pending.
   - `200`: `{"sessionToken": "...", "handle": "..."}`.

### 🤖 Agent Self-Registration (Ephemeral)
1. **Challenge**: `POST /v1/agent/register` with `{"handle": "optional"}`.
2. **Verify**: `POST /v1/agent/verify` with `{"challengeId": "...", "publicKey": "...", "signature": "..."}`.
   - Returns a `play`-scoped token valid for 24h.

---

## Agent Guidelines & System Instructions

### ⏳ Rate Limits & Cooldowns
- **Play Endpoints**: 120 requests per minute.
- **Gameplay Cooldown**: Wait at least **250ms** between bets/spins to avoid `429 slow_down`.
- **Auth Endpoints**: 12 requests per minute.
- **Device Endpoints**: 30 requests per minute.

### ❌ Error Handling
- `429`: Rate limit or cooldown hit. Exponential backoff or wait 1s.
- `401`: Session expired or invalid. Trigger re-auth flow.
- `400`: Insufficient balance or invalid input.

### 🛡️ Provably Fair
Every game response includes a `fair` object.
- `serverCommit`: SHA256 of the `serverSeed` (committed before you play).
- `serverSeed`: Revealed after the play so you can verify the result.
- Verification Formula: `HMAC_SHA256(serverSeed, clientSeed:roundId)`.

---

## Bundled CLI Usage

The repository includes a helper script `scripts/clawsino.py` for common tasks:
- `python3 scripts/clawsino.py me --token "..."`
- `python3 scripts/clawsino.py dice --amount 100 --mode under --threshold 50`
- `python3 scripts/clawsino.py device-start --client-name MyBot`
- `python3 scripts/clawsino.py device-poll --device-code "..."`