# Atmosphere Tickets

ATM Tickets is ATM's private ticketing module for AT Protocol event apps.
This guide was checked against ATM main 59432c22e on 2026-10-12.

- Start building: https://atmosphere.tickets/docs/agent-start.md
- Machine index (all pages, raw schemas and starter): https://atmosphere.tickets/docs/agent-index.json
- Overview: https://atmosphere.tickets/docs/overview.md
- Build: https://atmosphere.tickets/docs/build.md
- Callbacks: https://atmosphere.tickets/docs/callbacks.md
- Exact schemas/errors: https://atmosphere.tickets/docs/reference.md
- Operations: https://atmosphere.tickets/docs/operations.md
- Full agent guide: https://atmosphere.tickets/llms-full.txt
- Starter download (no repository access): https://atmosphere.tickets/docs/tickets-node-app.zip
- Starter source files as JSON: https://atmosphere.tickets/docs/tickets-node-app.json
- Source revision: https://atmosphere.tickets/docs/atm-source.json
- Machine scanner pilot: https://atmosphere.tickets/docs/SCANNER_API.md
- ATM payments docs: https://atmosphere.money/docs

Start without ATM credentials: download/unzip the starter, then npm ci,
npm run typecheck and npm run smoke (Node.js 22+). Smoke uses local HTTP/signature
fixtures. The build guide lists configuration/auth adapters needed for real test
access. Every HTML docs page has a generated Markdown mirror linked above.

Use a trusted backend and fresh exact-method app service-auth with the target
environment's configured broker audience. Organizer creation assertions are
required unless the app is itself the organizer; subsequent mutations require
current event control, not app provenance. Selling approval is separate.

The public records are tickets.atmosphere.ticketType, ticketedEvent and
checkInList. Capacity pools are private. Create/update/archiveTicketType replace
the older tier APIs. Use quantityTotal for a type cap and setEventCapacity for
shared event capacity. Availability returns ticketTypes; availableQuantity is
omitted when unlimited. Public listPublicConfig on ATM AppView requires organizer
and is unauthenticated catalog discovery, not live inventory.

Paid holds use items: [{ ticketTypeId, quantity }]. Supply buyerDid and
buyerAssertionJwt together, or omit both for guests. Asserted buyers are fixed
by default; explicitly switchable flows must reconcile CheckoutPayerChanged.
Persist holdId and private statusToken server-side; redirect to the top-level
url. Fulfill from verified tickets.issued or an authorized issued-ticket read.
Keep the same purchase key/request after an uncertain result.

Fresh claimFreeTicket requires buyerDid, its method-scoped assertion, private
customerEmail and the same item array. It creates no checkout/payment row.
Its wire idempotencyKey is optional but should be supplied for safe retries.
releaseFreeTicket requires buyer assertion and a stable release idempotencyKey;
it releases only active free claims. Paid types discounted to $0 still go through
checkout, create a $0 payment row and publish no payment proof.

listBuyerTickets uses exactly one of buyer (DID/handle) or paymentId;
listOrganizerTickets uses organizer. listEventWaitlist, listTicketFormResponses
and listCollaborations are POST procedures; assertions stay out of URLs.
Co-organizer revenueShareBps is manual reconciliation intent, never auto-payout.

Published SDK @atmosphere-money/app-node@0.0.0-beta.5 supports current item arrays
but still has older list selectors and omits some newer fields/methods/events.
Use authenticated raw XRPC and current schemas for those gaps. Do not infer a
published release from ATM's unreleased SDK or inactive checkout source.
Beta.5 types/sends paid catalog refs as productRef/priceRef, while ATM's wire
requires product (omit defaultPrice when supplying Product). Create/update paid
types with authenticated raw XRPC until the coordinated SDK release.

Callbacks use exact names ticket.checked-in and ticket.form-submitted. The
current envelope has id, type, createdAt, apiVersion, environment and data.
tickets.issued data contains hold, nonempty tickets, and paymentId or claimId;
issuedCount is not the current required payload. Verify signatures/raw bodies
and environment, then use durable atomic processing/deduplication.

Staff use scan.atmosphere.tickets with identity-only OAuth and private event/list
grants. App scanner XRPC uses app service-auth. The separate machine pilot uses
an ATM-issued bearer on the exact checkout origin; its body contains only
ticketToken. Check-in is idempotent per ticket/list. QR payloads carry only opaque
tokens/scan URLs. Buyer passes use tickets.atmosphere.tickets; optional hosted
event selection/OAuth uses events.atmosphere.tickets. This static docs site
remains atmosphere.tickets.

Buyer PII, answers, inventory enforcement, holds, issued ids, pass secrets,
codes/counters, scanner grants and check-in audit stay private. Presentation
restrictions do not automatically revoke a valid issued entitlement/admission.
Code in main, deployed migrations, protocol publication and live approval are
separate; this docs refresh establishes no release or deployment approval.