Docs

Agent integration

A concise checklist for using coding agents to add ATM checkout, webhooks, and tests safely.

Closed beta@atmosphere-money/app-nodeSDK beta: 0.0.0-beta.0ATM API beta: 2026-0642 lexicons

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

What to give the agent

Coding agents work best when they get a narrow ATM contract, a starter file, and a verification loop. Give the agent the package docs, your app's order model, and the exact backend route where checkout should start.

App Node SDK

Server-side helpers for checkout, status, webhooks, XRPC receivers, and Tickets.

Open guideFramework examples

Next, Node, Express, Fastify, Hono, and Worker-oriented examples.

Open guideTesting package

Signed fixture helpers for app receiver tests.

Open guideWebhook test console

Generate a test event and redrive receiver behavior.

Open guide

Safe implementation boundary

The agent should write server-side integration code. It should not put service-auth, webhook secrets, checkout envelopes, buyer assertions, ticket scan tokens, or fulfillment mutations into browser components.

Browser

  • Shows app UI
  • Calls your backend
  • Follows ATM checkout URL

App backend

  • Mints app service-auth
  • Creates checkout
  • Verifies events
  • Fulfills orders

ATM

  • Owns hosted checkout
  • Tracks payment state
  • Sends app events
  • Coordinates proofs and tickets

App database

  • Stores app order ids
  • Tracks fulfillment state
  • Deduplicates delivery ids
  • Stores ATM payment ids

Environment variables

Keep environment names boring and explicit. Agents can wire local examples faster when the variable names match the docs.

ATM_APP_DIDYour app DID. Used as the app service-auth issuer.
ATM_APP_SERVICE_AUDIENCEUsually did:plc:a54sdlhmv7xklga67xamqfyq#AttestedNetwork.
ATM_BASE_URLhttps://checkout.atmosphere.money for production or local ATM during development.
ATM_WEBHOOK_SECRETEnvironment-scoped signing secret from the ATM app dashboard.
ATM_WEBHOOK_PREVIOUS_SECRETOptional previous secret during rotation.

Prompt checklist

A good agent prompt should include the integration outcome and the test that proves it. This keeps the work scoped and reviewable.

text
Use @atmosphere-money/app-node from the backend only.
Add a checkout route for this app order model: <describe order>.
Call getPayoutStatus before initiatePayment.
Store the ATM payment token/id with the app order.
Add an ATM webhook route using createNextWebhookRoute or createNodeWebhookHandler.
Deduplicate by ATM delivery id before fulfillment.
Add tests using @atmosphere-money/testing fixtures.
Do not expose ATM_WEBHOOK_SECRET, service-auth, or checkout envelopes to browser code.

Webhook test loop

The fastest local loop is fixture first, dashboard event second, full sandbox checkout third.

  1. 01

    Fixture test

    Use @atmosphere-money/testing to create a signed payment.completed request.

  2. 02

    Route check

    Verify your handler rejects bad signatures and ignores duplicate delivery ids.

  3. 03

    Dashboard event

    Send a test event from the ATM app dashboard once your receiver URL exists.

  4. 04

    Sandbox checkout

    Run a test checkout and fulfill only from ATM event truth.

Common mistakes

  • Building atm.checkout.v1 envelopes in browser code.
  • Fulfilling from the checkout return page before a verified ATM event arrives.
  • Parsing webhook JSON before preserving the exact raw request body.
  • Reusing one service-auth JWT across multiple XRPC methods.
  • Treating a buyer DID hint as a payer OAuth grant.
  • Letting test and live webhook secrets share the same receiver state.
Agent integration - Atmosphere Money Docs