Начало работы с x402

Протокол x402 (также известный как L402) — это новый стандарт монетизации API, который позволяет оплачивать использование по запросу без необходимости подписки.

Точка доступа Minara x402: https://x402.minara.ai

Что такое x402?

x402 — это нативная система «плати за использование» для веба. Вместо предварительной оплаты подписки вы оплачиваете каждый вызов API непосредственно с помощью стейблкоинов, таких как $USDC.

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

• Подписка не требуется: Платите только за то, что используете

• Доступ без разрешений: Не требуется создание аккаунта или процесс одобрения

• Мгновенная активация: Начните использовать API сразу после оплаты

• Крипто-нативность: Платежи в USDC на Base, Solana или Polygon

• Прозрачное ценообразование: Точно знайте, сколько стоит каждый вызов API

Как это работает:

Протокол x402 следует схеме «платёж — вызов» с ключевыми шагами:

Полный поток

1. Начальный запрос (Клиент → Сервер)

   • Вы делаете запрос к защищённой конечной точке без оплаты

2. Запрос оплаты (Payment Challenge) (Сервер → Клиент)

   • Сервер отвечает с 402 Требуется оплата статус

   • Возвращает инструкции по оплате (сумма, валюта, адрес получателя, сеть)

3. Выбор способа оплаты (Клиент)

   • Вы выбираете способ оплаты и создаёте платёжные данные

   • Подготовьтесь к оплате в USDC в указанной сети

4. Аутентифицированный запрос (Клиент → Сервер)

   • Включите доказательство оплаты в x-payment-response заголовок

   • Повторите исходный запрос

5. Проверка (Сервер → Фасилитатор)

   • Сервер отправляет доказательство оплаты фасилитатору для проверки

   • Подтверждает действительность оплаты

6. Обработка платежа (Фасилитатор → Блокчейн)

   • Фасилитатор отправляет транзакцию в блокчейн

   • Транзакция подтверждена в сети

7. Расчёт/Завершение (Settlement) (Фасилитатор → Сервер)

   • Фасилитатор подтверждает завершение расчёта серверу

   • Платёж завершён

8. Доступ предоставлен (Сервер → Клиент)

   • Вы получаете ответ API

   • Квитанция об оплате включена в X-PAYMENT-RESPONSE заголовок

Ключевые компоненты

• Клиент: Ваше приложение, выполняющее запросы к API

