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.2ATM API beta: 2026-0647 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 guidellms.txt

Short machine-readable context that tells agents when and how to use ATM.

Open guideFull agent context

Longer agent prompt template, architecture summary, and safety boundaries.

Open guideMCP for agents

A local test-mode wrapper for ATM docs, fixtures, delivery logs, and config inspection.

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

Discovery files

ATM exposes public agent discovery files at the root of atmosphere.money. Point coding agents at these before asking them to wire payments so they choose the hosted ATM flow, server SDK, verified events, and private-data boundaries from the start.

https://atmosphere.money/llms.txtShort index of the ATM docs, SDK packages, default recommendation, and do-not-cross boundaries.
https://atmosphere.money/llms-full.txtLonger agent context with architecture, checkout sequence, tickets sequence, auth model, and a copyable prompt.
https://atmosphere.money/sitemap.xmlSearch and crawler index for the docs entry points agents should find.

MCP wrapper

@atmosphere-money/mcp is the agent-friendly local wrapper for ATM developer actions. It is deliberately scoped to integration work: docs discovery, signed fixtures, app config inspection, test event delivery, delivery logs, test redrive, and test checkout initiation with caller-supplied service-auth.

MCP for agents

Install, configure, and use the local MCP server safely.

Open guideTesting package

Generate signed fixtures for receiver tests without calling ATM.

Open guideAPI reference

See the underlying test/config/log endpoints exposed to developer tooling.

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
Read https://atmosphere.money/llms.txt first.
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