x402 소개
에이전트에게 유료 API를 쓰게 하려면 지금까지는 사람이 먼저 움직여야 했습니다. 서비스에 가입하고, 결제 수단을 등록하고, 발급받은 API 키를 에이전트 설정에 꽂아 넣는 절차입니다. RFC 7231 은 402 Payment Required 를 "향후 사용을 위해 예약" 된 상태 코드로 남겨 두었지만, 무엇을 어떻게 지불하라는 규격이 함께 정해지지 않아 그 자리는 수십 년간 비어 있었습니다. x402는 그 빈자리를 채워서 클라이언트와 서버가 HTTP 요청 한 번의 왕복 안에서 결제를 끝내도록 만드는 개방형 결제 표준입니다. 본 게시물에서는 x402의 결제 흐름과 파실리테이터 구조, 결제 스킴, 지원 네트워크, 그리고 2026년 7월 27일에 태그된 @x402/mcp v2.20.0 을 포함한 MCP 통합을 정리합니다.
동작 방식은 단순합니다. 보호된 자원에 결제 없이 요청이 들어오면 서버는 402 와 함께 PAYMENT-REQUIRED 헤더로 받아들일 수 있는 결제 조건을 알려줍니다. 여기에는 스킴과 네트워크, 금액, 자산 주소, 받을 지갑 주소가 담깁니다. 클라이언트는 그중 자기가 지불할 수 있는 조건 하나를 골라 서명한 결제 payload 를 PAYMENT-SIGNATURE 헤더에 담아 같은 요청을 다시 보냅니다. 계정도, 세션도, 자격증명 보관도 필요하지 않습니다. 서버 입장에서는 미들웨어 한 줄, 클라이언트 입장에서는 함수 하나가 이 절차 전체를 감쌉니다. 표준이 겨냥하는 범위는 암호화폐에만 걸려 있지 않습니다. 저장소는 x402가 "암호화폐와 법정통화 양쪽 네트워크, 그리고 스테이블코인과 토큰, 법정통화를 포함한 모든 형태의 가치" 를 지원하는 것을 목표로 한다고 밝히고, 명세도 asset 필드에 토큰 주소 대신 ISO 4217 통화 코드를 넣을 수 있도록 열어 두었습니다. 다만 지금 구현이 갖춰진 쪽은 온체인 결제이고, 법정통화 경로는 목표로 적혀 있는 단계입니다.
x402는 Coinbase 에서 시작해 지금은 Linux Foundation 아래의 x402 재단(x402 Foundation) 이 관리합니다. Linux Foundation 은 2026년 7월 14일 x402 재단의 운영 출범과 Coinbase 의 프로토콜 기여 완료를 발표했고, 그 시점까지 40개 조직이 회원으로 참여했습니다. Premier 회원에는 Adyen, AWS, American Express, Circle, Cloudflare, Coinbase, Fiserv, Google, Mastercard, MoonPay, Ripple, Shopify, Solana Foundation, Stripe, Visa 등이, General 회원에는 카카오페이와 헥토파이낸셜, Galaxia Moneytree 같은 국내 기업도 들어 있습니다. 실제 기술 결정을 내리는 기술 운영 위원회(TSC) 는 Coinbase, Cloudflare, Stripe 세 조직의 대표로 구성되어 있습니다.
기존 API 유료화 방식과 x402의 차이
x402가 겨누는 지점은 결제 자체가 아니라 결제에 도달하기까지의 절차입니다. 공식 FAQ 는 "API 키 등록은 계정을 만들고 결제 수단을 추가하고 API 키를 에이전트에 꽂는 여러 단계의 UI 흐름을 요구한다" 고 문제를 정리합니다. 사람이 브라우저에서 폼을 채우는 행위는 프로그램끼리 주고받는 인터넷의 성질과 어긋나고, 에이전트가 스스로 서비스를 넓혀 가려 할 때마다 그 사람이 병목이 됩니다.
| 구분 | 계정과 API 키 방식 | 카드 결제 폼 | x402 |
|---|---|---|---|
| 접근 전 준비 | 회원가입, 결제 수단 등록, 키 발급 | 결제 폼 입력 | 지갑만 준비, 계정과 키 발급 없음 |
| 요금 단위 | 월 구독 또는 선불 크레딧 | 건별 또는 구독 | 요청 건별 (예: $0.001) |
| 에이전트 자동화 | 사람이 UI 절차를 대신 수행 | 사람의 폼 입력을 전제 | HTTP 요청 왕복 안에서 완결 |
| 프로토콜 수수료 | 제공자 정책에 따름 | 카드 네트워크 수수료 | 표준 자체에는 0 |
| 정산 | 제공자의 청구 주기 | 카드 정산 주기 | 온체인 정산, 파실리테이터 경유 가능 |
표의 수수료 항목은 조금 더 설명이 필요합니다. 프로젝트가 말하는 "수수료 0" 은 x402 표준 안에 프로토콜 수수료가 정의되어 있지 않다는 뜻이고, 온체인 가스비는 그대로 발생합니다. FAQ 는 Base 와 Solana 를 fee-free 로 표기하면서 "가스는 온체인에서 지불되며, 많은 파실리테이터가 파실리테이터 수수료를 0으로 제공한다" 는 각주를 달아 두었습니다. 정산 속도에 대해서도 프로젝트는 "수수료를 거의 0에 가깝게 떨어뜨리고 약 1초 안에 정산한다" 고 설명하지만, 실제 확정 시간은 선택한 네트워크에 달려 있습니다.
규격이 실제로 돌아가고 있는지는 홈페이지가 공개하는 지표로 가늠할 수 있습니다. 2026년 8월 4일 기준으로 x402.org 는 지난 30일간 거래 7,541만 건, 거래액 2,424만 달러, 구매자 9만 4천 명, 판매자 2만 2천 곳을 표시하고 있습니다. 거래액을 건수로 나누면 한 건당 평균이 0.5달러에도 미치지 않는데, 이 표준이 겨냥하는 자리가 소액 건별 과금이라는 점이 수치에서도 드러납니다.
x402의 결제 흐름
저장소의 static/flow.png 은 클라이언트, 자원 서버, 파실리테이터, 블록체인 사이에서 메시지가 오가는 순서를 한 장으로 보여줍니다.
전체 절차는 저장소 README 가 12단계로 기술하고 있으며, 핵심만 추리면 이렇게 흘러갑니다. 클라이언트가 자원을 요청하면 서버는 402 응답과 함께 PaymentRequired 객체를 base64 로 인코딩해 PAYMENT-REQUIRED 헤더에 실어 보냅니다. 클라이언트는 응답의 accepts 배열에서 자기가 지불 가능한 항목을 하나 골라 그 스킴과 네트워크에 맞는 PaymentPayload 를 만들고, PAYMENT-SIGNATURE 헤더에 담아 원래 요청을 재전송합니다. 서버는 이 payload 를 자체적으로 검증하거나 파실리테이터의 /verify 엔드포인트에 POST 해서 확인하고, 유효하면 요청을 실제로 처리합니다. 마지막으로 서버가 직접 블록체인과 통신하거나 파실리테이터의 /settle 을 호출해 결제를 정산한 뒤, 200 OK 와 함께 정산 결과를 PAYMENT-RESPONSE 헤더에 담아 돌려줍니다.
서버가 내려보내는 402 응답 본문은 다음과 같은 모양입니다. 한 자원이 여러 네트워크의 결제 조건을 동시에 제시할 수 있다는 점이 눈에 띕니다.
{
"x402Version": 2,
"error": "PAYMENT-SIGNATURE header is required",
"resource": {
"url": "https://api.example.com/weather",
"description": "Weather data",
"mimeType": "application/json"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:84532",
"amount": "1000",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"payTo": "0xYourEvmAddress",
"maxTimeoutSeconds": 60,
"extra": { "name": "USDC", "version": "2" }
},
{
"scheme": "exact",
"network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
"amount": "1000",
"asset": "So11111111111111111111111111111111111111112",
"payTo": "YourSolanaAddress",
"maxTimeoutSeconds": 60,
"extra": { "feePayer": "EwWqGE4ZFKLofuestmU4LDdK7XM1N4ALgdZccwYugwGd" }
}
]
}
이 규격은 HTTP 에만 묶여 있지 않습니다. specs/transports-v2/ 디렉토리에는 http.md 와 나란히 mcp.md, a2a.md 가 들어 있어, 같은 결제 의미를 서로 다른 전송 계층에 어떻게 얹을지를 각각 규정합니다. MCP 가 부가 기능이 아니라 전송 계층의 하나로 명세에 들어와 있다는 뜻입니다. a2a.md 는 에이전트끼리 직접 주고받는 Agent-to-Agent 프로토콜 위의 결제를 다루고, 명세는 요청과 응답이 오가는 시스템이라면 어떤 것이든 같은 방식으로 x402를 얹을 수 있다고 적어 두었습니다.
x402 v2의 3계층 구조와 v1에서 바뀐 점
프로토콜 명세 v2 는 x402를 세 겹으로 나눠 설명합니다.
- 타입(Types):
PaymentRequirements,PaymentPayload,SettlementResponse처럼 전송 방식과 결제 스킴 양쪽에 무관한 데이터 구조입니다. - 로직(Logic): 결제를 만들고 검증하는 규칙으로, 스킴과 네트워크에 따라 달라집니다.
- 표현(Representation): 그 데이터를 어떻게 실어 보내고 신호할지를 정하는 층이며, 여기가 전송 방식에 종속됩니다.
세 층이 분리되어 있으면 HTTP 상태 코드로 표현하던 것을 JSON-RPC 오류나 MCP 도구 결과로 바꿔도 타입과 로직은 그대로 재사용됩니다. 명세가 응답 종류를 성공, 결제 필요, 잘못된 요청, 서버 오류 네 가지로만 정의하고 그것을 어떤 상태 코드나 오류 코드에 대응시킬지는 전송 명세에 넘기는 것도 같은 이유입니다. MCP 통합이 별도 구현이 아니라 표현 층 하나를 갈아 끼우는 일로 끝나는 배경이 여기 있습니다.
명세 문서 자체의 이력을 보면 이 구조가 나중에 잡혔다는 것을 알 수 있습니다. 2025년 8월 29일 초안에서 시작해 2025년 10월 3일에 전송 방식에 무관한 재설계가 들어갔고, 2025년 12월 9일에 프로토콜 v2 가 CAIP-2 네트워크 표기와 PaymentPayload·PaymentRequired 재구성, ResourceInfo 분리, 확장 지원을 담아 확정됐습니다.
그래서 v1 시절 예제를 그대로 따라가면 동작하지 않습니다. 마이그레이션 가이드 가 정리한 차이는 다음과 같습니다.
| 항목 | v1 | v2 |
|---|---|---|
| 결제 요청 헤더 | X-PAYMENT |
PAYMENT-SIGNATURE |
| 응답 헤더 | X-PAYMENT-RESPONSE |
PAYMENT-RESPONSE |
| 네트워크 표기 | 문자열 (base-sepolia) |
CAIP-2 (eip155:84532) |
| 버전 필드 | x402Version: 1 |
x402Version: 2 |
| 패키지 이름 | x402, x402-express, x402-axios |
@x402/core, @x402/express, @x402/axios, @x402/evm |
PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE 세 헤더의 값은 모두 base64 로 인코딩된 JSON 입니다. JSON 안의 특수문자 때문에 HTTP 구현마다 다르게 동작하는 문제를 피하려는 선택입니다.
x402의 파실리테이터 구조
파실리테이터(facilitator)는 결제의 검증과 실행을 대신 처리해 주는 서버입니다. 자원 서버가 직접 체인을 다루고 싶지 않을 때 /verify 와 /settle 을 호출하면, 파실리테이터가 서명 검증과 트랜잭션 제출, 확정 대기를 맡습니다. 저장소 README 가 세운 설계 원칙 중 하나는 클라이언트와 서버가 가스나 RPC 같은 세부 사항을 생각하지 않게 만드는 것이고, 파실리테이터는 그 복잡도를 흡수하는 자리에 있습니다. 다이어그램에도 "파실리테이터는 선택 사항이며, 서버가 스테이블코인이나 암호화폐를 직접 받는 경우 모든 논리적 단계를 서버가 수행할 수 있다" 는 주석이 붙어 있습니다.
명세가 정의한 파실리테이터 API 는 이 둘에 GET /supported 를 더한 셋입니다. 마지막 엔드포인트는 그 파실리테이터가 어떤 스킴과 네트워크, 확장을 받아 주는지 알려주고, 뒤에 나오는 코드 예시의 resourceServer.initialize() 가 서버 시작 시점에 이 목록을 읽어 옵니다. 핵심 프로토콜은 전송 방식에 무관하지만 파실리테이터 API 는 지금 HTTP 엔드포인트로만 표준화되어 있다는 점도 명세가 따로 밝혀 둔 부분입니다.
신뢰 문제는 서명 구조로 풉니다. 모든 결제 payload 는 구매자가 서명하고 정산은 온체인에서 직접 일어나므로, 파실리테이터가 트랜잭션을 손대면 서명 검증에서 걸려 정산 자체가 되지 않습니다. 프로토콜 원칙에도 파실리테이터나 자원 서버가 클라이언트의 의도를 벗어나 자금을 움직일 수 없어야 한다는 조항이 명시되어 있습니다. 파실리테이터 운영은 허가가 필요 없어 누구나 띄울 수 있습니다.
다만 저장소는 프로덕션 경로에 대해 분명한 경고를 남겨 두었습니다. 테스트넷 개발과 빠른 시작에는 공개 x402 파실리테이터가 가장 편하지만, 메인넷 라우트를 열 때는 파실리테이터 모델을 명시적으로 정해야 한다는 것입니다. 선택지는 대상 네트워크를 지원하는 상용 파실리테이터를 쓰거나, 직접 파실리테이터를 운영하거나, 자원 서버 안에서 스스로 정산하는 방식 세 가지입니다. README 는 "메인넷 EVM 라우트에서 공개 x402.org 파실리테이터가 기본 프로덕션 경로라고 가정하지 말라" 고 못을 박습니다.
x402의 재사용 공격 방어와 검증 단계
결제 payload 는 서명된 인증서에 가깝습니다. EVM 의 exact 스킴에서는 payload 안에 EIP-712 서명과 EIP-3009 인증 파라미터가 들어가고, 인증 파라미터는 지불자 주소와 수신 주소, 금액, 유효 시작·만료 시각, 32바이트 논스(nonce)로 구성됩니다.
{
"signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c",
"authorization": {
"from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
"to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
"value": "10000",
"validAfter": "1740672089",
"validBefore": "1740672154",
"nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480"
}
}
재사용(replay) 공격 방어는 네 겹입니다. 인증마다 고유한 32바이트 논스가 붙고, EIP-3009 계약이 스마트 컨트랙트 수준에서 논스 재사용을 막고, 인증에는 명시적인 유효 시간 창이 있고, 모든 인증은 지불자가 암호학적으로 서명합니다. 같은 요청을 가로채 다시 보내는 것으로는 두 번 과금할 수 없다는 뜻입니다.
파실리테이터가 /verify 에서 수행하는 검사도 명세에 단계별로 적혀 있습니다. EIP-712 서명이 지불자의 것인지 확인하고, 잔액이 충분한지 보고, 금액이 요구액과 정확히 일치하는지 대조하고, 유효 시간 창 안에 있는지 확인하고, 인증 파라미터가 원래의 결제 요구와 맞는지 맞춰 본 뒤, 마지막으로 transferWithAuthorization 트랜잭션을 시뮬레이션해 실제로 성공할지까지 확인합니다. 검증이 실패하면 insufficient_funds 나 invalid_exact_evm_payload_signature 처럼 표준화된 오류 코드가 돌아오므로, 클라이언트가 잔액 부족과 서명 오류를 구분해 다르게 대응할 수 있습니다.
x402의 결제 스킴: exact, upto, batch-settlement
스킴(scheme)은 돈을 옮기는 논리적 방식을 가리키는 필드입니다. 블록체인마다 자금을 움직이는 방법이 여러 가지라, x402는 결제 의미론을 스킴으로 분리해 두고 확장할 수 있게 만들었습니다. 공식 문서가 다루는 스킴은 세 가지입니다.
exact: 광고된 금액을 그대로 승인하는 고정 가격 방식입니다. 글 한 편에 1달러를 지불하는 식의 건별 과금이 여기 해당합니다.upto: 한 요청에 대해 구매자가 상한을 승인하고, 판매자가 실제 사용량만큼 그 상한 안에서 청구합니다. 토큰 수나 연산 시간, 대역폭처럼 호출 전에 확정할 수 없는 사용량 과금에 맞습니다.batch-settlement: 매 요청을 온체인에서 정산하기에는 비용이 큰 고빈도 소액 결제를 위한 EVM 전용 스킴입니다. 구매자가 에스크로 계약에 한 번 예치한 뒤 요청마다 오프체인 바우처에 서명하고, 판매자는 그 청구들을 묶어 온체인에서 일괄 상환합니다. 요청별 가격은 여전히 상한 방식이라 실제 청구액이 상한 안에서 달라질 수 있습니다.
스킴과 네트워크는 별개의 축입니다. 같은 exact 라도 Ethereum 에서 구현하는 방식과 Solana 에서 구현하는 방식이 다르기 때문에, 클라이언트와 파실리테이터는 자기가 지원하는 (스킴, 네트워크) 조합을 명시적으로 등록해야 결제 payload 를 만들고 검증할 수 있습니다. 스킴별 명세는 specs/schemes/ 에 들어 있고, 이 디렉토리에는 문서 사이트에 아직 올라오지 않은 auth-capture 명세도 함께 있습니다.
x402가 지원하는 네트워크와 토큰
네트워크 식별자는 CAIP-2 표기를 씁니다. eip155:8453 이 Base 를, eip155:84532 가 Base Sepolia 를 가리키는 식입니다. 명세는 블록체인이 아닌 네트워크도 같은 표기를 따르도록 권장하면서 ach:us 와 sepa:eu 를 예로 들어 두었는데, 앞서 말한 법정통화 지원 목표가 식별자 설계에까지 반영된 지점입니다. 문서가 정리한 지원 생태계와 전송 방식은 다음과 같습니다.
| 생태계 | 지원 토큰 | 전송 방식 |
|---|---|---|
| EVM | 모든 ERC-20 토큰 | EIP-3009 또는 Permit2 |
| Solana | 모든 SPL 또는 Token-2022 토큰 | SPL Transfer |
| TON (TVM) | 모든 TEP-74 제톤 | 서명된 W5R1 내부 메시지 |
| Algorand (AVM) | 모든 ASA | 원자적 그룹 내 ASA 전송 |
| Stellar | SEP-41 을 구현한 Soroban 토큰 | transfer(from, to, amount) |
| Aptos | 모든 대체 가능 자산 | primary_fungible_store::transfer |
| Hedera | HBAR 또는 HTS 대체 가능 토큰 | Hedera Transfer Transaction |
| Keeta | 모든 Keeta 토큰 | SEND 연산 |
| NEAR | 모든 NEP-141 토큰 | NEP-366 SignedDelegate |
| Concordium | CCD 또는 PLT 토큰 | 후원된 V1 전송 |
| XRPL | XRP 또는 발행 통화 | 지불자가 서명한 Payment 트랜잭션 |
EVM 에서는 토큰의 기능에 따라 전송 방식이 자동으로 갈립니다. USDC 처럼 transferWithAuthorization 을 지원하는 토큰은 오프체인 서명 한 번으로 끝나는 EIP-3009 경로를 타고, 그렇지 않은 일반 ERC-20 은 Uniswap 의 Permit2 계약을 경유합니다. 두 경로 모두 파실리테이터가 가스를 후원하는 가스리스 전송이지만, Permit2 는 온체인 승인을 한 번 받아야 하는 차이가 있습니다. 그 승인 단계마저 가스 없이 처리하도록 EIP-2612 와 ERC-20 승인 가스 후원 확장이 별도로 준비되어 있습니다.
가격을 적는 방법은 두 가지입니다. "$0.01" 처럼 달러 문자열을 쓰면 해당 체인에 미리 설정된 기본 스테이블코인이 선택되고, 기본값이 등록되지 않은 체인에서는 원자 단위 금액과 자산 주소를 직접 지정하는 TokenAmount 방식을 씁니다.
지원 범위를 읽을 때는 문서가 나눠 놓은 세 단계를 구분해야 합니다. 프로토콜 지원은 그 네트워크의 결제 요구와 payload 를 표현할 수 있다는 뜻이고, 런타임 지원은 서버가 그 네트워크를 등록해 호환 스킴 구현을 쓸 수 있다는 뜻이며, 프로덕션 지원은 상용 파실리테이터나 자체 운영, 자체 정산 중 실제로 동작하는 정산 경로를 갖췄다는 뜻입니다. 프로토콜은 임의의 eip155:<chainId> 를 표현할 수 있지만 실제로 돈을 받으려면 마지막 단계까지 가야 합니다. 위 표보다 명세가 앞서 있는 부분도 있습니다. specs/schemes/exact/ 에는 Cardano, Casper, Starknet, Sui 처럼 SDK 구현이 아직 없는 네트워크의 exact 명세도 함께 들어 있어, 명세가 먼저 들어오고 구현이 따라오는 순서로 확장되고 있음을 보여줍니다.
x402의 MCP 통합과 @x402/mcp v2.20.0
에이전트 관점에서 가장 직접적인 부분이 @x402/mcp 패키지입니다. MCP 서버 쪽에서는 유료 도구 호출을 만들고, MCP 클라이언트 쪽에서는 결제를 자동으로 처리합니다.
MCP 전송 명세는 결제 요구를 JSON-RPC 오류가 아니라 isError: true 인 도구 결과로 실어 보내도록 정의합니다. 서버는 PaymentRequired 객체를 structuredContent 와 content[0].text 두 형식으로 모두 제공해야 하고, 클라이언트는 structuredContent 를 우선 읽고 없으면 텍스트를 파싱합니다. 결제 payload 는 도구 호출 파라미터의 _meta["x402/payment"] 에 담기고, 정산 결과는 응답의 _meta["x402/payment-response"] 로 돌아옵니다.
@x402/mcp 서버: 유료 도구 만들기
서버 쪽 권장 방식은 결제 래퍼를 만들어 도구 핸들러를 감싸는 것입니다. 무료 도구는 래퍼 없이 그대로 등록하면 되므로, 한 서버 안에서 유료와 무료 도구가 섞여도 문제가 없습니다.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createPaymentWrapper, x402ResourceServer } from "@x402/mcp";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { z } from "zod";
const mcpServer = new McpServer({ name: "premium-api", version: "1.0.0" });
const facilitatorClient = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const resourceServer = new x402ResourceServer(facilitatorClient);
resourceServer.register("eip155:84532", new ExactEvmScheme());
await resourceServer.initialize();
const accepts = await resourceServer.buildPaymentRequirements({
scheme: "exact",
network: "eip155:84532",
payTo: "0x...",
price: "$0.10",
});
const paid = createPaymentWrapper(resourceServer, { accepts });
mcpServer.tool(
"financial_analysis",
"Advanced AI-powered financial analysis. Costs $0.10.",
{ ticker: z.string() },
paid(async (args) => {
const analysis = await performAnalysis(args.ticker);
return { content: [{ type: "text", text: analysis }] };
})
);
mcpServer.tool("ping", "Health check", {}, async () => ({
content: [{ type: "text", text: "pong" }],
}));
가격대를 나누고 싶으면 래퍼를 여러 개 만들어 도구마다 다른 래퍼를 적용합니다. 검증과 실행, 정산 사이에는 훅이 걸려 있어서, onBeforeExecution 에서 false 를 돌려주면 도구를 실행하지 않고 과금도 하지 않습니다. 지불자 주소 기준 속도 제한이나 차단 목록을 이 지점에 넣을 수 있고, onAfterSettlement 에서는 거래 해시를 받아 영수증을 발송하거나 기록할 수 있습니다.
@x402/mcp 클라이언트: 결제 자동화와 사람의 승인
클라이언트는 팩토리 함수로 만드는 방식이 가장 짧습니다. autoPayment 가 켜져 있으면 402 를 받은 뒤 결제를 붙여 자동으로 재시도하고, onPaymentRequested 훅에서 false 를 돌려주면 그 결제를 거부합니다. 사람이 개입하는 승인 단계를 넣을 자리가 바로 이 훅입니다.
import { createX402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
const client = createX402MCPClient({
name: "my-agent",
version: "1.0.0",
schemes: [{ network: "eip155:84532", client: new ExactEvmScheme(walletAccount) }],
autoPayment: true,
onPaymentRequested: async ({ paymentRequired }) => {
console.log(`Tool requires payment: ${paymentRequired.accepts[0].amount}`);
return true; // Return false to deny payment
},
});
const transport = new SSEClientTransport(new URL("http://localhost:4022/sse"));
await client.connect(transport);
const result = await client.callTool("financial_analysis", { ticker: "AAPL" });
if (result.paymentMade) {
console.log("Payment settled:", result.paymentResponse?.transaction);
}
이미 만들어 둔 MCP 클라이언트가 있다면 wrapMCPClientWithPayment 로 감싸는 경로도 있습니다. 클라이언트 훅으로는 onPaymentRequired, onBeforePayment, onAfterPayment 가 제공되며, 첫 번째 훅에서 캐시된 결제를 반환해 재사용하거나 아예 중단시킬 수 있습니다.
한 가지 우회 구현은 문서에 솔직하게 적혀 있습니다. MCP 전송 명세는 결제 오류를 JSON-RPC 의 error.code 402 로 표현하지만, MCP SDK 가 McpError 예외를 isError: true 인 도구 결과로 변환하면서 error.data 필드를 잃어버립니다. 그래서 @x402/mcp 는 오류 구조를 결과 콘텐츠 안에 {"x402/error": ...} 형태로 다시 심고 클라이언트가 그것을 파싱하도록 만들었습니다. 프로젝트는 이를 "상위 SDK 개선을 추적하는 동안 호환성을 유지하는 실용적 우회" 라고 설명합니다.
v2.20.0 과 최근 릴리즈에서 바뀐 점
@x402/mcp v2.20.0 태그 는 2026년 7월 27일에 붙었습니다. 패키지 CHANGELOG 를 보면 이 버전 자체는 @x402/core 2.20.0 으로의 의존성 갱신이고, 실제 변경은 core 쪽에 있습니다. core 2.20.0 은 HTTPFacilitatorClient 의 createAuthHeaders 콜백이 파실리테이터 경로별로 구분되지 않은 평평한 헤더 객체를 반환할 때 명확한 오류를 던지도록 바꿨습니다. 이전에는 이 상황에서 모든 요청의 인증이 조용히 사라졌기 때문에, 자체 파실리테이터에 인증을 붙여 운영하는 쪽에는 실질적인 영향이 있는 변경입니다.
MCP 사용자 입장에서 최근 몇 개 버전 중 눈여겨볼 것은 v2.18.0 입니다. Python 과 Go SDK 가 선택적 필드를 명시적 null 로 직렬화해 보내면 TypeScript 쪽 검증이 실패하던 문제를 고쳐서, 다른 언어로 구현된 서버의 402 응답도 자동 결제를 정상적으로 발동시키게 됐습니다. MCP 클라이언트가 결과와 오류 양쪽을 parsePaymentRequired 로 통일해 처리하도록 바뀐 것도 이 버전입니다. 그 앞으로는 v2.14.0 에서 x402 메타데이터를 붙일 때 기존 MCP 응답 메타데이터를 보존하도록 고쳤고, v2.11.0 에서는 PaymentWrapperConfig 에 extensions 필드가 들어와 유료 MCP 도구가 Bazaar 탐색 메타데이터를 선언할 수 있게 됐습니다. 조직 이전이 반영된 버전은 v2.9.0 으로, 이때 프로젝트가 coinbase/x402 에서 x402-foundation/x402 로 옮겨졌습니다.
x402의 확장 기능
핵심 결제 규격 위에는 선택적으로 끼워 넣는 확장 계층이 따로 있습니다. 자원 서버 확장은 라우트 등록 시점(enrichDeclaration), 402 응답을 만들 때(enrichPaymentRequiredResponse), 정산 응답을 만들 때(enrichSettlementResponse), 그리고 검증·정산 생애주기 훅 네 지점에 끼어들 수 있고, 파실리테이터 확장은 가스 후원처럼 정산 흐름에 서명 기능을 주입합니다. 서버가 PaymentRequired 에 지원 확장을 광고하면 클라이언트는 그것을 PaymentPayload 에 되돌려 보내는데, 받은 정보를 지우거나 덮어쓸 수는 없고 덧붙이는 것만 허용됩니다.
| 확장 | 하는 일 |
|---|---|
bazaar |
x402 지원 엔드포인트와 MCP 도구를 기계가 읽을 수 있는 목록으로 모으는 탐색 계층 |
sign-in-with-x |
CAIP-122 지갑 인증으로 이미 결제한 자원에 다시 결제하지 않고 접근 |
payment-identifier |
결제 ID 로 멱등성을 보장해 재시도가 중복 결제로 이어지지 않게 함 |
offer-receipt |
402 에 서명된 청구를, 200 에 서명된 영수증을 붙여 제3자가 검증 가능한 증빙 생성 |
builder-code |
ERC-8021 코드를 정산 트랜잭션 calldata 에 붙여 온체인 기여 추적 |
eip2612-gas-sponsoring |
Permit2 승인 단계의 가스를 후원 |
erc20-approval-gas-sponsoring |
ERC-20 승인 단계의 가스를 후원 |
에이전트를 운영하는 쪽에서 가장 먼저 눈에 들어올 것은 앞의 세 가지입니다. sign-in-with-x 는 "이미 산 콘텐츠를 매번 다시 결제해야 하나" 는 문제를 지갑 소유 증명으로 풉니다. payment-identifier 는 네트워크 실패나 클라이언트 재시작 뒤 같은 요청을 다시 보내도 결제가 두 번 처리되지 않게 하는데, 재시도를 기본 전략으로 삼는 에이전트에는 사실상 필수입니다. offer-receipt 의 서명된 영수증은 온체인 증명에 붙여 "실제로 지불하고 서비스를 받았다" 는 기록으로 쓸 수 있습니다.
x402 Bazaar: 에이전트가 유료 도구를 찾는 탐색 계층
결제 규격이 갖춰져도 남는 문제가 있습니다. 에이전트가 지불할 준비가 되어 있어도 어디에 무엇이 얼마에 있는지 모르면 아무 일도 일어나지 않습니다. Bazaar 확장은 이 탐색 문제를 담당하는 계층으로, x402를 지원하는 HTTP 엔드포인트와 MCP 도구를 기계가 읽을 수 있는 목록으로 모읍니다. Bazaar 확장을 지원하는 파실리테이터는 /discovery/resources 엔드포인트를 제공할 수 있고, 라우트 설정에 확장을 포함한 서비스가 그 목록에 올라갑니다.
문서는 현재 완성도를 스스로 낮춰 말합니다. "에이전틱 엔드포인트를 위한 구글을 만드는 것이 우리의 비전이지만, 지금은 야후 검색에 더 가깝다" 는 표현이 그대로 적혀 있고, 기능과 API 가 바뀔 수 있다는 단서도 붙습니다. 목록 규격 자체는 스킴의 일부로 공개되어 있어서 어떤 파실리테이터든 자기 탐색 계층을 구현할 수 있습니다. 결제 후에는 파실리테이터가 EXTENSION-RESPONSES 헤더로 목록 등록 결과를 success, processing, rejected 중 하나로 알려줄 수 있습니다. 목록 조회는 자원 종류와 받는 주소, 스킴, 네트워크, 확장 키로 걸러낼 수 있고, 자연어 질의로 찾는 /discovery/search 엔드포인트도 명세에 함께 정의되어 있습니다.
Bazaar 밖에도 커뮤니티가 운영하는 목록이 여러 곳 있습니다. 저장소는 x402scan.com 과 x402-list.com, Agentic.Market, Pay.sh 를 x402 서비스를 모아 보여주는 사이트로 소개하고, 검증된 서드파티 SDK 와 파실리테이터 목록은 Developer Tools 문서 에 정리해 두었습니다. 질문과 논의는 x402 Slack 에서 이뤄집니다.
x402의 SDK 지원 현황
레퍼런스 구현은 TypeScript, Python, Go 세 언어입니다. 저장소에는 Java 17 이상을 대상으로 하는 java/ 구현도 들어 있지만, 공식 SDK 기능 표 가 추적하는 대상은 앞의 세 언어입니다. 언어마다 지원 범위 차이가 뚜렷해서, 도입 전에 이 표를 확인하는 편이 좋습니다.
| 항목 | TypeScript | Go | Python |
|---|---|---|---|
| 서버, 클라이언트, 파실리테이터 | 지원 | 지원 | 지원 |
| HTTP 프레임워크 | Express, Hono, Next.js, Fastify | Gin, net/http, Echo | FastAPI, Flask |
| 네트워크 | 11개 생태계 전부 | EVM, Solana | EVM, Solana, TON |
upto 스킴 |
EVM | EVM | EVM |
batch-settlement 스킴 |
EVM | EVM | 미지원 |
| MCP 패키지 | typescript/packages/mcp |
go/mcp |
python/x402/mcp |
MCP 통합만 보면 세 언어 모두 전용 모듈을 가지고 있습니다. 반면 EVM 과 Solana 밖의 체인은 TypeScript 에만 구현되어 있어서, Go 나 Python 으로 Stellar 나 Aptos 결제를 받으려면 직접 구현해야 합니다. 확장 기능 쪽에서도 offer-receipt 는 TypeScript 전용이고, enrichPaymentRequiredResponse 같은 확장 훅은 Go 에 아직 없습니다.
x402는 누구에게 유용한가
요청 단위로 값을 매길 수 있는 API 나 데이터, MCP 도구를 이미 운영하고 있고 에이전트 트래픽을 사람 결제 절차 없이 받고 싶다면 충분히 시도해 볼 만합니다. Express 나 FastAPI 미들웨어를 붙이고 받을 지갑 주소를 넣는 것으로 시작할 수 있고, Base Sepolia 와 Solana Devnet 테스트넷에서 공개 파실리테이터로 실제 돈 없이 흐름을 끝까지 확인할 수 있습니다. 반대로 접근을 유료화할 지점이 명확하지 않은 서비스라면 결제 규격보다 과금 설계가 먼저입니다.
맞지 않는 경우도 분명합니다. 법정통화 정산과 인보이스, 환불, 세금 처리가 필수인 과금 체계라면 x402 하나로는 부족합니다. 프로젝트도 법정통화 온오프램프를 기본으로 지원하지 않으며 파실리테이터나 제3자 게이트웨이가 그 흐름을 감싸야 한다고 밝히고 있습니다. 표준이 법정통화를 목표에 포함한다는 점과 지금 당장 쓸 수 있는 구현이 온체인 결제라는 점은 구분해서 봐야 합니다. 구독 과금이 이미 안정적으로 돌고 에이전트 트래픽이 거의 없는 서비스가 굳이 바꿀 이유도 크지 않습니다. 메인넷을 열 계획이라면 상용 파실리테이터, 자체 운영, 자체 정산 중 어느 모델로 갈지를 먼저 정해야 하고, TypeScript 가 아닌 언어에서 EVM 과 Solana 밖의 체인을 쓸 계획이라면 SDK 기능 표를 먼저 확인해야 합니다.
x402 설치 및 사용법
TypeScript 는 필요한 패키지만 골라 설치합니다. 최소 구성은 코어와 체인 구현, 그리고 사용할 클라이언트나 서버 어댑터입니다.
# 최소 구성 Fetch 클라이언트
npm install @x402/core @x402/evm @x402/svm @x402/fetch
# 최소 구성 Express 서버
npm install @x402/core @x402/evm @x402/svm @x402/express
# MCP 통합
npm install @x402/mcp @x402/core @modelcontextprotocol/sdk
Python 과 Go 는 단일 패키지로 설치합니다.
pip install x402
go get github.com/x402-foundation/x402/go/v2
서버 쪽 통합은 보호할 라우트와 받아들일 결제 조건을 미들웨어에 넘기는 형태입니다. 아래는 공식 판매자 퀵스타트의 Express 예시를 줄여 옮긴 것으로, 같은 라우트에 EVM 과 Solana 두 네트워크의 조건을 동시에 제시합니다.
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";
const app = express();
const evmAddress = "0xYourEvmAddress";
const svmAddress = "YourSolanaAddress";
const facilitatorClient = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
app.use(
paymentMiddleware(
{
"GET /weather": {
accepts: [
{ scheme: "exact", price: "$0.001", network: "eip155:84532", payTo: evmAddress },
{
scheme: "exact",
price: "$0.001",
network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
payTo: svmAddress,
},
],
description: "Weather data",
mimeType: "application/json",
},
},
new x402ResourceServer(facilitatorClient)
.register("eip155:84532", new ExactEvmScheme())
.register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme()),
),
);
app.get("/weather", (req, res) => {
res.send({ report: { weather: "sunny", temperature: 70 } });
});
app.listen(4021);
브라우저로 들어온 사람 구매자에게는 @x402/paywall 패키지가 결제 화면을 대신 보여줍니다. 지갑 주소와 금액, 네트워크를 확인하고 버튼을 눌러 지불하는 형태로, 같은 402 응답이 에이전트에게는 헤더로, 사람에게는 화면으로 전달되는 셈입니다.
MCP 서버를 Claude Desktop 에 붙이는 경로는 MCP 서버 연동 가이드 가 따로 다룹니다. 저장소의 examples/typescript/clients/mcp 예시를 빌드해 Claude Desktop 설정의 mcpServers 에 등록하고, 지갑 개인키와 대상 서버 URL 을 환경 변수로 넘기는 방식입니다. 가이드는 Node.js v20 이상과 pnpm v10, 그리고 Base Sepolia 또는 Solana Devnet 에 USDC 가 있는 지갑을 준비물로 안내합니다.
x402의 라이선스
x402는 Apache 라이선스 2.0 으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 저장소의 NOTICE 파일에는 저작권자가 x402 Foundation 으로 표기되어 있습니다.
x402 공식 홈페이지
x402 공식 문서 사이트
x402 프로젝트 GitHub 저장소
더 읽어보기
-
Cloudflare Monetization Gateway: 에이전트에게 API, 데이터, MCP 도구를 x402로 판매하기
-
Universal Commerce Protocol(UCP), 에이전트 기반 차세대 커머스를 위한 오픈 프로토콜
-
AI 에이전트 프로토콜 개발자 가이드: MCP부터 A2A, UCP, AP2, A2UI, AG-UI까지 (feat. Google)
-
Cloudflare와 Stripe가 함께 만든 새 프로토콜로 AI 에이전트가 직접 계정 생성과 도메인 구매, 배포까지 처리합니다 (feat. Stripe Projects)
-
Agent Network Protocol(ANP): Agentic Web을 위한 AI 에이전트들의 직접적인 연결(P2P)을 돕는 오픈소스 프로토콜
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 