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

# Use an AI agent

> Copy the dashboard's instructions for your coding agent, keep the secrets yourself, check them by fingerprint, and give the agent these docs as Markdown, llms.txt or an MCP server.

A coding agent can do most of an integration in your codebase: the embed, the session endpoint, your Content Security Policy and, for a live casino, the wallet endpoints. The dashboard writes the instructions for it, with your casino's values filled in, and these docs are published in forms agents read directly.

## Copy the instructions from the dashboard

At the top of the **Integration** page, **Instructions for your coding agent** holds a Markdown text for your agent. As the page says: `Paste them into the agent you use. They cover every step below with your casino's values, and they hold no secrets.`

1. Choose what the instructions cover: **All steps**, **Embed**, **Session tokens** or **Wallet**.
2. Select **Copy instructions**. The text of the scope you chose goes to your clipboard.
3. Paste it into the agent you use, in your site's repository.

The dashboard fills the text in when you open the page, so copy it again after you change your settings or deploy another game server.

### What the instructions contain

With **All steps**, the text has these sections, in order:

| Section | What it holds |
| - | - |
| `# Lucky Star: integrate the casino games` | The task, and an instruction to read [llms-full.txt](https://docs.kinematic.run/llms-full.txt) first and to follow the docs over anything the agent remembers. |
| `## Values from the kinematic dashboard` | Your casino ID, game server origin, element tag, games, session issuer, currencies with their scales, allowed origins, mode and wallet URL. A value you have not set yet becomes an instruction to ask you, such as `Wallet URL: not set yet. Ask me for it; I set it on the dashboard's Settings page.` |
| `## Secrets` | The names `SESSION_SECRET` and `WALLET_SECRET`, the rules for handling them, and their fingerprints. Never their values. |
| `## 1. Put the games on a page` | The embed with your values and an `onError` handler, the rules for the element, and your Content Security Policy directives. |
| `## 2. Sign session tokens` | `POST /api/game-session`, the claims with your values, and a Node signer with no dependencies. |
| `## 3. Connect the wallet` | The three endpoints under your wallet URL, the signature check, idempotency, receipts and retries. |
| `## Check your work` | The checks the agent runs, and the ones it asks you to run on the dashboard. |
| `## Docs` | The docs pages for each step. |

**Embed**, **Session tokens** and **Wallet** hold the values and the step for that part only. **Embed** has no secrets section; **Session tokens** names only `SESSION_SECRET`, and **Wallet** only `WALLET_SECRET`.

## Keep the secrets yourself

Your casino has two secrets: `SESSION_SECRET`, which signs session tokens, and `WALLET_SECRET`, which checks your game server's wallet calls. The **Integration** page shows their values once, when an owner or an admin selects **Reveal secrets**.

* Put them in your servers' environment yourself, through your secret manager or your hosting settings.
* Never paste them into a chat with an agent, a prompt, a ticket or a commit.

The instructions tell the agent the same: read the secrets from the environment, never ask you to paste one into the chat, never hard-code, log, print or commit one, and stop and name any variable that is missing.

### Check a secret by its fingerprint

The agent checks that a variable holds the right secret without seeing it, by computing its fingerprint: the first 12 hex digits of HMAC-SHA256 over the text `kinematic-secret-fingerprint`, keyed with the secret. The instructions give the fingerprint of each secret, and the **Secrets** table on **Integration** shows the same values.

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

const fingerprint = (secret) => createHmac("sha256", secret).update("kinematic-secret-fingerprint").digest("hex").slice(0, 12);

for (const name of ["SESSION_SECRET", "WALLET_SECRET"]) {
  const secret = process.env[name];
  console.log(name, secret ? fingerprint(secret) : "is not set");
}
```

The script prints only fingerprints. If one differs from the dashboard's, the variable holds another value.

## When the agent finishes

The instructions end with `When you finish, list what you changed, the environment variables I must set and where, and the checks you could not run.` Read that list, then:

1. Set the environment variables it names, yourself.
2. Run the checks it could not run, such as opening the page in a browser and pressing **BET**.
3. Confirm that the bet appears on [Live](https://docs.kinematic.run/dashboard/live-monitor.md).
4. Once your casino is in live mode with your wallet URL, run **Check my wallet** on **Integration**. See [Test your integration](https://docs.kinematic.run/integrate/testing.md#check-my-wallet).

### Review what the agent wrote

Before you deploy, check these points in its changes:

* The session endpoint answers only for a signed-in player, and `sub` is that player's stable ID.
* Tokens expire within an hour, and the endpoint passes the element's `publicKey` into `cnf` unchanged.
* No secret appears in code, logs, client bundles or the repository.
* The wallet verifies every signature over the raw body before it parses JSON.
* The wallet records each receipt in the same transaction as the balance change, and answers a repeated ID with the original receipt.

Then run the checks in [Test your integration](https://docs.kinematic.run/integrate/testing.md).

## Give your agent the docs

| Form | Address | Use it for |
| - | - | - |
| llms.txt | [docs.kinematic.run/llms.txt](https://docs.kinematic.run/llms.txt) | An index of every page with its description. |
| llms-full.txt | [docs.kinematic.run/llms-full.txt](https://docs.kinematic.run/llms-full.txt) | Every page in one Markdown file. |
| Markdown pages | Add `.md` to any page's address, such as [docs.kinematic.run/integrate/wallet.md](https://docs.kinematic.run/integrate/wallet.md), or request it with `Accept: text/markdown`. | One page at a time. |
| MCP server | `https://docs.kinematic.run/mcp` | Search and read these docs from the agent while it works. |
| Skill | `npx skills add https://docs.kinematic.run` | Install these docs as a skill in agents that support skills. |
| OpenAPI | [docs.kinematic.run/api/wallet.openapi.yaml](https://docs.kinematic.run/api/wallet.openapi.yaml) | The wallet contract as OpenAPI 3.1. |

The menu at the top of every page copies the page as Markdown, opens it in ChatGPT, Claude or Perplexity, and connects the MCP server to Cursor or VS Code.

### Connect the MCP server

```bash Claude Code theme={null}
claude mcp add --transport http kinematic https://docs.kinematic.run/mcp
```

```json Cursor (mcp.json) theme={null}
{
  "mcpServers": {
    "kinematic": {
      "url": "https://docs.kinematic.run/mcp"
    }
  }
}
```

```json VS Code (.vscode/mcp.json) theme={null}
{
  "servers": {
    "kinematic": {
      "type": "http",
      "url": "https://docs.kinematic.run/mcp"
    }
  }
}
```

The server can search these docs, read pages and report a page that looks wrong. It cannot see your casino, your settings or your secrets.

## When something fails

The dashboard's instructions build an integration. To have an agent find the cause of a problem in an existing one, give it this prompt:

```text Debugging prompt wrap theme={null}
Our kinematic integration has a problem. Read https://docs.kinematic.run/troubleshooting and https://docs.kinematic.run/reference/errors, then find the cause in our code and fix it.

Ask me for what I see if you cannot see it yourself: the browser console's errors, the game server's answer in the Network tab, or the sentence the kinematic dashboard shows.

Check our session endpoint, our embed, our Content Security Policy and, if we are live, our wallet endpoints against the docs. Do not print, log or change any secret. If the cause is a setting in the kinematic dashboard, tell me which setting to change instead of guessing.
```

## Agents in your browser

When you are signed in to the dashboard in a browser that supports [WebMCP](https://webmachinelearning.github.io/webmcp), an agent in that browser can call these tools on your casino's pages:

| Tool | What it returns |
| - | - |
| `get_casino_status` | Your casino's name, ID and mode, the launch steps, each game server's address, state, release and last report, and your return to player. |
| `get_integration_instructions` | The instructions the **Integration** page copies, for all three steps or for `embed`, `session` or `wallet`. They contain no secrets. |
| `find_bet` | A bet by its ID, or a Solana transaction by its signature, as the lookup on the **Live** page shows it. |
| `list_pages`, `open_page` | Your casino's pages, and the page the agent asks to open. |

The tools change nothing in your casino, and every member of your team can use them. No browser turns WebMCP on by default yet; in Chrome, turn on `chrome://flags/#enable-webmcp-testing`.


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