USDC로 API 호출당 비용 결제하기 — 그리고 구매자에게 검증 가능한 영수증 제공하기

AI 에이전트(AI agents)가 이제 스스로 비용을 지불할 수 있습니다. x402 프로토콜은 HTTP 402 Payment Required를 재사용하여, 클라이언트(인간 또는 에이전트)가 API 키, 계정, 구독 없이 USDC로 API 호출당 비용을 지불하게 합니다. 이는 진정으로 훌륭한 프리미티브(primitive)입니다.

하지만 에이전트가 지불한 내용에 따라 행동하는 순간 문제가 되는 간극이 존재합니다: 결제 레일(payment rail)은 돈이 이동했다는 사실은 증명하지만, 돌아온 바이트(bytes) 데이터에 대해서는 아무것도 말해주지 않습니다. 에이전트는 완벽하게 결제하고도 변조되거나 스푸핑(spoofing)된 데이터에 따라 행동할 수 있습니다.

그래서 제가 구현한 방식과 여러분도 구현할 수 있는 방법을 소개합니다: 호출당 USDC로 비용을 청구하면서, 구매자에게 응답에 따라 행동하기 전에 검증할 수 있는 서명된 영수증을 전달하는 Express 엔드포인트입니다. 하단의 패키지들은 무료이며 MIT 라이선스입니다. 이것은 단순히 그 조립 과정을 명확하게 보여주는 것입니다.

우리가 구축하는 것

client ──GET /price──▶  402 Payment Required  (USDC 조건)
client ──pay USDC───▶  200 OK + 데이터 + X-BYTE-Attestation 영수증
client ──verify────▶  해시 재계산, 서명자 복구 → 실행 또는 거부

두 개의 작은 라이브러리가 작업을 수행합니다:

• @foreseal/gate — 판매자 측 Express 미들웨어(middleware). 모든 업스트림(upstream)을 유료이며 증명된(attested) 엔드포인트로 변환합니다.
• @payperbyte/sdk — 구매자 측 검증기(verifier).

둘 다 MIT 라이선스입니다. 여러분도 직접 연결할 수 있으며, 그것이 이 포스트의 목적입니다.

파트 1 — 미들웨어 호출 한 번으로 끝내는 판매자 설정

import express from "express";
import { trustMiddleware } from "@foreseal/gate";

...

이것이 통합의 전부입니다. 결제되지 않은 호출은 x402 USDC 조건이 포함된 402 응답을 받습니다. 결제가 완료되면, gate가 업스트림을 프록시(proxy)하고 응답에 **제공된 정확한 바이트(bytes)에 대한 EIP-712 증명(attestation)**을 X-BYTE-Attestation 헤더에 바이트 단위로 찍어줍니다.

파트 2 — 구매자가 보는 화면

curl -i http://localhost:3000/price
# HTTP/1.1 402 Payment Required
# ... x402 결제 조건 (자산, 금액, 네트워크, payTo) ...

클라이언트는 USDC로 결제하고, 결제 헤더(payment header)와 함께 재시도하여 데이터와 영수증이 포함된 200 응답을 받습니다. 표준적인 x402 흐름이며, 게이트웨이(gate)는 단지 영수증을 추가할 뿐입니다.

파트 3 — 실행 전 검증 (가장 중요한 부분)

이 부분은 모두가 건너뛰는 절반의 과정입니다. 코드(또는 에이전트)가 응답에 따라 동작하기 전에, 정확한 바이트(bytes)의 해시(hash)를 다시 계산하고 서명자(signer)를 복구(recover)해야 합니다. 둘 중 하나라도 틀리면 거부하십시오.

import { verifyFromGatewayResponse, ARBITRUM_SEPOLIA } from "@payperbyte/sdk";

const res    = await fetch(url, { headers: paymentHeaders }); // 결제된 호출
...

지갑이나 네트워크 없이도 오프라인에서 이 메커니즘을 증명할 수 있습니다. 샘플 영수증에 서명한 다음, 이를 검증하고 두 가지 공격을 테스트하십시오:

verify-before-act:
  genuine        → verified=true    수신된 바이트가 증명된 해시(attested hash) 및 서명자와 일치함 — 실행해도 안전함
  tampered byte  → verified=false   해시 불일치 (HASH MISMATCH) — 실행하지 마십시오
...

정상적인 것은 수락하고, 변조되거나 위조된 것은 거부하십시오. 그것이 게이트웨이의 역할입니다.

솔직한 고백: 진실이 아닌 출처(provenance)

이 점은 매우 중요하므로 명확히 짚고 넘어가야 합니다. 많은 "검증된 데이터" 피치(pitch)들이 이 부분을 모호하게 만들기 때문입니다:

