Kora와 x402 통합

구축할 내용

이 가이드는 Kora, 즉 Solana 가스 없는 서명 인프라와 완전한 x402(HTTP 402 Payment Required) 통합을 구현하는 과정을 안내합니다. 완료하면 다음과 같은 작동 시스템을 갖추게 됩니다:

• 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 호출당 센트의 일부만 지불
• AI 에이전트가 API 호출 비용을 지불할 수 있도록 함: AI 에이전트로 API 호출 비용 지불
• 구독 불필요: 사용자는 사용한 만큼만 지불
• Web3 결제: 온체인에서 투명하고 검증 가능한 결제
• 표준 HTTP: 결제가 필요할 때 HTTP 402 상태 코드를 사용하여 기존 웹 인프라와 작동

API 액세스에 대한 소액 결제를 요구하기 위해 x402를 사용하는 서버는 결제가 필요할 때 HTTP 402 상태 코드를 반환합니다. 보호된 엔드포인트에 액세스하려면 클라이언트는 X-PAYMENT 헤더에 유효한 결제를 서버에 전달해야 합니다. x402는 "촉진자"에 의존하여 트랜잭션을 검증하고 정산하므로 서버가 블록체인 인프라와 직접 상호작용할 필요가 없습니다.

퍼실리테이터 이해하기

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

퍼실리테이터의 역할:

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

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

Kora란 무엇인가요?

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

Kora의 주요 기능:

• 가스리스 트랜잭션: 사용자가 트랜잭션 실행을 위해 SOL이 필요하지 않음
• 수수료 추상화: USDC 또는 기타 SPL 토큰으로 수수료 지불
• JSON-RPC 인터페이스: 트랜잭션 처리를 위한 간단한 HTTP API
• 유연한 서명자: 여러 서명자 백엔드 지원(메모리, Vault, Turnkey, Privy)
• 정책 엔진: 트랜잭션 검증 및 수수료 정책에 대한 세밀한 제어

x402의 맥락에서 Kora는 퍼실리테이터를 위한 완벽한 백엔드 역할을 합니다. 네트워크 수수료를 처리하고, 트랜잭션에 서명하며, 트랜잭션을 검증합니다. Kora는 서명하기 전에 모든 트랜잭션을 검사하기 때문에, Kora 노드는 추가적인 보안 계층과 트랜잭션 검증 및 수수료 정책에 대한 보다 세밀한 제어를 제공합니다.

아키텍처 개요

x402 + Kora 통합은 완전한 요청/응답 주기를 가진 네 가지 상호 연결된 구성 요소로 이루어져 있습니다:

전체 결제 흐름:

1. 클라이언트가 보호된 리소스를 요청 → API가 402 Payment Required 응답 반환
2. 클라이언트가 x402 fetch 래퍼로 결제 트랜잭션 생성 (결제 명령이 포함된 Solana 트랜잭션 조립)
3. 클라이언트가 검증을 위해 Facilitator에 결제 전송
4. Facilitator가 Kora를 통해 검증하고, Kora가 서명 후 Solana에 제출
5. 트랜잭션이 온체인에서 확인되면 Facilitator가 API에 알림
6. API가 결제 영수증과 함께 보호된 콘텐츠를 클라이언트에 반환

구성 요소 분석

1. Kora RPC 서버 (포트 8080)

   • 핵심 가스리스 트랜잭션 서비스
   • 수수료 지불자로서 트랜잭션 서명 처리
   • 구성된 정책에 따라 트랜잭션 검증

2. Facilitator 래퍼/프록시 서버 (포트 3000)

   • Kora를 x402 프로토콜에 맞게 조정
   • /verify, /settle, /supported 엔드포인트 구현
   • x402와 Kora 데이터 형식 간 변환

3. 보호된 API (포트 4021)

   • 결제로 보호된 엔드포인트를 가진 데모 API 서버
   • 결제 처리를 위한 x402-express 미들웨어 사용
   • 성공적인 결제 후에만 데이터 반환

4. 클라이언트 애플리케이션

   • x402 fetch 래퍼 사용 예시
   • 사용자의 개인 키로 트랜잭션 서명

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

사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하세요:

• Rust (최신 안정 버전)
• Node.js (LTS 이상)
• Kora CLI (최신 버전 - cargo install kora-cli)
• pnpm (최신 버전)
• Solana 트랜잭션 및 SPL 토큰에 대한 기본 이해

프로젝트 설정

1단계: Kora 클론 및 빌드

중요: Kora의 main 브랜치는 통합 브랜치로 미출시 또는 베타 변경 사항이 포함될 수 있습니다. 항상 최신 안정 릴리스 태그를 사용하세요. 최신 안정 릴리스는 Kora 릴리스 페이지에서 확인할 수 있습니다.

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

