x402x-detector - x402x-docs

Overview

x402x-detector automatically identifies an ERC-20 token’s “gasless payment capability” — covering EIP-2612 Permit, EIP-3009, and Permit2 — and handles common proxy patterns (EIP-1967 / UUPS). Results are cached for millisecond-level access.

Key features

Full detection: Permit / EIP-3009 / Permit2
Proxy handling: EIP-1967 / UUPS / custom implementation
High performance: 2–5s on first run, <1ms with cache hits
Simple API: detect / getRecommendedMethod / initialize

Install

npm i x402x-detector@beta viem

Quick start

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

Examples

Functional API (no cache)
TokenDetector class (with cache)
Server integration (Express)
Detect recipient (EIP-7702 + settle)

Create detect.ts, core logic:

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) Detect capabilities
const capabilities = await detectTokenPaymentMethods(token, client);

// 2) Recommend payment method (eip3009 > permit > permit2)
const recommended = await getRecommendedPaymentMethod(token, client);

// 3) Read token info (name/version)
const info = await getTokenInfo(token, client);

Full example (functional 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();

Create detector.ts, core logic:

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

// Warm up cache (can be done at service startup)
await detector.initialize([
  "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
]);

// Millisecond response on cache hit
const result = await detector.detect("0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d");
const method = await detector.getRecommendedMethod("0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d");

Full example (class with cache)

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

  // Warm up common tokens at startup
  const tokens = [
    "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
  ];
  await detector.initialize(tokens);

  // Detection (super fast on cache hits)
  const result = await detector.detect(tokens[0]);
  console.log(result);

  // Recommended payment method
  const method = await detector.getRecommendedMethod(tokens[0]);
  console.log("recommended:", method);

  // Cache stats
  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);

// Warm up (recommended)
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 });
});

Detect whether a seller recipient address (recommended: EIP-7702 deployed wallet/contract) implements x402x settlement extension methods. Can be used for pre-launch checks, health checks, and canary rollouts.

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("Recipient does not implement any x402x settlement method. Please confirm EIP-7702 integration.");
}

How to understand settle detection (implementation highlights)

Settle methods are recognized by function selectors (via ERC-165 capability exposure or static bytecode analysis):
- settleWithPermit → 0x02ccc23e
- settleWithERC3009 → 0x1fe200d9
- settleWithPermit2 → 0xa7fcafbb
We recommend using the EIP-7702 account model to deploy an extension contract for the recipient address, so settlement can be performed across authorization methods.

Detection details

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

Proxy contracts: automatically read the implementation address (EIP-1967 storage slot / UUPS proxiableUUID(), etc.)

Recommended usage

Warm up on startup: detector.initialize([USDC, DAI, ...])
Choose a recommended type: detector.getRecommendedMethod(token)
For non-standard proxies, manually verify implementation address

API reference (condensed)

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[] };
}

For more types and return structures, see:

Parameters: /en/parameters-responses/detector/parameters
Responses: /en/parameters-responses/detector/responses

Performance and optimization

Warm up hot tokens: initialize([tokens]) on service startup
Parallel detection: prefer initialize for batch parallel detection
Detect on demand: slow the first time, fast afterwards (cache hits)
Periodic refresh: re-detect popular tokens on a schedule

Resources

Source: https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-detector
Issues: https://github.com/WTFLabs-WTF/x402x/issues

​Overview

​Key features

​Install

​Quick start

​Examples

​Detection details

​Recommended usage

​API reference (condensed)

​Performance and optimization

​Resources