web3-x402

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web3 x402

An alternative authentication and billing layer for the

web3-tools

skill. If you have an

X-API-KEY

, the

web3-tools

skill alone is sufficient. If you don't (e.g., autonomous agents), use this skill alongside

web3-tools

— this skill handles wallet-based auth and USDC payments, while

web3-tools

provides the API specs and parameters.

这是

web3-tools

技能的替代认证与结算层。如果你拥有

X-API-KEY

，单独使用

web3-tools

技能即可。如果没有（例如自主Agent），请将此技能与

web3-tools

配合使用——本技能负责基于钱包的认证和USDC支付，而

web3-tools

提供API规范和参数。

When to Use

使用场景

Calling Nodit APIs without an API key (wallet + USDC only)
SIWX authentication (SIWE for EVM, SIWS for Solana)
Credit mode: pre-charge USDC → off-chain credit deduction per request
PPU mode: per-request on-chain USDC settlement
Checking credit balance or transaction history
Understanding x402 pricing per API operation

无需API密钥调用Nodit API（仅使用钱包+USDC）
SIWX认证（EVM链使用SIWE，Solana链使用SIWS）
预充值模式：预先充值USDC → 每次请求从链下余额中扣除额度
按次付费（PPU）模式：每次请求在链上完成USDC结算
查询余额或交易历史
了解各API操作的x402定价

When NOT to Use

不适用场景

Querying blockchain data with a traditional API key → use
```
web3-tools
```
skill instead
Investment advice or token value speculation

使用传统API密钥查询区块链数据 → 请改用
```
web3-tools
```
技能
投资建议或代币价值投机

Constraints

约束条件

Do not give investment advice or speculate on token value
Use only data verifiable through the Nodit x402 proxy
Prefix responses with "According to the Nodit x402 Proxy," once
Ask the user if required context (address, chain, mode, etc.) is missing

不得提供投资建议或对代币价值进行投机性分析
仅使用可通过Nodit x402代理验证的数据
回复开头需添加一次“根据Nodit x402代理信息，”
若缺少必要上下文（地址、链、模式等），请询问用户

Mode Selection Guide

模式选择指南

mermaid

flowchart TD
    A[User request] --> B{Repeated API usage?<br/>Pre-charge preferred?}

    B -->|YES| C[Credit Mode<br/>1. SIWX auth → JWT<br/>2. Charge USDC → credits<br/>3. API calls deduct credits]

    B -->|NO / One-off| D[PPU Mode<br/>1. Send request without auth<br/>2. Receive 402 + payment terms<br/>3. Sign & pay per request]

    C --> E{Which API?}
    D --> E

    E -->|Indexed data<br/>balances, NFT, tokens, stats| F[Data API]
    E -->|Node calls<br/>eth_call, getBalance, etc.| G[Node API / JSON-RPC]

    style C fill:#2d6a4f,color:#fff
    style D fill:#7b2cbf,color:#fff
    style F fill:#1d3557,color:#fff
    style G fill:#6a040f,color:#fff

mermaid

flowchart TD
    A[用户请求] --> B{是否需要重复调用API？<br/>是否偏好预充值？}

    B -->|是| C[预充值模式<br/>1. SIWX认证 → 获取JWT<br/>2. 充值USDC → 获得额度<br/>3. API调用扣除额度]

    B -->|否 / 一次性调用| D[按次付费模式<br/>1. 无需认证发送请求<br/>2. 收到402响应及支付条款<br/>3. 签名并按请求支付]

    C --> E{选择哪种API？}
    D --> E

    E -->|索引数据<br/>余额、NFT、代币、统计信息| F[数据API]
    E -->|节点调用<br/>eth_call、getBalance等| G[节点API / JSON-RPC]

    style C fill:#2d6a4f,color:#fff
    style D fill:#7b2cbf,color:#fff
    style F fill:#1d3557,color:#fff
    style G fill:#6a040f,color:#fff

How to Use

使用步骤

Step 0: Confirm which wallet to use for payment

步骤0：确认用于支付的钱包

x402 requires a wallet with USDC to pay for API calls. Since this involves real funds, the user must explicitly choose which wallet to use.

Ask the user to provide their wallet address for x402 payment (EVM or Solana).

Look up the expected cost from

references/pricing-data-api.md

references/pricing-node-api.md

Show the wallet address and estimated cost: "Your asset will be charged approximately $XX USDC. May I proceed?"
Proceed to Step 1 only after the user grants permission.

x402要求钱包中持有USDC以支付API调用费用。由于涉及真实资金，用户必须明确选择使用的钱包。

请用户提供用于x402支付的钱包地址（EVM或Solana链）。

从

references/pricing-data-api.md

或

references/pricing-node-api.md

中查询预计费用。

向用户展示钱包地址和预估费用：“你的资产将被扣除约$XX USDC，是否继续？”
仅在用户确认后进入步骤1。

Step 1: Overview — Endpoints, URL patterns, 402 structure

步骤1：概述——端点、URL格式、402响应结构

Read

references/how-to-use.md

. It contains the Base URL, endpoint table, URL patterns, 402 response structure, payment-signature format, and business rules shared across all modes.

阅读

references/how-to-use.md

，其中包含所有模式通用的基础URL、端点表、URL格式、402响应结构、支付签名格式和业务规则。

Step 2: Mode-specific implementation guide

步骤2：特定模式实现指南

Read only the document for the relevant mode:

Credit mode →
```
references/credit-mode.md
```
— Full flow and code covering SIWX authentication (JWT issuance), credit charging, balance checking, and API calls
PPU mode →
```
references/ppu-mode.md
```
— Full flow and code covering receiving a 402 without authentication → generating a payment-signature → re-requesting

仅阅读对应模式的文档：

预充值模式 →
```
references/credit-mode.md
```
—— 包含SIWX认证（JWT签发）、预充值、余额查询和API调用的完整流程及代码
按次付费模式 →
```
references/ppu-mode.md
```
—— 包含无需认证发送请求→收到402响应→生成支付签名→重新发起请求的完整流程及代码

Step 3: Check supported chains

步骤3：查看支持的链

Read

references/supported-chains.md

to verify which chains and networks are available.

阅读

references/supported-chains.md

以确认可用的链和网络。

Step 4: Check pricing

步骤4：查看定价

Read

references/pricing-data-api.md

references/pricing-node-api.md

to find the credit cost and PPU price for the target operation.

阅读

references/pricing-data-api.md

或

references/pricing-node-api.md

以获取目标操作的预充值额度成本和按次付费价格。

Step 5: Look up the API spec

步骤5：查阅API规范

For request parameters and response schemas, refer to the

web3-tools

skill — the underlying APIs are the same. Use

web3-tools/references/quick-reference.md

to find the operationId, then read

web3-tools/references/spec/{operationId}.md

for the full spec.

关于请求参数和响应结构，请参考

web3-tools

技能——底层API是相同的。使用

web3-tools/references/quick-reference.md

找到operationId，然后阅读

web3-tools/references/spec/{operationId}.md

获取完整规范。