x402 payment demo

Agent의 x402 결제

Base 메인넷에서 API 요청, 지갑 서명, 0.01 USDC 정산을 확인하는 데모.

결제 체험 결제 흐름

Bloom Agentic Payments Onchain 행사 이후 개인적으로 구현했습니다. Bloom 공식 서비스나 제휴 상품이 아닙니다.

01 · 전체 흐름

x402 결제 흐름

첫 요청은 결제 조건을 받습니다. 두 번째 요청은 지갑 서명을 포함합니다. 단계 선택 시 관련 명령으로 이동합니다.

02 · 역할과 준비물

참여자와 준비 사항

Agent, 지갑, 판매 API, Facilitator, Base의 역할을 구분합니다.

참여자	역할	준비물	오해하지 말 것
구매 Agent	조건 확인, 예산 판단, 지갑 요청, API 재호출	실제 HTTP·터미널 도구를 실행할 수 있는 환경	개인키 전체를 직접 받는 것이 필수는 아님
구매 지갑	자산 보유, 권한 검사, 승인·서명	Agent 연결, Base USDC, 필요 시 Base ETH 검증 조합: Binance Agentic Wallet	서명 성공은 정산 성공과 다름
판매 API	결제 조건 제시, Facilitator 호출, 결과 제공	공개 HTTPS, 가격, 수령 주소, 서버 설정	구매자 개인키 불필요. 단순 수령에는 판매 지갑 개인키도 불필요
Facilitator	결제 검증, 블록체인 거래 제출, 정산 결과 반환	지원 체인·방식과 판매자 측 인증 현재: Coinbase CDP	구매대금을 자기 자금으로 내는 주체가 아님
Base	계약 실행, USDC 이동, 거래 기록	USDC는 결제 토큰, ETH는 가스 자산	같은 주소여도 Ethereum 메인넷 잔액과 Base 잔액은 별개

03 · 실행 환경

지원 환경

터미널 실행 지원과 Binance 지갑·x402 결제 검증 여부는 별도 항목입니다. 일반 채팅창이나 기본 curl은 자동 결제를 수행하지 않습니다.

OpenClaw

exec/터미널 도구와 네트워크 권한이 활성화된 실행 환경.

직접 검증: OpenClaw + Binance Agentic Wallet

Hermes Agent

terminal toolset이 활성화된 실행 환경. 지갑 스킬·CLI 설치와 권한을 별도 확인해야 합니다.

Claude Code

로컬·서버 셸과 도구 권한을 사용할 수 있는 CLI 환경. 이 데모와의 지갑 결제 조합은 별도 검증 대상입니다.

Codex CLI

로컬·서버 터미널에서 명령을 실행할 수 있는 환경. 네트워크·승인 정책과 지갑 도구를 별도 구성해야 합니다.

공통 준비물

명령 실행 도구와 실행 권한
공식 스킬 설치용 Node.js 18+
Binance 계정과 앱의 MPC/Keyless Wallet
연결된 Agentic Wallet
그 지갑의 Base USDC
필요 시 최초 승인용 Base ETH
허용 가격·횟수·지출 정책

04 · 코드

요청과 응답

CDP SDK 1.57.1, x402 Express 2.28.0과 현재 서버 구현 기준. 실행 명령과 설명용 구조를 구분했습니다.

최초 요청

보내는 방향: 구매 Agent → 판매 API
목적: 보호된 리소스를 평범한 HTTP GET으로 요청합니다.
돈의 이동: 없음

실행 가능 · 현재 공개 API

curl -i https://x402-demo-production-19f3.up.railway.app/demo

일반 curl은 요청과 헤더 전송 도구일 뿐, 지갑 연결·preview·서명·자동 결제를 해주지 않습니다.

HTTP 402와 결제 조건

보내는 방향: 판매 API → 구매 Agent
목적: 가격·체인·토큰·수령 주소·방식을 표준 형식으로 제시합니다.
돈의 이동: 없음 · 402는 청구서이지 영수증이 아닙니다

