Skip to main content

X402 flow

X402Flow handles the client-side x402 payment protocol for 4Mica. It turns the paymentRequirements from a 402 Payment Required response into a signed payment header (and an optional /settle call) that the facilitator accepts. Create a flow from your client:
There is no tab step: each payment carries a random 32-byte reqId minted locally — uniqueness is all core asks of it. The only read before signing is the asset’s active settlement cycle: the flow builds the payment with client.newPayment, scoped to that cycle and stamped by core’s clock, and signs it with the client as the payer. Both signing methods always use EIP-712 and error unless the scheme is exactly 4mica-credit.

What the SDK expects

At minimum, paymentRequirements must include:
  • scheme (exactly 4mica-credit) and network.
  • payTo (recipient address), asset, and maxAmountRequired (v1) or amount (v2).
  • Optionally extra.validation ({ validator, subject, deadline?, params? }) to gate the payment on an external validator.

Version 1

Version 1 returns payment requirements in the JSON response body. Sign them into an X-PAYMENT header.

Version 2

Version 2 delivers requirements in a base64-encoded payment-required header and signs them into a PAYMENT-SIGNATURE header. If accepted.extra.validation is present, the SDK attaches the validation requirement to the signed payment.

Settle through a facilitator

If your resource server proxies to a facilitator, reuse the SDK to settle a payment after verifying it. settlePayment POSTs { x402Version, paymentPayload, paymentRequirements } to {facilitatorUrl}/settle — paymentPayload is the envelope object, not the base64 header.
The signed payment carries the request in two forms: payment.payload is the wire object the envelope holds ({ payload, signature }), and payment.request is the same PaymentRequest, typed. When the facilitator relays the operator’s receipt, settlement.receipt holds it as a GuaranteeReceipt — check it with client.payment.verifyGuarantee.
settlePayment only hits /settle. Resource servers should still verify a payment before granting access. Rejections come back as HTTP 200 with success: false — check the receipt, not just the absence of an exception.

Next steps

Payment middleware

Charge for a route with @4mica/x402’s Express middleware.

Client operations

Deposit collateral, sign payments, and settle cleared cycles.