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:
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(exactly4mica-credit) andnetwork.payTo(recipient address),asset, andmaxAmountRequired(v1) oramount(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 anX-PAYMENT header.
Version 2
Version 2 delivers requirements in a base64-encodedpayment-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.
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.