• Сервер: Конечные точки Minara API (https://x402.minara.ai)

• Фасилитатор: Сервис проверки и расчёта платежей

• Блокчейн: Ончейн-расчёт платежей (Base, Solana или Polygon)

---

Как использовать x402 с Minara

1. Использование x402 SDK (рекомендуется)

Большинство разработчиков используют официальный x402 SDK, который автоматически обрабатывает все платёжные потоки.

Вам просто нужно делать запросы: SDK обрабатывает запросы на оплату, проверку и расчёт за вас.

Требования

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

• Криптокошелёк с USDC (любой кошелёк, совместимый с EVM)

• Node.js и npm, Go или Python и pip

• Приватный ключ вашего кошелька (для подписания платежей)

Шаг 1: Установите зависимости

Node.js / TypeScript

# Для клиентов на основе fetch (рекомендуется)
npm install @x402/fetch @x402/evm

# Для клиентов на основе axios
npm install @x402/axios @x402/evm

# Для поддержки Solana также добавьте:
npm install @x402/svm

Python

# Для httpx (async) - рекомендуется
pip install "x402[httpx]"

# Для requests (sync)
pip install "x402[requests]"

# Для поддержки Solana также добавьте:
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

Шаг 2: Настройте подписывающий кошелёк (Wallet Signer)

Node.js (с использованием viem)

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// Создайте signer из приватного ключа (используйте переменную окружения)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

Для Solana:

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python (с использованием eth-account)

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

Шаг 3: Делайте запросы: платежи обрабатываются автоматически!

SDK автоматически обрабатывает запросы на оплату за вас. Просто делайте запросы как обычно!

Node.js (с fetch)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Создайте signer
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Создайте x402 клиент и зарегистрируйте EVM схему
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Оберните fetch обработкой платежей
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Выполните запрос — оплата обрабатывается автоматически! 🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "Какова текущая цена BTC?"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// Получить квитанцию об оплате (опционально)
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 Полный пример на GitHub

Node.js (с axios)

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// Создайте signer
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Создайте x402 клиент и зарегистрируйте EVM схему
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Создайте экземпляр Axios с поддержкой платежей
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// Выполните запрос — оплата обрабатывается автоматически! 🎉
const response = await api.post("/x402/chat", {
  userQuery: "Проанализируй динамику цены ETH"
});

console.log("Response:", response.data.content);

📖 Полный пример на GitHub

Python (async с httpx)

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # Создайте клиент и зарегистрируйте EVM схему
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Выполните запрос — оплата обрабатывается автоматически! 🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "Какая цена BTC?"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 Полный пример на GitHub

Python (sync с requests)

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # Создайте клиент и зарегистрируйте EVM схему
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Выполните запрос — оплата обрабатывается автоматически! 🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "Какая цена BTC?"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 Полный пример на GitHub

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // Создайте EVM signer
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // Создайте x402 клиент и зарегистрируйте EVM схему
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // Оберните HTTP-клиент обработкой платежей
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // Подготовьте тело запроса
    reqBody := map[string]string{"userQuery": "Какая цена BTC?"}
    jsonData, _ := json.Marshal(reqBody)

    // Выполните запрос — оплата обрабатывается автоматически! 🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("Request failed: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 Полный пример на GitHub

Поддержка нескольких сетей (Base + Solana + Polygon)

Вы можете зарегистрировать несколько платёжных схем для поддержки всех цепочек Minara:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// Создайте signers для разных сетей
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// Создайте клиент с несколькими схемами
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Теперь вы можете вызывать ЛЮБУЮ конечную точку Minara! 🚀
// Конечные точки Base
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Конечные точки Solana  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Конечные точки Polygon
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

Полный пример: Чат с Minara

Вот полный рабочий пример, который вызывает AI-чат-конечную точку Minara:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. Настройте signer
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. Создайте x402 клиент
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. Оберните fetch
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. Выполните запрос — SDK автоматически обрабатывает оплату!
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// Использование
const answer = await chatWithMinara("Какова текущая цена BTC?");
console.log(answer);
// Вывод: "BTC сейчас торгуется по $98,450. Ключевые уровни поддержки..."

Для получения дополнительной информации, пожалуйста, ознакомьтесь с официальной документацией x402: Быстрый старт для покупателей

---

2. Ручной поток оплаты (без SDK)

Если вы предпочитаете не использовать SDK, вы можете обрабатывать платежи вручную:

Шаг 1: Сделайте начальный запрос

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "Какая цена BTC?"}'

Шаг 2: Получите запрос оплаты

{
  "error": "payment_required",
  "message": "Требуется оплата для доступа к этому ресурсу",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

Шаг 3: Оплатите с кошелька

Используйте MetaMask, Phantom или любой Web3-кошелёк, чтобы отправить USDC на адрес получателя.

Шаг 4: Повторите с доказательством оплаты

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "Какая цена BTC?"}'

Шаг 5: Получите ответ

{
  "content": "BTC сейчас торгуется по $98,450..."
}

---

Обработка ошибок

Типичные ошибки от Minara API

402 Требуется оплата

{ "error": "payment_required" }

→ Нормально! SDK справится с этим автоматически.

401 Неавторизован

{ "error": "unauthorized", "message": "Неверный токен ответа оплаты" }

→ Доказательство оплаты недействительно или просрочено. SDK попытается снова.

400 Неверный запрос

{ "error": "bad_request", "message": "Отсутствует обязательный параметр: userQuery" }

→ Проверьте, что в теле запроса присутствуют все обязательные поля.

Ограничения по частоте (Rate Limits)

Конечные точки x402 ограничены по частоте запросов на адрес кошелька:

• AI-конечные точки: 60 запросов/минуту

• Торговые конечные точки: 30 запросов/минуту

Если вы превышаете лимиты:

{
  "error": "rate_limit_exceeded",
  "message": "Слишком много запросов. Пожалуйста, попробуйте снова через 30 секунд.",
  "retryAfter": 30
}

---

Ресурсы и поддержка

📚 Официальные ресурсы x402

• Документация протокола x402

• Быстрый старт для покупателей

• Репозиторий x402 на GitHub

• Discord x402

📦 Пакеты NPM

• @x402/fetch - Обёртка для fetch

• @x402/axios - Интерцептор для Axios

• @x402/evm - Поддержка EVM (Base, Polygon)

• @x402/svm - Поддержка Solana

• Пакет x402 для Python

🔍 Специфично для Minara

• Minara на x402scan - Просмотреть все конечные точки

• Справочник Minara API (x402) - Справочник по API (x402)

Справочник API

Справочник по API (x402)