API платежей, разработанный для кода AI агента.
Небольшой REST API. Подписанные вебхуки. Официальные SDK на пяти языках. Создан так, чтобы ваш агент мог отправлять и завершать USDC и проверять платежи всего за несколько строк кода.
API Blockchain0x намеренно небольшой. Мы не хотим, чтобы вы читали документацию часами, чтобы сделать свой первый платеж. Мы хотим, чтобы вы скопировали фрагмент, вставили свой API-ключ и запустили его.
Небольшая поверхность, созданная для кода агента.
Маршруты, связанные с платежами, приведены ниже. Вебхуки, api-ключи и разрешения на расходы только для чтения завершают интерфейс; SDK оборачивает все это.
/v1/paymentsОтправьте платеж USDC из кошелька агента/v1/transactions/{id}Получите статус и хэш транзакции/v1/payment-requests/{id}/settleЗавершите счет с доказательством в цепочке/v1/agents/{id}Получите кошелек агента/v1/agentsСоздать кошелек агентаВсе подписаны с помощью HMAC-SHA256.
Подпись в X-Blockchain0x-Signature заголовок. Окно повторной передачи 5 минут. Ключи идемпотентности на каждом POST.
payment.receivedUSDC поступил в один из ваших кошельков агентов.
payment.sentисходящий платеж от вашего агента был завершен в цепочке
wallet.deployedумный кошелек агента был развернут
webhook.testтестовая доставка, которую вы инициировали с панели управления
Отправьте USDC из кошелька вашего агента.
from blockchain0x import Client
client = Client(api_key="sk_test_...") # sk_test_ testnet, sk_live_ mainnet
tx = client.payments.create(body={
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000", # USDC base units (6 decimals): 0.01 USDC
})
print(tx) # may return 503 until the chain adapter is wired for your networkТипизированные клиенты для TypeScript и Python.
npm install @blockchain0x/nodeРаботает с Node 18+. Нативные типы TypeScript.
pip install blockchain0xPython 3.9+. Синхронные и асинхронные клиенты.
Тела запросов, которые оборачивает SDK.
Это проверенные входные данные для каждого маршрута. Ответы здесь показаны кратко; полные типизированные формы находятся в SDK и справочнике API. Суммы указаны в базовых единицах USDC (6 десятичных знаков).
/v1/paymentsОтправьте платеж USDC (payments.create). amountWei - это базовые единицы USDC (6 десятичных знаков). Может вернуть 503, пока адаптер цепи не будет подключен.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settleЗавершите запрос на платеж (счет), созданный в панели управления, с доказательством в цепочке (paymentRequests.settle). Нет маршрута создания - только завершение.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}Получите одну транзакцию по идентификатору (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}Получите кошелек агента (agents.get). Его публичная страница находится по адресу wallet.blockchain0x.com/a/{slug}.
(no body){
"id": "agt_01J9QKE...",
"name": "research-bot",
"public_url": "https://wallet.blockchain0x.com/a/research-bot"
}/v1/agents/{id}/spend-permissionsЧитать разрешения на расходы агента. ТОЛЬКО ДЛЯ ЧТЕНИЯ через API - создание и изменения доступны только через панель управления.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}Всегда проверяйте подпись перед тем, как доверять полезной нагрузке.
Любой может отправить POST на ваш URL обратного вызова. Подпись подтверждает, что событие действительно пришло от нас.
Каждая доставка содержит X-Blockchain0x-Signature заголовок (t=<unix>,v1=<hex>) - HMAC-SHA256 для строки `${t}.${rawBody}` с вашим секретом вебхука, в пределах 5-минутного окна повторной передачи. В Node, webhooks.verify из @blockchain0x/node делает это и возвращает дискриминированный союз, на который вы ветвитесь. В других языках вычислите тот же HMAC и сравните за постоянное время. Читайте RAW тело, а не разобранную копию - повторная сериализация нарушает подпись.
import express from "express";
import { webhooks } from "@blockchain0x/node";
const app = express();
// Capture the RAW body. The HMAC is over the exact bytes on the wire.
app.use(express.raw({ type: "application/json" }));
app.post("/webhooks/payment", (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body, // Buffer, raw bytes
secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
});
if (!result.ok) return res.status(400).json({ code: result.code });
// result.eventType is "payment.received" | "payment.sent" | ...
handleEvent(result);
res.status(200).send("ok");
});import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode()
@app.post("/webhooks/payment")
def receive():
raw = request.get_data() # RAW bytes - do not parse first
sig = request.headers.get("X-Blockchain0x-Signature", "")
ts = request.headers.get("X-Blockchain0x-Timestamp", "")
# Header is "t=<unix>,v1=<hex>"; some proxies send bare hex + the ts header.
parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
t, v1 = parts.get("t", ts), parts.get("v1", sig)
want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300:
abort(401)
handle_event(request.headers.get("X-Blockchain0x-Event-Type"), request.get_json())
return "ok", 200Webhook secret возвращается один раз при создании или ротации webhook (webhooks.rotateSecret), а BLOCKCHAIN0X_WEBHOOK_SECRET - это переменная, из которой его читает ваш handler. Ротация делает старый secret недействительным, поэтому согласуйте rollout: задайте новый secret в env вашего сервера, разверните, затем выполните ротацию. Поставляемые события - payment.received, payment.sent, wallet.deployed и webhook.test - ветвитесь по типу события, остальное игнорируйте.
Повторите безопасно. API не заплатит дважды.
Повторные попытки кода агента. Сети теряют соединения. LLM решает вызвать инструмент дважды. Чтобы сделать это безопасным, отправьте Idempotency-Key заголовок в POST. payments.create в SDK автоматически создает стабильный для вас, так что повторный вызов сводится к единой отправке в цепочку вместо двойной оплаты. Переопределите его своим собственным ключом, когда хотите убрать дублирование одной и той же логической операции между процессами.
curl -X POST https://api.blockchain0x.com/v1/payments \
-H "Authorization: Bearer $BLOCKCHAIN0X_API_KEY" \
-H "Idempotency-Key: 8e2c3a40-pay-vendor-once" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agt_123", "to": "0xRecipient", "amountWei": "10000" }'- Первый вызов: отправляет платеж, возвращает транзакцию.
- Повторите с тем же ключом: сводится к одной отправке в цепочку вместо того, чтобы платить дважды.
- SDK обрабатывает это: payments.create автоматически создает стабильный Idempotency-Key, поэтому повторный вызов безопасен изначально.
- Переопределите это: передайте свой собственный ключ, когда хотите устранить дублирование одной и той же логической операции между процессами.
Рекомендуемый шаблон - генерировать UUID для каждой логической операции в коде вашего агента (например, один UUID на "оплатить поставщику X за заказ Y") и повторно использовать его при повторных попытках, пока операция не будет успешной. Официальные SDK автоматически генерируют один для payments.create, если вы его не укажете.
Читать ваш лимит из ответа, а не из таблицы.
Лимиты масштабируются в зависимости от вашего плана. Вместо того чтобы жестко кодировать числа, которые могут изменяться, каждый ответ сообщает вам, где вы находитесь, а SDK обрабатывают откат за вас.
Заголовки в каждом успешном ответе
X-RateLimit-Limit: постоянная ставка вашего планаX-RateLimit-Remaining: сколько вызовов осталось в этом окнеX-RateLimit-Reset: unix-секунды, когда окно сбрасывается
Когда вы достигли лимита (HTTP 429)
- Ответ включает
Retry-Afterв секундах - Официальные SDK повторяют попытку при 429 и 5xx с экспоненциальной задержкой, уважая Retry-After
- Большинство кода никогда не обрабатывает 429 вручную, потому что SDK уже это делает
Свободно говорит на x402. Работает и без него.
x402 это открытый протокол для HTTP-нативных платежей. Принцип: любой API, который возвращает 402 Payment Required, может рекламировать требования к платежам в ответе, и любой клиент, который понимает спецификацию, может платить и повторять - никакой регистрации, никакого API ключа, никаких внеплановых переговоров. Blockchain0x предоставляет реальные пакеты x402: клиент для оплаты и серверные адаптеры для получения. Единственная схема на сегодняшний день - exact-usdc, на Base.
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"version": 1,
"resource": "https://api.example.com/paid-endpoint",
"accepts": [
{ "scheme": "exact-usdc", "network": "eip155:8453" }
]
}Что делает вызывающий агент
- Читает тело 402: version 1, resource и непустой accepts[] с требованиями к оплате (scheme exact-usdc, network eip155:8453 для Base).
- Формирует платеж и повторно отправляет запрос с заголовком X-Payment: exact-usdc:<base64(json)>.
- На стороне оплаты createX402Client({ sdk }) из @blockchain0x/x402 делает это за вас - он автоматически отвечает на 402s.
- Ваш сервер проверяет заголовок X-Payment и выполняет исходный запрос.
Обе стороны, реальные пакеты
На стороне оплаты, createX402Client({ sdk }) из @blockchain0x/x402 оборачивает fetch и автоматически отвечает на 402. На стороне получения, createX402Plugin (Fastify) и createX402Middleware (Express) создайте свои собственные конечные точки. Или пропустите x402 и используйте REST API напрямую - оба совместимы, так что вы можете добавить x402, когда будете готовы.