如何设置支持 Monad 的 x402 启用端点

本指南演示如何使用 x402 支付和 Monad 的 facilitator 设置可付费的端点。它可在 Monad 测试网/主网上运行。

什么是 x402？

x402 是让 HTTP 402 “Payment Required” 状态码重新焕发生机，成为一个用于互联网原生微支付的极简协议。 x402 不再需要订阅或要求账户的付费墙，而是让任何 HTTP 端点即刻可付费：

客户端请求一个资源
服务器以 402 响应，并附带一个小的 JSON 支付要求
客户端签署一个支付授权并重新发送请求
服务器验证并提供内容

超越传统限制

x402 是为现代互联网经济而设计，解决了传统系统的关键限制：

降低手续费和摩擦： 无需中介、高额手续费或手动设置的直接链上支付。
微支付与基于用量的计费： 按调用或功能收费，简单可编程的按用付费流程。
机器对机器交易： 让 AI 代理自主付费和访问服务，无需密钥或人类介入。

为什么在 Monad 上使用 x402？

Monad 是一个完全兼容 EVM 的 Layer 1，具有：

10,000 TPS
约 0.3 秒的出块时间
单槽最终性
并行执行
极低的手续费

这些特性使 Monad 成为真正的微支付和代理间商务的理想环境。支付以极低成本立即结算，并避免 mempool 拥堵，非常适合大量 AI 代理按 API 调用付费的场景。

核心流程（直接支付）

Facilitator 流程（生产环境推荐）

facilitator 服务是可选的，但在生产环境中推荐使用。Facilitator 可以批量处理交易、承担 gas 费、处理退款，并简化客户端逻辑。

使用 Monad x402 facilitator 构建基于 x402 的应用

前置条件

Node.js 18+
一个 EVM 钱包
访问 Monad 测试网资金（下方的 USDC 测试代币）

Monad Facilitator 仅支持 x402 v2 及以上版本。迁移指南说明了差异：https://docs.x402.org/guides/migration-v1-to-v2

如何在 Monad 测试网上获取 USDC 代币

您可以使用 Circle 的水龙头为 Monad 测试网获取 USDC 代币：

访问 https://faucet.circle.com
选择 USDC 作为代币
从 Network 下拉菜单中选择 Monad Testnet
输入您的钱包地址
点击 Send 1 USDC

限制： 每对（稳定币，测试网）每 2 小时一次请求

您还需要测试网 MON 代币用于 gas 费。请从 Monad 水龙头获取。

步骤 1：初始化一个 Next.js 应用

创建一个新的 Next.js 项目：

npx create-next-app@latest my-x402-app

提示时选择以下选项：

