Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Facilitator (x402-facilitator) · Boson Protocol
Skip to content

Facilitator (x402-facilitator)

The facilitator is the relayer that takes a signed x402 payment payload, validates it, and submits the on-chain transaction. It pays gas on behalf of the buyer.

You can either run your own facilitator or use a hosted one.

Run your own

import express from "express"
import { createX402bFacilitatorExpress } from "@bosonprotocol/x402-facilitator-express"
import { ethers } from "ethers"
 
const relayerWallet = new ethers.Wallet(process.env.RELAYER_PRIVATE_KEY!)
const app = express()
 
app.use("/", createX402bFacilitatorExpress({
  signer: relayerWallet,
  supportedChains: [137, 8453],
}))
 
app.listen(8080)

The three endpoints

A facilitator exposes:

  • POST /verify — check whether a signed payment is valid (without submitting).
  • POST /settle — submit it on-chain.
  • POST /perform-action?action=<action> — settle and advance the exchange (e.g. atomic redeem).

Library shape

If you want to embed facilitator logic into an existing service, use x402-facilitator directly:

import { verify, settle, performAction } from "@bosonprotocol/x402-facilitator"
 
const result = await settle(paymentPayload, { signer: relayerWallet })
// result: { ok: true, exchangeId, txHash } | { ok: false, code, reason }

Gas economics

The facilitator pays gas. To stay solvent:

  • Charge a relayer fee per request (off-band, e.g. token markup on the price).
  • Cap allowed values to keep gas burn bounded.
  • Monitor relayer wallet balance; alert on low balance.

Common gotchas

  • Don't trust the buyer's signature blindly. Always verify before settle.
  • Race conditions. Two facilitators racing for the same payment causes one tx to revert. Use idempotency keys.
  • Nonce stampedes. Under high concurrency, your relayer wallet's nonce becomes a hotspot. Use a nonce manager.

Next