Getting Started
Get up and running with x402 Mantle SDK in 5 minutes.
Key Concepts
Facilitator
A service that executes blockchain transactions on behalf of users. Users sign authorizations (gasless), and the facilitator submits them to the blockchain.
- Self-Hosted (Recommended): Run your own facilitator with
npx create-mantle-facilitator— full control, no per-transaction fees - Hosted: Our managed service — just add
projectKeyfrom dashboard
Payment Flow
Uses EIP-3009 transferWithAuthorization - users sign a message that authorizes USDC transfer. No gas fees for users, the facilitator pays gas.
Pricing
You set prices in USD (e.g., $0.01). The SDK converts to USDC atomic units automatically. 1 cent = 10,000 atomic units (USDC has 6 decimals).
Supported Tokens
The SDK currently supports USDC only. This is because gasless payments require EIP-3009 (transferWithAuthorization), and USDC is the only token on Mantle implementing this standard. Learn more
Quick Start (Self-Hosted Facilitator)
Full control over your infrastructure with no per-transaction fees.
Step 1: Create Facilitator
npx create-mantle-facilitator
cd your-facilitator-path
npm install
Configure .env:
FACILITATOR_PRIVATE_KEY=0x... # Wallet that pays gas
RPC_URL=https://rpc.mantle.xyz
FACILITATOR_SECRET=fac_xxx... # Auto-generated
Start facilitator:
npm run dev
Step 2: Install SDK
npm install @puga-labs/x402-mantle-sdk ethers
Step 3: Protect Your API (Server)
// app/api/generate/route.ts
import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs';
import { NextRequest, NextResponse } from 'next/server';
const pay = mantlePaywall({
priceUsd: 0.01,
payTo: process.env.PAY_TO!,
facilitatorUrl: process.env.FACILITATOR_URL!,
facilitatorSecret: process.env.FACILITATOR_SECRET!
});
export const POST = pay(async (req: NextRequest) => {
const { prompt } = await req.json();
return NextResponse.json({ result: `Generated: ${prompt}` });
});
Step 4: Make Paid Requests (Client)
'use client';
import { useMantleX402 } from '@puga-labs/x402-mantle-sdk/react';
export function GenerateButton() {
// facilitatorUrl auto-detected from backend 402 response
const { postWithPayment } = useMantleX402();
const generate = async () => {
const { response, txHash } = await postWithPayment('/api/generate', {
prompt: 'Hello world'
});
console.log('Result:', response, txHash);
};
return <button onClick={generate}>Generate ($0.01)</button>;
}
Step 5: Test It
- Start your facilitator (
npm run devin facilitator directory) - Start your Next.js app (
npm run dev) - Connect MetaMask (Mantle network)
- Click the button
- Sign the transaction in MetaMask
- Receive the result!
Environment Variables
Create .env.local:
PAY_TO=0xYourWalletAddress
FACILITATOR_URL=http://localhost:8080
FACILITATOR_SECRET=fac_xxx... # Copy from facilitator .env
Quick Start (Hosted Facilitator)
The fastest way to get started — no infrastructure to deploy.
Step 1: Get Project Key
- Go to Dashboard
- Create a project
- Buy transaction pack (pay with MNT)
- Copy your project key (
pk_xxx)
Step 2: Install SDK
npm install @puga-labs/x402-mantle-sdk ethers
Step 3: Protect Your API (Server)
// app/api/generate/route.ts
import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs';
import { NextRequest, NextResponse } from 'next/server';
const pay = mantlePaywall({
priceUsd: 0.01,
payTo: process.env.PAY_TO!,
projectKey: process.env.PROJECT_KEY
});
export const POST = pay(async (req: NextRequest) => {
const { prompt } = await req.json();
return NextResponse.json({ result: `Generated: ${prompt}` });
});
Step 4: Make Paid Requests (Client)
'use client';
import { useMantleX402 } from '@puga-labs/x402-mantle-sdk/react';
export function GenerateButton() {
// facilitatorUrl and projectKey auto-detected from backend 402 response
const { postWithPayment } = useMantleX402();
const generate = async () => {
try {
const { response, txHash } = await postWithPayment('/api/generate', {
prompt: 'Hello world'
});
console.log('Result:', response);
console.log('Transaction:', txHash);
} catch (error) {
console.error('Payment failed:', error);
}
};
return <button onClick={generate}>Generate ($0.01)</button>;
}
Environment Variables
Create .env.local:
PAY_TO=0xYourWalletAddress
PROJECT_KEY=pk_xxx # From dashboard
Comparison
| Self-Hosted | Hosted | |
|---|---|---|
| Setup time | 10 minutes | 2 minutes |
| Infrastructure | Your server | None |
| Gas fees | You pay | We pay |
| Per-tx fee | Free | 1 MNT = 100 tx |
| Required config | facilitatorUrl + facilitatorSecret | projectKey |
| Control | Full | Standard |
Next Steps
- Installation — Detailed installation guide
- Self-Hosted Facilitator — Deploy your own
- Hosted Facilitator — Managed service details
- Client SDK — All client-side options
- Server SDK — All server frameworks
- Examples — Full working examples