agentkit-x402

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using AgentKit as an Agent

作为Agent使用AgentKit

This skill is for AI agents that interact with websites and APIs protected by x402 + AgentKit. It tells you how to prove you are backed by a real human so you can get free or discounted access instead of paying.

本技能适用于与受x402 + AgentKit保护的网站和API交互的AI Agent，教你如何证明自身有真实人类背书，从而获得免费或折扣访问权限，无需付款。

Critical Rule: Always Check for AgentKit Before Paying

关键规则：付款前务必检查是否存在AgentKit

When you receive a

402 Payment Required

response, do not immediately proceed to payment. First inspect the response for an

agentkit

extension. If one is present, attempt the AgentKit authentication flow below. Only fall back to payment if:

There is no
```
agentkit
```
extension in the 402 response
Your AgentKit authentication attempt fails and the server requires payment
You have exhausted your free-trial uses

当你收到

402 Payment Required

响应时，不要直接进入付款流程。首先检查响应中是否包含

agentkit

扩展。如果有，先尝试下方的AgentKit认证流程。仅在以下情况才 fallback 到付款流程：

402响应中不存在
```
agentkit
```
扩展
你的AgentKit认证尝试失败，服务器要求付款
你已用完免费试用次数

Wallet Types

钱包类型

Your wallet determines how you sign the challenge. There are two types:

你的钱包类型决定了签名挑战的方式，共分为两类：

EOA (Externally Owned Account)

EOA（外部拥有账户）

A standard wallet where you directly hold the private key (e.g. a raw private key, a mnemonic-derived wallet).

Signature type:
```
eip191
```
How to sign: Use
```
personal_sign
```
(EIP-191) to sign the SIWE message
Example:
```
wallet.signMessage(siweMessage)
```

你直接持有私钥的标准钱包（例如原始私钥、助记词派生的钱包）。

签名类型：
```
eip191
```
签名方式： 使用
```
personal_sign
```
（EIP-191）签名SIWE消息
示例：
```
wallet.signMessage(siweMessage)
```

Smart Contract Wallet (SCW)

智能合约钱包（SCW）

A wallet where the "account" is a smart contract and signing is done by an underlying owner key. The server verifies your signature on-chain via the contract's

isValidSignature

method (ERC-1271).

Examples: Coinbase Smart Wallet, Safe, any ERC-4337 account.

Signature type:
```
eip1271
```
How to sign: Sign the SIWE message using the wallet's SDK or internal signer. The signature format depends on the wallet implementation — use whatever the wallet SDK provides.

Example (Coinbase CDP):

account.signMessage({ message: siweMessage })

If you are unsure which type your wallet is: if you created it from a private key or mnemonic, it is an EOA. If you created it through a wallet SDK (Coinbase CDP, Safe SDK, etc.), it is likely an SCW.

这类钱包的“账户”是一个智能合约，签名由底层的所有者密钥完成。服务器会通过合约的

isValidSignature

方法（ERC-1271）链上验证你的签名。

示例：Coinbase Smart Wallet、Safe、任意ERC-4337账户。

签名类型：
```
eip1271
```
签名方式： 使用钱包的SDK或内部签名器对SIWE消息进行签名。签名格式取决于钱包的实现——直接使用钱包SDK返回的结果即可。

示例（Coinbase CDP）：

account.signMessage({ message: siweMessage })

如果你不确定自己的钱包类型：如果你是通过私钥或助记词创建的钱包，就是EOA；如果你是通过钱包SDK（Coinbase CDP、Safe SDK等）创建的，大概率是SCW。

The AgentKit Flow

AgentKit使用流程

Step 1: Parse the 402 Response

步骤1：解析402响应

When you receive a

402 Payment Required

, look for the

agentkit

extension in the response body. The 402 response contains

x402

data with extensions. The

agentkit

extension looks like:

json

{
  "agentkit": {
    "info": {
      "domain": "api.example.com",
      "uri": "https://api.example.com/data",
      "version": "1",
      "nonce": "abc123",
      "issuedAt": "2025-01-01T00:00:00.000Z",
      "statement": "Verify your agent is backed by a real human"
    },
    "supportedChains": [
      { "chainId": "eip155:8453", "type": "eip191" },
      { "chainId": "eip155:8453", "type": "eip1271" }
    ],
    "schema": { ... }
  }
}

Key fields to extract:

info
— the challenge data you must sign
supportedChains
— which chains and signature types the server accepts
mode
(if present) — tells you the access policy:
```
free
```
,
```
free-trial
```
, or
```
discount
```

当你收到

402 Payment Required

响应时，在响应体中查找

agentkit

扩展。402响应包含带扩展的

x402

数据，

agentkit

扩展的格式如下：

json

