x402 개발자 가이드: 유료 API 서비스 구축

Source: Dev.to

개요

이 가이드는 x402 프로토콜을 애플리케이션에 통합하여 유료 API 서비스를 구현하는 방법을 체계적으로 소개합니다. 튜토리얼을 마치면 전체 구현 방안을 숙지하고 x402의 결제 메커니즘을 깊이 이해하게 됩니다.

선행 조건

• Node.js 18+ 실행 환경
• EVM 호환 지갑 주소(결제 금액을 받을 용도)
• Base Sepolia 테스트넷 USDC(faucet.circle.com에서 무료로 받을 수 있음)

프로토콜 모델

x402은 삼자 협업 모델을 기반으로 합니다:

미들웨어는 핵심 컴포넌트로, 프로토콜 구현에 필요한 모든 복잡성을 담당합니다. 여기에는 결제 요구 생성, Facilitator와의 통신 조정, 결제 증명 검증이 포함됩니다.

미들웨어 핵심 기능

1. 미결제 요청

   • Accept 헤더를 기반으로 클라이언트 유형을 판단하고 해당 형식의 결제 요구를 반환
     • 브라우저(Accept: text/html) → 인터랙티브 결제 페이지를 렌더링하고 지갑 연결 및 승인 유도
     • 프로그래밍 요청(curl, fetch, AI Agent) → 구조화된 JSON 결제 요구 반환

2. 결제 완료 요청

   • X-PAYMENT 헤더에 포함된 결제 페이로드 파싱
   • Facilitator의 /verify 엔드포인트를 호출해 서명 유효성, 결제자 잔액, 결제 금액 일치 여부 등 다차원 검증 수행
   • 검증이 통과되면 즉시 콘텐츠 반환(200 OK), 이후 비동기로 /settle을 호출해 체인 상 자금 이체 완료

설계 포인트: 검증이 통과된 즉시 응답을 반환하므로 체인 정산을 기다릴 필요가 없어 사용자 경험이 크게 향상됩니다.

미들웨어와 Facilitator 인터페이스

위험 및 완화

• 위험 구간: 검증 통과와 정산 실행 사이에 결제자가 USDC를 이동시켜 정산이 실패할 수 있음.
• 위험 평가
  • 소액 시나리오($0.001‑$1): 위험이 통제 가능하며 기본 동작으로 충분.
  • 대액 시나리오($10+): 응답 전 정산을 완료하거나 에스크로(Escrow) 방식을 채택하는 맞춤 로직 구현 권장.

빠른 시작: Express 예제

npm install express x402-express

// app.js
import express from "express";
import { paymentMiddleware } from "x402-express";

const app = express();

// 수취 지갑 주소
const WALLET_ADDRESS = "0xYourWalletAddress";

// 유료 라우트 설정
app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/premium": {
        price: "$0.001",           // 가격(USD)
        network: "base-sepolia",   // 대상 블록체인 네트워크
        config: {
          description: "고급 데이터 인터페이스 접근",
        },
      },
    }
  )
);

// 보호된 비즈니스 엔드포인트
app.get("/api/premium", (req, res) => {
  res.json({
    message: "유료 콘텐츠에 오신 것을 환영합니다",
    data: { secret: "이 데이터는 $0.001 가치가 있습니다" },
  });
});

app.listen(4021, () => {
  console.log("서버가 시작되었습니다: http://localhost:4021");
});

미들웨어 자동 수행 내용:

• 미결제 요청에 402 상태 코드와 결제 요구 반환
• 브라우저 사용자에게 결제 화면 렌더링
• 결제 증명 검증 및 정산 수행
• 결제 성공 시 요청 통과

프레임워크 연동

지원 네트워크

공용 Facilitator(테스트 환경)

개발 단계에서는 x402.org가 제공하는 공용 Facilitator를 바로 사용할 수 있어 별도 설정이 필요 없습니다:

