x402lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

x402lint

Validate and create x402 payment configurations. The x402 protocol defines how HTTP 402 responses communicate payment requirements to clients.

For full protocol details, field rules, registries, and error codes, read references/protocol-spec.md.

验证并创建x402支付配置。x402协议定义了HTTP 402响应如何向客户端传达支付要求。

如需完整的协议细节、字段规则、注册表和错误码，请阅读references/protocol-spec.md。

Workflow

工作流程

Determine task type: Validating an existing config? -> Follow "Validation" below Creating a new config? -> Follow "Creation" below Debugging a failing config? -> Follow "Debugging" below

确定任务类型： 验证现有配置？ -> 遵循下方的「验证」流程 创建新配置？ -> 遵循下方的「创建」流程 调试失败的配置？ -> 遵循下方的「调试」流程

Validation

验证

Validate using the

x402lint

SDK in the project at

packages/x402lint/

typescript

import { check } from './packages/x402lint/src/index'

const result = check({
  body: configObject,           // or parse from header
  headers: { 'payment-required': base64String }
})

// result.valid        - boolean
// result.errors       - ValidationIssue[] (blocking)
// result.warnings     - ValidationIssue[] (non-blocking)
// result.normalized   - canonical v2 shape
// result.summary      - display-ready per-accept entries with registry data

For strict mode (warnings become errors):

check(response, { strict: true })

Also available:

validate(input)

for raw config objects,

extractConfig(response)

for parsing HTTP responses.

使用项目中

packages/x402lint/

路径下的

x402lint

SDK进行验证。

typescript

import { check } from './packages/x402lint/src/index'

const result = check({
  body: configObject,           // or parse from header
  headers: { 'payment-required': base64String }
})

// result.valid        - 布尔值
// result.errors       - 验证问题数组（阻塞性）
// result.warnings     - 验证问题数组（非阻塞性）
// result.normalized   - 标准v2格式
// result.summary      - 可直接展示的、包含注册表数据的每个accept条目

如需严格模式（警告将变为错误）：

check(response, { strict: true })

还提供以下方法：

validate(input)

用于验证原始配置对象，

extractConfig(response)

用于解析HTTP响应。

Creation

创建

When creating an x402 config, always produce v2 format. Template:

json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "<CAIP-2 identifier>",
      "amount": "<atomic units as string>",
      "asset": "<token contract address>",
      "payTo": "<recipient address with proper checksum>",
      "maxTimeoutSeconds": 300
    }
  ],
  "resource": {
    "url": "<the protected resource URL>",
    "method": "GET"
  }
}

创建x402配置时，请始终使用v2格式。模板如下：

json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "<CAIP-2 identifier>",
      "amount": "<atomic units as string>",
      "asset": "<token contract address>",
      "payTo": "<recipient address with proper checksum>",
      "maxTimeoutSeconds": 300
    }
  ],
  "resource": {
    "url": "<the protected resource URL>",
    "method": "GET"
  }
}

Critical rules when generating configs

生成配置的关键规则

amount
: Always a string of digits in atomic units (e.g.,
```
"1000000"
```
for 1 USDC with 6 decimals). Never use decimal notation.
network
: Always CAIP-2 format (
```
namespace:reference
```
). Use registry from protocol-spec.md. Never use simple names like
```
"base"
```
.
EVM
payTo
/
asset
: Use EIP-55 checksummed addresses (mixed-case). All-lowercase is valid but not recommended.
Solana
payTo
/
asset
: Use base58 addresses (32-44 characters).
maxTimeoutSeconds
: Always include; positive integer. 300 is a safe default.
resource
: Always include with at least a
```
url
```
.

amount
：必须是原子单位的纯数字字符串（例如，对于6位小数的1 USDC，使用
```
"1000000"
```
）。请勿使用小数表示法。
network
：必须使用CAIP-2格式（
```
namespace:reference
```
）。请使用protocol-spec.md中的注册表。请勿使用
```
"base"
```
这类简单名称。
EVM
payTo
/
asset
：使用符合EIP-55规范的校验和地址（大小写混合）。全小写地址有效，但不推荐使用。
Solana
payTo
/
asset
：使用base58格式的地址（长度32-44个字符）。
maxTimeoutSeconds
：必须包含该字段；值为正整数。300是安全的默认值。
resource
：必须包含该字段，且至少指定
```
url
```
。