{
  "agentkit": {
    "info": {
      "domain": "api.example.com",
      "uri": "https://api.example.com/data",
      "version": "1",
      "nonce": "abc123",
      "issuedAt": "2025-01-01T00:00:00.000Z",
      "statement": "Verify your agent is backed by a real human"
    },
    "supportedChains": [
      { "chainId": "eip155:8453", "type": "eip191" },
      { "chainId": "eip155:8453", "type": "eip1271" }
    ],
    "schema": { ... }
  }
}

需要提取的关键字段：

info
—— 你需要签名的挑战数据
supportedChains
—— 服务器接受的链和签名类型
mode
（如果存在） —— 告知访问策略：
```
free
```
、
```
free-trial
```
或
```
discount
```

Step 2: Pick a Chain and Signature Type

步骤2：选择链和签名类型

Match your wallet to one of the

supportedChains

entries:

Your wallet	Match `chainId`	Use `type`
EVM EOA	`eip155:*`	`eip191`
EVM Smart Contract	`eip155:*`	`eip1271`

Pick the entry that matches both your chain and wallet type.

将你的钱包与

supportedChains

中的条目匹配：

你的钱包类型	匹配 `chainId`	使用 `type`
EVM EOA	`eip155:*`	`eip191`
EVM 智能合约钱包	`eip155:*`	`eip1271`

选择同时匹配你的链和钱包类型的条目即可。

Step 3: Construct and Sign the SIWE/SIWS Message

步骤3：构造并签名SIWE/SIWS消息

Construct a SIWE (EIP-4361) message string from the challenge

info

fields. The format is a plain text string with this exact structure:

{domain} wants you to sign in with your Ethereum account:
{address}

{statement}

URI: {uri}
Version: {version}
Chain ID: {numericChainId}
Nonce: {nonce}
Issued At: {issuedAt}

Where

{numericChainId}

is extracted from the CAIP-2 chain ID (e.g.

eip155:8453

becomes

), and

{address}

must be EIP-55 checksummed.

If the challenge includes optional fields, append them in this order (only include lines for fields that are present):

Expiration Time: {expirationTime}
Not Before: {notBefore}
Request ID: {requestId}
Resources:
- {resources[0]}
- {resources[1]}

Full example:

api.example.com wants you to sign in with your Ethereum account:
0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Verify your agent is backed by a real human

URI: https://api.example.com/data
Version: 1
Chain ID: 8453
Nonce: abc123def
Issued At: 2025-01-01T00:00:00.000Z
Expiration Time: 2025-01-01T00:05:00.000Z
Request ID: req-456
Resources:
- https://api.example.com/tos

Important formatting rules:

There must be a blank line before and after the
```
{statement}
```
line
If there is no statement, there must be a single blank line between the address and
```
URI:
```
Each line ends with
```
\n
```
(LF, not CRLF)
No trailing newline after the last line

Then sign the message string:

typescript

// EOA — use personal_sign (EIP-191)
const signature = await wallet.signMessage(messageToSign)

// SCW — use the wallet SDK's signMessage
const signature = await smartWallet.signMessage({ message: messageToSign })

根据挑战的

info

字段构造SIWE（EIP-4361）消息字符串，格式为纯文本，需严格遵循以下结构：

{domain} wants you to sign in with your Ethereum account:
{address}

{statement}

URI: {uri}
Version: {version}
Chain ID: {numericChainId}
Nonce: {nonce}
Issued At: {issuedAt}

其中

{numericChainId}

是从CAIP-2链ID中提取的数值（例如

eip155:8453

对应

），

{address}

必须符合EIP-55校验和格式。

如果挑战包含可选字段，请按以下顺序追加（仅包含存在的字段对应的行）：

Expiration Time: {expirationTime}
Not Before: {notBefore}
Request ID: {requestId}
Resources:
- {resources[0]}
- {resources[1]}

完整示例：

api.example.com wants you to sign in with your Ethereum account:
0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Verify your agent is backed by a real human

URI: https://api.example.com/data
Version: 1
Chain ID: 8453
Nonce: abc123def
Issued At: 2025-01-01T00:00:00.000Z
Expiration Time: 2025-01-01T00:05:00.000Z
Request ID: req-456
Resources:
- https://api.example.com/tos

重要格式规则：

```
{statement}
```
行的前后必须各有一个空行
如果没有statement，地址和
```
URI:
```
之间必须有一个空行
每一行以
```
\n
```
结尾（LF，而非CRLF）
最后一行后不要加尾随换行符

然后对消息字符串进行签名：

typescript

// EOA — 使用personal_sign (EIP-191)
const signature = await wallet.signMessage(messageToSign)

// SCW — 使用钱包SDK的signMessage方法
const signature = await smartWallet.signMessage({ message: messageToSign })

Step 4: Send the Request

步骤4：发送请求

Base64-encode a JSON object containing the challenge

info

fields plus your

address

type

, and

signature

, and send it as the

agentkit

HTTP header:

typescript