# Checkout the latest stable tag
git checkout v2.0.5

# Build and install Kora
just install

이 명령어는 kora 바이너리를 시스템에 설치하며, 이를 사용하여 RPC 서버를 실행합니다.

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

cd examples/x402/demo

3단계: 의존성 설치

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

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

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

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

4단계: 환경 구성

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

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

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

pnpm run setup

이 명령어는 키페어를 생성하고 .env 파일에 추가합니다:

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

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

kora.toml

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

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

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

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

[kora.auth]
api_key = "kora_facilitator_api_key_example"

3. 수수료 지불자 정책: 세밀한 제어를 사용하여 원치 않는 트랜잭션 서명을 제한하도록 구성되었습니다:

[validation.fee_payer_policy.system]
allow_transfer = false
allow_assign = false
allow_create_account = false
allow_allocate = false

[validation.fee_payer_policy.system.nonce]
allow_initialize = false
allow_advance = false
allow_authorize = false
allow_withdraw = false

[validation.fee_payer_policy.spl_token]
allow_transfer = false
allow_burn = false
allow_close_account = false
allow_approve = false
allow_revoke = false
allow_set_authority = false
allow_mint_to = false
allow_initialize_mint = false
allow_initialize_account = false
allow_initialize_multisig = false
allow_freeze_account = false
allow_thaw_account = false

[validation.fee_payer_policy.token_2022]
allow_transfer = false
allow_burn = false
allow_close_account = false
allow_approve = false
allow_revoke = false
allow_set_authority = false
allow_mint_to = false
allow_initialize_mint = false
allow_initialize_account = false
allow_initialize_multisig = false
allow_freeze_account = false
allow_thaw_account = false

4. 허용된 프로그램: 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 서명자를 구성합니다. 이 파일을 변경할 필요는 없지만 다음 설정을 확인할 수 있습니다:

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

[[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를 요청해야 합니다.

데모 실행하기

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

터미널 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: Facilitator 시작

다음 명령을 실행하여 Facilitator를 시작하세요:

pnpm run start:facilitator

다음과 같이 표시됩니다:

Server listening at http://localhost:3000

터미널 3: Protected API 시작

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

pnpm run start:api

다음과 같이 표시됩니다:

Server listening at http://localhost:4021

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

pnpm run demo

구현 이해하기

성공적인 결제 흐름에서 발생하는 과정은 다음과 같습니다:

1. 클라이언트 요청 → API가 결제 요구사항과 함께 402를 반환
2. 결제 생성 → 클라이언트가 결제가 포함된 Solana 트랜잭션 생성
3. 결제 제출 → 클라이언트가 X-PAYMENT 헤더에 결제 정보를 담아 서버로 요청 전송
4. 검증 → Facilitator가 Kora의 signTransaction를 통해 검증
5. 정산 → Facilitator가 Kora의 signAndSendTransaction를 통해 정산(결제 트랜잭션을 Solana로 전송)
6. 접근 허용 → Facilitator가 트랜잭션 서명을 반환하고 API가 결제 영수증과 함께 보호된 콘텐츠 반환

트랜잭션 흐름

출처: x402 GitHub

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

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

Facilitator 래퍼/프록시 서버

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

Facilitator(facilitator/src/facilitator.ts)는 x402 프로토콜과 Kora RPC 사이의 브리지입니다. 세 가지 주요 엔드포인트를 구현합니다:

1. /verify 엔드포인트

이 엔드포인트는:

• Protected 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의 결합은 기존 웹 인프라에 솔라나의 강력한 기능을 제공합니다.

계속 구축하기

• 가격 사용자 지정: API를 수정하여 엔드포인트마다 다른 금액을 청구하세요
• 여러 토큰 추가: Kora를 구성하여 결제 시 다양한 SPL 토큰을 수락하도록 하세요
• 프로덕션 배포: 프로덕션 서명자(Vault, Turnkey 또는 Privy)를 사용하여 메인넷에 배포하세요
• 자체 API 구축: x402 결제를 통해 수익을 창출하는 실제 서비스를 만드세요

추가 리소스

x402 프로토콜

• x402 문서
• x402 GitHub
• x402 TypeScript SDK

Kora

• Kora 구성 가이드
• Kora 서명자 가이드
• Kora API 참조

솔라나

• 솔라나 문서
• SPL Token Program

지원

도움이 필요하신가요?

• kora 및 x402 태그와 함께 Solana Stack Exchange에 질문하세요
• Kora GitHub 리포지토리에서 이슈를 등록하세요