API Reference

Complete technical reference for x402 Mantle SDK.

TypeScript Types

Core Types

// Network identifier
type NetworkId = "mantle-mainnet" | (string & {});

// Asset configuration
interface AssetConfig {
  symbol: string;     // "USDC"
  address: string;    // Contract address
  decimals: number;   // 6 for USDC
}

// Payment requirements (402 response)
interface PaymentRequirements {
  scheme: "exact";
  network: NetworkId;
  asset: string;              // ERC-20 token address
  maxAmountRequired: string;  // Amount in atomic units
  payTo: string;              // Recipient address
  price?: string;             // Human-readable (e.g., "$0.01")
  currency?: string;          // "USD"
}

// EIP-3009 Authorization
interface Authorization {
  from: string;        // Payer address
  to: string;          // Recipient address
  value: string;       // Amount in atomic units
  validAfter: string;  // Unix timestamp
  validBefore: string; // Unix timestamp
  nonce: string;       // Random 32-byte hex
}

// Payment header structure
interface PaymentHeaderObject {
  x402Version: number;  // 1
  scheme: "exact";
  network: NetworkId;
  payload: {
    signature: string;         // EIP-712 signature
    authorization: Authorization;
  };
}

// Base64-encoded payment header
type PaymentHeaderBase64 = string;

Client Types

// High-level client config
interface MantleClientConfig {
  facilitatorUrl?: string;      // Auto-detected from 402 response
  resourceUrl?: string;         // Your API URL (default: window.location.origin)
  projectKey?: string;          // Auto-detected from 402 response
  getProvider?: () => EIP1193Provider;
  getAccount?: () => string | undefined;
}

// High-level client interface
interface MantleClient {
  postWithPayment<T = any>(
    url: string,
    body?: any
  ): Promise<CallWithPaymentResult<T>>;
}

// Low-level client config
interface PaymentClientConfig {
  resourceUrl: string;
  facilitatorUrl?: string;      // Auto-detected from 402 response
  provider: EIP1193Provider;
  userAddress?: string;
  projectKey?: string;          // Auto-detected from 402 response
}

// Payment result
interface CallWithPaymentResult<T> {
  response: T;
  txHash?: string;
  paymentHeader?: string;
  paymentRequirements?: PaymentRequirements;
}

// EIP-1193 Provider interface
interface EIP1193Provider {
  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
  on?(event: string, listener: (...args: unknown[]) => void): void;
  removeListener?(event: string, listener: (...args: unknown[]) => void): void;
}

Server Types

// Paywall configuration
interface MinimalPaywallOptions {
  priceUsd: number;                   // Price in USD (e.g., 0.01)
  payTo: string;                      // Your wallet address
  projectKey?: string;                // For hosted mode (from dashboard)
  facilitatorUrl?: string;            // For self-hosted (defaults to hosted)
  facilitatorSecret?: string;         // For self-hosted (required with facilitatorUrl)
  network?: NetworkId;                // Default: "mantle-mainnet"
  onPaymentSettled?: (entry: PaymentLogEntry) => void | Promise<void>;
  telemetry?: TelemetryConfig;        // Auto-uses projectKey if not set
}

// Payment log entry (onPaymentSettled callback)
interface PaymentLogEntry {
  id: string;                         // Unique payment ID (nonce)
  from: string;                       // Payer's wallet address
  to: string;                         // Your wallet address
  valueAtomic: string;                // Amount in atomic units
  network: NetworkId;                 // "mantle-mainnet"
  asset: string;                      // USDC contract address
  route?: string;                     // API route (e.g., "POST /api/generate")
  txHash?: string;                    // Blockchain transaction hash
  timestamp: number;                  // Unix timestamp (ms)
  facilitatorUrl?: string;
  paymentRequirements?: PaymentRequirements;
}

// Telemetry configuration
interface TelemetryConfig {
  projectKey?: string;  // Auto-derived from mantlePaywall projectKey
  debug?: boolean;      // Enable debug logging (default: false)
}

// Route configuration (for multi-route middleware)
interface RoutePricingConfig {
  priceUsdCents: number;
  network: NetworkId;
}

type RouteKey = string;  // "POST /api/generate"
type RoutesConfig = Record<RouteKey, RoutePricingConfig>;

React Hook Types

// useMantleX402 options
interface UseMantleX402Options {
  facilitatorUrl?: string;    // Auto-detected from 402 response
  resourceUrl?: string;       // Your API URL
  projectKey?: string;        // Auto-detected from 402 response
}

// useEthersWallet options
interface UseEthersWalletOptions {
  autoConnect?: boolean;      // Auto-connect on mount (default: false)
}

// useEthersWallet return type
interface UseEthersWalletReturn {
  address: string | undefined;
  isConnected: boolean;
  chainId: number | undefined;
  provider: BrowserProvider | undefined;
  connect: () => Promise<void>;
  disconnect: () => void;
  error: Error | undefined;
}

Configuration Modes

Self-Hosted Mode (Recommended)

// Requires both facilitatorUrl and facilitatorSecret
const pay = mantlePaywall({
  priceUsd: 0.01,
  payTo: '0xYourWallet',
  facilitatorUrl: 'https://your-facilitator.com',  // Required
  facilitatorSecret: process.env.FACILITATOR_SECRET!,  // Required
  projectKey: 'pk_xxx'  // Optional: for analytics
});

Hosted Mode

// No facilitatorUrl needed - defaults to hosted service
const pay = mantlePaywall({
  priceUsd: 0.01,
  payTo: '0xYourWallet',
  projectKey: 'pk_xxx'  // Required for hosted mode
});

Facilitator Endpoints

GET /health

Returns facilitator status.

Response:

{
  "status": "ok",
  "network": "mantle-mainnet",
  "chainId": 5000,
  "facilitatorAddress": "0x...",
  "blockNumber": 12345678,
  "mntBalance": "1.5"
}

GET /supported

Returns supported configuration.

Response:

{
  "x402Version": 1,
  "schemes": ["exact"],
  "networks": ["mantle-mainnet"],
  "assets": {
    "mantle-mainnet": [{
      "address": "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
      "symbol": "USDC",
      "decimals": 6
    }]
  }
}

POST /verify

Verifies a payment header.

Request:

{
  "x402Version": 1,
  "paymentHeader": "base64-encoded-header",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "mantle-mainnet",
    "asset": "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
    "maxAmountRequired": "10000",
    "payTo": "0x..."
  }
}

Response (valid):

{
  "isValid": true
}

Response (invalid):

{
  "isValid": false,
  "invalidReason": "Payment amount too low"
}

POST /settle

Executes USDC transfer on-chain. For self-hosted facilitators, requires settleToken for authentication.