Собственный REST API

Собственный API — это REST-интерфейс blockwallets: счета в центах США, идемпотентный ref для каждого заказа, статические депозитные аккаунты на всех сетях и вебхуки с подписью HMAC-SHA256. Он создаёт такие же счета на той же странице оплаты, что и API, совместимый с Cryptomus, с теми же комиссиями и балансом.

Ключи вы создаёте сами в кабинете, в разделе «Разработчикам › Интеграция и ключи»: ключ Live и ключ Test и секреты подписи их вебхуков. Каждый показывается один раз, в списке виден только префикс. Если в аккаунте включена двухфакторная аутентификация, для создания или обновления ключа Live нужно ввести код. Ещё нет аккаунта продавца? Запросите доступ. Уже работаете с Cryptomus? Посмотрите API, совместимый с Cryptomus (как выбрать).

Ключи и запросы

Базовый URL: https://blockwallets.io. Запросы и ответы — JSON. Каждый запрос содержит:

• Authorization: Bearer bw_live_… или Bearer bw_test_…: префикс определяет режим, поэтому ключ Test видит только счета Test и работает в тестовых сетях
• Content-Type: application/json в запросах POST
• Храните ключи только на сервере, никогда не размещайте их на веб-странице или в приложении; мы храним только их хеш

Ошибки возвращаются с HTTP-статусом и телом {"error": {"code": "…", "message": "…"}}: 400 invalid_request (отсутствует поле или оно неверного формата), 401 unauthorized (ключ отсутствует, неизвестен или отключён), 404 not_found, 409 conflict (запрос противоречит текущему состоянию счёта), 422 currency_unsupported.

Эндпоинты

Добавьте ?probe=1 к запросу счёта или депозитного аккаунта, чтобы заодно проверить блокчейн (не чаще раза в 10 секунд); без него вы получите последнее состояние от нашего сканера, который проверяет каждую минуту.

Создание счёта POST /v1/invoices

Вызовите POST /v1/invoices, когда клиент оформляет заказ, и перенаправьте его на pay_url из ответа.

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

Каждый URL должен быть на одном из доменов вашего сайта (кабинет → «Разработчикам › Интеграция и ключи»). Ответ — объект счёта ниже; network, address и pay_amount заполняются после выбора сети.

Объект счёта

Идентификаторы начинаются с inv_. amount — в центах США; pay_amount и paid_amount — количество монет десятичной строкой в выбранной сети.

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

Другие поля: pay_url (страница оплаты), payments (каждый перевод с txid, amount, confirmations и confirmed), expires_at, paid_at, closed_at; у BTC, LTC, DOGE, BCH и родных монет есть также rate (долларов США за монету, фиксируется на 30 минут), rate_locked_until и paid_cents (сколько уже пришло, в центах США).

Сети

Передавайте id как network. GET /v1/networks возвращает сети, открытые сейчас в вашем режиме; сеть может быть приостановлена, поэтому лучше читать этот список, чем зашивать значения в код.

Депозитные аккаунты (статические адреса) POST /v1/deposit-accounts

POST /v1/deposit-accounts с {"customer_ref": "user_42"} выдаёт этому клиенту постоянный адрес в каждой сети (все сети EVM используют один адрес). Всё, что он отправит, зачисляется в долларах США, по одному вебхуку deposit.credited на каждый перевод.

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref: 1–128 символов — буквы, цифры и _ . : @ -; одно и то же значение всегда возвращает один и тот же аккаунт. Необязательный return_url на ваших доменах
• В ответе есть deposit_url (страница с адресами, QR-кодами и последними депозитами) и networks (для каждой сети id, address, min_amount, confirmations)
• Идентификаторы депозитов начинаются с dep_; amount — центы США, amount_token — количество монет, а у монет с курсом указан применённый rate

Переводы ниже минимума (обычно $1, BTC $5) записываются как below_min и автоматически не зачисляются; чтобы их зачислили, свяжитесь с нами.

Вебхуки

Мы отправляем POST с JSON на URL вебхука из кабинета («Разработчикам › Интеграция и ключи»; у Live и Test свои URL и секрет). Тело — это событие:

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature: t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(секрет вебхука этого режима, t + . + исходное тело)
• X-BW-Event: id события (ev_…); убирайте дубликаты по нему
• X-BW-Delivery: номер попытки, начиная с 1

Проверяйте по исходному телу до разбора, отклоняйте t, отличающийся от ваших часов более чем на 300 секунд, и сравнивайте за постоянное время. invoice / deposit в теле — тот же объект, что возвращает запрос.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Ответ 2xx считается доставкой; иначе повторяем через 1 минуту, 5 минут, 30 минут, 2 часа, 12 часов, 24 часа и ещё 24 часа (всего 8 попыток).

События и повторная отправка

GET /v1/events?invoice_id=inv_… (или deposit_id=dep_…) показывает вебхуки по одному счёту или депозиту с их state, attempts, last_status и last_error. POST /v1/events/ev_…/redeliver сразу ставит вебхук в очередь заново, например после того, как вы исправили свой эндпоинт. Раздел «Разработчикам › Журнал вебхуков» в кабинете показывает каждую попытку с запросом и ответом.

Тестовый режим

Счета, созданные ключом bw_test_, работают в тестовых сетях и не затрагивают настоящие деньги. На странице оплаты есть кнопка «Симулировать оплату» (полная / половина / переплата), так что вы увидите смену статусов и вебхуки, не добывая тестовые монеты.