Developer docs

# Build ticketing into AT Protocol event apps.

Start with the architecture, roles, quickstart, and app setup model for Atmosphere Tickets.

[Read as Markdown](https://atmosphere.tickets/docs/overview.md) · [Agent build guide](https://atmosphere.tickets/docs/agent-start.md)

Developer beta SDK beta 0.0.0-beta.5 30 ticket lexicons Multi-app shared config roadmap

[Quickstart](https://atmosphere.tickets/docs.html#quickstart) [Read ATM docs](https://atmosphere.money/docs)

[Overview](https://atmosphere.tickets/docs.html) [Build](https://atmosphere.tickets/docs-build.html) [Callbacks](https://atmosphere.tickets/docs-callbacks.html) [Reference](https://atmosphere.tickets/docs-reference.html) [Operations](https://atmosphere.tickets/docs-operations.html)

## Building with an agent? Start here.

Give your agent this page's URL. The [agent build guide](https://atmosphere.tickets/docs/agent-start.md) provides the reading order, runnable starter, current contracts, SDK gaps, and test setup checklist. Start with local fixtures before configuring ATM test access.

[Read this page as Markdown](https://atmosphere.tickets/docs/overview.md) · [Agent index](https://atmosphere.tickets/llms.txt) · [Full agent guide](https://atmosphere.tickets/llms-full.txt) · [Schemas and downloads](https://atmosphere.tickets/docs/agent-index.json)

```
Build a ticketing integration using https://atmosphere.tickets/docs.
Follow the linked agent build guide and current raw schemas.
Run the starter's local smoke first; implement the server adapter and UI.
List the ATM test configuration needed to connect it.
```

## Introduction

Atmosphere Tickets is not a consumer event app. It is the ticketing module that event apps call when they need paid tickets, limited free tickets, shared inventory, issued tickets, scanner truth, and payment-linked auditability.

The important product split is simple: event apps own discovery, pages, organizer UX, social context, widgets, SEO, emails, scanner interfaces, and attendee presentation. Tickets owns the scarce state that must remain correct across every compatible app.

Standard ticket APIs, app callbacks, delivery, and scanner verification are core integration surfaces. ATM adds the payment control plane, organizer approval gates, app fee policy, receiver delivery, and test/live separation around those ticket contracts.

Event apps

### Own the experience

Events, RSVP/social UX, ticket picker UI, organizer tools, scanner screens, attendee account views, and analytics.

Tickets

### Own ticket truth

Ticketed-event config, types, capacity, holds, issuance, QR/pass tokens, scanner grants, forms, waitlists, collaborations, refunds, voids, and audit state.

ATM

### Own money movement

Checkout, settlement, app fees, receipts, refunds, payment dashboards, and attested.network payment proofs.

## Top-level architecture

This is the core ticketing loop. Event apps own the public event surface and user experience. ATM Tickets owns scarce ticket state. ATM checkout owns payment collection. App callbacks and scanner calls close the loop.

01

### Event app

Shows the event page, ticket picker, organizer UX, buyer account surfaces, and app-owned attendee/social workflows.

02

### ATM Tickets

Reads availability, creates holds, enforces capacity, issues tickets, delivers passes, manages scanner grants, and keeps ticket truth private.

03

### ATM checkout

Collects payment for paid tickets and confirms payment state to Tickets.

04

### Issue tickets

Promotes a paid hold or free claim into issued tickets and safe presentation data.

05

### App callback

Sends signed events such as tickets.issued so the app can show the ticket.

06

### Scanner

Verifies opaque QR/pass tokens and records idempotent check-in.

## Flow diagrams

These diagrams show the ticket-specific contract between event apps, ATM Tickets, ATM checkout, scanner staff, and app callbacks. Use them when explaining how one event can sell tickets across multiple compatible apps while keeping inventory and scan state private and consistent.

[ ![Multi-app ticket purchase and scan flow](https://atmosphere.tickets/assets/diagrams/atm-tickets-flow.svg?v=tickets-docs-20261013) ](https://atmosphere.tickets/assets/diagrams/atm-tickets-flow.svg?v=tickets-docs-20261013)  **Multi-app ticket purchase and scan flow**

Organizer setup, event records, ticket holds, ATM checkout, ticket issuance, wallet/pass tokens, and scanner verification.

[ ![App and user auth model](https://atmosphere.tickets/assets/diagrams/atm-tickets-auth-model.svg?v=tickets-docs-20261013) ](https://atmosphere.tickets/assets/diagrams/atm-tickets-auth-model.svg?v=tickets-docs-20261013)  **App and user auth model**

Organizer OAuth, app service-auth, buyer assertions, checkout redirects, optional public refs, and ticket-issued callbacks.

## Choose integration

Tickets is infrastructure for event apps, scanner apps, organizer tools, and agents. Start with the path closest to your product, then wire only the modules you need.

Event app

### Sell paid tickets

Use availability, paid holds, ATM checkout, tickets.issued events, and app-owned event pages.

Free event app

### Claim limited free tickets

Use app service-auth plus buyer assertions to issue scarce free tickets without checkout.

Scanner app

### Verify entry

Use opaque QR/pass tokens, verifyTicket, and idempotent checkInTicket calls.

Organizer tool

### Configure ticketing

Use current organizer authority for event/type configuration, event capacity, forms, codes and check-in lists.

### Use ATM docs for app setup.

App registration, payment setup, app fees, webhooks, XRPC receivers, environments, and dashboard operations are shared ATM concepts. Tickets docs focus on the ticket-specific calls and operational guarantees.

[Open ATM app onboarding](https://atmosphere.money/docs/app-onboarding)

## How to read these docs

Use this page for the ticketing model and first integration path. Use Build for implementation details, Callbacks for delivery and redrive, Reference for exact schemas, and Operations for launch checks. The deep reference sections are intentionally detailed, but the overview should stay short.

Build

### Implementation recipes

Auth model, availability, holds, free claims, QR/pass tokens, and scanner calls.

Callbacks

### Fulfillment truth

Ticket events, payload schemas, receiver options, webhook test commands, and redrive.

Reference

### Exact contracts

Generated XRPC methods, lexicons, errors, security boundaries, and feature mapping.

Operations

### Go-live checks

Sandbox walkthrough, testing cookbook, troubleshooting, and ATM payment boundary.

## Current contracts

Checked on 2026-10-12 against [ATM main 59432c22e](https://github.com/Atmosphere-Money/ATM/commit/59432c22e2a6dc47d852165a7d1e67c30c4810a1). The copied bundle has 30 lexicons. Use ticket types, per-type caps and `setEventCapacity`; current item bodies use `ticketTypeId` and free claims use an item array plus private delivery email.

The published `@atmosphere-money/app-node@0.0.0-beta.5` supports the current item arrays. Beta.5 types/sends paid catalog refs as `productRef`/`priceRef`, while ATM requires `product` (omit `defaultPrice` when supplying Product). Create/update paid types through authenticated raw XRPC until the coordinated SDK release. Some selector names, organizer mutation fields, payer binding/status typing and newer methods/events are ahead of that release: use authenticated raw XRPC and the current schema where needed. Do not treat unreleased SDK source or an inactive checkout cutover as a published API.

[Contract migration and regeneration](https://atmosphere.tickets/docs/LEXICONS.md) · [Exact source revision](https://atmosphere.tickets/docs/atm-source.json). Code in main, deployed runtime, protocol publication and live release approval are separate states.

## Quickstart

1. Register an ATM app, enable Tickets in test mode, configure app service-auth and verified callbacks.
2. Create a public event shell and ticket types with organizer consent; paid types need a matching active ticket Product and default Price.
3. Set optional type caps and shared event capacity, and obtain the organizer's approval for the selling app.
4. Read `getTicketAvailability` and render its `ticketTypes`.
5. Create a paid hold with `items: [{ ticketTypeId, quantity }]`; persist `holdId` and private `statusToken`, then redirect to its top-level `url`.
6. Show tickets after verified `tickets.issued` or an authorized issued-ticket read.

Zero-price types use `claimFreeTicket` with required buyer assertion and private delivery email, without checkout. A paid type discounted to $0 still uses ATM checkout.

## Starter kit

Use the local Tickets starter before wiring a production event app. It demonstrates availability, paid holds, free claims, webhook verification, optional XRPC receiver callbacks, and scan-token check-in with local mocked responses. Run a separate deployed sandbox pilot before live use.

The starter is intentionally framework-light. Copy the flow into Next.js, Hono, Workers, Express, Fastify, SvelteKit, or another trusted backend, but keep service-auth signing, ticket mutations, webhook secrets, and check-in calls on the server.

[Download the Node starter](https://atmosphere.tickets/docs/tickets-node-app.zip) or [read all starter files as JSON](https://atmosphere.tickets/docs/tickets-node-app.json). No repository access or ATM credentials are needed for the local smoke. Requires Node.js 22 or later.

```
curl -fsS https://atmosphere.tickets/docs/tickets-node-app.zip -o tickets-node-app.zip
unzip tickets-node-app.zip
cd tickets-node-app
npm ci
npm run typecheck
npm run smoke

# Optional local health endpoint; ticket calls need ATM test setup.
cp .env.example .env
npm run dev
```

| Availability | `GET /tickets/availability` calls `tickets.atmosphere.getTicketAvailability`. |
| --- | --- |
| Paid hold | `POST /tickets/hold` creates a scarce hold and returns an ATM checkout URL. |
| Free claim | `POST /tickets/free-claim` issues a limited free ticket without checkout. |
| Receiver | `POST /webhooks/atm` verifies `Atm-Signature` and `Atm-Delivery-Id`. |
| XRPC receiver | `POST /xrpc/money.atmosphere.event.receive` shows the optional AT Protocol callback shape. |
| Check-in | `POST /tickets/check-in` submits an opaque scan token to Tickets. |

## Agent integration

These docs are written so an app developer or coding agent can wire Tickets from contracts alone. The safe path is the same for humans and agents: use a trusted backend, install the ATM App Node SDK, run local fixtures, verify callbacks, and keep all secrets and ticket mutations out of browser code.

Default package

### Use the ATM App Node SDK

`@atmosphere-money/app-node` owns app service-auth calls, ticket holds, callbacks, and shared ATM payment helpers.

Local tooling

### Use MCP for developer actions

The ATM MCP wrapper is for test-mode setup, fixture generation, receiver validation, delivery logs, and redrive checks.

Guardrail

### No payment mutations from agents yet

Agents should not create live charges, refunds, organizer payout changes, or public repo writes unless the app developer explicitly wires that flow.

Discovery

### Machine-readable docs

Follow the [agent build guide](https://atmosphere.tickets/docs/agent-start.md), [agent index](https://atmosphere.tickets/llms.txt), or [full guide](https://atmosphere.tickets/llms-full.txt). Every docs page also has a Markdown version; the [JSON index](https://atmosphere.tickets/docs/agent-index.json) lists exact schemas and public starter files.

```
Recommended agent prompt

Build a ticketing integration with Atmosphere Tickets.
Use @atmosphere-money/app-node on the app server.
Create holds before checkout, verify ATM callbacks before fulfillment,
and keep buyer PII, scan tokens, service-auth JWTs, and webhook secrets private.
```

## Register in ATM

Event apps do not create a separate payment platform. They register as apps in ATM, enable the Tickets module, and keep test and live configuration separate. The organizer still completes payout setup in ATM before paid tickets can go on sale, and paid or scarce selling requires organizer approval of the app for ticket payments.

| Step | Configured in ATM | Why it matters |
| --- | --- | --- |
| App profile | Display name, avatar, app URL, contact | Used for app dashboard, ticket/pass branding, and developer trust. |
| Modules | Payments, Tickets, optional future modules | Controls which XRPC/service surfaces the app can call. |
| Organizer approval | Ticket recipient approval for the app | Required before availability reads, paid holds, or free limited claims can run for an organizer-owned event. |
| Environment | Test first, live explicitly | Keeps app sandbox traffic separate from production ticket sales. |
| Receivers | HTTP webhook URL or optional XRPC receiver | ATM signs outbound events and stores delivery/redrive logs. |
| Fees | App fee and optional ATM support share | Routes app revenue without exposing Stripe platform access. |

### Webhook URL can be added later.

ATM can mint an app secret and queue events before the app has a receiver endpoint. Delivery rows remain visible as configuration needed until the app adds a receiver and redrives them.

[Register an ATM app](https://atmosphere.money/docs/first-app)

## App onboarding checklist

This is the ATM setup checklist for a ticketing app. Details live in the ATM app dashboard guide; keep this page focused on the ticketing-specific requirements.

| App role | Sign into ATM with the app DID and request the app role. |
| --- | --- |
| Modules | Enable Payments and Tickets in the test environment. |
| Organizer approval | Request ticket recipient approval before reading availability or creating holds. |
| Receivers | Add HTTP webhook first; add XRPC receiver only if your app already hosts XRPC. |
| Service-auth | Copy the audience and method NSIDs into the app server. |
| Live access | Request live after hold, checkout, refund/void, free claim, and check-in tests pass. |

## App dashboard manual

The ATM app control plane manages module flags, fees, service-auth, test/live settings, HTTP/XRPC callbacks, test events, redrive, QR/wallet options and scanner grants. Current organizer event workspaces manage types, capacity, questions, check-in lists, codes, collaborators and lifecycle actions.

Ownership determines controls, independently of dashboard role. App management includes authorized events with no paid sales; app sales/delivery views retain seller-channel scope. Use current `manageUrl` and `scannerUrl` returned by ATM instead of constructing dashboard paths. A link never grants permission.

## First integration acceptance test

Use this as the pass/fail test for the first integration. The step-by-step implementation details live in Quickstart, Starter kit, Build first ticket app, and the Build page.

1. Test environment has Payments and Tickets enabled.
2. Organizer has approved the app for ticket selling in the target environment.
3. Receiver verifies auth and deduplicates delivery id.
4. Paid hold reserves capacity and returns ATM checkout URL.
5. Payment success emits `tickets.issued`.
6. Issued ticket appears through `listBuyerTickets`.
7. Opaque scan token verifies and checks in exactly once.

Pass condition

### No oversell

Concurrent holds never exceed type or capacity-group limits.

Pass condition

### Receiver safe

Webhook or XRPC callback verifies auth and deduplicates by delivery id.

Pass condition

### Checkout truth

Browser return is UX only; ticket display waits for issued-ticket truth.

Pass condition

### Private data

Buyer contact, scan token secrets, attendee answers, and check-in logs stay off protocol.

## Build first ticket app

Keep the community event graph and your app's event UX. Configure canonical ticketing through a trusted backend with current organizer authority.

```
organizer setup
  POST tickets.atmosphere.createTicketEvent
  POST tickets.atmosphere.createTicketType
  POST tickets.atmosphere.setEventCapacity
  POST tickets.atmosphere.setTicketTypeForm

buyer flow
  GET  tickets.atmosphere.getTicketAvailability -> ticketTypes
  POST tickets.atmosphere.createTicketHold -> holdId, statusToken, url
  redirect to url

issuance
  verified tickets.issued or GET tickets.atmosphere.listBuyerTickets
  display issued-ticket state, optionally through tickets.atmosphere.tickets
```

App provenance does not grant editing authority. Paid buyers supply both `buyerDid` and `buyerAssertionJwt`, or neither for a guest. Free claims always require the verified buyer pair and fresh delivery email.

## Integration lifecycle

A ticketing app usually integrates in stages. Each stage can ship independently as long as paid and scarce tickets always use Tickets for holds and issuance.

01

### App setup

Register in ATM, enable Tickets in test, configure receiver events, and generate service-auth from the app DID.

02

### Organizer setup

Organizer creates or approves app-scoped ticketed-event config, completes payout setup, and authorizes ticket types and capacity.

03

### Buyer flow

App reads availability, creates a hold, free claim, or waitlist offer, then shows issued tickets only after Tickets confirms truth.

04

### Entry and ops

Scanner verifies opaque tokens at `scan.atmosphere.tickets`, check-in is idempotent, refunds/voids revoke pass authority, and events are redriven if needed.

## Architecture

| Public event graph | `community.lexicon.calendar.event` and `community.lexicon.calendar.rsvp`. |
| --- | --- |
| Public ticket catalog | `tickets.atmosphere.ticketType`, `ticketedEvent` and `checkInList`. Catalog disclosure is not live availability. |
| Private Tickets service | Event/type capacity pools, holds, issued tickets, answers, waitlists, codes, staff grants, delivery and check-in audit. |
| Docs | `atmosphere.tickets` is this static site. |
| ATM runtime hosts | `events.atmosphere.tickets` for optional event selection/OAuth; `tickets.atmosphere.tickets` for buyer passes; `scan.atmosphere.tickets` for staff. |
| ATM payment service | Checkout, settlement, app fees, refunds, unified ledger and policy-gated payment proofs. |

## Reference deep links

Generated reference rows include direct links to raw lexicon JSON, field-level tables, API examples, and error handling. These anchors are intended for Discord, GitHub, and Tangled review threads.

Raw

### Review the schema

Links to published raw lexicon JSON under `/lexicons/`; the [schema index](https://atmosphere.tickets/docs/agent-index.json) lists every URL.

Fields

### Inspect contract shape

Jumps to generated field tables with required, nullable, limits, and descriptions.

Examples

### Copy the flow

Jumps to request examples that show auth mode and common edge behavior.

Errors

### Handle failure states

Jumps to the stable error code guidance for apps.

[PreviousHome](https://atmosphere.tickets/index.html) [Next pageBuild](https://atmosphere.tickets/docs-build.html)