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.