API 및 서비스 결제 (x402)

x402 작동 방식, 에이전트의 결제 처리 방법, 지원 네트워크 및 토큰

x402는 HTTP 상태 코드 402 Payment Required를 기반으로 구축된 결제 프로토콜입니다 — 1990년대부터 HTTP 스펙에 있었던 코드가 마침내 실제로 활용되고 있습니다. 에이전트가 구독이나 API 키 없이 요청별로 스테이블코인으로 API 접근 비용을 지불할 수 있게 합니다.

모의 데모

결제 흐름

1. 에이전트가 요청을 전송

   에이전트는 다른 API 호출과 마찬가지로 API 엔드포인트에 표준 HTTP 요청을 전송합니다.

2. 서버가 402 결제 필요로 응답

   데이터를 반환하는 대신 서버는 402 상태 코드와 함께 PAYMENT-REQUIRED 헤더에 결제 요건을 포함하여 응답합니다: 비용, 토큰 종류, 네트워크.

3. 에이전트가 결제

   에이전트의 지갑이 서명된 결제 페이로드를 구성하고 PAYMENT-SIGNATURE 헤더와 함께 요청을 재전송합니다. 사람의 승인이 필요하지 않습니다.

4. 서버가 데이터를 전달

   서버는 퍼실리테이터를 통해 결제를 검증하고 온체인에서 정산한 후 요청된 데이터를 반환합니다. 전체 흐름이 몇 초 내에 완료됩니다.

자금이 있는 지갑을 가진 에이전트는 사전 관계나 계정 없이 x402 지원 API를 이용할 수 있습니다.

x402 더 알아보기 →

x402 요청 처리

CDP Agentic Wallet

CDP Agentic Wallet 스킬이 설치된 경우 에이전트가 x402 결제를 자동으로 처리합니다:

Terminal

npx skills add coinbase/agentic-wallet-skills

search-for-service 스킬로 이용 가능한 서비스를 검색합니다:

Terminal

npx awal@latest x402 bazaar search "weather forecast"

pay-for-service 스킬로 유료 서비스를 호출합니다:

Terminal

npx awal@latest x402 pay https://example.com/api/weather \
  -X POST \
  -d '{"query": "New York"}'

또는 에이전트에게 직접 프롬프트합니다:

Find APIs for sentiment analysis
Call that weather API and get the forecast for New York

search-for-service와 pay-for-service 스킬이 검색, 결제, 재시도를 처리합니다.

CDP Agentic Wallet 스킬 →

Sponge Wallet

Sponge Wallet에는 서비스를 검색하고 결제를 자동으로 처리하는 내장 x402 프록시가 있습니다:

1단계 — 서비스 검색:

Terminal

curl "https://api.wallet.paysponge.com/api/discover?query=weather+forecast" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.1"

2단계 — 서비스 세부 정보 조회 (필수 — 건너뛰지 마세요):

Terminal

curl "https://api.wallet.paysponge.com/api/discover/{serviceId}" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.1"

baseUrl, 엔드포인트 경로, 파라미터, 가격이 반환됩니다.

3단계 — 서비스 호출 (결제 자동 처리):

Terminal

curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://{baseUrl}/{endpointPath}",
    "method": "POST",
    "body": { "query": "New York" },
    "preferred_chain": "base"
  }'

Sponge Wallet이 402를 감지하고 지갑에서 USDC로 결제한 후 API 응답을 반환합니다.

Sponge Wallet 문서 →

오류 처리 및 재시도

상태	의미	처리 방법
402	결제 필요	PAYMENT-REQUIRED 헤더를 파싱하고 결제
402 + X-Payment-Error	결제 거부	지갑 잔액과 토큰 승인 확인
408	결제 시간 초과	동일하거나 더 높은 결제 금액으로 재시도
429	속도 제한	지정된 지연 후 백오프 및 재시도

CDP Agentic Wallet pay-for-service 스킬과 Sponge Wallet의 x402 프록시가 재시도를 자동으로 처리합니다. 커스텀 클라이언트를 구축하는 경우 PAYMENT-REQUIRED 헤더를 파싱하고, 서명된 페이로드를 구성하고, PAYMENT-SIGNATURE 헤더와 함께 재시도합니다.

Bankr을 사용하는 경우 별도 설정이 필요하지 않습니다. 직접 프롬프트하면 됩니다:

Get the current ETH price from a paid data source
Find a weather API and get the forecast for New York
Get the token balances for 0xYourAddress on Base

Bankr이 서비스 검색, 결제, 데이터 추출을 자동으로 처리합니다.

영상 튜토리얼

관련 항목

결제 수락

자신의 엔드포인트를 게이팅하고 다른 에이전트에게 요청별 요금을 청구합니다.

x402 클라이언트-서버 모델

퍼실리테이터 엔드포인트와 프로토콜 주소입니다.