✅ TypeScript
✅ ESLint
✅ Tailwind CSS
✅ src/ 目录
✅ App Router
✅ 自定义默认导入别名：@/*（默认）

进入您的项目：

cd my-x402-app

安装 x402 相关包：

使用 @x402/evm >= 2.22.0。它自带内置的 Monad 主网 USDC 配置，具有正确的 EIP-712 域名，并引用了正确的 upto 代理。详情参见支持的支付方案。

npm install @x402/core @x402/evm @x402/fetch @x402/next

为您的环境变量创建 .env.local 文件：

touch .env.local

步骤 2：创建 `payTo` 地址

payTo 地址用于接收支付并从后端与区块链交互。复制钱包地址并将其作为 PAY_TO_ADDRESS 添加到您的 .env.local 文件中

PAY_TO_ADDRESS=0xYourWallet

步骤 3：创建服务端可付费端点

src/app/api/premium/route.ts

import { NextResponse } from "next/server";
import { withX402, type RouteConfig } from "@x402/next";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import type { Network } from "@x402/core/types";

// Monad Testnet configuration
const MONAD_NETWORK: Network = "eip155:10143";
const MONAD_USDC_TESTNET = "0x534b2f3A21130d7a60830c2Df862319e593943A3";

// Monad Facilitator URL
const FACILITATOR_URL = "https://x402-facilitator.molandak.org"; 

if (!process.env.PAY_TO_ADDRESS) {
  throw new Error("PAY_TO_ADDRESS environment variable is required");
}
const PAY_TO = process.env.PAY_TO_ADDRESS;

// Create facilitator client for Monad
const facilitatorClient = new HTTPFacilitatorClient({ url: FACILITATOR_URL });

// Create and configure x402 resource server
const server = new x402ResourceServer(facilitatorClient);

// Monad testnet USDC is not in @x402/evm's built-in asset table, so register
// it here. Mainnet (eip155:143) is built in since 2.22.0 and needs no parser.
const monadScheme = new ExactEvmScheme();
monadScheme.registerMoneyParser(async (amount: number, network: string) => {
  if (network === MONAD_NETWORK) {
    // Convert decimal amount to USDC smallest units (6 decimals).
    // `Math.floor(amount * 1_000_000)` is safe up to ~9 billion USDC
    // (~9 quadrillion atomic units) — bounded by JS Number's 2^53 precision.
    // For tokens with 18 decimals or very large balances, use `BigInt` to avoid
    // precision loss, e.g.:
    //   BigInt(Math.round(amount * 1e6)).toString()   // USDC, 6 decimals
    //   (BigInt(Math.round(amount * 1e9)) * 1_000_000_000n).toString()  // 18d, ≤9 fractional digits
    const tokenAmount = Math.floor(amount * 1_000_000).toString();
    return {
      amount: tokenAmount,
      asset: MONAD_USDC_TESTNET, // Raw address for EIP-712 verifyingContract
      extra: {
        name: "USDC",
        version: "2",
      },
    };
  }
  return null; // Use default parser for other networks
});

// Register Monad network with custom scheme
server.register(MONAD_NETWORK, monadScheme);

// Route configuration
const routeConfig: RouteConfig = {
  accepts: {
    scheme: "exact",
    network: MONAD_NETWORK,
    payTo: PAY_TO,
    price: "$0.001",
  },
  resource: "http://localhost:3000/api/premium", // Use relative path to avoid host mismatch
};

// Handler that returns full article content
async function handler(request: NextRequest) {
  return NextResponse.json({
    content: "Return premium content",
    unlockedAt: new Date().toISOString(),
  });
}

// Export GET method wrapped with x402 payment protection
export const GET = withX402(handler, routeConfig, server);

步骤 4：客户端设置（消费付费端点）

以下是使用 Next.js 应用消费付费端点的示例，然而该端点也可以通过代理脚本消费。

src/app/page.tsx

"use client";

import { useState, useCallback, useEffect } from "react";
import { useAccount, useWalletClient } from "wagmi";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { x402Client } from "@x402/core/client";

// x402 configuration
const x402Config = {
  chainId: "eip155:10143" as const,
  usdcAddress: "0x534b2f3A21130d7a60830c2Df862319e593943A3", // MONAD USDC TESTNET
  facilitator: "https://x402-facilitator.molandak.org", // MONAD FACILITATOR URL
  price: "0.001", // USDC
};

export default function Home() {
  const { isConnected, address } = useAccount();
  const { data: walletClient } = useWalletClient();
  const [message, setMessage] = useState("Pay $0.001 USDC to unlock premium content");
  const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");

  // This function allows signing a message, and pay USDC gaslessly. 
  const handleUnlock = useCallback(async () => {
    if (!walletClient || !address) {
      setError("Please connect your wallet first");
      return;
    }

    setIsLoading(true);
    setError(null);

    try {
      // Create EVM signer compatible with x402 ClientEvmSigner interface
      const evmSigner = {
        address: address as `0x${string}`,
        signTypedData: async (message: {
          domain: Record<string, unknown>;
          types: Record<string, unknown>;
          primaryType: string;
          message: Record<string, unknown>;
        }) => {
          return walletClient.signTypedData({
            domain: message.domain as Parameters<typeof walletClient.signTypedData>[0]["domain"],
            types: message.types as Parameters<typeof walletClient.signTypedData>[0]["types"],
            primaryType: message.primaryType,
            message: message.message,
          });
        },
      };

      // Create the Exact EVM scheme for signing
      const exactScheme = new ExactEvmScheme(evmSigner);

      // Create x402 client and register the scheme
      const client = new x402Client()
        .register(x402Config.chainId, exactScheme);

      console.log("x402 client configured for network:", x402Config.chainId);

      // Wrap fetch with x402 payment capability
      const paymentFetch = wrapFetchWithPayment(fetch, client);

      console.log("Making payment request to /api/article...");

      // Make request to protected endpoint
      const response = await paymentFetch("/api/premium", {
        method: "GET",
        headers: {
          "Content-Type": "application/json",
        },
      });

      if (!response.ok) {
        // Try to parse x402 payment-required header for detailed error
        const paymentHeader = response.headers.get("payment-required");

        if (paymentHeader && response.status === 402) {
          try {
            const paymentData = JSON.parse(atob(paymentHeader));
            console.error("Payment error details:", paymentData);

            // Extract user-friendly error message
            if (paymentData.error?.includes("insufficient_funds")) {
              throw new Error("INSUFFICIENT_FUNDS");
            }
            if (paymentData.error?.includes("unexpected_error")) {
              throw new Error("UNEXPECTED_ERROR");
            }
            if (paymentData.error) {
              throw new Error(paymentData.error);
            }
          } catch (e) {
            if (e instanceof Error && e.message === "INSUFFICIENT_FUNDS") {
              throw e;
            }
            // Failed to parse header, continue to generic error
          }
        }

        const errorText = await response.text().catch(() => "");
        let errorData: Record<string, unknown> = {};
        try {
          errorData = JSON.parse(errorText);
        } catch {
          // Not JSON
        }
        throw new Error(
          errorData.error as string ||
          errorData.details as string ||
          `Request failed: ${response.status}`
        );
      }

      const data = await response.json();

      // Cache the unlocked content in LocalStorage
      localStorage.setItem(
        "premimum_content_unlocked",
        JSON.stringify({
          content: data.content,
          timestamp: Date.now(),
        })
      );
    } catch (err) {
      console.error("Unlock error:", err);
      const message = err instanceof Error ? err.message : "Failed to unlock article";

      // Map technical errors to user-friendly messages
      if (
        message.includes("User rejected") ||
        message.includes("User denied") ||
        message.includes("user rejected")
      ) {
        setError("CANCELLED");
      } else if (message === "INSUFFICIENT_FUNDS" || message.includes("insufficient_funds")) {
        setError("INSUFFICIENT_FUNDS");
      } else if (message === "UNEXPECTED_ERROR" || message.includes("unexpected_error")) {
        setError("UNEXPECTED_ERROR");
      } else {
        setError(message);
      }
    } finally {
      setIsLoading(false);
    }
  }, [walletClient, address]);

  return (
    <main className="min-h-screen bg-zinc-950 flex items-center justify-center p-6">
      <div className="max-w-md w-full space-y-6">
        <div className="text-center space-y-2">
          <h1 className="text-2xl font-bold text-white">x402 on Monad</h1>
          <p className="text-zinc-400 text-sm">
            Micropayments via the Monad facilitator.{" "}
            <a href="https://docs.monad.xyz/guides/x402-guide" className="text-violet-400 hover:underline">
              Docs
            </a>
          </p>
        </div>

        <button
          onClick={handleUnlock}
          disabled={status === "loading"}
          className="w-full py-3 px-4 bg-violet-600 hover:bg-violet-500 disabled:bg-violet-800 disabled:cursor-wait text-white font-medium rounded-lg transition-colors"
        >
          {status === "loading" ? "Processing..." : "Pay & Unlock Content"}
        </button>

        <div className={`p-4 rounded-lg text-sm ${
          status === "error" ? "bg-red-950 text-red-300" :
          status === "success" ? "bg-green-950 text-green-300" :
          "bg-zinc-900 text-zinc-300"
        }`}>
          {message}
        </div>
      </div>
    </main>
  );
}

运行您的 x402 应用

现在您已经准备好测试您的 x402 支付流程了：

启动开发服务器：
npm run dev
在浏览器中打开 http://localhost:3000
点击”Pay & Unlock Content”
连接您的钱包
批准 USDC 支付
立即看到内容解锁！

Facilitator API

对于希望使用基本 Facilitator API 的开发者，以下是支持的端点及示例。 Facilitator URL：https://x402-facilitator.molandak.org 网络支持：主网（eip155:143，USDC 0x754704Bc059F8C67012fEd69BC8A327a5aafb603）和测试网（eip155:10143，USDC 0x534b2f3A21130d7a60830c2Df862319e593943A3）。在 @x402/evm >= 2.22.0 上，主网 USDC 从 SDK 的内置资产表中解析。测试网没有内置条目，需要上面快速入门中所示的自定义 money parser。

支持的支付方案

Monad facilitator 通过 GET /supported 公布两种 x402 v2 方案：

Scheme ID	使用场景	机制
`v2-eip155-exact`	固定价格支付（USDC 默认）	直接对代币使用 EIP-3009 `transferWithAuthorization`，或对非 EIP-3009 代币回退使用 Permit2 代理
`v2-eip155-upto`	可变金额/计量支付（LLM tokens、带宽、算力）	仅使用 Permit2 —— 客户端签署一个上限值，facilitator 按实际使用量 ≤ 上限进行结算。支持 $0 结算（无需链上交易）

对于 Monad 上的 USDC，按照 x402 规范推荐使用 exact 方案。Upto 需要位于 0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002 的规范 x402UptoPermit2Proxy（参见规范合约），以及由 facilitator 公布的 extra.facilitatorAddress，客户端必须将其绑定到 Permit2 witness 中。

对于 upto 方案，请使用 @x402/evm >= 2.12.0（推荐 >= 2.22.0）。 2.9.0–2.11.0 版本包含 upto 模块，但引用的代理地址（0x402039b3d6E6BEC5A02c2C9fd937ac17A6940002）并未部署在 Monad 上。支付将在结算时失败，且没有明确的错误。正确的地址（0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002）最早出现在 2.12.0 中，2.22.0 引用相同的代理，并增加了带有正确 EIP-712 域名的内置 Monad 主网 USDC 配置。如果您将来升级到更新的版本，请在部署到生产环境之前确认它引用了相同的代理地址。

可能的 HTTP 状态码

除了标准的 200 / 4xx / 5xx 代码外，facilitator 还可能返回：

412 PRECONDITION_FAILED —— 当 Permit2 支付因用户对代理合约的 Permit2 授权额度不足而无法进行时返回（PERMIT2_ALLOWANCE_REQUIRED）。客户端必须通过 Permit2 授权代理并重试。这与 400（请求体格式错误）和 402（资源服务器的支付要求响应）不同。

GET `/supported`

返回支持的网络、方案和签名者地址。

const FACILITATOR_URL = "https://x402-facilitator.molandak.org";

async function testSupported(): Promise<void> {
  console.log("\n--- GET /supported ---");

  const response = await fetch(`${FACILITATOR_URL}/supported`);
  if (!response.ok) throw new Error(`Failed: ${response.status}`);

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
  return data;
}

POST `/verify`

验证支付签名。

interface NetworkConfig {
  chainId: Network;
  name: string;
  rpcUrl: string;
  explorerUrl: string;
  usdcAddress: `0x${string}`;
  usdcDecimals: number;
  chainIdNumber: number;
}

/**
 * This function manually constructs and signs the EIP-712 typed data that
 * the x402 client library handles automatically.
 */
