메인 콘텐츠로 건너뛰기
Sign-In with X (SIWX)는 모든 API 요청에서 지갑으로 메시지에 서명하여 ChainStream에 인증할 수 있게 합니다 — API Key나 OAuth 토큰이 필요 없습니다. x402 결제를 통해 구독을 구매한 온체인 지갑을 가진 AI 에이전트를 위해 설계되었습니다.
SIWX는 API Key를 대체합니다. X-API-KEY 대신 각 요청에 Authorization: SIWX <token>을 전달합니다. 게이트웨이는 서명을 검증하고 실시간으로 유효한 x402 구독을 확인합니다.

동작 원리

기존의 챌린지/응답 플로우와 달리, SIWX는 무상태이며 자체 완결적입니다. 클라이언트가 로컬에서 메시지를 구성하고 서명한 후 모든 요청에 첨부합니다.

단계별 설명

  1. EIP-4361 메시지 구성 — 지갑 주소, 도메인, 논스, 만료 시간 포함
  2. 지갑 프라이빗 키로 메시지 서명
  3. SIWX 토큰으로 인코딩: base64(message).signature
  4. 모든 API 요청에 첨부: Authorization: SIWX <token>
  5. 게이트웨이가 서명을 검증하고 지갑에 활성 x402 구독이 있는지 확인
  6. 유효한 경우 요청이 정상적으로 처리됨 (API Key 인증과 동일)

토큰 형식

메시지는 EIP-4361 표준을 따릅니다:

필수 필드

만료 시간은 클라이언트가 설정합니다. 몇 분, 몇 시간, 또는 며칠 동안 유효한 메시지에 서명할 수 있습니다. 만료가 길수록 재서명이 적지만, 짧을수록 더 안전합니다.

지원 체인

사전 요구사항

SIWX 인증에는 지갑 주소에 연결된 활성 x402 구독이 필요합니다. 구독이 없으면 게이트웨이가 오류와 함께 요청을 거부합니다. 구독을 받으려면:
자세한 내용은 x402 결제를 참고하세요.

사용 예시

cURL

SDK

CLI

CLI는 지갑으로 로그인하면 자동으로 SIWX를 사용합니다:

SIWX vs API Key

보안 고려사항

  • 무상태: 서버 측 세션이 없습니다. 각 요청이 독립적으로 검증됩니다.
  • 만료: 클라이언트가 Expiration Time 필드를 통해 토큰 수명을 제어합니다. 만료된 토큰은 거부됩니다.
  • 도메인 바인딩: 메시지에 api.chainstream.io가 도메인으로 포함됩니다. 다른 도메인의 서명은 거부됩니다.
  • 프라이빗 키 미노출: 지갑은 평문 메시지에만 서명하며 — 프라이빗 키는 전송되지 않습니다.
  • 구독 확인: 유효한 서명이 있어도 지갑에 활성 x402 구독이 없으면 요청이 거부됩니다.