실제 응답 형태

HTTP/2 402
PAYMENT-REQUIRED: <Base64로 인코딩된 x402 v2 JSON>
content-type: application/json

현재 PAYMENT-REQUIRED 디코딩 JSON 보기

2026-10-04 KST 배포 기준

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://x402-demo-production-19f3.up.railway.app/demo",
    "description": "x402 Agent payment proof of concept",
    "mimeType": ""
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x711affb5dBc344b7D7BeB54a9870824bc3eB7F5d",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "assetTransferMethod": "permit2"
      }
    }
  ],
  "extensions": {
    "…": "현재 응답에는 가스 후원·Bazaar·builder-code 메타데이터도 포함"
  }
}

결제 preview

보내는 방향: 구매 Agent → Binance Agentic Wallet
목적: 지갑이 조건·잔액·정책·승인 필요 여부를 서명 전에 점검합니다.
돈의 이동: 없음

실행 가능 · 공식 CLI

baw x402-payment preview --paymentRequirements '<PAYMENT-REQUIRED 값 또는 디코딩 JSON>' --json

응답 필드 예시 보기

설명용 예시 · 실제 값은 실행 시 달라짐

{
  "success": true,
  "data": {
    "paymentId": "<preview가 반환한 paymentId>",
    "options": [
      {
        "index": 1,
        "status": "READY_TO_SIGN",
        "scheme": "exact",
        "assetTransferMethod": "permit2",
        "binanceChainId": "8453",
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "tokenSymbol": "USDC",
        "amount": "0.01",
        "payTo": "0x711affb5dBc344b7D7BeB54a9870824bc3eB7F5d",
        "userWalletAddress": "<구매 지갑 Base 주소>",
        "currentBalance": "<조회 시점 잔액>",
        "needApproveFirst": true
      }
    ]
  }
}

index는 0이 아니라 1부터 시작하며, 서명할 때 preview가 반환한 값을 그대로 selectedIndex에 넣습니다. READY_TO_SIGN은 서명 가능 상태이지 입금 완료가 아닙니다.

최초 Permit2 승인 — 필요할 때만

보내는 방향: 구매 지갑 → Base의 USDC 컨트랙트
목적: USDC가 Permit2 컨트랙트에 토큰을 사용할 수 있는 ERC-20 allowance를 부여합니다.
돈의 이동: 상품대금은 아직 이동하지 않음 · 승인 거래 가스용 Base ETH는 소모될 수 있음

Binance x402 흐름에는 별도의 추정 승인 명령을 만들지 않습니다. 다음 단계의 x402-payment sign이 필요 시 승인 거래를 함께 전송하고 approveTxHash를 돌려줍니다.

실행 가능 · 승인 거래가 반환된 경우

baw wallet tx-history --tx <approveTxHash> --json

두 거래를 구분하세요. 승인 해시는 “USDC → Permit2 권한 설정”, 정산 해시는 “구매자 → 판매자 0.01 USDC 이동”입니다. 서로 다를 수 있습니다.

결제 서명

보내는 방향: 구매 Agent → 구매 지갑
목적: preview에서 선택한 정확한 조건에 대한 일회성 암호학적 허가를 만듭니다.
돈의 이동: 서명만으로 상품대금 이동은 확정되지 않음 · 필요 시 승인 거래는 전송될 수 있음

실행 가능 · 사용자 확인 후

baw x402-payment sign --paymentId <paymentId> --selectedIndex 1 --json

서명 응답 예시 보기

설명용 예시

{
  "success": true,
  "data": {
    "paymentHeaderName": "PAYMENT-SIGNATURE",
    "paymentHeaderValue": "<공개하거나 로그에 남기지 않는 일회성 값>",
    "approveTxHash": "<승인이 필요하면 거래 해시, 아니면 null>",
    "binanceChainId": "8453",
    "signatureExpiresAt": "<UTC epoch seconds>"
  }
}

