Інтеграція 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 для обробки транзакцій
Гнучкі підписувачі: Підтримка кількох бекендів підписування (пам'ять, Vault, Turnkey, Privy)
Механізм політик: Детальний контроль валідації транзакцій та політик комісій

У контексті x402 Kora є ідеальним бекендом для фасилітаторів: вона обробляє мережеві комісії, підписує транзакції та валідує їх. Оскільки Kora інтроспектує кожну транзакцію перед підписанням, вузли Kora забезпечують додатковий рівень безпеки та більш точний контроль валідації транзакцій та політик комісій.

Огляд архітектури

Наша інтеграція x402 + Kora складається з чотирьох взаємопов'язаних компонентів із повним циклом запит/відповідь:

Повний цикл оплати:

Клієнт запитує захищений ресурс → API повертає 402 Payment Required
Клієнт створює платіжну транзакцію за допомогою обгортки x402 fetch (яка формує Solana-транзакцію з інструкцією платежу)
Клієнт надсилає платіж до Facilitator для перевірки
Facilitator валідує через Kora, яка підписує та відправляє до Solana
Транзакція підтверджується в блокчейні, Facilitator сповіщає API
API повертає захищений контент з квитанцією про оплату до Клієнта

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

Kora RPC-сервер (порт 8080)
- Основний сервіс безгасових транзакцій
- Обробляє підпис транзакцій як платник комісій
- Валідує транзакції відповідно до налаштованих політик
Обгортка/проксі-сервер Facilitator (порт 3000)
- Адаптує Kora до протоколу x402
- Реалізує ендпоїнти /verify, /settle та /supported
- Виконує перетворення між форматами даних x402 та Kora
Захищений API (порт 4021)
- Демонстраційний API-сервер з ендпоїнтами, що потребують оплати
- Використовує проміжне ПЗ 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

Тепер вам потрібно згенерувати або надати 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 налаштовує RPC-сервер Kora. Вам не потрібно вносити зміни до цього файлу, але ви можете перевірити наступні налаштування:

Токен оплати: Переконайтеся, що Devnet USDC mint знаходиться у списку дозволених:

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's Faucet. Переконайтеся, що вибрали "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: Запуск фасилітатора

Виконайте наступну команду для запуску фасилітатора:

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) використовує проміжне програмне забезпечення 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) демонструє, як автоматично працює 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