Common network + asset combinations

常见网络+资产组合

Base (USDC):

json

{ "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }

Base Sepolia testnet (USDC):

json

{ "network": "eip155:84532", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e" }

Avalanche (USDC):

json

{ "network": "eip155:43114", "asset": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E" }

Solana Mainnet (USDC):

json

{ "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }

Base (USDC):

json

{ "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }

Base Sepolia testnet (USDC):

json

{ "network": "eip155:84532", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e" }

Avalanche (USDC):

json

{ "network": "eip155:43114", "asset": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E" }

Solana Mainnet (USDC):

json

{ "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }

HTTP 402 endpoint pattern

HTTP 402端点示例

typescript

// Express/Node example
app.get('/api/premium', (req, res) => {
  // Check for valid payment proof in request...
  // If no payment, return 402:
  res.status(402).json({
    x402Version: 2,
    accepts: [{
      scheme: "exact",
      network: "eip155:8453",
      amount: "1000000",
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      payTo: "0xYourChecksummedAddress",
      maxTimeoutSeconds: 300
    }],
    resource: {
      url: "https://yourapi.com/api/premium",
      method: "GET"
    }
  })
})

Alternative: deliver via

Payment-Required

header with base64-encoded JSON body.

typescript

// Express/Node示例
app.get('/api/premium', (req, res) => {
  // 检查请求中的有效支付凭证...
  // 若未支付，返回402：
  res.status(402).json({
    x402Version: 2,
    accepts: [{
      scheme: "exact",
      network: "eip155:8453",
      amount: "1000000",
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      payTo: "0xYourChecksummedAddress",
      maxTimeoutSeconds: 300
    }],
    resource: {
      url: "https://yourapi.com/api/premium",
      method: "GET"
    }
  })
})

另一种方式：通过

Payment-Required

头传递base64编码的JSON内容。

Debugging

调试

When a config fails validation:

Run
```
check()
```
or
```
validate()
```
against the config
Inspect
```
result.errors
```
-- each has
```
code
```
,
```
field
```
,
```
message
```
, and optional
```
fix
```
Common issues and fixes:
- ```
INVALID_NETWORK_FORMAT
```
  : Use CAIP-2, e.g.,
```
"eip155:8453"
```
  not
```
"base"
```
- ```
INVALID_AMOUNT
```
  : Must be digit-only string in atomic units, not
```
"1.5"
```
  or
```
1000000
```
- ```
BAD_EVM_CHECKSUM
```
  : Fix address casing per EIP-55
- ```
MISSING_PAY_TO
```
  /
```
MISSING_ASSET
```
  : Required fields omitted
- ```
LEGACY_FORMAT
```
  : Config is v1; normalize to v2 with
```
normalize()
```
Apply the
```
fix
```
suggestion from each issue when available
Re-validate after fixes

当配置验证失败时：

对配置运行
```
check()
```
或
```
validate()
```
方法
检查
```
result.errors
```
-- 每个错误包含
```
code
```
、
```
field
```
、
```
message
```
字段，可选包含
```
fix
```
字段
常见问题及修复方案：
- ```
INVALID_NETWORK_FORMAT
```
  ：使用CAIP-2格式，例如
```
"eip155:8453"
```
  而非
```
"base"
```
- ```
INVALID_AMOUNT
```
  ：必须是原子单位的纯数字字符串，不能是
```
"1.5"
```
  或
```
1000000
```
  （数字类型）
- ```
BAD_EVM_CHECKSUM
```
  ：根据EIP-55规范修正地址大小写
- ```
MISSING_PAY_TO
```
  /
```
MISSING_ASSET
```
  ：遗漏了必填字段
- ```
LEGACY_FORMAT
```
  ：配置为v1版本；使用
```
normalize()
```
  方法将其标准化为v2版本
若每个问题提供了
```
fix
```
建议，请应用该建议
修复后重新验证