Интеграция протокола Solana x402 с Kora RPC

Что вы создадите

В этом руководстве описана полная реализация интеграции x402 (HTTP 402 Payment Required) с Kora — инфраструктурой безгазовой подписи Solana. По завершении у вас будет рабочая система, в которой:

API может взимать микроплатежи за доступ с использованием протокола x402
Пользователи платят в USDC, не нуждаясь в SOL для оплаты газа
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 — это открытый платёжный стандарт, обеспечивающий бесшовные микроплатежи за доступ к API. Вместо традиционных моделей подписки или API-ключей x402 позволяет серверам взимать плату за отдельные вызовы API, создавая настоящую инфраструктуру оплаты по факту использования.

Ключевые преимущества x402:

Мгновенные микроплатежи: Оплата долей цента за каждый вызов API
Поддержка платежей для ИИ-агентов: Оплата вызовов 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 Payment Required
Клиент создаёт платёжную транзакцию с помощью обёртки x402 fetch (которая формирует транзакцию Solana с платёжной инструкцией)
Клиент отправляет платёж фасилитатору для верификации
Фасилитатор выполняет валидацию через Kora, которая подписывает и отправляет транзакцию в Solana
Транзакция подтверждена в сети, фасилитатор уведомляет API
API возвращает защищённый контент с квитанцией об оплате клиенту

Разбор компонентов

Kora RPC Server (Порт 8080)
- Основной сервис безгазового выполнения транзакций
- Обрабатывает подписание транзакций в роли плательщика комиссий
- Валидирует транзакции согласно настроенным политикам
Facilitator Wrapper/Proxy Server (Порт 3000)
- Адаптирует Kora к протоколу x402
- Реализует эндпоинты /verify, /settle и /supported
- Преобразует данные между форматами x402 и Kora
Protected 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

При этом в вашу систему устанавливается бинарный файл kora, который мы будем использовать для запуска RPC-сервера.

Шаг 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 SDK, чтобы использовать TypeScript SDK Kora в фасилитаторе:

pnpm run build:kora-sdk

Шаг 5: Настройка окружения

Демо включает файл .env.example с необходимыми переменными окружения. Сначала настроим базовую конфигурацию:

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

Теперь вам нужно сгенерировать или предоставить 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 Server. Вносить изменения в этот файл не требуется, но вы можете проверить следующие параметры:

Платёжный токен: Убедитесь, что минт Devnet USDC находится в списке разрешённых:

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

Аутентификация API: В демо используется API-ключ для доступа к Kora. Он должен совпадать с KORA_API_KEY в файле .env:

[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, associated token program и compute budget 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 установлена в 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 для оплаты комиссий за транзакции. Вы можете выполнить airdrop devnet SOL на адрес подписанта Kora с помощью Solana CLI:

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

Также можно воспользоваться Solana Faucet для airdrop SOL на адрес подписанта Kora.

Devnet USDC

Ваш PAYER_ADDRESS, указанный в файле .env, потребует USDC для оплаты комиссий за транзакции.

Получите Devnet USDC из Circle's Faucet. Обязательно выберите «Solana Devnet» и укажите ваш PAYER_ADDRESS для запроса USDC.

Запуск демо

Для запуска всех компонентов из директории docs/x402/demo вам понадобятся четыре окна терминала.

Терминал 1: Запуск Kora RPC Server

Выполните следующую команду для запуска Kora RPC Server:

pnpm run start:kora

Вы должны увидеть серию логов, подтверждающих запуск Kora RPC Server, в том числе:

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
Верификация → Фасилитатор проверяет через signTransaction Kora
Исполнение → Фасилитатор исполняет через signAndSendTransaction Kora (отправляя платёжную транзакцию в Solana)
Доступ предоставлен → Фасилитатор возвращает подпись транзакции, а API возвращает защищённый контент с квитанцией об оплате

Давайте подробно рассмотрим, как работает каждый компонент:

Kora RPC (Порт 8080): Обрабатывает безгазовое подписание транзакций
Facilitator (Порт 3000): Связывает протокол x402 с Kora
Protected API (Порт 4021): Ваш монетизированный эндпоинт API
Клиент: Демонстрирует автоматический платёжный поток

Facilitator Wrapper/Proxy Server

Фасилитатор работает на порту 3000. Это сервер, обрабатывающий взаимодействие с Solana (в нашем случае через Kora). Он используется для верификации и исполнения x402-платежей.

Фасилитатор (facilitator/src/facilitator.ts) является мостом между протоколом x402 и Kora RPC. Он реализует три ключевых эндпоинта:

1. Эндпоинт `/verify`

Этот эндпоинт:

Получает платёжные данные x402 от сервера защищённого API
Извлекает транзакцию Solana с помощью вспомогательных инструментов x402
Использует signTransaction Kora для проверки корректности без широковещательной рассылки
Возвращает статус верификации, isValid

2. Эндпоинт `/settle`

Этот эндпоинт:

Получает платёжные данные x402 после того, как платёж был верифицирован эндпоинтом /verify
Использует signAndSendTransaction Kora для подписания и широковещательной рассылки транзакции
Возвращает подпись транзакции как подтверждение исполнения

3. Эндпоинт `/supported`

Этот эндпоинт фактически анонсирует возможности фасилитатора, включая:

Поддерживаемую версию x402
Схему платежей (точные платежи)
Сеть (solana-devnet)
Адрес плательщика комиссий, который мы получаем из Kora с помощью метода getPayerSigner

Защищённый 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 включает поддержку middleware для многих популярных фреймворков. Подробнее см. в разделе x402 TypeScript Packages.

Клиентское приложение

Клиент (client/src/index.ts) демонстрирует, как автоматически работает x402, отправляя запрос с помощью стандартного вызова fetch, а затем повторяя запрос через обёртку оплаты:

// 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
Возвращает успешный ответ

Подводим итоги

Поздравляем! 🔥 Вы успешно реализовали полный платёжный процесс x402 с использованием безгазовой инфраструктуры Kora. Этот пример показывает, как:

Протокол x402 обеспечивает беспрепятственную монетизацию API через микроплатежи
Kora RPC выступает в роли фасилитатора для платежей x402, выполняя проверку и расчёт транзакций
Пользователи могут оплачивать доступ к API, не держа SOL и не управляя газовыми комиссиями

Эта архитектура создаёт мощную основу для:

Маркетплейсов AI-агентов
API с оплатой за использование
Контентных платформ с микроплатежами
Тарификации SaaS на основе потребления
Любых сервисов, требующих мгновенных и верифицируемых платежей

Сочетание x402 и Kora привносит мощь Solana в традиционную веб-инфраструктуру.

Продолжайте разработку

Настройте ценообразование: изменяйте API для взимания разных сумм на разных эндпоинтах
Добавьте несколько токенов: настройте Kora для приёма различных SPL-токенов в качестве оплаты
Продакшн-развёртывание: разверните в основной сети с продакшн-подписантами (Vault, Turnkey или Privy)
Создайте собственный API: разработайте реальный сервис с монетизацией через платежи x402

Задавайте вопросы на Solana Stack Exchange с тегами kora и x402
Открывайте задачи в репозитории Kora на GitHub

Интеграция x402 с Kora — полное руководство по демо