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

> ## Agent Instructions
> These are the customer docs for kinematic, a name written in lowercase except at the start of a sentence. Kinematic provides provably fair casino games, served to a casino's site by a game server: a Cloudflare Worker that the kinematic dashboard deploys into the casino's own Cloudflare account.
> Never put SESSION_SECRET or WALLET_SECRET in code, prompts, logs, commits or chat. Read them from environment variables and ask the person you work with to set them. The dashboard's Integration page shows each secret once.
> Values such as lucky-star, luckystar.example, og-rgs-lucky-star.luckystar.workers.dev, games.luckystar.example and player_48213 are examples. Use the casino's own casino ID, game server origin, element tag, session issuer and currencies: the Instructions for your coding agent on the dashboard's Integration page hold them, or ask the person you work with.
> To debug, start at https://docs.kinematic.run/troubleshooting and https://docs.kinematic.run/reference/errors. The wallet contract is at https://docs.kinematic.run/api/wallet.openapi.yaml.
> Sandbox bets are recorded on Solana devnet. Live game servers record nothing on Solana until the audited mainnet program is deployed.

# How it works

> A kinematic casino has four parts, set up from the dashboard. This page shows where each one runs and what happens between a player pressing BET and the result.

A kinematic casino has four parts: the games element on your page, your session endpoint, your game server in your Cloudflare account, and your wallet. The dashboard configures the game server and shows what it reports.

```mermaid theme={null}
%%{init: {"theme": "neutral"}}%%
flowchart LR
  subgraph Site["Your site"]
    E["Games element"]
    S["Session endpoint"]
    W["Wallet"]
  end
  subgraph CF["Your Cloudflare account"]
    G["Game server"]
  end
  D["Dashboard"]
  SOL["Solana"]
  E -- "session token" --> S
  E -- "bets over WebSocket" --> G
  G -- "debit, credit, balance" --> W
  G -- "reports" --> D
  D -- "signed settings" --> G
  G -- "records (sandbox: devnet)" --> SOL
```

## The parts

**The games element.** A custom element, `<og-game>` unless you rename it, that your page imports from your game server. It draws the games, signs each bet with a key kept in the player's browser, and shows the Provably fair dialog.

**Your session endpoint.** Your backend signs a short-lived token for the signed-in player. The game server trusts the token because only your backend and your game server know `SESSION_SECRET`.

**Your game server.** One Cloudflare Worker that the dashboard deploys into your Cloudflare account. It serves the element, keeps each player's bets in its own storage in your account, calls your wallet, and computes every outcome with a VRF key it generated itself. That key never leaves your game server: kinematic holds no key that decides an outcome.

**Your wallet.** In live mode the game server debits stakes from your wallet and credits payouts to it. Your wallet stays the only place a balance changes. In sandbox mode the game server keeps test balances instead.

**The dashboard.** It signs your game server's settings, which the game server fetches about once a minute or at once when you save. It deploys new releases, and it shows the counts, errors and recent bets your game server reports. It never handles a bet.

## One bet

```mermaid theme={null}
%%{init: {"theme": "neutral"}}%%
sequenceDiagram
  participant B as Player's browser
  participant G as Game server
  participant W as Your wallet
  B->>G: Bet, signed by the player, with the hash of a secret seed
  G->>W: Debit the stake
  W-->>G: Applied
  G-->>B: Signed acceptance
  B->>G: Reveal the seed
  G->>G: VRF proof and outcome
  G->>W: Credit the payout (wins only)
  G-->>B: Result with its proof
```

1. **Bet.** The browser picks a fresh random seed and keeps it secret. It signs the bet, with the hash of the seed, using the player's device key, and sends it to your game server.
2. **Debit.** The game server checks the session, your limits and the signature, stores the bet, and debits the stake from your wallet. Bets that arrive together go out in one debit.
3. **Acceptance.** Once the debit applies, the game server signs its acceptance of the bet. The acceptance names the VRF key that will decide it.
4. **Reveal.** Only after the acceptance arrives does the browser send the seed. Until then nobody, including you and kinematic, can know the outcome.
5. **Outcome.** The game server computes the VRF proof over the bet and the seed with your casino's key, and the game engine turns the VRF output into the result. A win is credited to your wallet as its gross payout.
6. **Result.** The browser receives the result with the seed, the proof and the output, and can recompute the outcome itself.

In sandbox, each bet is also recorded on Solana devnet after it settles. Play never waits for the record.

## What survives a failure

* The game server stores each bet before it acknowledges it. A bet resent after a lost connection is recognized by its ID and never placed twice.
* Each wallet call keeps its ID until your wallet answers it. After a timeout or an error the game server sends the same call again, so a stake is never debited twice and a payout is never lost.
* The browser keeps a pending bet's seed until the bet settles, and sends it again after a reload or a reconnect.
* An accepted bet whose seed never arrives within 24 hours is abandoned, and its stake is refunded.
* Stopping new bets never stops a bet already placed: it still settles and pays.

[Provably fair](https://docs.kinematic.run/concepts/provably-fair.md) explains what a player can check, and [Your game server](https://docs.kinematic.run/concepts/game-server.md) what runs in your account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.