跳轉到主要內容
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 訂閱,請求也會被拒絕。