Docs

Framework examples

Framework-agnostic integration shape, with Next.js and Node examples that follow the same ATM contracts.

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

Architecture first

ATM is framework-agnostic. The durable integration is the server contract: create checkout from a trusted backend, redirect or embed the ATM-hosted checkout, verify ATM events, deduplicate delivery ids, and fulfill from ATM truth. Next.js is one polished example of that architecture, not the architecture itself.

Server first

Checkout envelopes, service-auth, webhook secrets, buyer assertions, and fulfillment mutations stay on your backend.

Client light

Browsers show app UX, call your backend, and return from checkout; they do not build private envelopes.

Events as truth

HTTP webhooks and optional XRPC receivers drive fulfillment. Browser returns are only UX hints.

Framework optional

Next.js, Express, Fastify, Hono, Workers, Go, or Python can all implement the same flow.

Portable backend contract

Every ATM app integration, regardless of framework, has the same five server-side steps.

01
Create app order
Store your app order, ticket hold, product selection, or subscription intent in your own backend.
02
Check payability
Call ATM payout status before exposing an active payment button.
03
Start checkout
Build the private ATM checkout envelope and call ATM from your backend.
04
Verify event
Verify signed HTTP webhooks or optional XRPC receiver service-auth.
05
Fulfill idempotently
Deduplicate by delivery id and ATM payment id before changing app state.

Implementation examples

Start with the runtime closest to your app. The code differs by routing framework; the payment, webhook, XRPC, and idempotency rules do not.

Next.js	Full starter with route handlers for checkout and webhooks.
Node HTTP	Minimal server for agents, services, or backend-only apps.
Express	Webhook route example using the same SDK verification helpers.
Fastify	Webhook route example for Fastify raw-body handling.
Hono / Workers	Edge-oriented recipes are available for webhook verification. Use the Node SDK where the runtime supports Node crypto; use the Web Crypto recipe on Workers.
Other languages	Use the XRPC contracts, signed webhook format, and event payload docs directly until official SDKs exist.

Next.js starter

The template at examples/atm-next-starter is for app teams already using Next.js route handlers. It maps the portable backend contract onto src/app/api, but the same SDK calls and verification rules apply outside Next.js.

cd examples/atm-next-starter
npm install
npm run typecheck
npm run dev

Checkout route	src/app/api/checkout/route.ts
Webhook route	src/app/api/webhooks/atm/route.ts
ATM client	src/lib/atm.ts
Order boundary	src/lib/orders.ts

Node HTTP starter

The existing starter at examples/atm-node-app is a minimal HTTP server for checkout, status polling, webhooks, optional XRPC receivers, and Tickets helper calls. It is the clearest reference if you want to port ATM to a different backend framework or language.

cd examples/atm-node-app
cp .env.example .env
npm run build --prefix ../../packages/app-node
npm install
npm run typecheck
npm run smoke

Additional runtimes

The SDK roadmap should stay architecture-agnostic. New examples should prove one runtime at a time without changing the core ATM contract.

Express and Fastify

Current route snippets show raw-body verification. Promote them into runnable mini apps once the package is public.

Hono and Workers

Hono can use the Node SDK in Node-compatible runtimes. Workers use the Web Crypto verification recipe until an edge-specific package exists.

Go and Python

Likely start as webhook verification and XRPC examples before full SDKs.

Browser package

Keep separate from app-node; only safe embedded checkout/status helpers belong in browser code.

What to copy

Server-only ATM client setup.
Payability check before showing checkout.
Checkout initiation with app order id in private metadata.
Raw-body webhook verification.
Delivery id deduplication before fulfillment.
Payment id stored beside the app order.
The same boundaries if you port the starter to another backend stack.

What to replace

Replace sample service-auth minting with a real AT Protocol service-auth flow.
Replace in-memory/no-op order functions with your database.
Replace app.example URLs with registered app origins.
Replace generic product purchase copy with your app module policy.
Pin @atmosphere-money/app-node@beta and review changelog notes before updating.