5분 가이드
빠른 시작 가이드
x402를 프로젝트에 통합하여 AI 에이전트로부터 수익을 창출하세요.
공식 SDK: 이 가이드는 @x402 공식 패키지를 사용합니다. 자세한 API 레퍼런스는 Coinbase 공식 문서를 참조하세요.
사전 준비
- 1
웹 애플리케이션
Next.js, Express, Hono 등 Node.js 기반 프레임워크
- 2
암호화폐 지갑 주소
USDC를 받을 Base 네트워크 지갑 (MetaMask, Coinbase Wallet 등)
- 3
Node.js 18+
최신 LTS 버전 권장
Step 1
패키지 설치
사용하는 프레임워크에 맞는 패키지를 설치하세요:
# Next.js 프로젝트
npm install @x402/next
# Express 프로젝트
npm install @x402/express
# Hono 프로젝트
npm install @x402/hono
# 클라이언트 (AI 에이전트 개발 시)
npm install @x402/fetchStep 2
환경 변수 설정
.env.local 파일에 필수 환경 변수를 설정하세요:
# .env.local
# 네트워크 설정
# 테스트넷 (개발용): base-sepolia
# 메인넷 (프로덕션): base
NETWORK=base-sepolia
# 결제를 받을 지갑 주소
RECEIVING_WALLET_ADDRESS=0xYourWalletAddress
# 퍼실리테이터 URL (선택사항)
# Coinbase CDP 사용 시 별도 설정 불필요
FACILITATOR_URL=https://x402.org/facilitator테스트넷 먼저: 개발 시에는 base-sepolia를 사용하세요. 프로덕션 배포 시 base로 변경합니다.
Step 3
미들웨어 설정 (Next.js)
프로젝트 루트에 middleware.ts 생성:
// middleware.ts
import { paymentMiddleware } from "@x402/next";
// 환경 변수 로드
const network = process.env.NETWORK || "base-sepolia";
const payTo = process.env.RECEIVING_WALLET_ADDRESS!;
const facilitatorUrl = process.env.FACILITATOR_URL;
// 경로별 결제 요구사항 정의
export const middleware = paymentMiddleware(
{
"GET /docs/:path*": {
price: "$0.01", // USDC 금액
network: network,
description: "문서 접근",
},
"GET /api/premium/:path*": {
price: "$0.02",
network: network,
description: "프리미엄 API",
},
},
{
payTo: payTo,
facilitatorUrl: facilitatorUrl,
}
);
export const config = {
matcher: ["/docs/:path*", "/api/premium/:path*"],
};대안
Express 서버 설정
// server.ts
import express from "express";
import { paymentMiddleware } from "@x402/express";
const app = express();
// 결제 미들웨어 적용
app.use(paymentMiddleware({
"GET /api/premium": {
price: "$0.01",
network: process.env.NETWORK || "base-sepolia",
payTo: process.env.RECEIVING_WALLET_ADDRESS!,
description: "Premium API endpoint",
},
}));
// 보호된 엔드포인트
app.get("/api/premium", (req, res) => {
res.json({ data: "Premium content" });
});
app.listen(3000);Step 4
테스트 및 배포
# 로컬 테스트
npm run dev
# 배포 (Vercel)
vercel deploy
# 배포 (기타)
npm run build && npm start보안 주의사항
- 프라이빗 키를 코드에 절대 하드코딩하지 마세요. 환경 변수를 사용하세요.
- 최대 결제 한도(maxPaymentAmount)를 설정하여 예상치 못한 대량 결제를 방지하세요.
- 프로덕션 배포 전 테스트넷(base-sepolia)에서 충분히 테스트하세요.
- 사용자에게 정확한 비용을 미리 표시하세요 (402 응답의 가격 정보 활용).
퍼실리테이터 설정 (선택)
Coinbase CDP 퍼실리테이터를 사용하면 Base 메인넷에서 수수료 없이 USDC 정산을 받을 수 있습니다.
- 1.Coinbase CDP Portal에서 계정 생성
- 2.x402 프로젝트 생성 및 API 키 발급
- 3.
FACILITATOR_URL환경 변수에 CDP 엔드포인트 설정
팁: 퍼실리테이터 없이도 x402를 사용할 수 있습니다. 기본 설정으로 시작하고, 필요시 퍼실리테이터를 추가하세요.
설정 완료!
이제 프로젝트에 x402가 적용되었습니다. 접근 방식에 따라 다르게 동작합니다:
사람 (브라우저)
JavaScript 검증 통과 → 무료 접근
AI 에이전트
402 응답 → USDC 결제 → 콘텐츠 접근