Bitcoin API: приём платежей BTC без запуска ноды

JSON-RPC Bitcoin Core хочет синхронизированную ноду перед первым полезным ответом. REST API хочет API-ключ. Разница видна в вашем календаре: первоначальная загрузка блоков занимает дни на типичном оборудовании, а после этого нода потребляет диск и пропускную способность и всё равно нуждается в мониторинге на протяжении всей жизни вашего продукта. Наша статья о blockchain API против blockchain node подробно сравнивает оба подхода. Запускайте собственную ноду, когда вам нужен контроль на уровне политики над вашим представлением о сети; используйте API, когда цель — платежи.

Повседневные вызовы чисто ложатся на REST-модель. Там, где интеграция с нодой оборачивает getnewaddress и listtransactions и опрашивает изменения, API назначает адреса и позволяет вебхуку заниматься наблюдением. Циклы опроса исчезают, а вместе с ними — cron-задачи, тихо ломающиеся по выходным.

Есть и второе отличие. Сырые методы RPC возвращают сырые данные. Chaingateway возвращает структурированный JSON с читаемыми полями, так что ответ может пойти прямо в вашу базу данных, минуя слой парсинга.

REST-сторона пути отправки — это три эндпоинта. POST /api/v2/bitcoin/wallets создаёт кошелёк, зашифрованный паролем, который Chaingateway не хранит — потеряете его, и никто не сможет восстановить кошелёк, в этом и суть. POST /api/v2/bitcoin/wallets/{wallet}/addresses выводит под ним столько адресов, сколько вам нужно; один кошелёк несёт их все. А POST /api/v2/bitcoin/transactions отправляет:

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

Ответ несёт txid транслированной транзакции. speed принимает fast, medium или slow и задаёт уровень комиссии — компромисс между стоимостью и временем до первого подтверждения. Необязательный subtractfee: true вычитает сетевую комиссию из суммы вместо добавления её сверху, что нужно, когда клиент выводит весь свой баланс.

Bitcoin добавляет блок примерно каждые десять минут, хотя отдельные интервалы сильно варьируются. Каждый новый блок, добытый поверх блока с вашей транзакцией, добавляет подтверждение, и каждое подтверждение усложняет разворот.

Шесть подтверждений — около часа — де-факто стандарт «расчёта» со времён ранних бирж, и это остаётся верным по состоянию на середину 2026 года.

Десять минут — это в среднем, а не по расписанию

Корректировка сложности удерживает это со временем, но отдельные интервалы разбросаны широко вокруг этого значения — два блока в минуту случаются, как и сорокаминутные затишья. UX платежей должен это учитывать: «около десяти минут» — это среднее, а не обещание, поэтому ваша страница кассы должна говорить «обычно в течение часа», а не запускать таймер обратного отсчёта, который не может сдержать.

Почему не зачислять при нуле подтверждений?

Потому что до попадания в блок транзакция сидит в мемпуле, где её можно заменить или потратить дважды, и даже самый новый блок может выпасть из цепочки при реорганизации. API разбивает эту работу на две части. Вебхук срабатывает, как только транзакция расчитается в сети — payload несёт сумму, адрес, txid и номер блока, — так что ваш UI может отреагировать сразу. Дальше GET /api/v2/bitcoin/transactions/{txid}/decoded возвращает текущее число подтверждений, так что ваш реестр зачисляет только деньги, достигшие вашего порога. Показывайте прогресс рано, расчитывайте поздно.

У Bitcoin нет балансов аккаунтов. То, что хранит сеть, — это неизрасходованные выходы транзакций — UTXO, каждый — дискретный комок стоимости, привязанный к адресу. «Баланс» кошелька — это число, которое ваше ПО выводит, суммируя каждый UTXO, контролируемый его адресами; протокол никогда не хранит эту сумму нигде. Трата потребляет целые UTXO и создаёт новые, включая выход сдачи обратно к себе, — так же, как оплата счёта на 7 евро десятиевровой купюрой возвращает монеты.

Ethereum работает по противоположной модели. У аккаунта один баланс, сеть хранит его напрямую, и депозит — это приращение. В сетях EVM нормально дать клиенту один адрес и позволить сотне депозитов накапливаться на нём годами.

Для обработки депозитов модель UTXO даёт практическое преимущество: она подталкивает вас к одному адресу на клиента или на счёт, что и так является более чистым дизайном. Каждый входящий платёж — это новый выход на адрес, который вы отслеживаете, поэтому атрибуция однозначна — без разбора memo, без сопоставления по сумме. Это также означает, что «баланс адреса» — вопрос, на который отвечает индексатор, а не сеть, и именно эту бухгалтерию вы отдаёте на аутсорс, используя API с вебхуками вместо запуска этой машинерии самостоятельно. Уведомление сообщает вам: эта сумма, этот адрес, эта транзакция, этот блок. Остальное делает ваш реестр.