async function testVerify(
  account: ReturnType<typeof privateKeyToAccount>,
  networkConfig: NetworkConfig
): Promise<{ isValid: boolean; payload: any }> {
  console.log("\n--- POST /verify ---");
  const now = Math.floor(Date.now() / 1000);
  const nonce = keccak256(toHex(Math.random().toString()));
  const ACCOUNT_ADDRESS = "0x0000000000000000000000000000000000000000";

  // TransferWithAuthorization parameters (ERC-3009)
  const authorization = {
    from: ACCOUNT_ADDRESS, // Account that is paying
    to: PAY_TO_ADDRESS, // Receiver address
    value: "1000", // 0.001 USDC (6 decimals)
    validAfter: (now - 60).toString(), // Start validity 60s in the past to handle clock skew
    validBefore: (now + 900).toString(), // 15 minutes
    nonce,
  };

  // EIP-712 domain - must match USDC contract's DOMAIN_SEPARATOR
  const domain = {
    name: "USDC",  // Monad USDC uses "USDC" (not "USD Coin")
    version: "2",
    chainId: BigInt(networkConfig.chainIdNumber),
    verifyingContract: networkConfig.usdcAddress,
  };

  // EIP-712 type definition for TransferWithAuthorization
  const types = {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" },
    ],
  };

  const message = {
    from: authorization.from,
    to: authorization.to,
    value: BigInt(authorization.value),
    validAfter: BigInt(authorization.validAfter),
    validBefore: BigInt(authorization.validBefore),
    nonce: authorization.nonce as `0x${string}`,
  };

  const signature = await account.signTypedData({
    domain,
    types,
    primaryType: "TransferWithAuthorization",
    message,
  });

  const requestBody = {
    x402Version: 2,
    payload: {
      authorization,
      signature,
    },
    // `resource` (and its `url` / `description` / `mimeType` fields) is OPTIONAL
    // in x402 v2; the facilitator only requires `payload` + `accepted`. Include it
    // when the resource server wants its identity recorded alongside the settlement.
    resource: {
      url: "http://test/resource",
      description: "Test resource",
      mimeType: "application/json",
    },
    accepted: {
      scheme: "exact",
      network: networkConfig.chainId,
      amount: authorization.value,
      asset: networkConfig.usdcAddress,
      payTo: authorization.to,
      maxTimeoutSeconds: 300,
      extra: {
        name: "USDC",
        version: "2",
      },
    },
  };

  const response = await fetch(`${FACILITATOR_URL}/verify`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(requestBody),
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));

  return { isValid: data.isValid, payload: requestBody };
}

