402The402Machine

HTTP API / COMPLETE FLOW / AGENT READY

Buy, pay, receive.
Then let it expire.

Use the native Lightning quote and polling flow, HTTP Payment Authentication with Lightning charge, or the L402 compatibility adapter. All three converge on the same atomic provisioning and narrowly scoped capabilities.

READY TO IMPORT

Use the format your tools understand.

Both files describe the public API only. They contain placeholders, never live invoices, tokens or capabilities.

01
OpenAPI 3.1Swagger UI, Redoc, code generators and validators
Download JSON ↓ 02
Postman collectionNative, Payment Auth and L402 requests
Download JSON ↓ 03
Agent discoveryCatalogue, OpenAPI, protocol, product, and guide entry points
Open JSON → 04
Agent purchase guideComplete curl flows and secret-safe capability handling
Read guide →

QUICKSTART

One purchase flow.
Three temporary tools.

Use a new idempotency key for each intended purchase. Repeating the same request with the same key returns the same order rather than creating another invoice.

1 · Catalogue→2 · Quote + pay→3 · Poll + save capability
STEP 1

Inspect the live catalogue

curl https://the402machine.com/api/catalog

Plan prices, lifetimes, quotas and availability come from the same catalogue used by the browser checkout.

STEP 2

Create a Lightning quote

curl -i -X POST https://the402machine.com/api/payments/catch \
  -H 'Idempotency-Key: replace-with-a-unique-key' \
  -H 'Content-Type: application/json' \
  --data '{"planId":"spark"}'

The expected response is HTTP 402 with orderId, amountSats and bolt11.

STEP 3

Poll until provisioned

curl https://the402machine.com/api/payments/{orderId}

HTTP 402 means payment is still pending. HTTP 200 returns the product capability once. Save it immediately.

Agent payment negotiation

Payment Auth
Send X-Payment-Protocol: payment. HTTP 402 carries WWW-Authenticate: Payment. Repeat the identical request with Authorization: Payment <credential>. HTTP 200 includes Payment-Receipt.
L402
Send X-Payment-Protocol: l402. HTTP 402 carries WWW-Authenticate: L402. Repeat the identical request with Authorization: L402 <macaroon>:<preimage>.

Never place invoices, preimages, macaroons or product capabilities in URLs, logs, analytics or shared environments. Credentials are bound to the request method, route and body.

BEFORE YOU CALL IT

Protocol rules.

The API deliberately uses capability URLs and bearer tokens instead of user accounts. Treat every dispensed token as a password.

AUTH

Authentication model

Owner, ingest, read and ping tokens have different roles. Send the correct value as Authorization: Bearer ***. Do not put bearer capabilities in query strings, logs, analytics or shared Postman environments.

PAYMENT

Three additive flows

The native flow returns a JSON quote and supports polling. Payment Authentication and L402 are optional agent adapters over the same BOLT11 invoice and provisioning path. This is not Coinbase x402 compatibility.

PRIVACY

WHISPER stays opaque

Encrypt WHISPER content locally with AES-256-GCM. Upload only application/octet-stream ciphertext. The encryption key never belongs in an API request.

LIFECYCLE

Expiry is final

Capabilities disappear at expiry, exhaustion or explicit destruction. Private responses use Cache-Control: no-store; clients should not assume recovery is possible.

Response codes

200 / 204
Success or successful no-content operation.
400
Invalid plan, payload, ciphertext, settings or schedule.
401
Owner authentication failed where existence is not hidden.
402
Lightning payment is required or still pending.
404
Unavailable, expired, consumed, destroyed or deliberately hidden resource.
425
A scheduled WHISPER has not reached its reveal time.
429
Rate limit reached. Respect Retry-After.

Public endpoints

Endpoint reference.

Operational provisioning endpoints are intentionally excluded. These are the routes intended for buyers, integrations and public status consumers.

01

PAYMENTS

Discover, quote and settle

GET/api/catalogPublic

GET /api/catalog Returns products, plans, prices, lifetimes, quotas and current availability.

POST/api/payments/catchIdempotency-Key

POST /api/payments/catch JSON body: {"planId":"spark|standard|long"}. Returns a CATCH invoice quote with HTTP 402.

POST/api/payments/whisperRaw ciphertext

POST /api/payments/whisper Requires X-Whisper-Plan. Set X-Whisper-Read-Limit to any whole number from 1 through the selected plan allowance. Optional X-Whisper-Reveal-At schedules reveal. Body must be client-encrypted AES-256-GCM bytes.

POST/api/payments/pulseIdempotency-Key

POST /api/payments/pulse JSON body: {"planId":"spark|standard|long"}. Returns a native quote by default. Add X-Payment-Protocol: payment or X-Payment-Protocol: l402 for agent negotiation.

GET/api/payments/{orderId}Public

GET /api/payments/{orderId} Poll payment state. HTTP 200 returns the provisioned CATCH, WHISPER or PULSE capability.

02

CATCH

Receive and inspect webhook traffic

ANY/c/{publicId}Optional ingest token

POST|PUT|PATCH|DELETE|GET|HEAD|OPTIONS /c/{publicId} Requests are accepted with or without the ingest token. Valid token-backed events are marked authenticated; tokenless or invalid-token requests remain public. Supported bodies are bounded JSON, text and form data.

GET/api/catch/{publicId}Owner token

GET /api/catch/{publicId} Private resource status, lifetime and quota usage.

GET/api/catch/{publicId}/eventsOwner token

GET /api/catch/{publicId}/events Cursor pagination with limit, cursor, access=public|authenticated, method, contentType and q filters. Bodies declare bodyEncoding; events include trusted sourceIp and locally resolved approximate IP location as ipLocation when available.

DELETE/api/catch/{publicId}/events/{eventId}Owner token

DELETE /api/catch/{publicId}/events/{eventId} Permanently deletes one stored event.

DELETE/api/catch/{publicId}Owner token

DELETE /api/catch/{publicId} Destroys the inbox, stored events and both CATCH capabilities.

03

WHISPER

Deliver client-encrypted bytes

GET/w/{publicId}Read token

GET /w/{publicId} Returns application/octet-stream ciphertext and spends one successful read. Scheduled messages return HTTP 425 with Retry-After before reveal. Exhausted, expired and invalid capabilities return 404.

04

PULSE

Ping, configure and publish status

POST/p/{publicId}Ping token

POST /p/{publicId} Records one heartbeat. Request bodies are ignored and never stored.

GET/api/pulse/{publicId}Owner token

GET /api/pulse/{publicId} Returns private monitor state, counters, settings and expiry.

PATCH/api/pulse/{publicId}Owner token

PATCH /api/pulse/{publicId} Updates any subset of name, description, expectedIntervalSeconds, graceSeconds and publicStatusEnabled.

GET/api/pulse/public/{publicStatusId}Public

When enabled, exposes only name, description, derived state and last signal time through an independent share-only identifier. It never exposes the heartbeat identifier, capabilities or operational settings.

DELETE/api/pulse/{publicId}Owner token

DELETE /api/pulse/{publicId} Destroys the monitor, both private capabilities and public sharing.

MACHINE-READABLE

Need exact schemas?

The OpenAPI file is the detailed contract for parameters, request bodies, security schemes and response shapes. Import the Postman collection when you want prepared requests and editable variables.

Download OpenAPIDownload Postman