swader/x402facilitators

The @swader/x402facilitators package offers a unified, drop-in configuration for all x402 facilitators

🌐 Live Website

View all facilitators in a mobile-friendly interface at facilitators.x402.watch (or build your own locally!)

Build & Serve the Website Locally

This project includes a static website generator built with Bun:

# Quick start - build and serve in one command
./serve.sh

# Or manually:
bun run build:website
cd dist && npx http-server -p 8080
# Open http://localhost:8080 in your browser

Installation

bun add @swader/x402facilitators
# or
npm install @swader/x402facilitators
# or
yarn add @swader/x402facilitators

Quick Start

Minimal Example

import { coinbase, thirdweb } from '@swader/x402facilitators';

paymentMiddleware(
  address,
  resources,
  coinbase // easily interchange any facilitator
);

paymentMiddleware(
  address,
  resources,
  thirdweb // easily interchange any facilitator
);

Auto Facilitator

The auto facilitator is a proxy that load-balances between other facilitators to guarantee uptime. Simply import and use it directly - no configuration required:

import { auto } from '@swader/x402facilitators';

paymentMiddleware(address, resources, auto);

Resource Discovery

Some facilitators support discovery - the ability to list all x402-protected resources they're facilitating.

This is useful for building agents that search for tools.

Discovery API

import { coinbaseDiscovery, kamiyoDiscovery, listAllFacilitatorResources } from '@swader/x402facilitators';

// List all resources from a facilitator
const resources = await listAllFacilitatorResources(coinbaseDiscovery);

// Or from KAMIYO (multi-chain)
const kamiyoResources = await listAllFacilitatorResources(kamiyoDiscovery);

Facilitators Supporting Discovery

The following facilitators currently support resource discovery:

• Coinbase - Enterprise-grade facilitator with SDK
• AurraCloud - Infrastructure-focused facilitator
• thirdweb - Web3 development platform
• PayAI - AI-payment infrastructure
• Ultravioleta DAO - Community-driven multichain facilitator
• KAMIYO - Multi-chain AI facilitator
• Questflow - AI workflow automation platform

Enumerate All Discoverable Facilitators

The package also exports a list of all facilitators that support discovery:

import {
  discoverableFacilitators,
  listAllFacilitatorResources,
} from '@swader/x402facilitators';

await Promise.all(
  discoverableFacilitators.map(facilitator =>
    listAllFacilitatorResources(facilitator)
  )
);

Available Facilitators

This package includes pre-configured integrations for the following X402 facilitators:

| Facilitator | Networks | Discovery | Setup Required | | -------------- | ------------- | --------- | ------------------------------ | | Auto | BASE | No | No | | Coinbase | BASE, SOLANA | ✅ Yes | Yes - Requires CDP API Creds | | AurraCloud | BASE | ✅ Yes | Yes - API key | | thirdweb | BASE, POLYGON | ✅ Yes | Yes - Secret key | | PayAI | BASE, SOLANA | ✅ Yes | No | | Daydreams | BASE, SOLANA | No | No | | X402rs | BASE, POLYGON | No | No | | Polygon | POLYGON | No | No | | Corbits | SOLANA | No | No | | Dexter | SOLANA | No | No | | Mogami | BASE | No | No | | OpenX402 | BASE, SOLANA | No | No | | Questflow | BASE | ✅ Yes | Yes - API key | | xEcho | BASE | No | No | | CodeNut | BASE | No | No | | Ultravioleta DAO | BASE, SOLANA | ✅ Yes | No | | Virtuals | BASE | No | No | | 402104 | BASE | No | No | | KAMIYO | BASE, POLYGON, SOLANA | ✅ Yes | No | | Heurist | BASE | No | No |

Import Individual Facilitators

// Simple facilitators (no setup)
import {
  auto,
  coinbase,
  payai,
  daydreams,
  x402rs,
  polygon,
  corbits,
  dexter,
  mogami,
  openx402,
  xecho,
  codenut,
  ultravioletadao,
  virtuals,
  f402104,
  kamiyo,
  heurist
} from '@swader/x402facilitators';