POST `/settle`

在链上执行支付。Facilitator 支付 gas 费。

interface NetworkConfig {
  chainId: Network;
  name: string;
  rpcUrl: string;
  explorerUrl: string;
  usdcAddress: `0x${string}`;
  usdcDecimals: number;
  chainIdNumber: number;
}

/** POST /settle - Execute the payment on-chain. Facilitator pays gas. */
async function testSettle(
  payload: any,
  networkConfig: NetworkConfig
): Promise<void> {
  console.log("\n--- POST /settle ---");

  const response = await fetch(`${FACILITATOR_URL}/settle`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));

  if (data.success && data.transaction) {
    // Transaction success
  } else if (data.errorReason) {
    console.log(`Failed: ${data.errorReason}`);
  }
}

下一步做什么？

您已成功在 Monad 上构建了一个启用 x402 支付的应用！以下是一些扩展您实现的想法：

添加更多可付费端点 - 为不同的内容或 API 调用创建不同的价格层
构建 AI 代理集成 - 使自主代理能够为访问您的 API 付费

资源

需要帮助？

如果您遇到问题或有疑问，请加入 Monad 开发者 Discord 祝您构建愉快！

简介

开发者要点

工具和基础设施

JSON-RPC

指南

资源

面向 AI 智能体

如何设置支持 Monad 的 x402 启用端点

