Desktop Only

This application is optimized for desktop browsers. Please open it on a device with a screen width of at least 1024px.

Frequently Asked Questions

General

What is x402?

x402 is a payment protocol based on HTTP 402 "Payment Required" status code. It enables API monetization with cryptocurrency payments.

Which blockchain does this SDK support?

This SDK is built specifically for Mantle Network (Chain ID: 5000).

What currency is used for payments?

USDC (USD Coin) on Mantle. It's a stablecoin pegged to US Dollar.

Why does the SDK only support USDC?

Gasless payments require tokens that implement EIP-3009 (transferWithAuthorization). This standard allows users to sign payment authorizations off-chain while the facilitator pays gas and submits transactions.

On Mantle mainnet, USDC is currently the only token implementing EIP-3009. As other stablecoins adopt this standard, we will add support for them.

Do users need to pay gas fees?

No! Users only sign a message in their wallet. The facilitator pays all gas fees. This is enabled by EIP-3009 transferWithAuthorization.

Pricing

How do I set prices?

Set prices in USD using the priceUsd option:

  • priceUsd: 0.01 = 1 cent
  • priceUsd: 0.10 = 10 cents
  • priceUsd: 1.00 = 1 dollar

What's the minimum price?

Technically any amount, but very small amounts may not be economical due to gas costs. We recommend minimum $0.001 (0.1 cent).

Are there any fees?

  • Self-hosted: Only blockchain gas (~$0.01 per transaction)
  • Hosted facilitator: Small fee (see dashboard)

Technical

Which frameworks are supported?

Server:

  • Express.js
  • Next.js (App Router)
  • Hono
  • Cloudflare Workers
  • Deno
  • Bun

Client:

  • React (hooks)
  • Vanilla JavaScript
  • Any framework with fetch API

Do I need to run my own facilitator?

We recommend running your own facilitator for full control and no per-transaction fees. Use npx create-mantle-facilitator to get started. Alternatively, our hosted facilitator is available for those who prefer not to manage infrastructure.

How do I test without real money?

Currently, you need real USDC on Mantle for testing. We recommend using very small amounts ($0.01) for development.

What wallets are supported?

Any EIP-1193 compatible wallet:

  • MetaMask
  • Coinbase Wallet
  • WalletConnect
  • Rainbow
  • And more...

Troubleshooting

"User rejected transaction"

The user clicked "Reject" in their wallet. This is normal user behavior.

"Insufficient funds"

User doesn't have enough USDC. They need to:

  1. Bridge USDC to Mantle: https://bridge.mantle.xyz
  2. Or buy USDC on a Mantle DEX

"Wrong network"

User is on wrong network. Add network switching:

if (chainId !== 5000) {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x1388' }]  // 5000 in hex
  });
}

"Facilitator unreachable"

  • Check facilitator URL is correct
  • Check your internet connection
  • If self-hosted, check your facilitator is running

My payment was successful but I got an error

The payment went through on blockchain, but something else failed:

  • Check your API endpoint for errors
  • Check the txHash on explorer: https://explorer.mantle.xyz

What happens if my API returns an error after payment?

Currently, the payment is processed before your API handler runs. If your API returns an error, the user is still charged.

We're working on automatic refunds for API errors in future SDK versions. For now, you can monitor failed deliveries in the Dashboard — look for the Delivery Rate metric to track successful vs failed API responses.

How do I refund a payment?

Payments are final on blockchain. For refunds, you would need to send USDC back manually from your wallet to the user's address.

Security

Is this secure?

Yes. The SDK uses:

  • EIP-712 typed data signing (no raw transaction signing)
  • EIP-3009 transfer authorization (standard USDC feature)
  • Nonces prevent replay attacks
  • Time windows prevent stale authorizations

What if someone intercepts the payment header?

Payment headers are tied to specific:

  • Payer address (can only pay from signer's wallet)
  • Recipient address (your wallet)
  • Amount
  • Nonce (one-time use)
  • Time window (expires in minutes)

Even if intercepted, it can only send money TO you.

Should I trust the facilitator?

The facilitator can only:

  • Execute the exact transfer you authorized
  • To the exact recipient you specified
  • For the exact amount you signed

It cannot steal funds or change parameters.

Next Steps