const header = btoa(JSON.stringify({
  ...info,                               // all fields from the challenge
  address: walletAddress,
  chainId: "eip155:8453",               // from the supportedChains entry you picked
  type: "eip191",                        // "eip191" for EOA, "eip1271" for SCW
  signature: signature,                  // hex string from signing
}))

const response = await fetch("https://api.example.com/data", {
  headers: {
    "agentkit": header,
  },
})

If the server grants access (based on the mode), you will receive the resource directly — no payment needed.

If the server responds with another 402 or an error, fall back to the normal x402 payment flow.

将包含挑战

info

字段、你的

address

、

type

和

signature

的JSON对象进行Base64编码，作为

agentkit

HTTP头发送：

typescript

const header = btoa(JSON.stringify({
  ...info,                               // 挑战的所有字段
  address: walletAddress,
  chainId: "eip155:8453",               // 你选择的supportedChains条目中的chainId
  type: "eip191",                        // EOA填"eip191"，SCW填"eip1271"
  signature: signature,                  // 签名得到的十六进制字符串
}))

const response = await fetch("https://api.example.com/data", {
  headers: {
    "agentkit": header,
  },
})

如果服务器批准访问（基于mode），你将直接获得请求的资源——无需付款。

如果服务器返回另一个402或错误，请 fallback 到常规的x402付款流程。

Access Modes

访问模式

The

mode

field in the AgentKit extension tells you what to expect:

Mode	What it means
`free`	Human-backed agents always get free access
`free-trial`	First N requests are free, then you must pay (N is per human, not per agent)
`discount`	You get N% off the price (pay the discounted amount via x402)

For

discount

mode: send both the

agentkit

header and the x402 payment header, but pay the discounted price. The server will reconcile the underpayment using your human-backed status.

AgentKit扩展中的

mode

字段会告知你可享受的访问策略：

模式	含义说明
`free`	有人类背书的Agent始终可获得免费访问权限
`free-trial`	前N次请求免费，之后必须付款（N按人类用户计数，而非按Agent计数）
`discount`	你可享受N%的价格优惠（通过x402支付折扣后的金额）

对于

discount

模式：同时发送

agentkit

头和x402付款头，但仅支付折扣后的金额即可。服务器会根据你的人类背书身份核销差额。

Common Errors and How to Handle Them

常见错误及处理方案

"Agent is not registered in the AgentBook"

Your wallet address is not registered. You need to register first using the AgentKit CLI:

bash

npx @worldcoin/agentkit-cli register <your-wallet-address>

This opens a World ID verification flow that ties your wallet to an anonymous human identifier on-chain. Registration only needs to happen once per wallet.

你的钱包地址未注册，需要先通过AgentKit CLI完成注册：

bash

npx @worldcoin/agentkit-cli register <your-wallet-address>

该命令会打开World ID验证流程，将你的钱包与链上的匿名人类标识符绑定。每个钱包仅需注册一次。

"Signature verification failed"

Wrong signature type: Make sure
```
type
```
matches your wallet. Use
```
eip191
```
for EOA,
```
eip1271
```
for SCW.
Wrong message format: The SIWE message must follow the exact format described in Step 3. Pay close attention to blank lines around the statement and field ordering.
Wrong chain ID: The
```
chainId
```
in the payload must be CAIP-2 format (
```
eip155:8453
```
), but the SIWE message
```
chainId
```
field must be the numeric chain ID (
```
8453
```
).

签名类型错误： 确保
```
type
```
与你的钱包类型匹配，EOA用
```
eip191
```
，SCW用
```
eip1271
```
。
消息格式错误： SIWE消息必须严格遵循步骤3中描述的格式，特别注意statement前后的空行和字段顺序。
链ID错误： payload中的
```
chainId
```
必须是CAIP-2格式（
```
eip155:8453
```
），但SIWE消息中的
```
chainId
```
字段必须是数值型链ID（
```
8453
```
）。

"Invalid agentkit header: not valid base64"

Your header is not properly base64-encoded. Ensure you are encoding the full JSON string:

btoa(JSON.stringify(payload))

你的头没有正确进行Base64编码，确保你编码的是完整的JSON字符串：

btoa(JSON.stringify(payload))

。

"Message validation failed" / "issuedAt is too old"

The challenge has expired. Re-fetch the 402 response to get a fresh challenge (new nonce, new

issuedAt

) and sign again. Challenges expire after 5 minutes by default.

挑战已过期，重新请求402响应获取新的挑战（新的nonce、新的

issuedAt

）后重新签名即可。默认情况下挑战的有效期为5分钟。

"Unsupported chain namespace"

You are using a chain that the server does not support. Check

supportedChains

in the 402 response and pick a chain/type pair that matches your wallet.

你使用的链不在服务器支持范围内，检查402响应中的

supportedChains

，选择与你的钱包匹配的链/类型对即可。