SIWX는 API Key를 대체합니다.
X-API-KEY 대신 각 요청에 Authorization: SIWX <token>을 전달합니다. 게이트웨이는 서명을 검증하고 실시간으로 유효한 x402 구독을 확인합니다.동작 원리
기존의 챌린지/응답 플로우와 달리, SIWX는 무상태이며 자체 완결적입니다. 클라이언트가 로컬에서 메시지를 구성하고 서명한 후 모든 요청에 첨부합니다.단계별 설명
- EIP-4361 메시지 구성 — 지갑 주소, 도메인, 논스, 만료 시간 포함
- 지갑 프라이빗 키로 메시지 서명
- SIWX 토큰으로 인코딩:
base64(message).signature - 모든 API 요청에 첨부:
Authorization: SIWX <token> - 게이트웨이가 서명을 검증하고 지갑에 활성 x402 구독이 있는지 확인
- 유효한 경우 요청이 정상적으로 처리됨 (API Key 인증과 동일)
토큰 형식
필수 필드
만료 시간은 클라이언트가 설정합니다. 몇 분, 몇 시간, 또는 며칠 동안 유효한 메시지에 서명할 수 있습니다. 만료가 길수록 재서명이 적지만, 짧을수록 더 안전합니다.
지원 체인
사전 요구사항
SIWX 인증에는 지갑 주소에 연결된 활성 x402 구독이 필요합니다. 구독이 없으면 게이트웨이가 오류와 함께 요청을 거부합니다. 구독을 받으려면:사용 예시
cURL
SDK
CLI
CLI는 지갑으로 로그인하면 자동으로 SIWX를 사용합니다:SIWX vs API Key
보안 고려사항
- 무상태: 서버 측 세션이 없습니다. 각 요청이 독립적으로 검증됩니다.
- 만료: 클라이언트가
Expiration Time필드를 통해 토큰 수명을 제어합니다. 만료된 토큰은 거부됩니다. - 도메인 바인딩: 메시지에
api.chainstream.io가 도메인으로 포함됩니다. 다른 도메인의 서명은 거부됩니다. - 프라이빗 키 미노출: 지갑은 평문 메시지에만 서명하며 — 프라이빗 키는 전송되지 않습니다.
- 구독 확인: 유효한 서명이 있어도 지갑에 활성 x402 구독이 없으면 요청이 거부됩니다.

