x402x-detector

概述

x402x-detector 用于自动识别 ERC-20 Token 的“免 Gas 支付能力”，覆盖 EIP-2612 Permit、EIP-3009、Permit2 等标准，并能处理常见代理模式（EIP-1967 / UUPS）。结果会永久缓存以获得毫秒级访问。

核心特性

🔍 全面检测：Permit / EIP-3009 / Permit2
🧭 代理处理：EIP-1967 / UUPS / 自定义 implementation
⚡ 高性能：首次 2-5s，命中缓存 <1ms
🧰 简洁 API：detect / getRecommendedMethod / initialize

安装

npm i x402x-detector@beta viem

快速上手

import { TokenDetector } from "x402x-detector";
const detector = new TokenDetector(publicClient);
const info = await detector.detect("0xUSDC"); // { supportedMethods: ["permit", ...], name, version }

示例

函数式 API（无缓存）
TokenDetector 类（带缓存）
服务端集成（Express）
检测收款地址（EIP-7702 + settle）

创建 detect.ts，核心逻辑如下：

import { detectTokenPaymentMethods, getRecommendedPaymentMethod, getTokenInfo } from "x402x-detector";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";

const client = createPublicClient({ chain: bsc, transport: http() });
const token = "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"; // USD1 (BSC)

// 1) 检测支付能力
const capabilities = await detectTokenPaymentMethods(token, client);

// 2) 推荐支付方式（eip3009 > permit > permit2）
const recommended = await getRecommendedPaymentMethod(token, client);

// 3) 读取代币信息（name/version）
const info = await getTokenInfo(token, client);

查看完整示例代码（函数式 API）

import { detectTokenPaymentMethods, getRecommendedPaymentMethod, getTokenInfo } from "x402x-detector";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";

async function main() {
  const client = createPublicClient({ chain: bsc, transport: http() });
  const token = "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"; // USD1 (BSC)

  const capabilities = await detectTokenPaymentMethods(token, client);
  console.log("capabilities:", capabilities);

  const recommended = await getRecommendedPaymentMethod(token, client);
  console.log("recommended:", recommended);

  const info = await getTokenInfo(token, client);
  console.log("token info:", info);
}

main();

创建 detector.ts，核心逻辑如下：

import { TokenDetector } from "x402x-detector";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";

const client = createPublicClient({ chain: bsc, transport: http() });
const detector = new TokenDetector(client);

// 预热缓存（可在服务启动时执行）
await detector.initialize([
  "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
]);

// 缓存命中时毫秒级返回
const result = await detector.detect("0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d");
const method = await detector.getRecommendedMethod("0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d");

查看完整示例代码（带缓存类）

import { TokenDetector } from "x402x-detector";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";

async function main() {
  const client = createPublicClient({ chain: bsc, transport: http() });
  const detector = new TokenDetector(client);

  // 启动时预热常用 Token
  const tokens = [
    "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
  ];
  await detector.initialize(tokens);

  // 检测（命中缓存速度极快）
  const result = await detector.detect(tokens[0]);
  console.log(result);

  // 推荐支付方式
  const method = await detector.getRecommendedMethod(tokens[0]);
  console.log("recommended:", method);

  // 缓存统计
  console.log(detector.getCacheStats());
}

main();

import express from "express";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";
import { TokenDetector } from "x402x-detector";

const app = express();
const client = createPublicClient({ chain: bsc, transport: http() });
const detector = new TokenDetector(client);

// 推荐预热
detector.initialize([
  "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
]);

app.get("/api/token/:address/capabilities", async (req, res) => {
  const data = await detector.detect(req.params.address);
  res.json(data);
});

app.get("/api/token/:address/recommended", async (req, res) => {
  const method = await detector.getRecommendedMethod(req.params.address);
  res.json({ recommendedMethod: method });
});

用于检测卖家收款地址（建议使用 EIP-7702 部署的钱包/合约）是否实现 x402x 结算扩展方法。可在上线前自检，或做健康检查与灰度。

import { detectSettleMethods } from "x402x-detector";
import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";

const client = createPublicClient({ chain: bsc, transport: http() });
const recipient = "0xSellerEIP7702RecipientAddress";

const settle = await detectSettleMethods(client, recipient);
// {
//   supportsSettleWithPermit: boolean;    // 0x02ccc23e
//   supportsSettleWithERC3009: boolean;   // 0x1fe200d9
//   supportsSettleWithPermit2: boolean;   // 0xa7fcafbb
// }

if (!settle.supportsSettleWithPermit && !settle.supportsSettleWithERC3009 && !settle.supportsSettleWithPermit2) {
  throw new Error("收款地址未实现任一 x402x 结算方法，请确认已按 EIP-7702 集成扩展。");
}

如何理解 settle 检测（实现要点）

settle 方法通过函数选择器进行识别（基于 ERC-165 能力暴露或静态字节码分析）：
- settleWithPermit → 0x02ccc23e
- settleWithERC3009 → 0x1fe200d9
- settleWithPermit2 → 0xa7fcafbb
建议采用 EIP-7702 账户模型为收款地址部署扩展合约，以便在多种授权方式下完成结算。

检测细节

Permit: permit() / DOMAIN_SEPARATOR() / nonces(owner)
EIP-3009: transferWithAuthorization()、authorizationState()
Permit2: allowance(user, token, spender)

代理合约：自动读取实现地址（EIP-1967 存储槽 / UUPS proxiableUUID() 等）

建议用法

启动预热：detector.initialize([USDC, DAI, ...])
选择推荐类型：detector.getRecommendedMethod(token)
非标准代理合约需手动校验实现地址

API 参考（精简）

class TokenDetector {
  constructor(client: PublicClient);
  detect(tokenAddress: string): Promise<{
    address: string;
    supportedMethods: ("eip3009" | "permit" | "permit2" | "permit2-witness")[];
    details: { hasEIP3009: boolean; hasPermit: boolean; hasPermit2Approval: boolean };
    name: string;
    version: string;
  }>;
  getRecommendedMethod(tokenAddress: string): Promise<"eip3009" | "permit" | "permit2" | null>;
  initialize(tokenAddresses: string[]): Promise<any[]>;
  clearCache(tokenAddress?: string): Promise<void>;
  getCacheStats(): { size: number; keys: string[] };
}

更多类型与返回结构请参考：

参数说明：/parameters-responses/detector/parameters
返回结构：/parameters-responses/detector/responses

性能与优化

预热常用 Token：服务启动时 initialize([tokens])
并行检测：优先使用 initialize 批量并行
按需检测：首次慢、后续快（命中缓存）
定期刷新：周期性对热门 Token 重新检测

Packages

概述

核心特性

安装

快速上手

示例

检测细节

建议用法

API 参考（精简）

性能与优化

相关资源

​概述

​核心特性

​安装

​快速上手

​示例

​检测细节

​建议用法

​API 参考（精简）

​性能与优化

​相关资源

概述

核心特性

安装

快速上手

示例

检测细节

建议用法

API 参考（精简）

性能与优化

相关资源