# In-person check-ins with a code (/docs/build/station-codes)



Print a QR code at each station of an event, such as a booth, a door or a stage. A member scans it with their phone's camera, which opens your app's scan page, and the quest completes for that station. Members need no wallet and pay nothing.

Each station has a secret code that Domino keeps, and the printed QR code carries it. Domino checks the code, limits guessing, and pays each member once per station. Your app serves the scan page, and Domino draws the QR codes for it.

This is experimental: a minor release can change it. For members who check in with a mobile wallet instead, see [In-person quests with Solana Pay](/docs/build/solana-pay).

## What members see [#what-members-see]

1. The member scans the station's QR code with their phone's camera, and it opens your app's scan page.
2. If they aren't signed in, the page asks them to sign in first, then checks them in.
3. The page says "You're checked in at North gate", and the quest shows as complete for that station.

```mermaid
sequenceDiagram
    participant M as Member's phone
    participant A as Your scan page
    participant D as Domino
    M->>A: Open the QR code's link
    A-->>A: Take the code out of the address bar
    A-->>M: Sign in, if needed
    A->>D: Check in with the station's code
    D-->>D: Check the code, complete the station
    D-->>A: The attempt
    A-->>M: Checked in
```

## Set it up [#set-it-up]

### 1. Declare the code stations [#1-declare-the-code-stations]

