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 訂閱,請求也會被拒絕。

