Build ticketing into AT Protocol event apps.

Building with an agent? Start here.

Give your agent this page's URL. The agent build guide 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 · Agent index · Full agent guide · Schemas and downloads

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.

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.

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.

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.

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.

Current contracts

Checked on 2026-10-12 against ATM main 59432c22e. 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 · Exact source revision. 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 or read all starter files as 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

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.

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.

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

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.

Architecture

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.