跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt

Use this file to discover all available pages before exploring further.

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 token：base64(message).signature
  4. 附加到每个 API 请求：Authorization: SIWX <token>
  5. 网关验证签名并检查该钱包是否有有效的 x402 订阅
  6. 验证通过后，请求正常处理（等同于 API Key 认证）

​
Token 格式

Authorization: SIWX base64(message).signature
消息遵循 EIP-4361 标准： 
api.chainstream.io wants you to sign in with your Ethereum account:
0xYourWalletAddress

Sign in to ChainStream API

URI: https://api.chainstream.io
Version: 1
Chain ID: 8453
Nonce: abc123def456
Issued At: 2026-03-26T10:00:00Z
Expiration Time: 2026-03-27T10:00:00Z

​
必填字段

字段说明
Domain必须为 api.chainstream.io
Address你的钱包地址（EVM 0x... 或 Solana base58）
URIhttps://api.chainstream.io
Version1
Nonce随机字符串（客户端生成，用于防重放）
Issued AtISO 8601 时间戳
Expiration TimeISO 8601 时间戳（超过此时间 token 将被拒绝）
过期时间由客户端设置。你可以签署有效期为几分钟、几小时或几天的消息。更长的有效期意味着更少的重签，但更短的有效期更安全。

​
支持的链

链地址格式签名验证方式
EVM（Base、Ethereum）0x 前缀，40 位十六进制EIP-191 personal_sign 恢复
SolanaBase58 编码，32-44 字符Ed25519 签名验证

​
前提条件

SIWX 认证需要与钱包地址关联的有效 x402 订阅。没有订阅时，网关会拒绝请求并返回错误。 获取订阅： 
# 通过 CLI（自动）
chainstream login
chainstream token info --chain sol --address So11111111111111111111111111111111111111112
# → 402 触发套餐选择 → x402 支付 → API Key 已保存

# 或通过直接 x402 购买
curl https://api.chainstream.io/x402/purchase?plan=nano
# → 按 x402 支付流程操作
详见 x402 支付。

​
使用示例

​
cURL

# 1. 构造并签名消息（使用你偏好的工具）
# 2. Base64 编码消息并附加签名
TOKEN="base64EncodedMessage.signatureHex"

# 3. 在任何 API 调用中使用
curl https://api.chainstream.io/v2/token/sol/So11111111111111111111111111111111111111112 \
  -H "Authorization: SIWX $TOKEN"

​
SDK

import { ChainStreamClient } from "@chainstream-io/sdk";

const cs = new ChainStreamClient({
  auth: {
    type: "siwx",
    address: "0xYourWalletAddress",
    signMessage: async (message: string) => {
      return await wallet.signMessage(message);
    },
  },
});

const token = await cs.token.getToken("So11111111111111111111111111111111111111112", "sol");

​
CLI

使用钱包登录后，CLI 会自动使用 SIWX： 
chainstream login
chainstream token info --chain sol --address So11111111111111111111111111111111111111112

​
SIWX 与 API Key 对比

SIWXAPI Key
请求头Authorization: SIWX <token>X-API-KEY: <key>
凭证管理无需存储 Key — 按需签名需要存储和保护 Key
前提条件钱包 + x402 订阅Dashboard 账号
适用场景拥有钱包的 AI Agent应用、脚本、MCP
Token 过期由客户端设置（每条消息）在 Dashboard 设置（或永不过期）

​
安全注意事项

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