Documentation Index
Fetch the complete documentation index at: https://docs.x402x.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 }
创建 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();
创建 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 方法通过函数选择器进行识别（基于 ERC-165 能力暴露或静态字节码分析）：
settleWithPermit → 0x02ccc23esettleWithERC3009 → 0x1fe200d9settleWithPermit2 → 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 重新检测
相关资源
- 源代码：
https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-detector
- 问题反馈：
https://github.com/WTFLabs-WTF/x402x/issues
