Deploy your own branded x402 payment facilitator in minutes.
Website • Quick Start • Documentation • Contributing
OpenFacilitator is an open source platform that lets anyone deploy their own x402 payment facilitator. Self-host for free or use our managed service for instant setup.
# Clone the repository
git clone https://github.com/rawgroundbeef/openfacilitator.git
cd openfacilitator
# Start with Docker
docker compose up -dYour facilitator will be running at http://localhost:3001
Visit openfacilitator.io to deploy your own facilitator:
- $5/mo: Bring your own domain with auto-SSL
openfacilitator/
├── apps/
│ └── dashboard/ # Next.js dashboard UI
├── packages/
│ ├── core/ # Facilitator logic (verify, settle, supported)
│ ├── server/ # Multi-tenant Express server
│ └── sdk/ # TypeScript SDK for integrating x402 payments
├── docker-compose.yml
├── LICENSE
└── README.md
OpenFacilitator uses Better Auth - a fully open source, self-contained authentication solution:
- Email/Password - Traditional signup and signin
- Session Management - Secure cookie-based sessions
- SQLite/Postgres - Works with the same database
- Zero External Services - No third-party auth providers needed
import { betterAuth } from 'better-auth';
export const auth = betterAuth({
database: db,
emailAndPassword: { enabled: true }
});- Node.js 20+
- pnpm 9+
# Install dependencies
pnpm install
# Start development servers
pnpm devThis starts:
- Dashboard: http://localhost:3002
- API Server: http://localhost:3001
# Build all packages
pnpm build
# Build specific package
pnpm turbo build --filter=@openfacilitator/server| Endpoint | Method | Description |
|---|---|---|
/supported |
GET | List supported payment networks and tokens |
/verify |
POST | Verify a payment authorization |
/settle |
POST | Execute a payment settlement |
/discovery/resources |
GET | List available resources (products/links) |
/health |
GET | Health check |
| Endpoint | Method | Description |
|---|---|---|
/api/auth/sign-up/email |
POST | Create new account |
/api/auth/sign-in/email |
POST | Sign in with email/password |
/api/auth/sign-out |
POST | Sign out |
/api/auth/session |
GET | Get current session |
| Endpoint | Method | Description |
|---|---|---|
/api/admin/me |
GET | Get current user info |
/api/admin/facilitators |
GET | List user's facilitators |
/api/admin/facilitators |
POST | Create new facilitator |
/api/admin/facilitators/:id |
GET | Get facilitator details |
/api/admin/facilitators/:id |
PATCH | Update facilitator |
/api/admin/facilitators/:id |
DELETE | Delete facilitator |
/api/admin/facilitators/:id/export |
POST | Export self-host config |
curl https://yourdomain.com/supported{
"kinds": [
{
"x402Version": 1,
"scheme": "exact",
"network": "base"
},
{
"x402Version": 2,
"scheme": "exact",
"network": "eip155:8453"
}
]
}| Variable | Description | Default |
|---|---|---|
PORT |
Server port | 3001 |
HOST |
Server host | 0.0.0.0 |
DATABASE_PATH |
SQLite database path | ./data/openfacilitator.db |
NODE_ENV |
Environment | development |
BASE_RPC_URL=https://mainnet.base.org
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
ETHEREUM_RPC_URL=https://eth.llamarpc.comDashboard on Vercel:
# Deploy from the apps/dashboard directory
vercel --prodAPI Server on Railway:
- Connect your GitHub repo to Railway
- Set the root directory to the repo root
- Railway will detect the Dockerfile.server
- Add a volume mounted at
/datafor the database - Set environment variables (see below)
DNS Setup:
openfacilitator.io→ Vercelapi.openfacilitator.io→ Railway*.openfacilitator.io→ Railway (wildcard for tenant subdomains)custom.openfacilitator.io→ Railway (CNAME target)
# Start all services
docker compose up -d
# View logs
docker compose logs -f
# Stop services
docker compose down# Build server image
docker build -f Dockerfile.server -t openfacilitator-server .
# Run server
docker run -d \
-p 3001:3001 \
-v openfacilitator-data:/data \
openfacilitator-serverServer (.env):
NODE_ENV=production
PORT=3001
HOST=0.0.0.0
DATABASE_PATH=/data/openfacilitator.db
BETTER_AUTH_SECRET=your-secret-key-min-32-chars
DASHBOARD_URL=https://dashboard.openfacilitator.ioDashboard:
NEXT_PUBLIC_API_URL=https://api.openfacilitator.ioOpenFacilitator uses a multi-tenant architecture:
┌─────────────────────────────────────┐
│ Load Balancer │
│ (subdomain/custom domain routing) │
└─────────────────────────────────────┘
│
┌─────────────────────────────────────┐
│ OpenFacilitator Server │
│ │
│ ┌─────────┐ ┌─────────────────┐ │
│ │ Tenant │ │ Facilitator │ │
│ │Resolver │──│ Router │ │
│ └─────────┘ └─────────────────┘ │
│ │ │
│ ┌───────────────────▼───────────┐ │
│ │ Core Logic │ │
│ │ (verify, settle, supported) │ │
│ └───────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼───────────┐ │
│ │ SQLite Database │ │
│ │ (facilitators, transactions) │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
- Key Management: Private keys can be encrypted at rest or brought externally
- Non-Custodial: Keys never leave your infrastructure when self-hosting
- SSL/TLS: Auto-provisioned via Let's Encrypt for custom domains
Contributions are welcome! Please read our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Built with ❤️ for the x402 ecosystem