서명은 잔액 보장·입금 완료·사람의 직접 확인을 뜻하지 않습니다. paymentHeaderValue는 일회성이며 페이지·로그·문서에 공개하지 않습니다.

서명을 붙여 API 재호출

보내는 방향: 구매 Agent → 판매 API
목적: 원래 요청에 지갑이 반환한 헤더 이름과 값을 그대로 붙입니다.
돈의 이동: 서버가 검증·정산에 성공하면 이 요청 중 0.01 USDC 이동

실행 가능 · 실제 서명은 절대 페이지에 입력하지 않음

curl -i \
  -H 'PAYMENT-SIGNATURE: <paymentHeaderValue>' \
  https://x402-demo-production-19f3.up.railway.app/demo

approveTxHash가 있으면 먼저 확정을 기다립니다. 정산 상태가 불명확하면 같은 서명을 반복하거나 새 서명으로 자동 재결제하지 않습니다.

판매 서버 → Facilitator

보내는 방향: 판매 API → Coinbase CDP Facilitator
목적: 구매자 서명을 검증하고, 서버가 정한 조건으로 정산을 요청합니다.
돈의 이동: verify 단계는 없음 · settle 성공 시 온체인 이동

현재 실행 코드

createX402Server({ environment: "production", payToConfig, routes })와 paymentMiddlewareFromHTTPServer가 JWT 생성과 verify/settle 통신을 처리합니다.

직접 REST 연동 시

POST /platform/v2/x402/verify 후 POST /platform/v2/x402/settle에 같은 구조를 보냅니다.

/verify · /settle 요청 구조 보기

설명용 구조 · 서명/JWT는 가림

{
  "x402Version": 2,
  "paymentPayload": "<구매자가 PAYMENT-SIGNATURE로 보낸 서명 데이터>",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000",
    "payTo": "0x711affb5dBc344b7D7BeB54a9870824bc3eB7F5d",
    "maxTimeoutSeconds": 300,
    "extra": {
      "assetTransferMethod": "permit2"
    }
  }
}

공식 SDK 방식 · 의사코드

import { generateJwt } from "@coinbase/cdp-sdk/auth";

const jwt = await generateJwt({
  apiKeyId: process.env.CDP_API_KEY_ID,
  apiKeySecret: process.env.CDP_API_KEY_SECRET,
  requestMethod: "POST",
  requestHost: "api.cdp.coinbase.com",
  requestPath: "/platform/v2/x402/verify",
  expiresIn: 120
});

서로 다른 두 인증: 구매 지갑 서명은 0.01 USDC 결제 허가이고, 판매 서버의 CDP JWT는 CDP API 호출 인증입니다. 서버는 구매자가 보낸 가격을 신뢰하지 않고 자기 paymentRequirements와 대조합니다.

정산 결과

보내는 방향: Facilitator ↔ Base 블록체인 → 판매 API
목적: 거래를 제출하고 체인 결과와 정산 거래 해시를 돌려줍니다.
돈의 이동: 성공하면 0.01 USDC가 구매자에서 판매자 주소로 이동

공식 SettlementResponse 형식에 맞춘 예시

{
  "success": true,
  "payer": "<검증된 구매 지갑 주소>",
  "transaction": "0x<정산 거래 해시>",
  "network": "eip155:8453"
}

Facilitator는 구매대금을 자기 자금으로 대신 내는 주체가 아닙니다. 검증·제출·결과 확인을 맡으며 직접 구현도 가능합니다.

최종 데이터와 결제 영수증

보내는 방향: 판매 API → 구매 Agent
목적: 유료 데이터를 반환하고 PAYMENT-RESPONSE로 정산 메타데이터를 전달합니다.
돈의 이동: 정산 성공 상태

현재 API 성공 본문

HTTP/2 200
PAYMENT-RESPONSE: <Base64 정산 결과>
content-type: application/json