• 영수증은 해당 바이트가 귀하가 지정한 증명자(attester)에 의해 서명되었으며, 원본 그대로이고 변경되지 않았음을 증명합니다. 변조 방지(Tamper-evident), 서명자 고정(signer-pinned), 재계산 가능(recomputable)합니다.
• 영수증은 데이터가 정확함을 증명하지는 않습니다. 잘못된 숫자에 대해 정상적인 영수증이 발행될 수 있습니다. 즉, 바이트는 원본이지만 값은 쓰레기(garbage value)일 수 있다는 뜻입니다.

따라서 주장은 좁지만 유용합니다: _"이것은 판매자가 서명한 실제 바이트입니다"_라고 말하는 것이지, _"이 숫자가 맞습니다"_라고 말하는 것이 아닙니다. 판매자를 신뢰할지 여부는 여전히 귀하의 결정입니다. 영수증은 단지 귀하가 판매자의 실제 바이트를 받았는지에 대한 의문을 제거해 줄 뿐입니다. 귀하의 사용자들에게 어떤 의미인지 명확히 전달하십시오.

모두를 넘어뜨리는 단 하나의 함정

EIP-712 서명 도메인 (signing domain)은 서명 복구 (signature recovery)를 위한 _고정된 서명 네임스페이스 (frozen signing namespace)_인 **chainId 421614 (Arbitrum Sepolia)**에 고정되어 있습니다. 이것은 결제 체인 (settlement chain)이 아닙니다. 결제는 Base 메인넷의 USDC로 정산됩니다. 따라서 돈은 Base에서 이동하더라도 검증기 (verifier)에는 ARBITRUM_SEPOLIA를 전달해야 합니다. 복구는 도메인에서 일어나고, 정산은 레일 (rail)에서 일어납니다. 이 둘을 혼동하면 서명이 복구되지 않을 것입니다. 여기서 5분 정도 혼란을 겪을 수 있지만, 한 번 익히고 나면 다시는 실수하지 않을 것입니다.

오늘은 테스트넷, 준비되면 메인넷으로

기본값은 **base-sepolia**로 설정하십시오. 공개 x402 퍼실리테이터 (facilitator)는 테스트넷을 광고하므로, 키 없이도 테스트넷 USDC를 사용하여 전체 402 → pay → 200 → receipt 루프를 무료로 작동시킬 수 있습니다. (메인넷 퍼실리테이터가 없는 Base 메인넷에서는 유료 경로가 올바르게 실패 처리됩니다.)

Base 메인넷의 실제 USDC를 사용하려면 Coinbase CDP 퍼실리테이터를 지정하십시오:

NETWORK=base
FACILITATOR_AUTH=cdp
CDP_API_KEY_ID=...
...

저는 이를 Base 메인넷에서 엔드 투 엔드 (end-to-end)로 실행했습니다. 402는 정식 Base USDC 자산인 network: eip155:8453을 광고하며, 귀하의 payTo로 연결됩니다. 테스트넷에서 개발하고, 메인넷으로 전환할 때는 환경 변수 블록 하나만 바꾸십시오. 그것이 유일한 변경 사항입니다.

1초 만에 시도하기

설치도, 지갑도 필요 없습니다. 로컬에서 전체 accept-genuine / refuse-tampered 루프를 확인해 보세요:

npx @foreseal/demo

이 명령은 오프라인에서 실행되며, 에이전트가 유효한 바이트에는 **동작(act)**하고, 변조된 바이트, 위조된 서명, 누락된 영수증, 그리고 포크된 서명 도메인 (forked signing domain)에 대해서는 **거부(refuse)**하는 모습을 약 1초 만에 보여줍니다.

더 나아가기

• MCP를 통해 데이터를 구매해야 하는 **AI 에이전트 (AI agent)**를 구축 중이신가요? byte-mcp-server (MIT)는 Claude Desktop / Claude Code / Cursor에 즉시 사용 가능한 buy → verify-before-act (구매 후 실행 전 검증) 도구를 제공합니다.
• 직접 조립하는 대신, 이미 연결되어 바로 배포 가능한 버전을 원하시나요? 저는 두 가지 스타터 키트를 패키징했습니다. x402 + verify-before-act Express 키트와 MCP 에이전트 키트 (서버 + 예제 + 배포/통합 가이드 포함)이며, 각각 39달러입니다. 위의 라이브러리들은 MIT 라이선스로 계속 무료로 유지되지만, 키트는 이들을 연결하는 데 소요될 시간을 아껴주는 도구입니다.

어떤 방식이든: 만약 당신의 코드가 비용을 지불한 데이터에 따라 동작한다면, 먼저 검증하십시오. 출처 (Provenance) 확인은 저렴하지만, 변조된 바이트 (tampered bytes)에 따라 동작하는 비용은 결코 저렴하지 않습니다.

질문이나 수정 사항은 댓글로 언제든 환영합니다 — 잘못된 상태로 두느니 차라리 수정하는 편을 택하겠습니다.