Добавьте заголовок X-Network: testnet, и каждый вызов на этой странице выполнится против тестовой сети Bitcoin: те же маршруты, те же формы ответов, монеты без ценности. Краники бесплатно раздают тестовый BTC, так что весь поток депозита — адрес, платёж, вебхук, подтверждения — можно отрепетировать от начала до конца, не потратив ни одного сатоши.

Держите заголовок за конфигурацией, а не разбросанным по коду, и дайте вашему staging-окружению отдельный callback URL, чтобы тестовые депозиты не могли просочиться в продакшн-реестр. Когда репетиция сработает, уберите заголовок. Больше ничего в интеграции не меняется, в этом и суть: первый депозит в mainnet должен быть скучным.

Платёжный бэкенд зарабатывает свою репутацию в плохие дни, так что планируйте пути сбоев явно.

На уровне HTTP правила стандартны для REST. 401 означает, что Bearer-токен неверен или отсутствует; исправьте ключ, а не повторяйте. Другие ответы 4xx указывают на сам запрос — логируйте тело, называющее проблему, и относитесь к этому как к багу. Ответы в диапазоне 5xx и таймауты временны; повторяйте их с задержкой.

Специфичные для Bitcoin сценарии сбоя живут выше HTTP. Депозит, который никогда не подтверждается, обычно заплатил слишком маленькую комиссию и застрял в мемпуле; он может подтвердиться часы спустя или полностью выпасть, поэтому detected и settled должны оставаться отдельными состояниями в вашей системе. Уведомление о сумме ниже суммы счёта — это бизнес-решение, а не ошибка; обрабатывайте это в коде, а не в очереди поддержки. И если ваша конечная точка вебхука была недоступна, неудачные доставки ждут вас: GET /api/v2/bitcoin/webhooks/notifications/failed перечисляет их, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry повторно отправляет каждую, а полный список на GET /api/v2/bitcoin/webhooks/notifications позволяет сравнить с реестром и зачислить пропущенное. Запускайте это сравнение каждую ночь, даже когда ничего не выглядит неправильным. Сверка, запускающаяся только после инцидентов, находит свои баги в продакшене.

У самого Bitcoin нет USDT или USDC — стейблкоины живут в других сетях. Что даёт общая платформа — это форa: ваша интеграция Bitcoin уже говорит на том же API, что и наши эндпоинты Ethereum и TRON. Принимайте BTC сегодня, добавьте USDT на TRON в следующем спринте тем же ключом и тем же обработчиком вебхуков. Обзор blockchain API перечисляет все семь поддерживаемых сетей.

Практический порядок для большинства команд: сначала запустите депозиты BTC, потому что это то, что клиенты просят по имени, затем позвольте платёжным данным подсказать, какой стейблкоин-рельс добавить вторым. В Chaingateway этот второй рельс переиспользует вашу проверку подписи, вашу задачу сверки и ваш конечный автомат депозита без изменений.

• У него самая долгая история среди всех блокчейнов, работающая с 2009 года, и самое широкое признание среди конечных пользователей.
• Сеть расчитывается круглосуточно. Нет банковских часов и региональных отсечек.
• Подтверждения следуют предсказуемому ритму, с новым блоком примерно каждые десять минут, что упрощает рассуждения о платёжных потоках.
• Принятие — крупнейшее среди всех криптосетей, поэтому «принимаете ли вы Bitcoin?» всё ещё первый вопрос, который задают клиенты.

Ни одно из этих свойств не появилось из обновления дорожной карты; это те же гарантии, с которыми сеть была выпущена. Эта стабильность — аргумент в пользу BTC для продуктов с долгим горизонтом: интеграция, построенная в этом году, не устареет из-за поворота протокола в следующем — а это больше, чем может заявить большинство платёжных стеков.

Очевидный случай — касса: клиент выбирает Bitcoin, и ваше приложение назначает адрес; вебхук подтверждает платёж. Те же строительные блоки несут и более тяжёлые нагрузки. Биржи и игровые платформы держат по одному депозитному адресу на пользователя и зачисляют балансы при подтверждении. Потоки выплат и денежных переводов проталкивают трансграничные переводы без корреспондентских банков посередине. Подписные сервисы генерируют свежий адрес счёта каждый цикл и позволяют вебхуку закрывать его.

Что объединяет эти случаи — это форма работы. Bitcoin занимается расчётами; ваше приложение — состоянием. API находится между ними и превращает события сети в HTTP-вызовы, которые ваш фреймворк уже умеет маршрутизировать, — поэтому случай кассы и случай биржи работают на одной и той же горстке эндпоинтов.