# Atmosphere Tickets Full Agent Guide Checked against ATM main 59432c22e2a6dc47d852165a7d1e67c30c4810a1 on 2026-10-12. Exact source: https://atmosphere.tickets/docs/atm-source.json Human docs: https://atmosphere.tickets/docs Payment docs: https://atmosphere.money/docs ## Start from one link Build guide: https://atmosphere.tickets/docs/agent-start.md Machine index: https://atmosphere.tickets/docs/agent-index.json All five docs pages have generated Markdown mirrors linked in that index. Starter archive: https://atmosphere.tickets/docs/tickets-node-app.zip Readable starter files: https://atmosphere.tickets/docs/tickets-node-app.json With Node.js 22+, download/unzip the starter, then npm ci, npm run typecheck and npm run smoke. No private repository or ATM credentials are needed for this mocked HTTP/signature test. Start building the server adapter and UI from current schemas; the build guide lists test setup needed to connect real ATM calls. Replace the starter's static auth fixtures, fixed operation keys and logging with fresh exact-method auth, persistent private state and durable processing. ## Boundaries Event apps own discovery, event pages, SEO, widgets, organizer/buyer UX and optional custom scanners. Use community.lexicon.calendar.event and RSVP for the public event graph; RSVP/Going is social intent, not admission authority. ATM owns checkout, fees, settlement, refunds, app config and callbacks. Tickets owns private capacity, holds, issued tickets, forms, waitlists, code budgets, scanner grants, delivery and lifecycle audit inside ATM. Public ticket records: tickets.atmosphere.ticketType, ticketedEvent, checkInList. Paid type configuration requires an exact active organizer-owned kind=ticket Product with a matching one-time default Price. When sending product, omit the legacy defaultPrice input because ATM derives it. Free/RSVP types may omit Product. Checkout lists on the ticketType record URI. Optional record display copies and indexed catalog state are never settlement authority. ## Current methods and verbs GET queries: - tickets.atmosphere.getTicketAvailability - tickets.atmosphere.listBuyerTickets - tickets.atmosphere.listOrganizerTickets - tickets.atmosphere.listPublicConfig (public ATM AppView, no auth) POST procedures: - tickets.atmosphere.createTicketEvent - tickets.atmosphere.updateTicketEvent - tickets.atmosphere.cancelTicketEvent - tickets.atmosphere.createTicketType - tickets.atmosphere.updateTicketType - tickets.atmosphere.archiveTicketType - tickets.atmosphere.setEventCapacity - tickets.atmosphere.setTicketTypeForm - tickets.atmosphere.createTicketHold - tickets.atmosphere.releaseTicketHold - tickets.atmosphere.claimFreeTicket - tickets.atmosphere.releaseFreeTicket - tickets.atmosphere.joinWaitlist - tickets.atmosphere.claimWaitlistOffer - tickets.atmosphere.listEventWaitlist - tickets.atmosphere.listTicketFormResponses - tickets.atmosphere.inviteOrganizerCollaboration - tickets.atmosphere.acceptCollaboration - tickets.atmosphere.listCollaborations - tickets.atmosphere.revokeCollaboration - tickets.atmosphere.verifyTicket - tickets.atmosphere.checkInTicket Exact schemas/errors: https://atmosphere.tickets/docs/generated-reference.json The 30-schema bundle contains these 26 methods, three records and shared defs. No public capacity pool API is served. Configure quantityTotal on each type and setEventCapacity with exactly one of capacity or unlimited:true. Availability is the minimum over all relevant private pools; omitted availableQuantity means unlimited. Type caps may sum above the shared event cap. listBuyerTickets requires exactly one of buyer (DID/handle) or paymentId. listOrganizerTickets uses organizer. Public listPublicConfig requires organizer; optional eventUri must belong to that organizer, and indexed records never reserve capacity or authorize access to another app's private seller channel. ## Identity and organizer authority Mint fresh app JWTs for the target environment's configured broker audience and exact method lxm. Creation requires organizerAssertionJwt unless the app is itself the organizer. Subsequent edits require current event control; creating a configuration grants no continuing owner authority. Accepted co-organizers can perform supported operational edits, reads and forms. Price, currency, capacity, raw metadata/PWYW, archival and cancellation remain primary-only. The co-organizer's own assertion is mandatory to accept a collaboration. revenueShareBps records manual reconciliation intent, not an automatic split. Organizer selling approval is separate from setup assertions. Validate the app/module, environment, approval and paid Product/Price graph for the exact seller channel. Public catalog discovery is not blanket cross-app selling. Paid hold buyers supply buyerDid plus buyerAssertionJwt together, or neither for guest checkout. Buyer assertion lxm is money.atmosphere.payment.assertPayer; app lxm is tickets.atmosphere.createTicketHold. Asserted identity is fixed by default. Explicit payerBinding:switchable requires handling CheckoutPayerChanged and final-buyer reconciliation; idempotent replay may not relax the original binding. Keep raw assertions private/single-use and retain only verification metadata. Assertions grant no public repository write permission. Free claim/release buyer assertions are scoped to their exact ticket method. Payer receipt and optional public RSVP require separate exact OAuth grants and applicable buyer consent. ATM owns payer-record publication; apps do not receive payer OAuth credentials or unpublished canonical receipt bytes. ## Integration and recovery 1. Register the event app and configure Tickets, service-auth and receivers in the intended test environment. 2. Configure the public event shell, types, caps and private forms with current organizer authority, and obtain applicable organizer selling approval. 3. Read getTicketAvailability; render ticketTypes and respect sale/hidden state. 4. Paid purchase: createTicketHold with items:[{ticketTypeId,quantity}] and a caller-stable purchase key. Save holdId/statusToken server-side, redirect to the top-level url. The browser token/URL may rotate independently. 5. Fresh zero-price claim: required verified buyer pair, private customerEmail, same item array. Supply a stable key for safe retries (wire key is optional). No checkout or payment row. 6. Display tickets after signed tickets.issued or authorized issued-ticket reads. 7. Verify/check in opaque tokens through an authorized scanner backend or PWA. 8. Reconcile refunds, voids, cancellation, free releases and callbacks from ATM's durable lifecycle authority, not local counters or browser returns. Reuse the same exact key/request after an uncertain purchase/release response. Do not create a replacement sale while the original outcome is unknown. Use ATM's returned expiresAt/current lifecycle, not hard-coded client timers. Guarded session expiry prevents a payable processor session from outliving its seat reservation. Quantity is fixed by the hold. releaseFreeTicket requires a stable release key and verified buyer assertion; it voids only active free-claim tickets, never paid, transferred or checked-in tickets. No-op returns releasedCount:0. Reuse the original key so newly claimed tickets cannot be consumed by a retry. Existing lifecycle/grant authority must not depend solely on a current module toggle. Waitlists take no capacity until an offer hold is reserved. claimWaitlistOffer starts checkout against that existing hold; ATM never auto-charges. If passing buyerDid to waitlist calls, also pass a verified buyer assertion. Price coupons and hidden-type access codes are separate private mechanisms. Managed event codes combine supported behavior under a ticket-quantity budget. A paid type with a Free/100%-off coupon uses normal $0 checkout, writes a $0 payment row/private audit and no public payment proof. New comp-code creation is retired. Count attendance from issued tickets and exclude $0 rows from revenue. ## SDK compatibility Published @atmosphere-money/app-node@0.0.0-beta.5 supports ticketTypeId item arrays, holds/free claims and callback verification. It still types/sends older buyerDid/organizerDid list selectors and lacks some newer organizer fields, eventCode, payerBinding/statusToken typing, releaseFreeTicket and lifecycle event types. Use authenticated direct XRPC/current schemas for those gaps. Do not advertise ATM's unreleased SDK source or inactive new checkout methods as a published or activated release. The starter keeps current buyer reads on raw XRPC and pins the published SDK; its smoke uses local HTTP/signature fixtures. Beta.5 types/sends paid catalog refs as productRef/priceRef. ATM's current wire uses product (omit defaultPrice when supplying Product); the SDK's old fields do not satisfy the required paid-type Product. Create/update paid types through authenticated raw XRPC until the coordinated SDK release. ## Callback contracts Verify exact raw HTTP bodies with Atm-Signature and Atm-Delivery-Id, or ATM service-auth for the optional XRPC receiver. Current envelopes use id, type, createdAt (ISO datetime), apiVersion, environment, data. Payload $type refs are under money.atmosphere.event.defs. Durable atomic processing must deduplicate retries/redrive and recover interrupted side effects. Exact event names: - ticket.hold.created - ticket.hold.expired - tickets.issued - ticket.released - ticket.refunded - ticket.voided - ticket.partial-refund-review - ticket.failed-refund-review - ticket.event-canceled - ticket.checked-in - ticket.form-submitted - ticket.waitlist.joined - ticket.waitlist.offered - ticket.collaboration.invited - ticket.collaboration.accepted - ticket.collaboration.revoked tickets.issued carries hold, nonempty tickets and paymentId or claimId; derive count from tickets, not an assumed issuedCount field. Check-in carries ticket and checkIn objects. Form events contain answeredFieldKeys, not answer values. Waitlist notifications contain redacted offer state, not buyer contact email. Handle partial/failed-refund review separately from full ticket revocation. ## Hosts, presentation and scanners atmosphere.tickets: this static developer site. events.atmosphere.tickets: optional ATM-hosted selection and buyer OAuth. tickets.atmosphere.tickets: buyer email/QR/wallet presentation. scan.atmosphere.tickets: staff PWA. All three runtime subdomains are served by ATM. Use ATM-returned manageUrl and scannerUrl locators; links do not grant organizer/staff authority. Staff PWA uses identity-only AT Protocol OAuth and active private event/list grants; its session supplies scanner DID. App scanner XRPC uses app service-auth; optional scannerDid is an app-asserted audit identity, not independently verified by ATM. Check-in is inherently idempotent per ticket/list, returning checked-in, already-checked-in or not-valid without a current wire idempotencyKey. The private machine scanner pilot is POST /api/pilot/tickets/check-in on the exact stable checkout origin using an ATM-issued bearer. Body: ticketToken only (full QR URL or opaque token). ATM derives exact origin/environment/app/event/ list/scanner scope. Response: status,eventId,ticketId,did,checkedInAt; guest did is null. Deduplicate badge jobs by ticketId. Retry an indeterminate response with the identical QR and bounded backoff. Keep bearer/token out of logs/URLs/telemetry. Current deployment authority is ATM_TICKET_SCANNER_API_PILOT_CONFIG, configured separately by ATM, not the retired broad pilot-scope setting. Full contract: https://atmosphere.tickets/docs/SCANNER_API.md Current moderation can suppress ticket/event copy, images, email or wallet presentation without deleting an issued entitlement or changing admission. Keep immutable purchase/monetary snapshots for audit; verification/check-in resolves private ticket/grant state even when current display is unavailable. Never publish buyer PII, attendee answers, exact inventory, holds, issued ids, pass secrets, codes/counters, staff grants or admission history. QRs contain only opaque scan tokens/URLs. Show provider wallet actions only when usable passes exist; QR is the fallback. Local docs checks do not prove deployed migrations, protocol publication, live-sales approval or runtime release readiness.