x402 Merchant & Facilitator

x402 Merchant & Facilitator API

Base URL: https://ai.cryptoapis.io/x402/merchant. Authenticated with a Crypto APIs key that has the X402_FACILITATOR feature. The facilitator verifies a buyer's signed payment and settles it on-chain with its own gas wallet — non-custodially: it can never move funds the buyer did not authorize.

The 402 challenge

When an unpaid request hits your paid endpoint, your API answers 402 Payment Required with a PaymentRequirements object describing what to pay (asset, amount, network, pay-to address, and any family-specific extra). The buyer authorizes and signs it (see x402 Buyer), then retries with the signed payment attached.

Endpoints

• POST /verify — check a buyer's signed payment against the PaymentRequirements without settling. Returns { isValid, payer, invalidReason?, invalidDetail?, simulationLogs? }. Verification is actionable: a failure names the specific cause (e.g. simulation_reverted + evm_insufficient_balance, requirements_mismatch, unsupported_asset) and populates payer even on rejection.
• POST /settle — verify and then broadcast the payment on-chain with the facilitator's gas wallet. Returns the settlement result and transaction reference.
• GET /supported — the assets, networks and per-network facilitator signers currently operational. A network listed with an empty signers array is announced but not yet live.

Settlement quota headers

/verify and /settle carry the merchant's per-billing-cycle settlement quota on every reply as X-X402-Settlement-Limit / -Remaining / -Reset, so you can self-throttle before hitting a 429.

Integrating

Use @cryptoapis-io/x402-merchant-sdk (Express / Hono / Next.js) to wire the paywall, the 402 challenge, and the verify/settle round-trip in a few lines. The SDK is non-custodial and holds no keys.