{
  "message": "Agent가 실제 결제에 성공했습니다!",
  "demo": true
}

HTTP 200, 지갑 서명 성공, Facilitator 정산 성공은 서로 다른 상태입니다. 실제 성공 판정은 200 + PAYMENT-RESPONSE + 온체인 receipt + 예상 금액 이동을 함께 확인합니다.

05 · 개념

핵심 개념

Base64, 서명, Permit2, x402의 역할을 구분합니다.

Agentic Payment와 x402

Agentic Payment는 Agent가 위임받은 범위 안에서 구매·결제를 수행하는 행동입니다. x402는 HTTP 요청과 응답에서 가격·서명·영수증을 주고받는 통신 규칙입니다.

카드 기반 Agent 결제

카드 기반 Agent 결제도 Agentic Payment입니다. x402는 서비스가 공통 형식으로 결제 조건을 제시해 Agent와 API가 직접 상호운용하도록 돕습니다. 카드를 모두 대체한다는 뜻은 아닙니다.

회원가입과 로그인

건별 디지털 리소스 구매에서는 줄일 수 있습니다. 배송, 연령·신원 확인, 환불, 구독, 서비스 정책에 필요한 정보는 별개입니다.

결제 서명의 의미

특정 결제 조건에 대한 암호학적 허가 증거입니다. 잔액 보장, 입금 완료, 사람이 매번 화면을 직접 확인했다는 증거는 아닙니다.

개인키 관리

baw는 지갑에 서명을 요청하는 도구입니다. Binance MPC 지갑은 키를 분산 관리해 Agent에게 개인키 전체를 건네는 구조가 아닙니다. 확인하지 않은 키 조각의 구체적 저장 위치는 이 데모에서 추정하지 않습니다.

Base64, hash, signature

개념	무엇인가	되돌릴 수 있나
Base64	바이너리/문자를 안전한 문자로 표현	예 · 암호화 아님
Hash	데이터의 고정 길이 지문	일반적으로 원문 복원 불가
Signature	특정 키가 특정 데이터에 허가했음을 검증하는 값	원문 복원이 목적이 아님

Hello → SGVsbG8= → Hello. 가운데 값은 Base64이며 누구나 되돌릴 수 있습니다.

Permit2와 EIP-3009

Permit2는 먼저 토큰 컨트랙트가 Permit2 사용을 승인한 뒤, nonce가 있는 건별 서명으로 결제를 허가할 수 있습니다. EIP-3009는 토큰 자체의 서명 기반 전송 기능을 사용합니다. 현재 데모의 성공 경로는 Permit2입니다. 이전 EIP-3009 시도는 CDP에서 execution reverted로 거절됐지만 원인은 확정되지 않았습니다.

Facilitator의 역할

서명 검증, 블록체인 거래 제출, 정산 결과 확인을 대신합니다. 외부 업체가 반드시 필요한 것은 아니며 직접 구현할 수도 있습니다. 현재 데모는 Coinbase CDP를 사용합니다.

06 · 체험

결제 체험

지갑 연결과 0.01 USDC 구매를 별도 지시문으로 제공합니다. 페이지는 비밀정보를 입력받지 않습니다.

1. 지갑 연결 지시문

설치·로그인·잔액 조회까지만. 송금과 결제는 금지합니다.

Agent에게 그대로 전달

Binance Agentic Wallet 공식 스킬을 설치하고 지갑 연결만 진행해줘.

npx skills add binance/binance-skills-hub/skills/binance-web3/binance-agentic-wallet

로그인 링크 또는 QR을 받아 Binance 앱에서 승인해. 연결 후 Base(chain ID 8453) 주소와 Base USDC·Base ETH 잔액을 읽기 전용으로 보여줘. 이 연결 단계에서는 송금, 교환, 승인, 서명, 결제를 실행하지 마. 개인키·복구 문구·로그인 토큰을 요구하거나 출력하지 마.

