FAQ

General Questions

Do I need an account to use 0xmeta.ai?

No! The facilitator is permissionless. No signup, no API keys, no registration.Just:

Approve facilitator for USDC spending (one-time)
Integrate x402 middleware
Start accepting payments

What is x402?

x402 is a protocol for HTTP-based payments. It’s like a “402 Payment Required” status code, but with built-in payment authorization using blockchain signatures.Key principle: Customers pay merchants directly (no intermediaries).

What networks are supported?

Currently:

Base Mainnet (Chain ID: 8453)
Base Sepolia (Chain ID: 84532, testnet)

More networks coming soon.

Merchant Setup

Why do I need to approve the facilitator?

Technical reason: The facilitator collects a $0.01 fee per settlement from your USDC balance using the standard ERC-20 transferFrom pattern before executing the settlement.How it works:

// You approve facilitator (one-time)
USDC.approve(treasury, 100 * 10^6); // 100 USDC

// Before each settlement, facilitator collects fee FIRST
USDC.transferFrom(merchant, treasury, 0.01 * 10^6); // $0.01

// Then executes customer → merchant payment

Why this pattern:

x402 requires customers pay merchants directly (trust-minimization)
Facilitator can’t split customer payments
Pre-settlement fee collection prevents free service exploitation
Solution: Merchant pays fee separately via approval, BEFORE settlement

How do I approve the facilitator?

Use our provided script:

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

# Run approval
node approve-facilitator.mjs

This approves the facilitator treasury to spend USDC on your behalf.See x402 Integration Guide for details.

How much should I approve?

Recommended: 100-1000 USDCCalculation: Approval = Settlements × $0.01Examples:

100 USDC = 10,000 settlements
500 USDC = 50,000 settlements
1000 USDC = 100,000 settlements

Avoid: Infinite approval (max uint256) for security reasons.

Can I revoke approval?

Yes! At any time:

# Set approval to 0
APPROVAL_AMOUNT=0 node approve-facilitator.mjs

Effect: All future settlements will fail at the pre-settlement fee collection step with insufficient_allowance error. Customers won’t be charged.To resume: Re-run approval with desired amount.

How do I check my remaining allowance?

Use our monitoring script:

node check-allowance.mjs

# Output:
# 📍 Base Mainnet
#    USDC Balance: 500.00 USDC
#    Fee Allowance: 95.50 USDC
#    Settlements: 9,550
#    ✅ Good

Set up automated monitoring via cron or alerts.

Trust & Security

How do I know the facilitator won't steal customer funds?

It’s cryptographically impossible.Why:

Customers authorize payments directly to your address (not facilitator)
EIP-3009 signatures are cryptographically bound to recipient
Facilitator has zero access to customer authorizations
Facilitator cannot redirect customer funds

Technical details:

// Customer signs authorization
const authorization = {
  from: customerAddress,
  to: YOUR_MERCHANT_ADDRESS,  // ← Cryptographically bound
  value: "20000",
  signature: "0x..."
};

// Facilitator can only execute this EXACT transfer
// Cannot change recipient or amount

This is the core principle of x402: trust-minimization.

Can the facilitator drain my USDC balance?

No. Only the approved amount is accessible.Example:

You approve: 100 USDC
Maximum risk: 100 USDC
Your remaining USDC: Safe

Pre-settlement protection: Fee collected BEFORE settlement. If you have insufficient balance, settlement is blocked and customer isn’t charged.Best practice: Approve reasonable amounts (100-1000 USDC), not infinite.Monitoring: Use check-allowance.mjs to track remaining approval.

What if the facilitator is hacked?

Worst case: Attacker drains your approved amount only.Protection:

Limit approval: Don’t approve more than you’re willing to risk
Monitor regularly: Check allowance frequently
Revoke if suspicious: Set approval to 0 immediately

Your customer funds: Always safe (facilitator has no access).Pre-settlement benefit: Attacker can only collect fees for settlement attempts, not steal customer funds.

Is this more secure than traditional payment processors?

Yes, in several ways:Traditional:

❌ Custody of customer funds
❌ Can freeze/hold payments
❌ Opaque settlement process

0xmeta (x402 with pre-settlement):

✅ No custody (direct to merchant)
✅ Cannot freeze payments
✅ On-chain auditable
✅ Cryptographic guarantees
✅ Fee collected before settlement (no free service)

Trade-off: Requires blockchain familiarity and USDC approval.

Fees & Pricing

How are fees collected?

Pre-settlement via transferFrom:Flow:

Customer authorizes $0.02 to your address
Facilitator collects $0.01 fee from your approved USDC balance FIRST
Then facilitator executes customer → merchant payment ($0.02)
You receive 100% of customer payment ($0.02)

Technical:

// Step 1: Collect fee from merchant FIRST (pre-settlement)
transferFrom(merchant, treasury, 10000); // $0.01

