x402와 agentwallet-sdk를 사용한 유료 API 엔드포인트 구축: 개발자 가이드

I’m ready to translate the article for you, but I’ll need the text you’d like translated. Could you please paste the content you want converted to Korean (excluding the source line you’ve already provided)? Once I have the text, I’ll keep the source link at the top and translate the rest while preserving all formatting, markdown, and technical terms.

x402가 실제로 무엇인지

x402는 HTTP‑네이티브 결제 프로토콜입니다. 클라이언트가 자금이 첨부되지 않은 유료 엔드포인트에 접근하면, 서버는 기계가 읽을 수 있는 결제 페이로드와 함께 402 응답을 반환합니다. 클라이언트는 결제를 수행하고, 결제 증명을 포함해 요청을 다시 시도하면 리소스를 받게 됩니다—리다이렉트도, OAuth 절차도, 별도의 청구 API도 필요 없습니다.

Coinbase는 몇 달 동안 x402를 프로덕션에서 운영하며 1억 1500만 건 이상의 마이크로페이먼트를 처리했습니다. Stripe는 최근 통합 지원을 발표했으며, 이를 통해 x402가 실험적인 Web3 개념에서 주류 인프라로 이동하고 있습니다.

프로토콜이 HTTP 계층에서 동작하기 때문에 언어에 구애받지 않으며 기존의 모든 HTTP 클라이언트와 함께 사용할 수 있습니다. 에이전트가 fetch() 호출을 할 수 있다면 API 접근에 대한 결제를 할 수 있습니다.

비수탁형이 올바른 아키텍처인 이유

대부분의 결제 통합은 여러분의 자금을 대신 보관합니다. 수탁형 지갑은 제3자가 여러분의 키를 보유한다는 의미입니다. 인간 사용자에게는 사소한 불편일 수 있지만, 24시간 운영되는 자율 에이전트에게는 단일 장애 지점과 신뢰 병목을 초래합니다.

agentwallet‑sdk는 다른 접근 방식을 취합니다: 에이전트가 자체 개인 키를 보유하고 로컬에서 결제를 서명합니다. 암호학적 증명 외에는 에이전트에서 아무것도 나가지 않습니다. 이는 다음을 의미합니다:

• 지출을 승인하기 위해 지갑 서비스에 API 호출이 없음
• 수탁형 제공자의 속도 제한이나 장애가 없음
• 에이전트가 “본부에 연락” 없이 완전 자율적으로 작동 가능
• 모든 결제가 체인 상에서 감사 가능

이러한 아키텍처는 에이전트가 다른 에이전트를 고용하거나, 데이터를 구매하거나, 몇 초마다 마이크로트랜잭션을 정산하는 에이전시 워크플로우에 필수적입니다. 수탁형 솔루션은 이러한 패턴에 전혀 확장되지 않습니다.

Source: …

코드 워크스루

설치

npm install agentwallet-sdk

에이전트 지갑 초기화

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({
  // Agent가 자체 키를 생성하고 보관합니다
  privateKey: process.env.AGENT_PRIVATE_KEY,
  // 낮은 수수료를 위해 Base를 권장합니다
  defaultChain: "base",
});

console.log("Agent address:", wallet.address);

유료 API 엔드포인트 생성 (서버 측)

import express from "express";
import { x402Middleware } from "agentwallet-sdk/middleware";

const app = express();

// 이 엔드포인트를 $0.001 결제 요구 조건으로 보호합니다
app.use(
  "/api/premium-data",
  x402Middleware({
    price: "0.001",
    currency: "USDC",
    chain: "base",
    receiverAddress: process.env.MY_WALLET_ADDRESS,
  })
);

app.get("/api/premium-data", (req, res) => {
  res.json({ data: "This is paid content", timestamp: Date.now() });
});

유료 엔드포인트 호출 (에이전트 측)

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({ privateKey: process.env.AGENT_PRIVATE_KEY });

// SDK가 402 → 결제 → 재시도 흐름을 자동으로 처리합니다
const response = await wallet.fetch("https://api.example.com/api/premium-data");
const data = await response.json();

curl 로 테스트

첫 번째 호출은 402 응답을 반환합니다:

curl -i https://api.example.com/api/premium-data
# HTTP/1.1 402 Payment Required
# x402-payment-payload: {...}

SDK가 결제를 자동으로 처리하면 에이전트는 402 응답을 보지 못합니다—재시도가 투명하게 이루어집니다.

지원되는 체인

SDK는 현재 17개의 네트워크를 지원합니다. 주요 체인은 다음과 같습니다:

전체 지원 체인 목록은 SDK 문서에서 확인할 수 있습니다.

더 큰 그림

x402와 비보관 지갑을 결합하면 에이전트 경제에 적합한 원시 기능을 제공합니다. 에이전트는 유료 API를 발견하고, 소비한 만큼 정확히 비용을 지불하며, 인간 개입 없이 이를 수행할 수 있습니다.

청구 부서나 구독 시스템이 필요 없습니다. API는 호출당 요금을 부과하고, 에이전트는 호출당 비용을 지불하며, 전체 과정은 중개자 없이 온체인에서 실행됩니다.

시작하기

npm install agentwallet-sdk

SDK는 MIT‑라이선스를 따릅니다. 소스 코드, 예제, 그리고 체인 문서는 npm에 호스팅됩니다. 질문 및 풀 리퀘스트를 환영합니다.