Skip to main content

​
Overview

0xmeta is an x402-compliant payment facilitator that enables gasless payments on Base networks using EIP-3009 with pre-settlement fee collection.
Pre-Settlement Fees: The facilitator collects a $0.01 fee from your pre-approved USDC balance BEFORE executing the settlement. Customer payments then go directly to your address. No fee collection = no settlement.

​
What You Need

1

Your Merchant Address

An Ethereum address where you’ll receive customer payments
2

USDC for Fees

~100 USDC for facilitator fees (covers ~10,000 settlements)
3

ETH for Gas

~0.001 ETH for one-time approval transaction

​
Three-Step Setup

​
Step 1: Approve Facilitator

The facilitator collects fees from your USDC balance via transferFrom before executing settlements. This requires one-time approval: 
# Install dependencies
npm install ethers dotenv

# Configure
export EVM_PRIVATE_KEY=0x...
export NETWORK=sepolia  # or mainnet

# Run approval
node approve-facilitator.mjs
What this does: 
USDC.approve(treasury, 100 * 10^6);  // Approve 100 USDC
Script: See approve-facilitator.mjs
Expected: Approval of 100 USDC = 10,000 settlements

​
Step 2: Setup Server

Install x402 middleware and configure with YOUR merchant address: 
import { config } from "dotenv";
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

config();

const evmAddress = process.env.EVM_ADDRESS as `0x${string}`;
const facilitatorUrl = "https://facilitator.0xmeta.ai/v1";

const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [{
          scheme: "exact",
          price: "$0.02",              // Your price + $0.01 fee
          network: "eip155:84532",      // Base Sepolia
          payTo: evmAddress,            // YOUR address
        }],
        description: "Weather data"
      }
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:84532", new ExactEvmScheme())
  )
);

app.get("/weather", (req, res) => {
  res.send({ weather: "sunny", temperature: 70 });
});

app.listen(4021, () => {
  console.log(`Server ready at http://localhost:4021`);
});
Critical: Use YOUR merchant address in payTo, not the facilitator treasury. Customer payments must go directly to you.

​
Step 3: Start Server

npm start
Your server is now accepting x402 payments! 🎉

​
Payment Flow

Key Points:
  • ✅ Facilitator collects $0.01 fee from merchant’s approved balance FIRST
  • ✅ Then executes customer → merchant payment ($0.02)
  • ✅ Client authorizes payment to YOUR address
  • ✅ You receive 100% of customer payment
  • ✅ No facilitator custody of customer funds
  • ⚠️ If fee collection fails, settlement is blocked (no free rides)

​
Network Configuration

​
Base Sepolia (Testnet)

ResourceValue
Chain ID84532
CAIP-2eip155:84532
USDC0x036CbD53842c5426634e7929541eC2318f3dCF7e
Treasury0x5D791e3554D0e83f171126905Bda1640Bf6f9A8B
RPChttps://sepolia.base.org

​
Base Mainnet (Production)

ResourceValue
Chain ID8453
CAIP-2eip155:8453
USDC0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Treasury0x5D791e3554D0e83f171126905Bda1640Bf6f9A8B
RPChttps://mainnet.base.org

​
Testing

​
Get Testnet Assets

Base Sepolia ETH

Free testnet ETH

Base Sepolia USDC

Free testnet USDC

​
Test Payment Flow

# 1. Start server
npm start

# 2. Use x402 client (or curl)
# Client will:
# - Request /weather
# - Receive 402 with your address
# - Create authorization to your address
# - Submit to facilitator
# - Receive weather data
Expected flow: 
✅ Client requests /weather
✅ Server returns 402 with YOUR address
✅ Client authorizes payment to YOUR address
✅ Facilitator verifies authorization
✅ Facilitator collects $0.01 from YOUR approved balance (PRE-SETTLEMENT)
✅ Facilitator settles: Client → YOU ($0.02)
✅ Server returns 200 + weather data

​
Monitoring

​
Check Remaining Settlements

node check-allowance.mjs

# Output:
# 📍 Base Sepolia
#    USDC Balance: 500.00 USDC
#    Fee Allowance: 95.50 USDC
#    Settlements: 9,550
#    ✅ Good
Script: See check-allowance.mjs

​
Top Up When Low

# When allowance runs low, approve more
node approve-facilitator.mjs

​
Production Deployment

​
Switch to Base Mainnet

// v2
network: "eip155:8453"  // Base Mainnet

// v1
network: "base"

​
Run Approval on Mainnet

# Get real USDC and ETH first!
NETWORK=mainnet node approve-facilitator.mjs
Production checklist:
  • ✅ Tested on Sepolia thoroughly
  • ✅ Approved USDC on mainnet
  • ✅ Verified merchant address receives payments
  • ✅ Monitoring setup for allowance
  • ✅ Private keys secured

​
Common Issues

Cause: You haven’t approved facilitatorSolution:
node approve-facilitator.mjs
Cause: Wrong address in payToSolution: Verify you’re using YOUR merchant address (not treasury):
payTo: process.env.EVM_ADDRESS  // ✅ Your address
Causes:
  • Insufficient USDC balance for fees
  • Insufficient allowance
  • Authorization expired
  • Nonce already used
Solution: Check facilitator error response for specific reason

​
Next Steps

Complete Guide

Full setup documentation

Architecture

Understand pre-settlement fee collection

x402 Integration

Both v1 and v2 examples

API Reference

Explore endpoints
You’re ready! Approve facilitator, configure your server with YOUR address, and start accepting payments.