// Step 2: Execute customer → merchant (AFTER fee)
transferWithAuthorization(customer, merchant, 20000); // $0.02

Key: No fee collection = no settlement. This prevents free service.

Why does the merchant pay the fee, not the customer?

Technical constraint: x402 requires customer payments go directly to merchants (trust-minimization). EIP-3009 signatures are cryptographically bound to exact recipient and amount. Cannot split customer payment.Solution: Merchant pays facilitator fee separately via standard ERC-20 approval, collected before settlement execution.Merchant pricing: Add fee to your prices:

Your price: $0.01
Facilitator fee: $0.01
Customer pays: $0.02

Economic protection: Pre-settlement collection ensures merchant pays for service.

What if settlement fails after fee collection?

You paid $0.01 for the settlement attempt.Why this is fair:

Facilitator verified customer authorization
Facilitator attempted settlement execution
Resources were consumed (RPC calls, API calls, gas estimation)
Service was rendered

Why pre-settlement: Without collecting fee first, merchants could intentionally cause settlement failures to get free verification service. Pre-settlement prevents this exploitation.Mitigation: Test thoroughly on Base Sepolia testnet before production. Monitor settlement success rates.

Are there any hidden fees?

No.What you pay:

$0.01 USDC per settlement (collected pre-settlement)

What you DON’T pay:

❌ Monthly fees
❌ Setup fees
❌ Gas fees (facilitator pays)
❌ Withdrawal fees
❌ Percentage fees
❌ Minimum volume requirements

Transparency: Every fee collection is an on-chain transaction you can verify.

Technical Questions

What happens if I revoke approval mid-settlement?

Settlement fails at pre-settlement fee collection step.Flow:

Customer submits payment authorization
Facilitator attempts fee collection (pre-settlement)
Fee collection fails (approval revoked)
Settlement BLOCKED
Customer NOT charged

Error response:

{
  "error": {
    "code": "insufficient_allowance",
    "message": "Merchant must approve facilitator",
    "details": {
      "note": "Settlement blocked - customer not charged"
    }
  }
}

Customer protection: Pre-settlement means if fee collection fails, settlement never executes.

Can I use a different token besides USDC?

Not yet. Currently only USDC is supported.Roadmap: Multi-token support planned (USDT, DAI, etc.)Why USDC first: Most stable, widely adopted, best EIP-3009 support.

How do I test on testnet?

Use Base Sepolia:

# 1. Get testnet USDC (Circle faucet)
# 2. Approve facilitator on testnet
NETWORK=sepolia node approve-facilitator.mjs

# 3. Configure server for testnet
# network: "eip155:84532" (v2) or "base-sepolia" (v1)

# 4. Test payments

Testnet addresses:

USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Treasury: 0x5D791e3554D0e83f171126905Bda1640Bf6f9A8B

Recommendation: Thoroughly test pre-settlement fee collection on Sepolia before mainnet.

What's the difference between x402 v1 and v2?

Network format:

v1: "base-sepolia" (string)
v2: "eip155:84532" (CAIP-2 format)

Both supported! Use v2 for new integrations.Pre-settlement works the same in both versions.Migration: See x402 Integration Guide

How long do settlements take?

Typical timing:

Verification: < 2 seconds
Pre-settlement fee collection: 5-10 seconds (on-chain tx)
Settlement execution: 30-60 seconds (via 1Shot)

Total: 35-70 seconds averageKey: Fee collection happens FIRST, then settlement. If fee collection fails, settlement never starts.Factors:

Network congestion
RPC provider latency
1Shot API processing time

Can I see all transactions on-chain?

Yes! All transactions are public.Pre-settlement fee collection:

https://basescan.org/tx/{fee_tx_hash}

Settlement (after fee):

https://basescan.org/tx/{settlement_tx_hash}

Merchant address activity:

https://basescan.org/address/{your_merchant_address}

Verification: You can verify fee was collected BEFORE settlement execution by comparing timestamps.

Why pre-settlement instead of post-settlement?

Economic security and sustainability:Pre-settlement (current):

✅ Fee collected FIRST
✅ If fee fails → settlement blocked → customer safe
✅ No free service exploitation
✅ Sustainable business model

Post-settlement (rejected):

❌ Settlement executes first
❌ Fee collection could fail → free service
❌ Merchants could exploit for free verification
❌ Unsustainable

Trade-off: Merchant pays $0.01 even if settlement fails after fee. This is fair payment for the attempt.

Troubleshooting

Error: insufficient_allowance

Cause: You haven’t approved facilitator, or approval is depleted.Solution:

# Check current allowance
node check-allowance.mjs

# If low/zero, approve more
node approve-facilitator.mjs

Pre-settlement: This error occurs at fee collection step, BEFORE settlement. Customer is not charged.

Error: fee_collection_failed

