단위 테스트는 모두 성공하지만, 통합 테스트는 실패할 수 있습니다. x402의 함정은 거의 모두 경계 조건에 있습니다: 402 응답 헤더는 전송되었지만 브라우저에서 읽을 수 없음(누락된 CORS 노출 헤더), 서명 계산은 정확했지만 facilitator가 거부함(nonce 중복 / 금액 단위 오류), 자금은 도착했지만 장부가 맞지 않음(잘못된 대조 소스 사용). 이 도구는 「무료 탐지 → 402 → 서명 기반 결제 → 데이터 수신 → 체인상 대조」라는 5단계에 따라, 한 번에 실행 가능한 통합 테스트 스크립트와 각 단계별 「기대값 + 일반적인 실패 원인」이 포함된 체크리스트를 생성합니다.
—
—
| 현상 | 실제 원인 | 수정 방법 |
|---|---|---|
| 패킷 캡처 시 402 응답이 보이지만, JS에서 헤더를 읽을 수 없습니다. | 설정되지 않음 Access-Control-Expose-Headers | payment-required 등 사용자 정의 헤더를 노출 목록에 추가하세요 |
| facilitator에서 invalid nonce 오류 보고 | nonce 재사용 또는 서명 도메인과 체인 ID 불일치 | | 매번 임의의 nonce를 새로 생성; domain의 chainId를 확인하세요 |
| facilitator에서 amount mismatch 오류 보고 | 금액 단위 오류(USDC는 6자리 소수점) | 0.01 USDC = 10000이며, 1e16이 아님 | |
| 구매자의 가스 잔고가 없어도 결제 가능합니다(정상 동작입니다). | EIP-3009 transferWithAuthorization facilitator가 가스비를 대신 지불함 | | 구매자는 단지 USDC를 보유하기만 하면 됩니다. |
| 자금이 도착했지만 대조가 맞지 않음 | 체인 상 이벤트가 아닌 플랫폼 자체 기록을 기준으로 정산합니다. | 체인상 Transfer 이벤트만 인식하며, 허용 오차는 ±$0.02 | |
| 계속 입금되지 않음 | 정산 시작 기준 금액에 도달하지 않음 / 아직 정산일이 아님 | 자연월 집계, 익월 10일 정산, 최소 $50부터 정산 | |
| 헬스 체크에서 엔드포인트를 비활성 상태로 잘못 판단함 | MCP 엔드포인트가 SSE를 반환하지만 클라이언트에서 JSON 파싱에 실패함 | HTTP 상태 코드만으로 판단하며, 200과 402 모두 정상 작동으로 간주함 |
1 · 402 응답이 전송되었지만 브라우저에서 읽을 수 없습니다.패킷 캡처로 응답 헤더는 확인 가능하지만 JS 내에서는 접근 불가 — 사용자 정의 응답 헤더는 명시적으로 추가되어야 함 Access-Control-Expose-Headers그렇지 않으면 브라우저가 보안 정책에 따라 요청을 직접 차단합니다.
2 · 헬스 체크 오진.JSON 클라이언트로 SSE를 반환하는 MCP 엔드포인트를 점검하면 항상 '비활성'으로 판정됨; 올바른 방법은 HTTP 상태 코드만 확인하는 것으로, 200과 402 모두 '활성'으로 간주함.
3 · 금액 단위.USDC는 소수점 이하 6자리이며, 0.01은 10000으로 작성해야 함; 1e16으로 작성하면 facilitator에서 즉시 거부되며, 오류 메시지는 단위 오류를 명시하지 않음
4 · 대조는 블록체인 상의 거래만 인정합니다.플랫폼 자체 기록은 프로세스 재시작 또는 메모리 내 오래된 값 덮어쓰기 등으로 인해 부정확할 수 있으므로, 대조는 반드시 블록체인 상의 Transfer 이벤트를 기준으로 해야 함.