SIWX 替代了 API Key。你不需要传
X-API-KEY,而是在每个请求中传 Authorization: SIWX <token>。网关实时验证签名并检查是否有有效的 x402 订阅。工作原理
与传统的 challenge/response 流程不同,SIWX 是无状态且自包含的。客户端在本地构造并签名消息,然后附加到每个请求上。分步说明
- 构造 EIP-4361 消息,包含钱包地址、domain、nonce 和过期时间
- 用钱包私钥签名消息
- 编码为 SIWX token:
base64(message).signature - 附加到每个 API 请求:
Authorization: SIWX <token> - 网关验证签名并检查该钱包是否有有效的 x402 订阅
- 验证通过后,请求正常处理(等同于 API Key 认证)
Token 格式
必填字段
过期时间由客户端设置。你可以签署有效期为几分钟、几小时或几天的消息。更长的有效期意味着更少的重签,但更短的有效期更安全。
支持的链
前提条件
SIWX 认证需要与钱包地址关联的有效 x402 订阅。没有订阅时,网关会拒绝请求并返回错误。 获取订阅:使用示例
cURL
SDK
CLI
使用钱包登录后,CLI 会自动使用 SIWX:SIWX 与 API Key 对比
安全注意事项
- 无状态:没有服务端会话。每个请求独立验证。
- 过期控制:客户端通过
Expiration Time字段控制 token 有效期。过期 token 会被拒绝。 - 域名绑定:消息包含
api.chainstream.io作为域名。为其他域名的签名会被拒绝。 - 无私钥泄露:钱包只签署明文消息 — 私钥永远不会被传输。
- 订阅检查:即使签名有效,如果钱包没有有效的 x402 订阅,请求也会被拒绝。

