Skip to main content
A facilitator in the x402 protocol is a service that processes payments and provides settlement. It exposes /verify and /settle endpoints that work with x402 middleware to handle payment flows using ERC-3009 TransferWithAuthorization.

Prerequisites

  • Node.js 18+
  • pnpm (install via pnpm.io/installation)
  • A SKALE Chain endpoint
  • A wallet private key for signing settlement transactions
  • Basic knowledge of TypeScript

Overview

A facilitator service:
  1. Exposes /verify endpoint - Validates payment authorizations without onchain settlement
  2. Exposes /settle endpoint - Executes onchain payment settlements
  3. Exposes /supported endpoint - Returns supported payment schemes and networks
  4. Handles EIP-712 signature verification
  5. Prevents replay attacks via nonce tracking

Implementation

Step 1: Project Setup

Create a new project and install dependencies:
Install the required packages:
Update your package.json:

Step 2: TypeScript Configuration

Create tsconfig.json:

Step 3: Environment Configuration

Create .env file in the project root:
Add the variables:
Never commit your private key to version control. Add .env to your .gitignore file.

Step 4: Main Application

Create facilitator.ts with the facilitator server:

Running the Facilitator

Start the development server:
Your facilitator will be available at http://localhost:4022.

API Endpoints

GET /supported

Returns supported payment schemes and networks.Response:

POST /verify

Validates payment authorization without onchain settlement.Request:
Response (success):
Response (failure):

POST /settle

Settles a verified payment by broadcasting the transaction onchain.Request body is identical to /verify.Response (success):
Response (failure):

Lifecycle Hooks

The facilitator supports lifecycle hooks for custom logic:

Security Considerations

  • Store private keys securely in environment variables
  • Never commit .env files to version control
  • Implement rate limiting for production deployments
  • Monitor for suspicious activity
  • Use HTTPS in production
  • Consider using a multi-sig wallet for high-value operations

Resources