Build with Atmosphere Tickets.

Auth model

Most ticket actions need two identities: the app that is making the infrastructure call, and the user whose intent is attached to the action. The app DID is not the buyer or organizer. It identifies the event app for module access, fees, webhooks, environment, and app-scoped visibility.

app service-auth JWT
  iss = app DID
  aud = ATM broker/service DID
  lxm = tickets.atmosphere.createTicketHold

buyerAssertionJwt
  iss = buyer DID
  aud = ATM broker/service DID
lxm = money.atmosphere.payment.assertPayer

App dashboard config

The ATM app dashboard is the control plane for ticketing apps. Organizers should not see service-auth, receiver signatures, fee routing, or redrive logs unless they are also the app operator.

SDK examples

Keep ticket calls on the app server. Tickets uses ATM's published beta @atmosphere-money/app-node package rather than a separate ticket SDK because holds, checkout, webhooks, and payment status all share ATM app auth.

import { createAtmAppClient } from "@atmosphere-money/app-node";

const atm = createAtmAppClient({
  getServiceAuthToken: async ({ lxm, aud }) => {
    return mintMyAppServiceAuthJwt({ lxm, aud });
  }
});

// Node/TypeScript: create a paid ticket hold
const hold = await atm.createTicketHold({
  environment: "test",
  eventUri: "at://did:plc:organizer/community.lexicon.calendar.event/abc",
  buyerDid: "did:plc:buyer",
  buyerAssertionJwt,
  items: [{ ticketTierId: "tier_...", quantity: 2 }],
  returnUrl: "https://events.example/orders/123",
  cancelUrl: "https://events.example/e/abc",
  idempotencyKey: "hold:event:buyer:tier:2"
});

# curl: read availability
curl "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.getTicketAvailability?eventUri=at://...&environment=test" \
  -H "Authorization: Bearer $APP_SERVICE_AUTH"

SDK beta and compatibility

Tickets uses the same beta app SDK and testing helpers as ATM. Keep SDK updates paired with ATM API version notes, because ticket holds, app callbacks, checkout, and payment status share the same app authentication and event envelope.

MCP and testing tools

The MCP server is not required to integrate with Tickets. It is a convenience layer for coding agents and local developer workflows that need to inspect configuration, create fixtures, send test events, and debug receiver delivery without browsing the dashboard.

Framework recipes

Tickets follows the same model as ATM docs: the contract is framework-neutral, and framework examples all implement the same app-server responsibilities. Keep service-auth minting, hold creation, webhook/XRPC receiver verification, and fulfillment mutations on a trusted backend.

Integration recipes

These are the minimum app-server recipes most event apps need: paid checkout, free scarce claims, scanner check-in, and event receiver handling. Keep app service-auth and receiver secrets on your server.

const availability = await tickets.getTicketAvailability({
  environment: "test",
  eventUri
});

assertCanBuy(availability, tierId, quantity);

const hold = await tickets.createTicketHold({
  environment: "test",
  eventUri,
  buyerDid,
  buyerAssertionJwt,
  items: [{ ticketTierId: tierId, quantity }],
  returnUrl: "https://events.example/orders/123",
  cancelUrl: "https://events.example/e/abc"
});

return Response.redirect(hold.checkout.url);

const claim = await tickets.claimFreeTicket({
  environment: "test",
  eventUri,
  ticketTierId: tierId,
  buyerDid,
  buyerAssertionJwt,
  idempotencyKey: "claim:" + eventUri + ":" + buyerDid + ":" + tierId
});

return Response.json({ ticket: claim.ticket });

const result = await tickets.checkInTicket({
  ticketToken: scannedQrToken,
  checkInListId,
  idempotencyKey: "scan:" + scannedQrTokenHash
});

if (result.status === "already_checked_in") {
  showAlreadyCheckedIn(result.checkedInAt);
} else {
  showEntryAllowed(result.ticket);
}

async function handleAtmTicketEvent(event) {
  if (!(await insertDeliveryId(event.deliveryId))) return;

  switch (event.type) {
    case "tickets.issued":
      await showTicketsToBuyer(event.data);
      break;
    case "ticket.checked_in":
      await updateScannerDashboard(event.data);
      break;
    case "ticket.voided":
      await revokeVisiblePass(event.data.ticketId);
      break;
  }
}

Sequence diagrams

Paid ticket
buyer -> app: select tier
app -> Tickets: createTicketHold(app auth + buyer assertion)
Tickets -> app: hold + ATM checkout URL
buyer -> ATM: pay
ATM -> Tickets: payment confirmed
Tickets -> app: tickets.issued

Availability

Availability is a private service read derived from capacity, active holds, issued tickets, sale windows, tier visibility, and app environment. Apps should call availability from their server before rendering purchase buttons. Public records can show a safe availability hint, but they are not inventory truth.

GET /xrpc/tickets.atmosphere.getTicketAvailability
Authorization: Bearer <app service-auth jwt>

query:
  eventUri = at://...
  environment = test

Helper snippets

These snippets belong on the event app server. Replace token minting stubs with your AT Protocol auth stack and keep app service-auth, buyer assertions, webhook secrets, and scan tokens out of browser code.

