Docs

API reference

Durable ATM XRPC methods for payout status, checkout, subscriptions, app links, and app events.

Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.

Contract index

This index mirrors the current local lexicon set used by the ATM app and AppView. Treat it as the docs-facing contract index; the source of truth remains the checked-in lexicons and generated types.

network.attested.payment.initiate	Strict broker initiation. Request body is only product.
network.attested.payment.status	Strict broker status lookup by token.
network.attested.payment.lookup	Strict payment lookup by supported refs.
money.atmosphere.actor.getPayoutStatus	App-facing payability check for a recipient DID.
money.atmosphere.actor.getProfile	Indexed ATM payment profile read.
money.atmosphere.payment.listSubscriptions	List app-visible payer or recipient subscription state.
money.atmosphere.payment.cancelSubscription	Cancel subscription through ATM-managed state.
money.atmosphere.payment.registerPayerRecord	Register or reconcile delegated payer record state.
money.atmosphere.payment.registerCreatorProof	Register creator proof state when explicitly delegated.
money.atmosphere.payment.declineRecord	Decline or mark a pending proof slot as unavailable.
money.atmosphere.catalog.registerAppLink	Register private app fulfillment for ATM catalog records.
money.atmosphere.event.receive	Optional app-hosted XRPC event receiver.
tickets.atmosphere.*	Ticketing module methods for availability, holds, issuance, verification, and check-in.

Auth matrix

Most integration bugs come from using the wrong identity for a call. App identity controls app configuration and fees. User assertions prove user intent. OAuth grants are only needed for PDS writes.

Surface	Auth	Environment	Notes
Hosted checkout initiation	App service-auth	test or live app config	Buyer assertion may be included privately when available.
Dashboard APIs	ATM dashboard session	current account	Human dashboard actions only.
HTTP webhooks	ATM signature	event envelope environment	Verify raw body and deduplicate delivery id.
XRPC receiver	ATM service-auth to app	event envelope environment	Optional AT Protocol-native callback path.
Ticket hold	App service-auth + optional buyer assertion	test or live app config	Required before paid scarce ticket checkout.
Ticket tier setup	App service-auth + organizer assertion	test or live app config	Proves the organizer authorized the app to configure tickets.

Endpoint card format

Endpoint cards use the same structure across the API reference so app developers can scan quickly: method, NSID, auth, retry behavior, idempotency boundary, common errors, request example, and response example.

Auth

Who signs the request or callback, and whether it is app service-auth, dashboard session, buyer assertion, or ATM service-auth.

Retry

Whether the call can be retried, and what state to check first if the request timed out.

Idempotency

The stable app-side key or resource boundary that prevents duplicate side effects.

Errors

Stable ATM error codes plus the developer action expected for each failure mode.

Payment initiation

POST

network.attested.payment.initiate

Start a broker-defined ATM checkout session.

Method: POST
Auth: App service-auth
Retry behavior: Retry transient 5xx failures with the same app order id only after checking whether a token was already returned.
Idempotency: One app order id and checkout token per purchase attempt.
Common errors: InvalidProduct, RecipientNotPayable, BrokerDidUnsupported, AppUnauthorized

request example

{
  "product": "atm.checkout.v1:<private-envelope>"
}

response example

{
  "token": "atm_checkout_...",
  "url": "https://checkout.atmosphere.money/checkout/..."
}

Payment status

GET

network.attested.payment.status

Poll status for a checkout/payment token.

Method: GET
Auth: App service-auth
Retry behavior: Safe to poll with backoff while the browser return page shows processing.
Idempotency: Read-only.
Common errors: TokenNotFound, AppUnauthorized

request example

/xrpc/network.attested.payment.status?token=atm_checkout_...

response example

{
  "status": "paid",
  "token": "atm_checkout_...",
  "payment": {
    "amount": 500,
    "currency": "usd"
  }
}

Payout status

GET

money.atmosphere.actor.getPayoutStatus

Check whether a creator or project can receive payments.

Method: GET
Auth: App service-auth
Retry behavior: Cache briefly; retry transient unavailable states before enabling checkout.
Idempotency: Read-only.
Common errors: ActorRequired, ActorNotFound, AppUnauthorized

request example

/xrpc/money.atmosphere.actor.getPayoutStatus?actor=did:plc:creator

response example

{
  "actor": "did:plc:creator",
  "payable": true,
  "status": "ready"
}

Subscriptions

GET

money.atmosphere.payment.listSubscriptions

List app-visible subscription relationships.

Method: GET
Auth: App service-auth or dashboard session
Retry behavior: Read-only; safe to retry with backoff.
Idempotency: Read-only.
Common errors: AppUnauthorized, InvalidRole

request example

/xrpc/money.atmosphere.payment.listSubscriptions?role=payer

response example

