Solana x402 프로토콜과 Kora RPC 통합

빌드할 내용

이 가이드는 Kora(Solana 가스리스 서명 인프라)와 함께 완전한 x402(HTTP 402 결제 필요) 통합을 구현하는 과정을 안내합니다. 가이드를 마치면 다음과 같은 작동 시스템을 갖추게 됩니다:

API가 x402 프로토콜을 사용하여 액세스에 대한 소액 결제를 청구할 수 있습니다
사용자는 가스 수수료를 위한 SOL 없이 USDC로 결제합니다
Kora가 가스리스 퍼실리테이터로서 모든 트랜잭션 수수료를 처리합니다
결제는 Solana 블록체인에서 원자적으로 정산됩니다

최종 결과물은 완전히 기능하는 결제 보호 API입니다:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
X402 + KORA PAYMENT FLOW DEMONSTRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/4] Initializing payment signer
  → Network: solana-devnet
  → Payer address: BYJV...TbBc
  ✓ Signer initialized

[2/4] Attempting to access protected endpoint without payment
  → GET http://localhost:4021/protected
  → Response: 402 Payment Required
  ✅ Status code: 402

[3/4] Accessing protected endpoint with x402 payment
  → Using x402 fetch wrapper
  → Payment will be processed via Kora facilitator
  → Transaction submitted to Solana
  ✅ Status code: 200

[4/4] Processing response data
  ✓ Payment response decoded

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUCCESS: Payment completed and API accessed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Response Data:
{
    "data": {
        "message": "Protected endpoint accessed successfully",
        "timestamp": "2025-09-25T20:14:04.242Z"
    },
    "status_code": 200,
    "payment_response": {
        "transaction": "5ULZpdeThaMAy6hcEGfAoMFqJqPpCtxdCxb6JYUV6nA4x8Lk2hKEuzofGUPoe1pop6BdWMSmF5oRPrXsbdWmpruf",
        "success": true,
        "network": "solana-devnet"
    }
}

x402란 무엇인가요?

x402는 API 액세스를 위한 원활한 소액 결제를 가능하게 하는 개방형 결제 표준입니다. 기존의 구독 모델이나 API 키 방식 대신, x402는 서버가 개별 API 호출에 대해 요금을 청구할 수 있게 하여 진정한 사용량 기반 인프라를 구현합니다.

x402의 주요 이점:

즉각적인 소액 결제: API 호출당 1센트 미만의 금액 결제
AI 에이전트의 API 호출 결제 지원: AI 에이전트로 API 호출 비용 결제
구독 불필요: 사용자는 사용한 만큼만 결제
Web3 결제: 온체인에서 투명하고 검증 가능한 결제
표준 HTTP: 결제가 필요한 경우 HTTP 402 상태 코드를 사용하여 기존 웹 인프라와 함께 작동

x402를 사용하여 API 액세스에 소액 결제를 요구하는 서버는 결제가 필요한 경우 HTTP 402 상태 코드를 반환합니다. 보호된 엔드포인트에 액세스하려면 클라이언트가 X-PAYMENT 헤더에 유효한 결제 정보를 서버에 전달해야 합니다. x402는 서버가 블록체인 인프라와 직접 상호작용하지 않아도 되도록 트랜잭션을 검증하고 정산하는 "퍼실리테이터"에 의존합니다.

퍼실리테이터 이해하기

퍼실리테이터는 x402 생태계의 핵심 구성 요소입니다. API 서버를 대신하여 블록체인 결제를 추상화하는 전문 서비스 역할을 합니다.

퍼실리테이터의 역할:

결제 검증: 클라이언트의 결제 페이로드가 올바르게 구성되었으며 충분한지 유효성 검사
복잡성 추상화: 서버가 블록체인 인프라(서명 및 네트워크 수수료 지불)와 직접 상호작용할 필요성 제거
트랜잭션 정산: 검증된 트랜잭션을 Solana(또는 다른 네트워크)에 제출

이 데모에서는 Kora를 활용하여 트랜잭션을 검증하고 정산하는 퍼실리테이터를 생성합니다(자세한 내용은 아래 참조).

Kora란 무엇인가요?

Kora는 서명 및 가스리스 트랜잭션 서비스를 제공하는 Solana 서명자 노드입니다. 애플리케이션이 가스 수수료를 추상화할 수 있게 하여, 사용자가 SOL 이외의 토큰으로 트랜잭션 비용을 지불하거나 수수료를 완전히 후원받을 수 있도록 합니다.

Kora의 주요 기능:

가스리스 트랜잭션: 사용자가 트랜잭션 실행을 위해 SOL이 필요하지 않음
수수료 추상화: USDC 또는 다른 SPL 토큰으로 수수료 결제
JSON-RPC 인터페이스: 트랜잭션 처리를 위한 간단한 HTTP API
유연한 서명자: 다양한 서명자 백엔드 지원(memory, Vault, Turnkey, Privy)
정책 엔진: 트랜잭션 유효성 검사 및 수수료 정책에 대한 세분화된 제어

x402의 맥락에서 Kora는 퍼실리테이터의 완벽한 백엔드 역할을 합니다: 네트워크 수수료를 처리하고, 트랜잭션에 서명하며, 트랜잭션을 검증합니다.

아키텍처 개요

x402 + Kora 통합은 완전한 요청/응답 사이클을 갖춘 네 가지 상호 연결된 구성 요소로 이루어집니다:

전체 결제 흐름:

클라이언트가 보호된 리소스 요청 → API가 402 결제 필요 반환
클라이언트가 x402 fetch 래퍼로 결제 트랜잭션 생성(결제 명령어가 포함된 Solana 트랜잭션 조립)
클라이언트가 검증을 위해 퍼실리테이터에 결제 전송
퍼실리테이터가 Kora를 통해 유효성 검사 후 서명하여 Solana에 제출
온체인에서 트랜잭션 확인, 퍼실리테이터가 API에 알림
API가 결제 영수증과 함께 보호된 콘텐츠를 클라이언트에 반환

구성 요소 분류

Kora RPC 서버 (포트 8080)
- 핵심 가스리스 트랜잭션 서비스
- 수수료 지불자로서 트랜잭션 서명 처리
- 구성된 정책에 따라 트랜잭션 유효성 검사
퍼실리테이터 래퍼/프록시 서버 (포트 3000)
- Kora를 x402 프로토콜에 맞게 조정
- /verify, /settle, /supported 엔드포인트 구현
- x402와 Kora 데이터 형식 간 변환
보호된 API (포트 4021)
- 결제 보호 엔드포인트를 갖춘 데모 API 서버
- 결제 처리를 위해 x402-express 미들웨어 사용
- 성공적인 결제 후에만 데이터 반환
클라이언트 애플리케이션
- x402 fetch 래퍼 사용법 시연
- 사용자의 개인 키로 트랜잭션 서명

다중 구성 요소 방식이 복잡해 보일 수 있지만, 결제 처리, API 서빙, 클라이언트 애플리케이션이 별도의 관심사로 분리된 실제 프로덕션 시스템을 반영합니다.

사전 요구 사항

시작하기 전에 다음을 확인하세요:

Rust (최신 안정 버전)
Node.js (LTS 이상)
pnpm (최신 버전)
Solana 트랜잭션 및 SPL 토큰에 대한 기본 이해

프로젝트 설정

1단계: Kora 복제 및 빌드

# Clone the repository
git clone https://github.com/solana-foundation/kora.git
cd kora

# Checkout the release branch as Kora is currently in a feature freeze for audit
git checkout release/feature-freeze-for-audit

# Build and install Kora
make install

이 명령은 RPC 서버를 실행하는 데 사용할 kora 바이너리를 시스템에 설치합니다.

2단계: 데모 디렉터리로 이동

cd docs/x402/demo

3단계: 의존성 설치

모든 데모 구성 요소에 대한 Node.js 의존성 설치:

# Install dependencies for all components (facilitator, API, and client)
pnpm run install:all

이 스크립트는 다음에 대한 의존성을 설치합니다:

퍼실리테이터 래퍼 서비스
보호된 API 서버
클라이언트 데모 앱

4단계: Kora SDK 빌드

퍼실리테이터에서 Kora TypeScript SDK를 사용할 수 있도록 Kora SDK를 빌드합니다:

pnpm run build:kora-sdk

5단계: 환경 구성

데모에는 필요한 환경 변수가 포함된 .env.example 파일이 있습니다. 먼저 기본 구성을 설정합니다:

# Copy the example environment file
cp .env.example .env

이제 데모를 위한 keypair를 생성하거나 제공해야 합니다. 다음 명령어를 실행하여 keypair를 생성하세요:

pnpm run setup

이 명령은 keypair를 생성하고 .env 파일에 추가합니다:

KORA_SIGNER_ADDRESS - Kora 서명자의 주소
KORA_SIGNER_PRIVATE_KEY - Kora 서명자의 개인 키
PAYER_ADDRESS - 보호된 API에 액세스하기 위해 결제할 지불자의 주소
PAYER_PRIVATE_KEY - 지불자의 개인 키

5단계: 구성 파일 업데이트

kora.toml

kora/kora.toml 파일은 Kora RPC 서버를 구성합니다. 이 파일을 변경할 필요는 없지만 다음 설정을 확인할 수 있습니다:

결제 토큰: Devnet USDC 민트가 허용 목록에 있는지 확인:

allowed_tokens = [
    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", # USDC devnet
]

