Paid APIs and x402

A Paxeer X paid endpoint advertises its price through x402 version 2. The buyer selects an accepted offer, authorizes payment, and retries with payment evidence. The seller releases the resource after verifying the receipt and required commitment. Exact, metered, and subscription schemes share this evidence-bound lifecycle.

The HTTP payment exchange

1. The buyer requests the resource without payment.
2. The seller returns HTTP 402 with a PAYMENT-REQUIRED header and matching JSON body.
3. The buyer selects a supported scheme and network, verifies payee terms, and constructs a payment payload.
4. The buyer retries with PAYMENT-SIGNATURE, preserving the accepted offer and required extensions.
5. The seller verifies settlement and records fulfillment before returning the resource with PAYMENT-RESPONSE.
6. The buyer independently verifies the response receipt and settlement reference.

HTTP headers carry standard-base64 JSON. MCP and A2A bindings carry the corresponding JSON values. Settlement identity stays consistent across transports, so redelivering the same payment through another binding retains the same economic identity.

Define the offer

For a layerx:* network, extra.layerx.account names the destination account, such as agent:<did>:main, and currency names its money currency. The offered payTo must derive from that account under a supported account-ID derivation. Buyers refuse a mismatched recipient.

Add seller middleware

The Node package @sidiora/layerx-seller-middleware exports SellerMiddleware, ReceiptPayloadAuthority, and the payment-header codecs. Supply a trusted authority resolver, payment requirements, and a durable fulfillment repository. The following handler is the resource-release pattern used by the paid API example; middleware is the configured seller instance.

import { PAYMENT_SIGNATURE_HEADER } from "@sidiora/layerx-seller-middleware";

const header = request.headers[PAYMENT_SIGNATURE_HEADER.toLowerCase()];
const paymentHeader = Array.isArray(header) ? undefined : header;
const decision = await middleware.handle(
  "public-paid-api",
  paymentHeader,
  async () => resourceBody,
);
const headers = decision.kind === "payment-required"
  || decision.kind === "refused"
  || decision.kind === "released"
  ? decision.headers
  : { "retry-after": "1" };
response.writeHead(decision.status, {
  "content-type": "application/json", ...headers,
});
response.end(JSON.stringify(
  decision.kind === "payment-required" ? decision.body
    : decision.kind === "released" ? decision.resource
    : { state: decision.kind },
));

The example serves GET /paid. Its configuration selects protocol version, network, price, Asset, recipient, account, currency, receipt authority, and fulfillment directory. Keep credentials in the configured environment variables. Set the resource URL to the externally reachable endpoint your customer requests.

Persist fulfillment

A fulfillment record binds the caller's idempotency key to the request digest, canonical receipt, authorized batch, and returned resource. Persist it durably and return the stored resource for a matching retry. Refuse reuse of the same key for a different request. The example writes an exclusive file, synchronizes it and its directory, and checks the existing record after a concurrent write.

Integrate the buyer

BuyerMiddleware accepts a production client, source account, protocol selection, supported scheme/network pairs, configured receipt authorities, and retry policy. prepare(paymentRequiredHeader, callerIdempotencyKey) parses the offer and prepares payment through the typed quote workflow. fetch drives the HTTP exchange, while captureSettlement verifies the result. Use fetchGrant and captureGrantSettlement for grant-backed receives.

The buyer validates offered account and currency terms before quoting. Required extensions are echoed unchanged. Choose a stable caller idempotency key for one purchase and retain it with the accepted offer and activity identifier until the outcome is resolved.

Metered requests and subscriptions

A metered or subscription offer additionally commits to a nonzero payer and purpose hash. Subscription offers require a positive decimal-string windowSeconds below 2^64; metered offers omit the field.

The payer signs a canonical 346-byte Asset ordinal-7 grant. The receiver submits a canonical 733-byte Asset ordinal-6 receive that embeds the grant and receiver authorization. Every metered request is one draw. Every subscription renewal uses a distinct signed receive and idempotency key; a recurring allowance alone does not establish one renewal per period.

{
  "receive": "<733-byte canonical receive as hex>",
  "idempotencyKey": "<64-hex key>"
}

Validation binds the payer, recipient, Asset, amount, purpose, network, grant identity, allowance, per-draw maximum, expiry, controller, and signed context. Metered grants are non-recurring with a zero window. Unknown, paused, or unregistered Assets and changed payment facts are refused.

Select settlement assurance

Set extra.layerx.commitment to the assurance your resource requires. Authority keys come from verifier configuration. Missing evidence keeps settlement pending or refused; it never silently lowers the requested assurance.

Receipt verification and capture

The seller verifies canonical receipt encoding, activity binding, successful result, protocol body, authorized sequencer signature, and the accepted Asset, amount, and recipient. The gateway records a receipt-verified settlement. Success returns transaction: "lxp:<receipt_digest>".

The buyer checks success, the layerx extension, verificationLevel: "sequencer-signed", canonical receipt bytes, payer, network, Asset, recipient, and amount. It recomputes the receipt digest and requires both the declared digest and lxp: reference to match. An HTTP 200 or acknowledgement by itself does not establish settlement.

Recover uncertain payment outcomes

The public payment transport is JSON-RPC 2.0 at gateway POST /rpc. Submit a canonical activity with lx_sendActivity(canonical_hex, commitment). After an uncertain response, query the same activity with lx_getActivityStatus(activity_id) and lx_getReceipt(activity_id). Verify recovered evidence before releasing or capturing the resource.

For batched assurance, request lx_getProof("receipt", activity_id), require its canonical value to equal the recovered receipt, and verify inclusion against the authorized signed header. Preserve payment identity throughout recovery; a replacement debit does not resolve the original purchase.

Facilitators and transport interoperability

The x402 facilitator exposes /supported, /verify, and /settle. Verification is read-only; settlement is state-changing and completes against verified canonical receipts. HTTP, MCP, and A2A share the same message semantics. An identical settlement identity and receipt digest recover the existing settlement; a swapped receipt for that identity is an idempotency conflict.

Use service agreements for work that needs deadlines, delivered artifacts, review, and disputes. Continue with the SDK and native protocol modules for account, Asset, and activity integration.