Build ticketing into AT Protocol event apps.

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.

Quickstart

1. Register your event app in ATM and enable the Tickets module in the test environment.
2. Use your app DID to mint app service-auth for ticket XRPC calls.
3. When an organizer creates paid ticketing, create ticket tiers and capacity groups through Tickets.
4. On the event page, call availability before showing ticket purchase controls.
5. Create a hold before sending the buyer to ATM checkout.
6. Fulfill only after Tickets emits an issued-ticket event or your app reads issued tickets from the service.

Event page
  GET  tickets.atmosphere.getTicketAvailability
  POST tickets.atmosphere.createTicketHold
  redirect buyer to hold.checkout.url

ATM checkout
  payment succeeds
  ATM notifies Tickets
  Tickets issues tickets
  Tickets notifies originating app

Starter kit

Use the local Tickets starter before wiring a production event app. It proves availability, paid holds, free claims, webhook verification, optional XRPC receiver callbacks, and scan-token check-in against the ATM app sandbox.

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.

cd examples/tickets-node-app
cp .env.example .env
npm install
npm run dev

curl http://localhost:8788/health
curl http://localhost:8788/tickets/availability

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

Tickets configuration starts in the ATM app dashboard. Event apps should treat ATM as the app control plane for modules, fee policy, service-auth details, receiver config, delivery logs, scanner grants, and test/live separation. Production event apps can also configure ticketed events, tiers, capacity groups, forms, waitlists, and check-in lists programmatically through app service-auth.

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

A ticketing integration has three actors: the event app, the organizer, and the buyer. The app owns the public event page and user experience. Tickets owns scarce inventory and issued-ticket truth. ATM owns payment and app events.

1. Register the event app in ATM and enable Tickets in test mode.
2. Create or reference a community.lexicon.calendar.event event.
3. Create app-scoped ticketed-event config, ticket tiers, and capacity groups from the organizer UI or trusted app server.
4. Request organizer approval for the selling app before availability, holds, or free claims.
5. Render availability from getTicketAvailability.
6. Create a hold when the buyer selects tickets.
7. Redirect paid tickets to ATM checkout, or claim free tickets directly.
8. Show tickets only after tickets.issued or listBuyerTickets confirms issuance.

event app server
  create organizer assertion
  POST tickets.atmosphere.createTicketEvent
  POST tickets.atmosphere.createTicketTier
  POST tickets.atmosphere.createCapacityGroup
  POST tickets.atmosphere.setTierForm

buyer clicks buy
  GET tickets.atmosphere.getTicketAvailability
  POST tickets.atmosphere.createTicketHold
  redirect to ATM checkout

after payment
  receive tickets.issued
  show QR/pass from issued-ticket state
  link to tickets.atmosphere.tickets for hosted ticket view

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

Publish discovery, display, and social intent. Centralize scarce inventory, payment-linked issuance, and verification. Public repo records are excellent for catalog metadata; they are not suitable for serializable inventory writes across multiple apps.

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.