Cause: Your USDC balance is insufficient for the $0.01 fee.Solution: Add USDC to your merchant address.Check balance:

node check-allowance.mjs
# Shows: USDC Balance: 0.00 USDC ← Problem

Critical: This is a pre-settlement error. Settlement never executed, customer not charged.

Settlement taking too long

Normal: 35-70 secondsIf longer:

Check if pre-settlement fee collection succeeded
Check Base network status
Verify 1Shot API status
Check settlement status via API

Polling:

const status = await checkSettlement(settlement_id);
// status: "pending" | "settled" | "failed"

Note: Fee is collected in first 5-10 seconds. Remaining time is settlement execution.

How do I get support?

Options:

Documentation: https://docs.0xmeta.ai
GitHub Issues: https://github.com/0xmetaHQ/x402-facilitator/issues
Email: [email protected]
Discord: https://discord.gg/0xmeta

Include:

Settlement ID or verification ID
Error message (if applicable)
Network (mainnet or sepolia)
Whether error occurred at fee collection or settlement

Comparison to Alternatives

How is this different from other x402 facilitators?

0xmeta:

✅ Paid service ($0.01/settlement, pre-settlement)
✅ Production-ready infrastructure
✅ Guaranteed uptime (99.9% SLA)
✅ Professional support
✅ No free service exploitation (pre-settlement)

Free facilitators:

⚠️ May shut down anytime
⚠️ No guarantees
⚠️ Limited support
⚠️ May use post-settlement (exploitable)

Trade-off: Pay for reliability and economic sustainability vs. free but uncertain.

Why use a facilitator at all?

Without facilitator:

❌ You verify signatures yourself
❌ You execute settlements on-chain
❌ You pay gas fees
❌ You handle errors/retries
❌ Complex infrastructure

With 0xmeta:

✅ Signature verification handled
✅ Settlement execution managed
✅ Gas fees covered
✅ Error handling built-in
✅ Simple integration (x402 middleware)
✅ Pre-settlement fee collection (no free service)

Cost: $0.01 per settlement for all infrastructure, collected pre-settlement.

Pre-Settlement Deep Dive

What exactly is pre-settlement fee collection?

Definition: The facilitator collects the $0.01 fee from the merchant’s approved USDC balance BEFORE executing the customer → merchant payment.Order of operations:

Customer submits payment authorization
Facilitator verifies authorization
✅ Facilitator collects $0.01 from merchant (pre-settlement)
✅ Facilitator executes customer → merchant payment

Critical: If step 3 fails, step 4 never happens. Customer is never charged.

What are the benefits of pre-settlement?

For customers:

✅ Never charged if fee collection fails
✅ Protected from failed settlement attempts

For facilitator:

✅ Guaranteed payment for service
✅ No free service exploitation
✅ Sustainable business model

For merchants:

✅ Transparent fee structure
✅ Predictable costs
⚠️ Pay for settlement attempts (fair trade for preventing exploitation)

What happens in each scenario?

Scenario 1: Everything succeeds

1. Fee collection: ✅ Success ($0.01 from merchant)
2. Settlement: ✅ Success ($0.02 to merchant from customer)
Result: Merchant pays $0.01, receives $0.02, net +$0.01

Scenario 2: Fee collection fails

1. Fee collection: ❌ Failed (insufficient allowance/balance)
2. Settlement: 🚫 Blocked (never attempted)
Result: Customer not charged, merchant not charged

Scenario 3: Fee succeeds, settlement fails

1. Fee collection: ✅ Success ($0.01 from merchant)
2. Settlement: ❌ Failed (expired authorization, etc.)
Result: Merchant pays $0.01 for the attempt, customer not charged

Why scenario 3 is fair: Merchant received verification and settlement attempt services worth $0.01.

Get Started

No signup required - just start building:

# 1. Approve facilitator
EVM_PRIVATE_KEY=0x... node approve-facilitator.mjs

# 2. Add x402 middleware
npm install @x402/express @x402/evm @x402/core

# 3. Start accepting payments
npm start

Questions not answered here? Check the x402 Integration Guide or contact [email protected]Remember: Pre-settlement fee collection means the $0.01 fee is collected BEFORE executing the customer payment. This protects customers and prevents free service exploitation.

Get Started

Micro Protocols

Guides

API Reference

Advanced

Support

General Questions

Merchant Setup

Trust & Security

Fees & Pricing

Technical Questions

Troubleshooting

Comparison to Alternatives

Pre-Settlement Deep Dive

Get Started

​General Questions

​Merchant Setup

​Trust & Security

​Fees & Pricing

​Technical Questions

​Troubleshooting

​Comparison to Alternatives

​Pre-Settlement Deep Dive

​Get Started

General Questions

Merchant Setup

Trust & Security

Fees & Pricing

Technical Questions

Troubleshooting

Comparison to Alternatives

Pre-Settlement Deep Dive

Get Started