async function getAvailability(eventUri) {
  const params = new URLSearchParams({ environment: "test", eventUri });
  const response = await fetch(
    "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.getTicketAvailability?" + params,
    { headers: { authorization: "Bearer " + appServiceAuthJwt } }
  );
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

async function createHold({ eventUri, ticketTierId, buyerDid, buyerAssertionJwt }) {
  const response = await fetch(
    "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.createTicketHold",
    {
      method: "POST",
      headers: {
        authorization: "Bearer " + appServiceAuthJwt,
        "content-type": "application/json"
      },
      body: JSON.stringify({
        environment: "test",
        eventUri,
        buyerDid,
        buyerAssertionJwt,
        items: [{ ticketTierId, quantity: 1 }]
      })
    }
  );
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

async function claimFreeTicket({ eventUri, ticketTierId, buyerDid, buyerAssertionJwt }) {
  const idempotencyKey = "claim:" + eventUri + ":" + buyerDid + ":" + ticketTierId;
  const response = await fetch(
    "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.claimFreeTicket",
    {
      method: "POST",
      headers: {
        authorization: "Bearer " + appServiceAuthJwt,
        "content-type": "application/json"
      },
      body: JSON.stringify({
        environment: "test",
        eventUri,
        ticketTierId,
        buyerDid,
        buyerAssertionJwt,
        idempotencyKey
      })
    }
  );
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

async function checkInTicket({ ticketToken, checkInListId }) {
  const response = await fetch(
    "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.checkInTicket",
    {
      method: "POST",
      headers: {
        authorization: "Bearer " + scannerServiceAuthJwt,
        "content-type": "application/json"
      },
      body: JSON.stringify({ ticketToken, checkInListId })
    }
  );
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

API examples

curl "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.getTicketAvailability?eventUri=at://...&environment=test" \
  -H "Authorization: Bearer $APP_SERVICE_AUTH"

{
  "environment": "test",
  "eventUri": "at://...",
  "buyerDid": "did:plc:buyer",
  "buyerAssertionJwt": "...",
  "items": [{ "ticketTierId": "tier_...", "quantity": 2 }],
  "returnUrl": "https://events.example/orders/123",
  "cancelUrl": "https://events.example/e/abc"
}

{
  "environment": "test",
  "eventUri": "at://...",
  "ticketTierId": "tier_free",
  "buyerDid": "did:plc:buyer",
  "buyerAssertionJwt": "...",
  "idempotencyKey": "claim:event:buyer:tier"
}

{
  "ticketToken": "opaque_scan_token",
  "checkInListId": "list_...",
  "idempotencyKey": "scan:..."
}

Interactive API explorer

Generate copyable request shells for common Tickets calls. This docs widget does not send requests; it gives your app server a starting point.

curl "https://checkout.atmosphere.money/xrpc/tickets.atmosphere.getTicketAvailability?eventUri=at://...&environment=test" \
  -H "Authorization: Bearer $APP_SERVICE_AUTH"

Holds and checkout

Paid and scarce tickets start with a hold. The hold reserves capacity for a short checkout window and returns the ATM checkout URL. If checkout fails, cancels, or expires, the hold releases. If ATM confirms payment, Tickets promotes the hold into issued tickets exactly once.

BEGIN
  lock capacity groups in deterministic order
  lock ticket tiers
  compute available = capacity - sold - active held
  reject if available is too low
  create hold with expiresAt
COMMIT

Checkout quantity should not be adjustable after the hold is created. If an app later needs adjustable quantities, reserve the maximum possible quantity before checkout and release unused capacity after confirmation.

Concurrency and idempotency

No-oversell is the core contract. Apps can render many storefronts, but Tickets must serialize scarce writes in the private database. Public repo records and relay/event-stream timing are never inventory locks.

Free limited tickets

Limited free tickets should use the same capacity transaction as paid tickets, without sending the user through checkout. This is expected to use tickets.atmosphere.claimFreeTicket. Apps should include buyer DID and a buyer assertion so free claims do not become anonymous RSVP spam.

1. Buyer clicks Get ticket inside the event app.
2. Event app calls Tickets with app service-auth.
3. Request includes buyer DID and buyer assertion.
4. Tickets verifies the app, buyer assertion, limits, and capacity.
5. Tickets issues the ticket immediately and emits app events.

QR and wallet passes

QR codes and wallet passes are presentation layers over issued tickets. Apps can enable hosted QR tickets, Apple Wallet passes, and Google Wallet passes per environment without building a pass provider integration themselves. Pass branding should use the app profile plus organizer, event, and tier display metadata. QR payloads must contain only opaque scan tokens or scan URLs, never DIDs, emails, payment ids, ticket ids, attendee answers, or raw secrets.

Hosted buyer ticket pages use tickets.atmosphere.tickets. Scanner staff can use the default QR scanner app at scan.atmosphere.tickets, so event apps do not need to ship scanner infrastructure just to launch ticketed events. Apps can still build custom scanner UX later by calling the same verification and check-in methods. Both hosted surfaces are served by the ATM runtime for launch, with atmosphere.money fallback URLs available for operational recovery.