Introducion

What is x402 Facilitator?

The x402 protocol introduces the Facilitator, an optional service designed to streamline payment processing for payees. Its primary goal is to simplify how payees validate payment credentials from payers and settle transactions.

A Facilitator's core duties include:

• Payment Verification: Confirming the validity of a payer's submitted payment.
• Payment Settlement: Executing the payment settlement on the blockchain network for the payee.
• Result Reporting: Communicating the outcome of the verification and settlement back to the server, which then determines whether to grant the client's request.

Leveraging a Facilitator abstracts away the complexities of the blockchain. payees are freed from the need to run their own nodes or develop bespoke payment validation systems, leading to a simpler integration process and ensuring that transactions are verified accurately and in real time.

How x402 work with Facilitator？

The x402 protocol relies on EIP-3009. EIP-3009 is an extension of the ERC20 standard, with its core feature being transferWithAuthorization. This function allows User A (payer) to sign a transfer transaction off-chain (the payload includes from, to, value, an expiration time, and a random nonce). This payload and its signature are then sent to User B (payee) off-chain. User B can then submit this to the blockchain to execute the ERC20 transfer, bearing all the gas fees in this scenario.

The x402 protocol flow is as follows:

1. The payer sends an initial request to the payee. The payee responds with an HTTP 402 Payment Required status code, along with a PaymentRequirements object (containing the stablecoin address, settlement network, required amount, and recipient address).
2. The payer signs a transaction based on the PaymentRequirements and sends the resulting signature to the payee.
3. The payee verifies the signature with a Facilitator. Upon successful verification, the payee processes the original request. After processing, the payee instructs the Facilitator to execute the on-chain settlement and, based on the settlement result, determines whether to deliver the final response to the payer.

Quickstart for Zan x402 Facilitator

1. Registration and API Key: register with the Zan x402 Facilitator service (comming soon) to obtain your API key. This key is required to authenticate your requests.
2. Check Supported Protocols：before initiating payments, you can query the /supported endpoint to get the facilitator's capabilities.
3. Verifying and Settling Payment: as a payee, you can use any x402-compatible facilitator client to interact with the Zan x402 Facilitator. The facilitator exposes two primary endpoints for processing payments submitted by your payers.
   • use /verify to verify the user payment is valid before handling user request.
   • use /settle to execute the transaction and get the funds after handling request

CoreAPI

/supported Endpoint

Get the facilitator's capabilities:

• The supported x402 protocol version(s).
• The accepted payment scheme (e.g., transferWithAuthorization).
• The supported blockchain network(s).

/verify Endpoint

Use this endpoint to confirm the validity of a payment without executing it on-chain.

• Function: It receives an x402 payment payload, extracts the underlying transaction, and verifies its validity (e.g., signature, nonce, value) without broadcasting it to the network.
• Response: Returns a status indicating whether the payment is valid (isValid: true/false).

/settle Endpoint

Use this endpoint to execute the transaction and claim the funds after a payment has been successfully verified.

• Function: It receives the same x402 payment payload, signs it, and broadcasts the transaction to the blockchain network.
• Response: Upon successful execution, it returns the on-chain transaction signature as proof of settlement. The tokens are then transferred from the payer's address to your designated recipient address.

Integration with x402-express middleware

For a quick setup, use the x402-express middleware. It automatically enforces x402 payments on your Express routes.

Functionality:

1. Intercepts requests to protected routes.
2. Responds with 402 Payment Required if payment is missing.
3. Handles payment validation and settlement via a Facilitator.
4. Grants access after successful payment.

📘

Note:

Middleware for other popular frameworks is also available. See the x402 packages for more information.

app.use(
  paymentMiddleware(
    ${PAYEE_ADDRESS},           // payee address
    {
      "GET /path/to/protected": {
        price: "$0.0001",         // Price in USD
        network: ${NETWORK},         // network for payee address
      },
    },
    {
      url: https://api.zan.top/facilitator/v1,       
      createAuthHeaders: async () => ({       // token to verify on ZAN
        verify: { "Authorization": "Bearer token" },  
        settle: { "Authorization": "Bearer token" }
      })
    }
  ),
)

Call API with HTTP Client

You can also call the zan facilitator endpoint on by building the following request. See the x402 packages for more information.

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "${NETWORK}",
    "payload": {
      "signature": "${PAYMENT_SIGNATURE}",
      "authorization": {
        "from": "${PAYER_ADDRESS}",
        "to": "${PAYEE_ADDRESS}",
        "value": "${PAYMENT_AMOUNT}",
        "validAfter": "${PAYMENT_VALID_AFTER_TIMESTAMP}",
        "validBefore": "${PAYMENT_VALID_BEFORE_TIMESTAMP}",
        "nonce": "${PAYMENT_RANDOM_NONCE}"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "${NETWORK}",
    "maxAmountRequired": "${PAYMENT_AMOUNT}",
    "resource": "${REQUEST_RESOURCE}",
    "description": "${REQUEST_DESCRIPTION}",
    "payTo": "${PAYEE_ADDRESS}",
    "maxTimeoutSeconds": ${EXPIRE_TIME_SECOND},
    "asset": "${PAYMENT_ASSET_ADDRESS}",
    "extra": {
      "name": "${PAYMENT_ASSET_NAME}",
      "version": "${PAYMENT_ASSET_VERSION}"
    }
  }
}

And You need to curl with ZAN facilitator bear token.

curl --location 'https://api.zan.top/facilitator/v1/${API_PATH}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ${TOKEN}' \
    --data '${PAYLOAD}'

Our agentic payment is coming soon

1. A financial-grade identity verification framework for agents, powered by TEE and ZK, enables secure, auditable identity anchoring and supports a permissionless, decentralized Trustless Agent Store.
2. Natively compatible with A2A, AP2, and X402, the system provides enhanced Communication Protection (CP) and cross-chain trust assurance to ensure payment intents are authentic, tamper-proof, and Sybil-resistant.
3. Developers and enterprises can quickly integrate micropayments, revenue-sharing, and auto-settlement via lightweight options—ADK, APIs, and RESTful interfaces—for scalable, low-latency, compliant agentic payments.