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. ATM broker methods are served through a lex-server router at the same /xrpc/{nsid} paths. Treat this 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.app.requestRecipientApproval	Request creator approval before accepting payments for that recipient.
money.atmosphere.billing.requestKofiMigrationBatch	Create a private creator billing migration review batch.
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 repo writes through a user's PDS.

Surface	Auth	Environment	Notes
Hosted checkout initiation	App service-auth	test or live app config	Requires approved app-recipient scope unless the app is selling for itself.
Creator approval request	App service-auth	test or live app config	Creates or updates a private approval request for the creator to confirm in ATM.
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.
Developer utility APIs	Environment webhook secret	test or live, with live mutations blocked where noted	Used by dashboard helpers, setup scripts, and the local ATM MCP server.
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"
}

Creator app approval

POST

money.atmosphere.app.requestRecipientApproval

Request creator approval for an app to accept payments for that recipient.

Method: POST
Auth: App service-auth
Retry behavior: Safe to retry. The request is idempotent by app DID, recipient DID, and environment.
Idempotency: One approval scope per app DID, recipient DID, and environment.
Common errors: AppUnauthorized, RecipientNotFound, RecipientAppApprovalBlocked

request example

{
  "recipientDid": "did:plc:creator",
  "environment": "test",
  "paymentTypes": ["tip", "shop"],
  "feeShareBps": 300,
  "publicRecords": {
    "defaults": {
      "appRecord": "public",
      "attestation": "public",
      "payerCanChoose": true,
      "coupleInCheckout": true
    }
  },
  "requestReason": "Enable Example App checkout",
  "setupReturnUrl": "https://app.example/settings/payments"
}

response example

{
  "id": "apr_...",
  "status": "pending",
  "dashboardUrl": "https://atmosphere.money/dashboard?tab=creator&focus=apps&appApproval=apr_...",
  "onboardingUrl": "https://atmosphere.money/onboard?intent=creator&appApproval=apr_...",
  "paymentTypes": ["tip", "shop"],
  "feeShareBps": 300
}

Billing migration

POST

money.atmosphere.billing.requestKofiMigrationBatch

Create a private review batch for importing creator billing relationships from a Ko-fi-style membership export.

Method: POST
Auth: App service-auth
Retry behavior: Safe to retry with the same creator, environment, export, and requested cutover time after checking the returned batch.
Idempotency: App DID plus creator DID plus environment plus normalized migration export.
Common errors: AppUnauthorized, CreatorNotFound, InvalidCsv, MigrationSourceUnsupported

request example

{
  "creatorDid": "did:plc:creator",
  "environment": "test",
  "csvText": "Name,Email,Tier,Amount...",
  "requestedCutoverAt": "2026-07-01T00:00:00.000Z",
  "metadata": {
    "appCreatorRef": "creator_123"
  }
}

response example

{
  "batch": {
    "id": "mig_...",
    "status": "review_required"
  },
  "dashboardUrl": "https://atmosphere.money/dashboard?tab=creator&focus=billing-migration",
  "summary": {
    "totalRows": 120,
    "matchedRows": 108,
    "needsReviewRows": 12
  },
  "tiers": [
    {
      "name": "Monthly supporter",
      "count": 84
    }
  ],
  "warnings": [
    "12 rows need creator review before import."
  ]
}

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
}

Developer utilities

These are Next.js app utility routes rather than lexicon-backed XRPC contracts. They exist so app developers, setup scripts, CI, and the local ATM MCP server can inspect configuration and test receivers without opening the dashboard.

GET

/api/app/developer/config

Read sanitized app developer configuration for test or live.

Method: GET
Auth: Environment webhook secret
Retry behavior: Read-only; safe to retry.
Idempotency: Read-only.
Common errors: AppRequired, AppConfigNotFound, Unauthorized

request example

/api/app/developer/config?app=did:plc:app&environment=test

response example

{
  "appDid": "did:plc:app",
  "environment": "test",
  "status": "active",
  "webhook": {
    "configured": true,
    "paused": false
  },
  "modules": {
    "payments": true,
    "products": true,
    "tickets": false
  }
}

POST

/api/app/developer/test-event

Queue a test-mode app.webhook.test event to the app webhook or XRPC receiver.

Method: POST
Auth: Test environment webhook secret
Retry behavior: Safe to retry; test events are observability probes and should not fulfill real orders.
Idempotency: Each call creates a separate test delivery.
Common errors: LiveDeveloperActionUnsupported, WebhookNotConfigured, AppConfigNotFound, Unauthorized

request example

/api/app/developer/test-event?app=did:plc:app&environment=test

response example

{
  "ok": true,
  "environment": "test",
  "deliveryId": "whd_..."
}

GET

/api/webhooks/atm

List delivery logs for app webhook and XRPC receiver deliveries.

Method: GET
Auth: Environment webhook secret
Retry behavior: Read-only; safe to retry.
Idempotency: Read-only.
Common errors: AppRequired, AppConfigNotFound, Unauthorized

request example

/api/webhooks/atm?app=did:plc:app&environment=test&status=failed&limit=50

response example

{
  "deliveries": [
    {
      "id": "whd_...",
      "eventType": "payment.completed",
      "status": "failed",
      "attemptCount": 1
    }
  ]
}

POST

/api/webhooks/atm

Redrive a delivery or status-filtered batch for the selected app environment.

Method: POST
Auth: Environment webhook secret
Retry behavior: If the request times out, list deliveries before retrying to avoid confusing duplicate operator actions.
Idempotency: Delivery id or status-filtered redrive batch.
Common errors: DeliveryNotFound, AppConfigNotFound, Unauthorized

request example

{
  "deliveryId": "whd_..."
}

response example

{
  "ok": true,
  "queued": 1
}

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. First-party scanner authority is derived from the scanner session and private grant, not from a browser-submitted DID.

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, ScannerNotAuthorized, TicketAlreadyCheckedIn

request example

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

response example

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