// Facilitators requiring setup
import { aurracloud, thirdweb, questflow } from '@swader/x402facilitators';

aurracloud({
  apiKey: process.env.AURRACLOUD_API_KEY,
});

questflow({
  apiKey: process.env.QUESTFLOW_API_KEY,
});

thirdweb({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});

Access Facilitator Metadata

import { coinbaseFacilitator, payaiFacilitator } from '@swader/x402facilitators';

console.log(coinbaseFacilitator);
// {
//   id: 'coinbase',
//   metadata: {
//     name: 'Coinbase',
//     image: 'https://x402scan.com/coinbase.png',
//     docsUrl: 'https://docs.cdp.coinbase.com/x402/welcome',
//     color: '#2563EB'
//   },
//   config: { ... },
//   addresses: { base: [...], solana: [...] },
//   discoveryConfig: { ... }
// }

Types

Facilitator<Props>

Represents a complete facilitator with configuration and metadata:

interface Facilitator<Props = void> {
  id: string; // Unique identifier
  metadata: FacilitatorMetadata; // Display info (name, image, docs)
  config: FacilitatorConfig | FacilitatorConfigConstructor<Props>;
  addresses: Partial<Record<Network, FacilitatorAddress[]>>;
  discoveryConfig?: FacilitatorConfig; // For resource discovery
}

FacilitatorConfig

Configuration passed to X402 middleware for payment verification:

// From 'x402/types'
type FacilitatorConfig = {
  url: string; // Facilitator API endpoint
};

FacilitatorConfigConstructor<Props>

For facilitators requiring initialization parameters:

type FacilitatorConfigConstructor<Props = void> = (
  requirements: Props
) => FacilitatorConfig;

Example - Simple facilitator (no setup required):

import { payai } from '@swader/x402facilitators';

// Use directly - just a URL configuration
paymentMiddleware(address, resources, payai);

Example - Facilitator with required props:

import { aurracloud } from '@swader/x402facilitators';

// Must call with required props first
paymentMiddleware(
  address,
  resources,
  aurracloud({ apiKey: process.env.AURRACLOUD_API_KEY })
);

FacilitatorMetadata

Display information for UIs:

interface FacilitatorMetadata {
  name: string; // Display name
  image: string; // Logo URL
  docsUrl: string; // Documentation link
  color: string; // Brand color
}

Network

Supported blockchain networks:

enum Network {
  BASE = 'base',
  POLYGON = 'polygon',
  SOLANA = 'solana',
}

Development

This project is built with Bun for optimal performance and developer experience.

Prerequisites

• Bun >= 1.0.0

Setup

# Install dependencies
bun install

# Type check
bun run check:types

# Lint code
bun run lint

# Build library
bun run build:lib

# Build website
bun run build:website

# Build everything (library + website)
bun run build

Adding a New Facilitator

1. Create a new file in src/facilitators/your-facilitator.ts

2. Export the config and facilitator object following the pattern:

   import type { Facilitator, FacilitatorConfig } from '../types';
   
   export const yourfacilitator: FacilitatorConfig = {
     url: 'https://your-facilitator-url.com',
   };
   
   export const yourfacilitatorFacilitator = {
     id: 'yourfacilitator',
     metadata: {
       name: 'Your Facilitator',
       image: 'https://x402scan.com/your-logo.png',
       docsUrl: 'https://docs.yourfacilitator.com',
       color: '#000000',
     },
     config: yourfacilitator,
     addresses: {
       // Network addresses
     },
   } as const satisfies Facilitator;

3. Add exports to src/facilitators/index.ts

4. Add to the list in src/lists/all.ts

5. Rebuild: bun run build

After the PR is merged and a new release is tagged, your facilitator will appear on both the website and in the lib.