// 테스트 환경 즉시 사용
app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/test": {
        price: "$0.001",
        network: "base-sepolia", // 자동으로 x402.org Facilitator와 연동
      },
    }
  )
);

지원 네트워크는 base-sepolia와 solana-devnet을 포함합니다.

프로덕션 환경: Coinbase Facilitator

메인넷에 배포할 때는 Coinbase 공식 Facilitator와 연동해야 합니다:

1. Coinbase Developer Platform (CDP) 계정 등록
2. CDP API 자격증명(Key ID와 Secret) 발급

npm install @coinbase/x402

import { paymentMiddleware } from "x402-express";
import { facilitator } from "@coinbase/x402";

const WALLET_ADDRESS = "0xYourWalletAddress";

app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/premium": {
        price: "$0.10",
        network: "base", // 메인넷 환경
      },
    },
    facilitator // Coinbase 프로덕션 Facilitator 지정
  )
);

환경 변수 예시:

CDP_API_KEY_ID=your-key-id
CDP_API_KEY_SECRET=your-key-secret

프로그래밍 테스트: x402-fetch

npm install x402-fetch viem

// test.js
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } } from "x402-fetch";
import { baseSepolia } from "viem/chains";

const TEST_PRIVATE_KEY = "0xYourTestPrivateKey";

const account = privateKeyToAccount(TEST_PRIVATE_KEY);
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

const fetchWithPay = wrapFetchWithPayment(fetch, client);

async function test() {
  const response = await fetchWithPay("http://localhost:4021/api/premium");
  const data = await response.json();
  console.log("응답 데이터:", data);
}

test();

실행 흐름

1. 최초 요청 시 402 응답과 결제 요구를 수신
2. x402-fetch가 자동으로 결제 서명을 생성하고 X-PAYMENT 헤더를 포함해 재시도 요청
3. 보호된 리소스를 성공적으로 획득

브라우저에서 http://localhost:4021/api/premium에 직접 접근하면 결제 페이지가 표시되어 지갑 연결 및 승인을 유도합니다.

고급 커스터마이징: 직접 검증·정산 구현

위험 구간(검증 후 정산 전)을 완전히 없애려면 Facilitator를 우회하고 다음 절차를 직접 구현합니다:

1. X-PAYMENT 헤더 파싱
2. EIP‑712 서명 검증
3. 체인 상 결제자 USDC 잔액 조회
4. nonce 고유성 확인
5. USDC transferWithAuthorization 트랜잭션 구성 및 전송
6. 트랜잭션 확인 후 비즈니스 콘텐츠 반환

이 방식은 복잡도가 높으며 고가 거래, 에스크로 요구, 자체 규제 환경에 적합합니다.

흔히 묻는 질문(FAQ)

• 검증과 정산 사이에 결제자가 자금을 이동하는 경우

  • 소액 결제에서는 기본 동작으로 충분합니다. 대액 거래는 사전 정산 로직 구현 또는 에스크로 사용을 권장합니다.

• 네트워크 혼잡으로 트랜잭션 타임아웃 발생

  • 재시도 횟수를 늘리거나 가스 비용을 높여 보세요.

• Facilitator 서비스 장애

  • 헬스 체크를 모니터링하고 필요 시 예비 Facilitator(예: Coinbase)로 전환합니다.

• 프로덕션 로그 및 재시도

  • 결제 검증, 정산 요청, 응답 상태, 오류 정보를 기록하고 지수 백오프 재시도 전략을 적용하는 것이 좋습니다.

기타 자료

• 공식 기술 문서：
• 오픈소스 코드 저장소：
• 프로토콜 백서：
• 생태계 전반 해설：

위 단계들을 따라 하면 몇 줄의 미들웨어 설정만으로 유료 API를 구현할 수 있으며, 테스트넷에서 비즈니스 모델을 검증하고 프로덕션 환경으로 원활히 이전할 수 있습니다. 개발에 행운을 빕니다!