跳转到主要内容

​
概述

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);

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();

​
检测细节

  • 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 重新检测

​
相关资源

  • 源代码：https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-detector
  • 问题反馈：https://github.com/WTFLabs-WTF/x402x/issues