{
  "subscriptions": [
    {
      "id": "sub_...",
      "amount": 500,
      "currency": "usd",
      "cadence": "month",
      "status": "active"
    }
  ]
}

POST

money.atmosphere.payment.cancelSubscription

Cancel a subscription through ATM so payment state and proofs stay aligned.

Method: POST
Auth: App service-auth or dashboard session
Retry behavior: If the request times out, fetch subscription state before retrying cancellation.
Idempotency: Subscription id.
Common errors: SubscriptionNotFound, NotAllowed, ProcessorError

request example

{
  "subscriptionId": "sub_..."
}

response example

{
  "subscriptionId": "sub_...",
  "status": "canceled"
}

Catalog app links

POST

money.atmosphere.catalog.registerAppLink

Method: POST
Auth: App service-auth
Retry behavior: Safe to retry with the same product, app DID, and appProductRef.
Idempotency: Product URI plus app DID plus appProductRef.
Common errors: ProductNotFound, AppUnauthorized, InvalidFulfillmentUrl

request example

{
  "product": {
    "uri": "at://did:plc:creator/money.atmosphere.product/abc",
    "cid": "bafy..."
  },
  "appProductRef": "product_123",
  "fulfillmentUrl": "https://app.example/dashboard/products/product_123"
}

response example

{
  "ok": true
}

App event receiver

POST

money.atmosphere.event.receive

Optional app-hosted XRPC receiver for ATM events.

Method: POST
Auth: ATM service-auth to app
Retry behavior: ATM redrives failed deliveries; receivers should return 2xx for already-processed delivery ids.
Idempotency: ATM deliveryId plus event id.
Common errors: InvalidSignature, UnsupportedEvent, DuplicateDelivery

request example

{
  "id": "evt_...",
  "deliveryId": "del_...",
  "environment": "test",
  "type": "payment.completed",
  "data": {}
}

response example

{
  "ok": true
}

Tickets XRPC

Ticket-specific methods live under tickets.atmosphere.*. ATM hosts the runtime for launch, but ticket-specific guides live on atmosphere.tickets.

GET

tickets.atmosphere.getTicketAvailability

Read app-scoped ticket availability derived from private capacity, holds, issued tickets, and sale windows.

Method: GET
Auth: App service-auth
Retry behavior: Read-only; safe to refresh with short backoff.
Idempotency: Read-only.
Common errors: EventRequired, AppUnauthorized, TicketsModuleDisabled

request example

/xrpc/tickets.atmosphere.getTicketAvailability?eventUri=at://...&environment=test

response example

{
  "eventUri": "at://...",
  "items": [
    { "tierId": "tier_...", "available": 42 }
  ]
}

POST

tickets.atmosphere.createTicketHold

Atomically reserve paid ticket capacity and return an ATM checkout URL.

Method: POST
Auth: App service-auth plus optional buyer assertion
Retry behavior: If no response arrives, check for an existing hold tied to the app order before creating another hold.
Idempotency: App order id plus buyer DID plus tier ids and quantities.
Common errors: TicketHoldUnavailable, BuyerAssertionInvalid, AppUnauthorized

request example

{
  "environment": "test",
  "eventUri": "at://...",
  "buyerDid": "did:plc:buyer",
  "buyerAssertionJwt": "...",
  "items": [{ "ticketTierId": "tier_...", "quantity": 2 }]
}

response example

{
  "holdId": "hold_...",
  "expiresAt": "2026-06-05T00:10:00.000Z",
  "checkout": {
    "url": "https://checkout.atmosphere.money/checkout/..."
  }
}

POST

tickets.atmosphere.claimFreeTicket

Claim a limited free ticket without checkout while enforcing capacity transactionally.

Method: POST
Auth: App service-auth plus buyer assertion
Retry behavior: Safe to retry with the same idempotency key; duplicate claims return existing issued-ticket state.
Idempotency: Required idempotency key for the event, buyer, tier, and app.
Common errors: TicketHoldUnavailable, BuyerAssertionInvalid, DuplicateClaim

request example

{
  "environment": "test",
  "eventUri": "at://...",
  "ticketTierId": "tier_...",
  "buyerDid": "did:plc:buyer",
  "buyerAssertionJwt": "..."
}

response example

{
  "ticket": {
    "id": "ticket_...",
    "status": "issued"
  }
}

POST

tickets.atmosphere.checkInTicket

Check in an issued ticket through an opaque scan token.

Method: POST
Auth: App service-auth or scanner authority
Retry behavior: Safe to retry the same scan; repeat check-in should return the existing checked-in state.
Idempotency: Scanner idempotency key or ticket token plus check-in list.
Common errors: TicketTokenInvalid, TicketVoided, TicketAlreadyCheckedIn

request example

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

response example

{
  "status": "checked_in",
  "checkedInAt": "2026-06-05T00:00:00.000Z"
}