List the stations on the quest, each with a key, a label and `proof: "code"`, and optional opening and closing times. Deploy it to test. [Stations a code proves](/docs/build/wallets#stations-a-code-proves) has each rule.

> [!DEV]
> The quest must be one members check in to: `trigger: manual()`, without input. Use `completion: perStation()` so each member completes each station once.
>
> ```ts
> import {
>   defineLedger,
>   defineQuest,
>   manual,
>   perStation,
>   points,
>   settings,
> } from "@domino-sdk/relay/authoring"
>
> const community = defineLedger({ key: "community", name: "Community points" })
>
> export default defineQuest({
>   key: "booth-check-in",
>   title: "Check in at our booths",
>   settings: settings.object({}),
>   trigger: manual(),
>   completion: perStation(),
>   stations: [
>     { key: "north-gate", label: "North gate", proof: "code" },
>     {
>       key: "keynote",
>       label: "Keynote stage",
>       proof: "code",
>       opensAt: Date.parse("2027-11-12T09:00:00Z"),
>       closesAt: Date.parse("2027-11-12T18:00:00Z"),
>     },
>   ],
>   rewards: [points(community, 20)],
> })
> ```
>
> A station's key is in its printed QR code, so keep it once the codes are printed. The `station-codes` snippet installs this quest with a scan page: `pnpm dlx shadcn@4.21.0 add https://snippets.domino.run/r/station-codes.json`.

### 2. Set each station's code [#2-set-each-stations-code]

Codes aren't part of the quest. Each environment keeps its own code for each station, so test codes never check anyone in to live, and a code you print for live stays out of your test project.

**In Console**, open the quest and select the environment. Its **Check-in stations** section shows **Code: Set** or **Code: Not set** on each code station, never the code itself. With publish permission:

1. Choose **Set code**, then **Generate code**. Domino makes a code and shows it once, with **Copy secret**. Or choose **Choose a code** and type one, 6 to 64 letters, digits, `-` or `_`.
2. Once a station has a code, the menu reads **Rotate code**. **Clear code** removes it, and the station takes no check-ins in that environment until it gets another.

> [!DEV]
> From a terminal, `domino quests stations code generate booth-check-in north-gate` makes a code and prints it this once, and `printf %s "$CODE" | domino quests stations code set booth-check-in north-gate` sets one you chose. The code commands use test unless you pass `--environment live`. In code, `management.quests.stations.generateCode(quest, station)`, `setCode(quest, station, { code })` and `clearCode(quest, station)`. [Stations a code proves](/docs/build/wallets#stations-a-code-proves) has the details.

### 3. Serve the scan page from your app [#3-serve-the-scan-page-from-your-app]

The scan page is the page of your app the QR codes open, such as `https://your-app.example/check-in`. It reads the station and code from the link, signs the member in if needed, and checks them in. It takes the code out of the address bar as soon as it reads it, so a screenshot of the page or a link someone shares doesn't show it.

> [!DEV]
> In a React app that signs members in through Domino, `useStationCheckIn()` from `@domino-sdk/relay/react` runs the page. Render it inside `RelayProvider`:
>
> ```tsx
> import type { ReactNode } from "react"
> import { useStationCheckIn } from "@domino-sdk/relay/react"
>
> // The quest's stations, from a module the quest imports too.
> const stations = [
>   { key: "north-gate", label: "North gate" },
>   { key: "keynote", label: "Keynote stage" },
> ]
>
> export function CheckInPage({ signIn }: { signIn: ReactNode }) {
>   const checkIn = useStationCheckIn({ stations })
>
>   switch (checkIn.status) {
>     case "none":
>       return <p>Scan a station's QR code to check in.</p>
>     case "sign-in-required":
>       return signIn
>     case "checking":
>       return <p>Checking you in at {checkIn.station.label}…</p>
>     case "checked-in":
>       return <p>You're checked in at {checkIn.station.label}.</p>
>     case "refused":
>       return <p>We couldn't check you in ({checkIn.code}).</p>
>     case "failed":
>       return <button onClick={() => void checkIn.retry()}>Try again</button>
>   }
> }
> ```
>
> | Status | What it means |
> | --- | --- |
> | `none` | The page was opened without a station's link, and no check-in is waiting. |
> | `sign-in-required` | Nobody is signed in. The check-in waits in the tab's session storage, so it survives a sign-in that leaves the page, such as an OAuth provider's, and goes ahead by itself once a member signs in, wherever the hook renders next in that tab. |
> | `checking` | Reading the session or sending the check-in. |
> | `checked-in` | Domino took it. `attempt` is the queued attempt, and the quest experience is read again. |
> | `refused` | Domino refused it, with `code`, one of the refusals in [What Domino refuses](/docs/build/wallets#what-domino-refuses), and `retryAfter` in milliseconds for `rate-limited`. |
> | `failed` | It couldn't be sent, or its answer was lost. `error` says why. |
>
> `retry()` sends a `failed` check-in again, and one refused with `rate-limited` or `attempt-pending`, with the same action ID, so a check-in that did reach Domino isn't made twice. Other refusals are final for that code. `station` is `{ key, label }`: pass the quest's stations as `stations` to name it by its label, or it's named by its key. Keep the stations in a module the quest and the page both import, without the authoring imports, so the page's bundle stays small.
>
> Without React, `checkInAtStation(relay, { stations })` from `@domino-sdk/relay/browser` does the same once and answers the same states. Call it when the page loads and again once the member signs in.
>
> Both send the check-in with `relay.quests.checkIn(quest, station, { code })`. Apps on an SDK older than this feature need to upgrade, because their portal proxy doesn't forward the route.

**Or check codes in your app's server.** If your app keeps members' sessions itself, such as a [hosted app](/docs/build/hosted-app) with its own sign-in, its server can send the check-in for the member it signed in.

> [!DEV]
> The server needs a key with **Ingest**. A hosted app's own key has it.
>
> ```ts
> import { signedInMember } from "@domino-sdk/relay/portal-proxy"
> import { hostedManagementClient, type HostedManagementEnv } from "@domino-sdk/relay/server"
>
> type Env = HostedManagementEnv & { DOMINO_PARTICIPANT_API?: string }
>
> export async function checkIn(request: Request, env: Env) {
>   const member = await signedInMember(request, env, { apiUrl: "https://relay.domino.run" })
>   if (!member) {
>     return new Response("Sign in first", { status: 401 })
>   }
>   // The page sends one actionId per check-in and repeats it on a retry, so a retry after a lost
>   // answer gets the first attempt back instead of a new one.
>   const { quest, station, code, actionId } = (await request.json()) as Record<string, string>
>   try {
>     const attempt = await hostedManagementClient(env).attempts.submitStationCode({
>       quest,
>       station,
>       code,
>       member,
>       actionId,
>     })
>     return Response.json({ checkedIn: true, attempt: attempt.id })
>   } catch (error) {
>     // Domino's status and code: a refusal such as 422 station-code-invalid or 429 rate-limited,
>     // or a 5xx the page can retry with the same actionId.
>     const { status = 502, code } = error as { status?: number; code?: string }
>     return Response.json({ checkedIn: false, code }, { status })
>   }
> }
> ```
>
> Domino applies the same guess limits as for a member's own check-in, so the route needs no limit of its own. Read the code from the link in the browser with the same care: take it out of the address bar with `history.replaceState` before the page shows anything.

### 4. Print the QR codes [#4-print-the-qr-codes]

1. In Console, open the quest and select the environment. Enter your scan page in **Scan page URL**, an https address. Console remembers it in your browser for that quest and environment.
2. Use **Download QR** on a station for an SVG to print, or a PNG. Domino draws it from the station's code: it links to your scan page with the quest, the station and the code added, and prints the station's label under it.

Download needs publish permission, because the QR code carries the code. Keep the files private until they're printed.

> [!DEV]
> `domino quests stations qr booth-check-in --page-url https://your-app.example/check-in` writes `<station key>.svg` for each code station that has a code, and lists the others under `skipped`. Add `--environment live` for live's codes. In code, `management.quests.stations.codeQr(quest, station, { url })`.

### 5. Test it [#5-test-it]

1. In test, download a station's QR code and scan it with your phone. Sign in when the page asks: the quest completes for that station.
2. Scan it again: the quest stays complete once for that station.
3. Change a letter of the code in the link and open it: the page reports a wrong code.

> [!DEV]
> `runQuest(quest, { now, action: { kind: "station-code", reference: "north-gate" } })` simulates a check-in with the station's code in [quest tests](/docs/build/testing): it refuses a station the quest lacks, one transactions prove, or one closed at `now`, and takes the code as right, since Domino checks it before the quest runs.

## Go live [#go-live]

1. Promote the quest. The promotion carries the stations, never their codes, and it warns about each code station that has no code in live.
2. Set or generate each station's code in live, as in [step 2](#2-set-each-stations-code).
3. Print the live QR codes, as in [step 4](#4-print-the-qr-codes), with live selected. QR codes from test don't check anyone in to live.

## At the event [#at-the-event]

**Time windows.** A station takes check-ins between its opening and closing times. A code carries no time of its own, so Domino judges the window when the check-in arrives. Open each station only while the event runs: it's the best guard against a code shared after the event.

**Once per member per station.** A member who scans the same station twice completes it once. A quest with several stations completes once for each.

**Guess limits.** Domino counts only wrong codes. Each member has 10 wrong codes an hour at a station, which leaves room for typos, and a station takes 600 wrong codes in 10 minutes from all members together. While either is spent, the station refuses every check-in that limit covers, right codes included, until it ends. The scan page tells the member to wait and try again.

**A leaked code.** If a station's QR code is photographed and shared, open the quest in Console and choose **Revoke** on the station, with a reason. From then on Domino refuses every check-in at that station in that environment. Completions it already gave stay. Revoking isn't a change to the quest, so it takes effect in live at once, without a promotion.

**Rotating a code and reprinting.** To replace a leaked code, choose **Rotate code** on the station, then download and print its QR code again. The old printed codes stop working at once. Then **Restore** the station if you revoked it. To retire a station for good, give it a closing time, or add a station with a new key.

> [!DEV]
> `management.quests.stations.revoke(quest, station, { reason })` and `restore(...)` revoke and restore a station, as for [Solana Pay stations](/docs/build/solana-pay#at-the-event). `management.quests.stations.list(quest)` answers each station's `status`, whether it has a code there (`codeSet`), and its `completions`.

## Where next [#where-next]

- [Stations a code proves](/docs/build/wallets#stations-a-code-proves) — Every rule for code stations, their codes, and what Domino refuses.
- [In-person quests with Solana Pay](/docs/build/solana-pay) — The same stations, checked in with a signed transaction from a mobile wallet.
- [Start from a snippet](/docs/build/first-quest#start-from-a-snippet) — The `station-codes` recipe installs a quest with code stations and its scan page.