2. 구매 지시문

가격·횟수·재시도 정책과 결과 보고 형식을 고정합니다.

Agent에게 그대로 전달

다음 x402 API를 Base USDC 0.01로 정확히 한 번만 구매해줘: https://x402-demo-production-19f3.up.railway.app/demo

1) 먼저 미결제 GET으로 HTTP 402 조건을 받고 x402 v2, eip155:8453, Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, amount 10000, payTo 0x711affb5dBc344b7D7BeB54a9870824bc3eB7F5d, exact + Permit2인지 검증해.
2) Binance Agentic Wallet로 preview하고 paymentId, 1-based index, amount, payTo, currentBalance, assetTransferMethod, needApproveFirst를 보여줘.
3) 결제 서명 전에 내 확인을 받아. needApproveFirst가 true면 신규 승인 금액과 예상 Base ETH 가스 조건을 먼저 설명해.
4) 승인이 전송되면 approveTxHash 확정을 확인한 뒤에만 결제 헤더로 원래 요청을 한 번 재호출해.
5) 정산 상태가 불명확하거나 재요청이 실패하면 새 서명으로 자동 재결제하지 마.
6) 완료하면 HTTP 상태, 받은 JSON, 실제 결제액, 정산 거래 해시, BaseScan 링크, 승인 거래가 있었다면 그 별도 해시를 보고해. PAYMENT-SIGNATURE 원문은 출력하거나 저장하지 마.

이 페이지는 구매자 개인키, 복구 문구, Binance 로그인 토큰, PAYMENT-SIGNATURE를 입력받지 않습니다.

Binance 공식 설치 안내 열기 ↗

07 · 검증

실제 검증 기록

2026-10-04 KST에 OpenClaw와 Binance Agentic Wallet로 현재 0.01 USDC 상품을 결제했습니다.

현재 상품 · 실제 결제

0.01 USDC

Agent가 실제 결제에 성공했습니다.

검증 시각2026-10-04 09:23 KST

HTTP200 OK

정산PAYMENT-RESPONSE success

온체인receipt status 1

구매자 잔액25.375221 → 25.365221 USDC

판매자 잔액1.000000 → 1.010000 USDC

Permit2 승인신규 거래 없음

거래BaseScan ↗

구매 지갑 0x06b57dfB4e6dE7344108B10bA1Fc394554c5DAD2. Base 블록 52142027의 USDC Transfer는 구매자 −10000, 판매자 +10000으로 확인됐습니다.

이전 PoC — 1 USDC

현재 0.01 USDC 상품과 다른 기록

2026-10-03 KST에 Permit2 승인과 1 USDC 정산을 실제로 완료한 선행 검증입니다.

상품 결제액1.00 USDC

승인 거래BaseScan ↗

정산 거래BaseScan ↗

CLI 지출 한도 사용량은 서명 시도로 증가할 수 있어 실제 온체인 출금액과 같다고 볼 수 없습니다.

08 · 범위

적용 범위와 제약

Agent 구매

데이터·검색·컴퓨팅·도구를 건별로 구매하고 후속 작업을 계속할 수 있습니다.

권한 범위

전체 지갑 통제권 대신 예산·대상·횟수를 제한한 구매 권한을 사용할 수 있습니다.

API 판매

판매 API는 가격과 수령 주소를 결제 조건으로 제공합니다.

적용 한계

x402는 카드 결제 전체나 배송·신원 확인·서비스 정책을 대체하지 않습니다.

운영 과제

체인·토큰·서명·가스·Facilitator 호환, 응답 유실 복구, 중복 청구 방지가 필요합니다.

현재 설정

Base 8453 · USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 · exact + Permit2 · 0x711affb5dBc344b7D7BeB54a9870824bc3eB7F5d.

x402 v2 공식 사양 ↗Exact EVM · Permit2 사양 ↗Coinbase CDP Facilitator ↗Binance x402 CLI 명세 ↗