x402 v2 유료 API 도입 전 확인 조건

짙은 회색 스웨터를 입은 남성이 서버 랙 선반에 놓인 태블릿 화면을 살펴보고 있다.

 

당신이 유료 API에 결제를 붙이고 있다면, 결제 승인 검증에 성공했다는 이유만으로 유료 본문을 내보내서는 안 됩니다. 이 실습의 기본 승인 흐름에서는 정산 성공을 확인한 뒤 본문을 전달합니다. 먼저 Base Sepolia 테스트넷에서 결제 조건 선택부터 실제 전송 내역 확인까지 점검합니다.

 

승인 확인과 입금 확인을 나누는 이유

인조이스의 원문 기사는 API 요청에 결제를 연결하는 과정을 Node.js 예제로 설명합니다. 결제 정보가 없는 요청에 서버가 HTTP 402와 결제 조건을 보내면, 클라이언트는 허용된 조건을 골라 결제 승인을 서명하고 다시 요청합니다. 체인·토큰·금액·수취인을 제한해 의도한 조건에만 서명하도록 만드는 방식입니다.

예제 가격은 호출당 0.001 USDC이며, 인조이스의 원문 기사에 표시된 확인일은 2026-10-28입니다. USDC의 소수 자릿수 6자리를 적용하면 최소 단위는 1000입니다. 서버에 설정한 가격과 전달받은 결제 조건의 금액을 이 기준으로 대조할 수 있습니다.

결제 검증과 정산을 맡는 facilitator의 /verify는 승인이 유효한지 검사하며 온체인 상태를 바꾸지 않습니다. 따라서 /settle의 정산 결과를 따로 확인해야 합니다. 검증이나 정산이 실패하거나 성공을 확인하지 못하면 유료 본문을 차단하는 것이 이 실습의 원칙입니다.

 

준비, 402 결제 요청과 서명 재요청, 조건 선택, 거래 해시로 정산 검증, 전환 점검을 정리한 인포그래픽

 

x402 실습 자료에서 확인할 내용

인조이스의 원문 기사에는 v1과 v2의 헤더·본문 구조 비교, 서버와 클라이언트 예제, 결제 조건을 대조할 표가 있습니다. 당신이 기존 구현을 옮기는 중이라면 헤더 이름만 바꿔서는 맞지 않는 데이터 구조를 확인하는 데 도움이 됩니다.

예제의 검증 범위는 타입 검사와 모의 결제 흐름까지이며 실제 테스트넷 송금 완료를 확인한 예제는 아니므로, 안내된 실행 절차와 공식 문서를 바탕으로 온체인 결과를 직접 확인해야 합니다.

 

인조이스에서 전체 내용 확인하기

 

성공 응답을 받았을 때 대조할 항목

테스트 결제 뒤 성공 응답을 받은 상황이라면, 응답의 성공 표시와 수취 내역을 나눠 차례로 확인할 수 있습니다. 거래 영수증의 성공 상태만으로는 지정한 수취인에게 USDC가 전달됐는지까지 알 수 없습니다.

1. 정산 응답의 거래 해시로 거래 영수증을 조회하고, 조회에 사용하는 RPC의 Chain ID가 허용한 체인과 같은지 확인합니다.
2. 거래 영수증이 성공 상태인지, 전송 이벤트를 발생시킨 주소가 해당 체인의 공식 USDC 컨트랙트인지 대조합니다.
3. Transfer 이벤트의 보내는 주소·받는 주소·금액이 결제자·설정한 수취 주소·요구한 최소 단위 금액과 일치하는지 확인합니다.

이 예제에서는 전송 금액을 최소 단위 1000과 비교합니다. 금액만 맞는 거래를 확인하는 데서 멈추지 않고, 허용한 체인에서 정해진 상대에게 보낸 결제인지까지 확인하는 점검 방식입니다.

 

개발 환경과 운영 전환을 먼저 구분할 대상

당신이 API를 수정할 수 있는 개발 환경과 테스트 지갑을 갖췄다면 실습을 진행할 수 있습니다. 예제의 기준은 Node.js 22와 x402 SDK 2.28.0입니다. 결제를 받을 EVM 지갑 주소와 별도의 결제용 테스트 지갑을 준비하는 구성이며, 첫 실행은 Base Sepolia에서 진행하도록 안내합니다.

Base Sepolia 테스트 USDC에는 금융 가치가 없습니다. 같은 지갑 주소라도 체인이 달라지면 잔액이 별개이므로, 테스트넷 정산을 실제 매출로 기록해서는 안 됩니다.

실제 자산 결제로 옮기려는 단계라면 테스트용 최소 구성이라는 범위를 먼저 확인할 필요가 있습니다. 운영 배포 전에는 의존성 보안 경고, 중복 요청 처리, facilitator 인증과 실제 정산을 검증해야 합니다. 테스트 성공만으로 운영 준비가 끝났다고 판단할 수는 없습니다.

 

창가에서 여성이 평평하게 펼친 노트북으로 입력하고 있으며, 화면에는 목록과 두 경로가 합쳐지는 흐름도가 보인다.

 

키 보관과 재시도에서 남는 의문

수취 서버에도 지갑 개인키가 필요한가요?

이 예제의 수취 서버에는 공개 수취 주소만 넣습니다. 결제 승인에 사용하는 개인키는 클라이언트 프로세스에서만 읽도록 구성합니다.

PAYMENT-RESPONSE가 없으면 새로 결제해도 되나요?

먼저 기존 요청의 정산 상태를 확인해야 합니다. 응답이 사라지거나 시간이 초과되면 정산 결과를 알 수 없는 상태일 수 있으므로, 새 결제 승인부터 만드는 순서로 처리해서는 안 됩니다.

AI 에이전트의 총지출도 자동으로 제한되나요?

이 예제는 개별 요청의 결제 조건만 제한합니다. 반복 호출로 쌓이는 지출을 관리하려면 별도의 예산 정책이 필요합니다.

 

실습을 시작한다면 Circle Testnet Faucet에서 Base Sepolia를 선택하고, 결제용 테스트 지갑 주소로 테스트 USDC를 요청하는 것부터 진행할 수 있습니다. 인조이스의 원문 기사에서 준비 절차와 실행 순서를 확인하세요.

 

x402 결제 2026 v2 구현과 정산 검증 - Injoys

 

이 글은 인조이스(injoys.com)가 운영하는 채널의 도움을 받아 작성했습니다. 원문과 출처는 위 링크에서 확인할 수 있습니다.