Answer a request with HTTP 402 and a payment envelope that names the asset, amount, recipient and required commitment level. The caller returns your alternative unchanged with a receipt or a signed grant draw attached. You verify the evidence before releasing anything, then hand back a settlement reference of lxp:<receipt_digest>. Pick exact per call, metered grant draws or subscription renewals. Idempotency keys and fulfilment records make a retry replay one payment instead of charging twice.

What it does

A service that wants payment answers with HTTP 402 and a PAYMENT-REQUIRED header: a Base64 JSON envelope at x402Version: 2 carrying the resource URL and between one and 32 payment alternatives for that same resource. The caller selects one alternative, returns it unchanged in a PAYMENT-SIGNATURE header, and attaches either a canonical LayerX receipt or a signed grant draw as the payload. The seller verifies the evidence that the selected alternative asked for before releasing anything, then answers with a PAYMENT-RESPONSE header whose settlement reference is lxp:<receipt_digest>. An acknowledgement, a queue position, a submission identifier or a successful HTTP response is never treated as proof of payment.

Key capabilities

• Three schemes: exact per call, metered per-request grant draws, and subscription renewals.
• Every alternative names its own asset, amount, recipient and commitment; the buyer may not substitute any of them.
• Commitment levels executed, batched and finalised decide which receipt evidence the seller must verify.
• Idempotency keys plus persisted fulfilment records make a retry replay one payment rather than charging twice.
• Buyer and seller middleware are part of both the TypeScript and Python SDKs.
• A reference-bound invoice settles once; a second attempt is refused with INVOICE_ALREADY_SETTLED (-217).

Differentiators

The commitment level travels inside the offer and is never inferred from the payment header: executed needs the sequencer-signed receipt, batched adds Merkle inclusion in an authorised batch header, finalised adds the guarantor checkpoint certificate, and missing evidence never downgrades a request to executed. Trust inputs come from the verifier's configured network authority, not from the payment response. For grant draws the payer signs the authorisation and the seller cannot manufacture it; the ledger checks both signatures and every grant restriction before debiting.

Outcomes

• Charge per request without an account, an invoice cycle or a card
• Buyers verify a receipt digest against the chain instead of your word
• Each settlement is a LayerX activity, priced at 1/10 of a cent

Technical notes

• Header limits: each Base64 envelope must decode to at most 65,536 bytes; network matches layerx:<id>, asset and payTo are 64 lowercase hex characters, amount is a canonical decimal at most 2^128−1, and maxTimeoutSeconds is at most 2^32−1.
• extra.layerx.commitment is one of executed, batched, finalised. The spelling finalized is invalid at both boundaries. An exact offer with no extra.layerx requires executed. Unknown schemes and incomplete extra.layerx values are refused.
• The receipt digest is SHA-256 over LXP/v1/merkle-leaf, one zero byte, then the complete canonical receipt bytes. The canonical receive payload is 733 bytes; the gateway's payment requirement is 160 bytes as a signing preimage and 224 bytes encoded with the service signature.
• Grant issue is Asset ordinal 7, revoke is 8, and each draw is a receiver-signed ordinal-6 activity bound to the payer's grant, the request digest and a 32-byte idempotency key. A purpose that does not match the challenge is refused with PURPOSE_MISMATCH (-216).
• Transport is JSON-RPC 2.0 at the gateway's POST /rpc, with POST /v1/settle for merchant settlement. The public examples read LAYERX_RPC_URL, LAYERX_FAUCET_URL and LAYERX_DID, and authenticate with LAYERX_RPC_TOKEN and LAYERX_FAUCET_TOKEN.
• Each settlement is a LayerX activity, and a LayerX activity costs 1/10 of a cent.
• Not yet fully implemented: the payload's verificationLevel is only ever the literal sequencer-signed, so the finalised commitment is reachable in the envelope but not in that field. Finalised verification also needs operator-supplied RpcCheckpointAuthority inputs: bonded guarantor keys, required guarantor count, settlement domain and availability confirmation. Those inputs are not in the repository, and a deployment without them stays unqualified for finalised payments.
• Runtime floors: Node.js 22 or newer, Python 3.11 or newer.

# pip install layerx-sdk
from layerx_sdk.x402_http import BuyerMiddleware

buyer = BuyerMiddleware(rpc, signatures, resolve_receipt, {("exact", "layerx:1")})
challenge = response.headers["PAYMENT-REQUIRED"]
required, offer = buyer.parse_offer(challenge)
header = buyer.prepare(challenge, canonical_hex, activity_id, payer)
if header is None:
    raise RuntimeError("payment pending; recover the receipt for this activity")
paid = session.get(required["resource"]["url"], headers={"PAYMENT-SIGNATURE": header})

More in LayerX agent domain