API 인증: 데모는 Kora 액세스를 위해 API 키를 사용합니다. 이는 .env 파일의 KORA_API_KEY와 일치해야 합니다:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

수수료 지불자 정책: 원치 않는 트랜잭션 서명을 제한하도록 구성:

[validation.fee_payer_policy]
allow_sol_transfers = false
# all other settings are false

허용된 프로그램: System Program, Token Program, 연결된 토큰 프로그램 및 컴퓨팅 예산 프로그램이 허용 목록에 있는지 확인:

allowed_programs = [
    "11111111111111111111111111111111",             # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # Token Program
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program
    "ComputeBudget111111111111111111111111111111",  # Compute Budget Program
]

signers.toml

kora/signers.toml 파일은 Kora 서명자를 구성합니다. 이 파일을 변경할 필요는 없지만 다음 설정을 확인할 수 있습니다:

서명자 환경 변수: 서명자 환경 변수 private_key_env가 .env 파일의 환경 변수 이름과 일치하는 KORA_SIGNER_PRIVATE_KEY로 설정되어 있는지 확인하세요.

[[signers]]
name = "main_signer"
type = "memory"
private_key_env = "KORA_SIGNER_PRIVATE_KEY"
weight = 1

6단계: 계정 자금 조달

Devnet SOL

Kora 서명자 주소는 트랜잭션 수수료 지불을 위해 SOL이 필요합니다. Solana CLI를 사용하여 Kora 서명자 주소에 devnet SOL을 에어드랍할 수 있습니다:

# Airdrop SOL
solana airdrop 1 <KORA_SIGNER_ADDRESS> --url devnet

또는 Solana Faucet을 사용하여 Kora 서명자 주소에 SOL을 에어드랍할 수 있습니다.

Devnet USDC

.env 파일에 설정된 PAYER_ADDRESS는 트랜잭션 수수료 지불을 위해 USDC가 필요합니다.

Circle의 Faucet에서 Devnet USDC를 받으세요. "Solana Devnet"을 선택하고 PAYER_ADDRESS를 사용하여 USDC를 요청하세요.

데모 실행

docs/x402/demo 디렉터리에서 모든 구성 요소를 실행하려면 터미널 창이 네 개 필요합니다.

터미널 1: Kora RPC 서버 시작

다음 명령어를 실행하여 Kora RPC 서버를 시작합니다:

pnpm run start:kora

Kora RPC 서버가 실행 중임을 나타내는 일련의 로그가 표시되어야 합니다:

INFO kora_lib::rpc_server::server: RPC server started on 0.0.0.0:8080, port 8080

터미널 2: 퍼실리테이터 시작

다음 명령어를 실행하여 퍼실리테이터를 시작합니다:

pnpm run start:facilitator

다음이 표시되어야 합니다:

Server listening at http://localhost:3000

터미널 3: 보호된 API 시작

다음 명령어를 실행하여 보호된 API를 시작합니다:

pnpm run start:api

다음이 표시되어야 합니다:

Server listening at http://localhost:4021

터미널 4: 클라이언트 데모 실행

pnpm run demo

구현 내용 이해하기

성공적인 결제 흐름 중에 일어나는 일:

클라이언트 요청 → API가 결제 요구 사항과 함께 402 반환
결제 생성 → 클라이언트가 결제가 포함된 Solana 트랜잭션 생성
결제 제출 → 클라이언트가 X-PAYMENT 헤더에 결제 정보를 포함하여 서버에 요청 전송
검증 → 퍼실리테이터가 Kora의 signTransaction을 통해 검증
정산 → 퍼실리테이터가 Kora의 signAndSendTransaction을 통해 정산 (Solana에 결제 트랜잭션 전송)
액세스 허용 → 퍼실리테이터가 트랜잭션 서명을 반환하고 API가 결제 영수증과 함께 보호된 콘텐츠 반환

각 구성 요소가 어떻게 작동하는지 자세히 살펴보겠습니다:

Kora RPC (포트 8080): 가스리스 트랜잭션 서명 처리
퍼실리테이터 (포트 3000): x402 프로토콜과 Kora 연결
보호된 API (포트 4021): 수익화된 API 엔드포인트
클라이언트: 자동 결제 흐름 시연

퍼실리테이터 래퍼/프록시 서버

퍼실리테이터는 포트 3000에서 실행됩니다. 이 서버는 Solana와의 통신을 처리합니다(이 경우 Kora를 통해). x402 결제를 검증하고 정산하는 데 사용됩니다.

퍼실리테이터(facilitator/src/facilitator.ts)는 x402 프로토콜과 Kora RPC 사이의 브릿지입니다. 세 가지 핵심 엔드포인트를 구현합니다:

1. `/verify` 엔드포인트

