> ## 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.

# Quickstart

> Go from a new account to a settled sandbox bet on your own page: create your casino, deploy your game server to Cloudflare, sign session tokens and embed the games.

This guide takes you from sign-up to a settled bet on a page of your own site. You stay in sandbox mode, where the game server holds test balances for your players, so you need no wallet yet. The sandbox is free.

You need:

* A Cloudflare account you can sign in to.
* A page you control, on your site or on a local development server.
* A backend route that knows which player is signed in. The examples use Node.js.

**1. Create your account and your casino**

Sign up at [app.kinematic.run/sign-up](https://app.kinematic.run/sign-up) with your name, your work email and a password, and open the link in the confirmation email: it signs you in. Or select **Continue with Google**, which needs no confirmation email.

The dashboard asks `What is your casino called?`. Enter the **Casino name** and the **Website** your players visit, for example `Lucky Star` and `luckystar.example`, and select **Continue**. Your casino gets an ID made from its name, such as `lucky-star`. It never changes, and your session tokens carry it.

The first-run steps follow: **Your team**, **Size and price**, **Currencies**, **Games**, **Look** and **Done**. In sandbox, **Currencies** has `TEST` chosen for you: it is the sandbox's play money, and each test player starts with 100,000.00 TEST. You can skip **Your team** with **I'll do it myself** and **Look** with **Keep the default look**. The last page, `Your sandbox is ready`, finishes the setup. See [Create your casino](https://docs.kinematic.run/dashboard/create-casino.md).

**2. Check your allowed origins and session issuer**

Open **Settings** and find **Players and sessions**. The dashboard filled both fields from the website you entered:

* **Allowed origins** lists the pages that can show the games. For `luckystar.example` it holds `https://luckystar.example` and `https://www.luckystar.example`.
* **Session issuer** is the value your tokens carry as `iss`, here `https://luckystar.example`.

If you test on another page, add its origin to **Allowed origins**, one per line, for example `https://staging.luckystar.example` or `http://localhost:5173`. An origin is the scheme, host and port, with no path and no trailing slash. Sandbox accepts `http` origins; live accepts only `https`. Select **Save**. See [Settings](https://docs.kinematic.run/dashboard/settings.md#players-and-sessions).

**3. Deploy your game server**

Open **Game server**. Under **Connect Cloudflare**, select **Connect Cloudflare** and approve the access on Cloudflare's own page. You come back to the dashboard, which shows `Cloudflare is connected.`

Under **Choose where it runs**, choose your **Cloudflare account**, keep the suggested **Worker name** (`og-rgs-lucky-star`), choose **workers.dev** as the **Address** and leave **Update automatically** on. Select **Deploy**. The deploy takes about a minute; keep the page open until it finishes.

The game server's card then shows its address. Select **Copy the address** to copy it, for example `https://og-rgs-lucky-star.luckystar.workers.dev`. To use a hostname of your own instead, see [Game server](https://docs.kinematic.run/dashboard/game-server.md#choose-an-address).

**4. Store your secrets**

Open **Integration** and go to **Secrets**. Have your secret manager open, select **Reveal secrets**, then **Reveal** in `Reveal your secrets?`. The page shows a `.env` block with `SESSION_SECRET` and `WALLET_SECRET`. This is the only time you see their values.

Put both into your secret manager and your backend's environment: `SESSION_SECRET` signs session tokens now, and `WALLET_SECRET` checks your game server's wallet calls once you go live. Afterwards the page shows only each secret's fingerprint and the date it was shown. Only owners and admins can reveal the secrets. If you lose one, write to [hello@kinematic.run](mailto:hello@kinematic.run).

> [!WARNING]
>
> Anyone with `SESSION_SECRET` can sign in as any of your players. Never put it in code, in a browser, in a log or in a chat with a coding agent.

**5. Optional: give the next two steps to a coding agent**

At the top of **Integration**, **Instructions for your coding agent** holds the next two steps with your casino's values filled in, and no secrets. Select **Copy instructions** and paste them into the agent you use in your site's repository. See [Use an AI agent](https://docs.kinematic.run/agents.md).

**6. Sign session tokens on your backend**

The element asks your backend for a session token when it connects, and again before each token expires. Add this module to your backend:

```js session-token.mjs theme={null}
import { createHmac } from "node:crypto";

const SESSION_SECRET = process.env.SESSION_SECRET;
const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");

export function sessionToken({ player, currency, publicKey }) {
  const claims = {
    sub: player, // your stable player ID: 1 to 128 letters, digits, - or _
    tenant: "lucky-star", // your casino ID
    iss: "https://luckystar.example", // your session issuer, exactly as in Settings
    aud: "og-rgs-v1",
    currency, // one of your currencies, such as "TEST"
    exp: Math.floor(Date.now() / 1000) + 900, // at most one hour ahead
  };
  // The player's device key: the session may sign bets only with this key.
  if (publicKey) claims.cnf = { jwk: { kty: "OKP", crv: "Ed25519", x: publicKey } };
  const unsigned = encode({ alg: "HS256", typ: "JWT" }) + "." + encode(claims);
  return unsigned + "." + createHmac("sha256", SESSION_SECRET).update(unsigned).digest("base64url");
}
```

Then answer `POST /api/game-session` behind your own login, with the token as plain text. In any framework that hands you a Fetch API `Request`:

```js game-session.mjs theme={null}
import { sessionToken } from "./session-token.mjs";

// `player` is the player your own login authenticated for this request.
export async function gameSession(request, player) {
  const { publicKey } = await request.json(); // absent on the element's first call
  const token = sessionToken({ player: player.id, currency: "TEST", publicKey });
  return new Response(token, {
    headers: { "content-type": "text/plain", "cache-control": "no-store" },
  });
}
```

The **Sign session tokens** step on **Integration** shows the claims with your casino ID and issuer, under **Session token claims**. [Session tokens](https://docs.kinematic.run/integrate/session-tokens.md) explains each claim and the device key.

**7. Put the games on your page**

The **Put the games on your page** step on **Integration** shows this code, under **Your page**, with your game server's origin, your element's tag and your first game:

```html theme={null}
<og-game game="dice" controls></og-game>
<script type="module">
  import { connect } from "https://og-rgs-lucky-star.luckystar.workers.dev/element/v1/loader.js";
  connect(document.querySelector("og-game"), {
    token: ({ publicKey }) =>
      fetch("/api/game-session", { method: "POST", body: JSON.stringify({ publicKey }) }).then((r) => r.text()),
  });
</script>
```

Copy it into your page. If your page sends a `Content-Security-Policy` header, merge the directives under **Content Security Policy, for pages that send one**, below the code. See [Content Security Policy](https://docs.kinematic.run/integrate/csp.md).

**8. Place a sandbox bet**

Sign in to your site as a player and open the page. The game shows the player's sandbox balance: 100,000 of the currency, such as 100,000.00 TEST. Press **BET**.

The result appears on the game's screen and the balance moves. Open **Provably fair** in the game's toolbar to see the bet's proofs checked in your browser. Once the bet is recorded on Solana devnet, its record appears there too.

The bet shows on the dashboard's [Live](https://docs.kinematic.run/dashboard/live-monitor.md) page. Once your game server reports it, the **Put the games on your page** and **Sign session tokens** steps on **Integration** show **Done**.

> [!TIP]
>
> Your page, your session endpoint and your game server work together. Every later step builds on these three.

## Next steps

> [card] [Implement your wallet](https://docs.kinematic.run/integrate/wallet.md)
>
> Build the debit, credit and balance endpoints a live game server calls.

> [card] [Make it look like your site](https://docs.kinematic.run/dashboard/appearance.md)
>
> Take a theme from your site, set your logo and rename the element.

> [card] [Test before you go live](https://docs.kinematic.run/integrate/testing.md)
>
> Check your integration in sandbox, then run the wallet check before live.

> [card] [Go live](https://docs.kinematic.run/dashboard/go-live.md)
>
> Switch your casino to live mode.


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