402The402Machine

HTTP API / COMPLETE FLOW / AGENT READY

Buy, pay, receive.
Then let it expire.

Use native Lightning, HTTP Payment Authentication, or L402. All three return the same temporary product capabilities.

READY TO IMPORT

Pick a contract.

Public API definitions with placeholders only. No live credentials.

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.

G

GATE CONTRACT PREVIEW / DISABLED BY DEFAULT

Paywall an external API route

POST/api/gate/intentsProject capability

POST /api/gate/intents Creates or recovers one request-bound invoice. The stored Lightning Address receives the payment directly.

POST/api/gate/intents/{intentId}/provePayer proof

POST /api/gate/intents/{intentId}/prove Submits a preimage or Payment Authentication credential for the existing intent. A verified success returns Gate-Receipt.

GET/api/gate/intents/{intentId}Optional verify

GET /api/gate/intents/{intentId} Polls provider verification only when cryptographic proof is available.

GET/.well-known/gate-jwks.jsonPublic

Publishes the Ed25519 key for GATE receipts. GATE is HTTP 402 and Payment Authentication, not x402 compatibility.

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?

Use OpenAPI for the contract or Postman for prepared requests.

Download OpenAPIDownload Postman