이 엔드포인트는:

보호된 API 서버로부터 x402 결제 페이로드 수신
x402 헬퍼를 사용하여 Solana 트랜잭션 추출
Kora의 signTransaction을 사용하여 브로드캐스트 없이 유효성 검사
검증 상태 isValid 반환

2. `/settle` 엔드포인트

이 엔드포인트는:

/verify 엔드포인트에 의해 결제가 검증된 후 x402 결제 페이로드 수신
Kora의 signAndSendTransaction을 사용하여 트랜잭션 서명 및 브로드캐스트
정산 증명으로 트랜잭션 서명 반환

3. `/supported` 엔드포인트

이 엔드포인트는 퍼실리테이터의 기능을 효과적으로 알리며, 다음을 포함합니다:

지원되는 x402 버전
결제 방식(정확한 결제)
네트워크(solana-devnet)
getPayerSigner 메서드를 사용하여 Kora에서 가져온 수수료 지불자 주소

보호된 API

API 서버(api/src/api.ts)는 x402-express 미들웨어를 사용하여 엔드포인트를 보호합니다:

app.use(
  paymentMiddleware(
    KORA_PAYER_ADDRESS, // Where payments should go
    {
      "GET /protected": {
        price: "$0.0001", // Price in USD
        network: NETWORK // solana-devnet
      }
    },
    {
      url: FACILITATOR_URL // Our facilitator wrapper
    }
  )
);

미들웨어는:

보호된 엔드포인트(이 경우 /protected 엔드포인트)에 대한 요청 가로채기
결제가 없는 경우 402 상태 반환
퍼실리테이터를 통해 결제 유효성 검사 및 처리
성공적인 결제 후 액세스 허용

Express를 사용하고 있지만, x402 라이브러리는 다양한 공통 프레임워크에 대한 미들웨어 지원을 포함합니다. 자세한 내용은 x402 TypeScript 패키지를 참조하세요.

클라이언트 애플리케이션

클라이언트(client/src/index.ts)는 표준 fetch 호출로 요청을 전송한 후 결제 래퍼를 통해 요청을 재시도하는 방식으로 x402의 작동 방식을 자동으로 시연합니다:

// Create a signer from private key
const payer = await createSigner(NETWORK, PAYER_PRIVATE_KEY);

// Wrap fetch with x402 payment capabilities
const fetchWithPayment = wrapFetchWithPayment(fetch, payer);

// First attempt: Regular fetch (will fail with 402)
const expect402Response = await fetch(PROTECTED_API_URL);
console.log(`Status: ${expect402Response.status}`); // 402

// Second attempt: Fetch with payment wrapper (succeeds)
const response = await fetchWithPayment(PROTECTED_API_URL);
console.log(`Status: ${response.status}`); // 200

x402 fetch 래퍼:

402 응답 감지
보호된 API의 결제 요구사항에 따라 자동으로 결제 트랜잭션 생성
사용자의 개인 키로 서명
검증 및 처리를 위해 퍼실리테이터에게 결제 전송
x-payment-response 헤더에 결제 증명을 포함하여 요청 재시도
성공 응답 반환

마무리

축하합니다! 🔥 Kora의 가스리스 인프라를 활용하여 완전한 x402 결제 흐름을 성공적으로 구현했습니다. 이 데모는 다음을 보여줍니다:

x402 프로토콜은 소액 결제를 통해 마찰 없는 API 수익화를 가능하게 합니다
Kora RPC는 트랜잭션을 검증하고 정산함으로써 x402 결제의 퍼실리테이터 역할을 합니다
사용자는 SOL을 보유하거나 가스비를 관리하지 않고도 API 액세스 비용을 지불할 수 있습니다

이 아키텍처는 다음을 위한 강력한 기반을 형성합니다:

AI 에이전트 마켓플레이스
사용량 기반 API
소액 결제 콘텐츠 플랫폼
사용량 기반 SaaS 요금제
즉각적이고 검증 가능한 결제가 필요한 모든 서비스

x402와 Kora의 결합은 Solana의 강력한 기능을 전통적인 웹 인프라에 제공합니다.

계속 빌드하기

가격 커스터마이징: 엔드포인트별로 다른 금액을 청구하도록 API 수정
다중 토큰 추가: 다양한 SPL 토큰을 결제 수단으로 허용하도록 Kora 설정
프로덕션 배포: 프로덕션 서명자(Vault, Turnkey 또는 Privy)를 사용하여 메인넷에 배포
나만의 API 구축: x402 결제를 통해 수익화하는 실제 서비스 만들기

kora 및 x402 태그를 사용하여 Solana Stack Exchange에서 질문하세요
Kora GitHub 저장소에서 이슈를 등록하세요

x402와 Kora 통합 - 완전한 데모 가이드