跳转到主要内容
Sign-In with X (SIWX) 允许你在每个 API 请求中通过钱包签名进行认证 — 无需 API Key 或 OAuth Token。这是为拥有链上钱包并通过 x402 支付 购买了订阅的 AI Agent 设计的。
SIWX 替代了 API Key。你不需要传 X-API-KEY,而是在每个请求中传 Authorization: SIWX <token>。网关实时验证签名并检查是否有有效的 x402 订阅。

工作原理

与传统的 challenge/response 流程不同,SIWX 是无状态且自包含的。客户端在本地构造并签名消息,然后附加到每个请求上。

分步说明

  1. 构造 EIP-4361 消息,包含钱包地址、domain、nonce 和过期时间
  2. 用钱包私钥签名消息
  3. 编码为 SIWX tokenbase64(message).signature
  4. 附加到每个 API 请求Authorization: SIWX <token>
  5. 网关验证签名并检查该钱包是否有有效的 x402 订阅
  6. 验证通过后,请求正常处理(等同于 API Key 认证)

Token 格式

消息遵循 EIP-4361 标准:

必填字段

过期时间由客户端设置。你可以签署有效期为几分钟、几小时或几天的消息。更长的有效期意味着更少的重签,但更短的有效期更安全。

支持的链

前提条件

SIWX 认证需要与钱包地址关联的有效 x402 订阅。没有订阅时,网关会拒绝请求并返回错误。 获取订阅:
详见 x402 支付

使用示例

cURL

SDK

CLI

使用钱包登录后,CLI 会自动使用 SIWX:

SIWX 与 API Key 对比

安全注意事项

  • 无状态:没有服务端会话。每个请求独立验证。
  • 过期控制:客户端通过 Expiration Time 字段控制 token 有效期。过期 token 会被拒绝。
  • 域名绑定:消息包含 api.chainstream.io 作为域名。为其他域名的签名会被拒绝。
  • 无私钥泄露:钱包只签署明文消息 — 私钥永远不会被传输。
  • 订阅检查:即使签名有效,如果钱包没有有效的 x402 订阅,请求也会被拒绝。