什么是 x402？

超越传统限制

为什么在 Monad 上使用 x402？

核心流程（直接支付）

Facilitator 流程（生产环境推荐）

使用 Monad x402 facilitator 构建基于 x402 的应用

前置条件

步骤 1：初始化一个 Next.js 应用

步骤 2：创建 `payTo` 地址

步骤 3：创建服务端可付费端点

步骤 4：客户端设置（消费付费端点）

运行您的 x402 应用

Facilitator API

支持的支付方案

可能的 HTTP 状态码

GET `/supported`

POST `/verify`

POST `/settle`

下一步做什么？

资源

需要帮助？

​什么是 x402？

​超越传统限制

​为什么在 Monad 上使用 x402？

​核心流程（直接支付）

​Facilitator 流程（生产环境推荐）

​使用 Monad x402 facilitator 构建基于 x402 的应用

​前置条件

​步骤 1：初始化一个 Next.js 应用

​步骤 2：创建 payTo 地址

​步骤 3：创建服务端可付费端点

​步骤 4：客户端设置（消费付费端点）

​运行您的 x402 应用

​Facilitator API

​支持的支付方案

​可能的 HTTP 状态码

​GET /supported

​POST /verify

​POST /settle

​下一步做什么？

​资源

​需要帮助？

什么是 x402？

超越传统限制

为什么在 Monad 上使用 x402？

核心流程（直接支付）

Facilitator 流程（生产环境推荐）

使用 Monad x402 facilitator 构建基于 x402 的应用

前置条件

步骤 1：初始化一个 Next.js 应用

步骤 2：创建 `payTo` 地址

步骤 3：创建服务端可付费端点

步骤 4：客户端设置（消费付费端点）

运行您的 x402 应用

Facilitator API

支持的支付方案

可能的 HTTP 状态码

GET `/supported`

POST `/verify`

POST `/settle`

下一步做什么？

资源

需要帮助？