Інтеграція протоколу 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?

x402 — це відкритий платіжний стандарт, який забезпечує безперебійні мікроплатежі для доступу до API. Замість традиційних моделей підписки або ключів API, x402 дозволяє серверам стягувати плату за окремі виклики API, створюючи справжню інфраструктуру оплати за використання.

Ключові переваги x402:

Миттєві мікроплатежі: Платіть частки цента за кожен виклик API
Надайте ШІ-агентам можливість платити за виклики 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)
- Основний сервіс безгазових транзакцій
- Обробляє підписання транзакцій як платник комісій
- Валідує транзакції відповідно до налаштованих політик
Сервер-обгортка/проксі посередника (Порт 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

Це встановлює бінарний файл 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 для демонстрації. Виконайте наступну команду для генерації 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: Демонстрація використовує ключ 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, асоційована програма токенів і програма обчислювального бюджету є у списку дозволених:

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's Faucet. Обов'язково оберіть "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
Верифікація → Посередник верифікує через signTransaction Kora
Розрахунок → Посередник виконує розрахунок через signAndSendTransaction Kora (надсилаючи платіжну транзакцію до Solana)
Доступ надано → Посередник повертає підпис транзакції, а API повертає захищений вміст із квитанцією про оплату

Розгляньмо детально, як працює кожен компонент:

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) використовує проміжне програмне забезпечення 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-токенів як платіж
Розгортання у продакшн: розгорніть у mainnet з продакшн-підписантами (Vault, Turnkey або Privy)
Створіть власний API: розробіть реальний сервіс із монетизацією через платежі x402

Ставте запитання на Solana Stack Exchange з тегами kora та x402
Відкривайте issue у репозиторії Kora на GitHub

Інтеграція x402 з Kora — Повний посібник з демонстрації