Интеграция x402 с Kora

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

Это руководство проведет вас через реализацию полной интеграции 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?

x402 — это открытый стандарт платежей, который обеспечивает бесшовные микроплатежи за доступ к API. Вместо традиционных моделей подписки или API-ключей x402 позволяет серверам взимать плату за отдельные вызовы API, создавая настоящую инфраструктуру с оплатой за использование.

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

Мгновенные микроплатежи: Платите доли цента за каждый вызов API
Возможность для AI-агентов оплачивать вызовы API: Оплачивайте вызовы API с помощью AI-агентов
Без подписок: Пользователи платят только за то, что используют
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 служит идеальным бэкендом для фасилитаторов: она обрабатывает комиссии сети, подписывает транзакции и валидирует их. Поскольку Kora анализирует каждую транзакцию перед подписанием, узлы Kora предлагают дополнительный уровень безопасности и более точный контроль валидации транзакций и политик комиссий.

Обзор архитектуры

Наша интеграция x402 + Kora состоит из четырёх взаимосвязанных компонентов с полным циклом запроса/ответа:

Полный процесс оплаты:

Клиент запрашивает защищенный ресурс → API возвращает 402 Payment Required
Клиент создает платежную транзакцию с помощью обертки x402 fetch (которая собирает транзакцию Solana с платежной инструкцией)
Клиент отправляет платеж Фасилитатору для проверки
Фасилитатор валидирует через Kora, который подписывает и отправляет в Solana
Транзакция подтверждается в блокчейне, Фасилитатор уведомляет API
API возвращает защищенный контент с платежной квитанцией Клиенту

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

RPC-сервер Kora (Порт 8080)
- Основной сервис безгазовых транзакций
- Выполняет подписание транзакций как плательщик комиссии
- Валидирует транзакции согласно настроенным политикам
Прокси-сервер Фасилитатора (Порт 3000)
- Адаптирует Kora к протоколу x402
- Реализует эндпоинты /verify, /settle и /supported
- Обеспечивает перевод между форматами данных x402 и Kora
Защищенный API (Порт 4021)
- Демонстрационный API-сервер с эндпоинтами, защищенными оплатой
- Использует middleware x402-express для обработки платежей
- Возвращает данные только после успешной оплаты
Клиентское приложение
- Демонстрирует использование обертки x402 fetch
- Подписывает транзакции приватным ключом пользователя

Многокомпонентный подход может показаться сложным, но он отражает реальные продакшн-системы, где обработка платежей, обслуживание API и клиентские приложения являются отдельными функциями.

Предварительные требования

Перед началом убедитесь, что у вас установлены:

Rust (последняя стабильная версия)
Node.js (LTS или новее)
Kora CLI (последняя версия - cargo install kora-cli)
pnpm (последняя версия)
Базовое понимание транзакций Solana и SPL-токенов

Настройка проекта

Шаг 1: Клонирование и сборка Kora

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

Платёжный токен: Убедитесь, что минт 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.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

Разрешенные программы: Убедитесь, что 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 для оплаты комиссий за транзакции. Вы можете получить devnet SOL на адрес подписанта Kora с помощью Solana CLI:

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

Либо вы можете использовать Solana Faucet для получения SOL на адрес подписанта Kora.

Devnet USDC

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

Получите Devnet USDC через Кран Circle. Убедитесь, что выбрали «Solana Devnet» и используйте ваш PAYER_ADDRESS для запроса USDC.

Запуск демонстрации

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

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

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

pnpm run start:kora

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

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: Запуск защищенного 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 возвращает защищенный контент с квитанцией об оплате

Поток транзакций

Источник: x402 GitHub

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

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

Прокси-сервер обертки фасилитатора

Фасилитатор работает на порту 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) использует middleware 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
    }
  )
);

Middleware:

Перехватывает запросы к защищенным конечным точкам (в нашем случае, конечная точка /protected)
Возвращает статус 402, если платеж отсутствует
Проверяет и обрабатывает платежи через посредника
Предоставляет доступ после успешной оплаты

Хотя мы используем Express, библиотека x402 включает поддержку middleware для многих популярных фреймворков. Дополнительную информацию см. в Пакетах TypeScript x402.

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

Клиент (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

Обертка fetch для x402:

Обнаруживает ответы 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
Открывайте issue в репозитории Kora на GitHub