Ethereum API: переводы ERC-20 одним REST-вызовом

JSON-RPC — нативный протокол каждой ноды Ethereum, и для некоторых задач (инструменты консенсуса, собственная индексация) вам нужен именно такой уровень доступа. Наше руководство по взаимодействию с нодами через JSON-RPC показывает, как это выглядит на PHP, Python и JavaScript.

Подсчёт циклов делает мысль наглядной. Перевод токена через сырой JSON-RPC затрагивает как минимум четыре метода — eth_gasPrice, eth_estimateGas, eth_getTransactionCount и eth_sendRawTransaction — с кодированием ABI и подписью транзакции между ними.

Для платежей эта абстракция окупается. В запросе на транзакцию Chaingateway лимит gas, цена gas и nonce — необязательные поля: опустите их, и API заполнит их сам при построении и трансляции транзакции; передавайте их явно, когда хотите контроль. Ваша сторона обмена — один HTTP-запрос, который можно написать на любом языке со стандартной библиотекой.

Если вы сейчас поддерживаете интеграцию с web3.js, вот честное сравнение. Перевод ERC-20 через библиотеку выглядит примерно так:

// web3.js против вашей собственной конечной точки RPC
const { Web3 } = require("web3");
const web3 = new Web3("https://your-rpc-endpoint");

const token = new web3.eth.Contract(ERC20_ABI, "0xdAC17F958D2ee523a2206206994597C13D831ec7");
const data = token.methods.transfer(recipient, amountInBaseUnits).encodeABI();

const tx = {
  from: sender,
  to: token.options.address,
  data,
  gas: await web3.eth.estimateGas({ from: sender, to: token.options.address, data }),
  gasPrice: await web3.eth.getGasPrice(),
  nonce: await web3.eth.getTransactionCount(sender),
};

const signed = await web3.eth.accounts.signTransaction(tx, PRIVATE_KEY);
await web3.eth.sendSignedTransaction(signed.rawTransaction);

Помимо того, что помещается в фрагмент, этот код владеет файлом ABI, преобразует человеческие суммы в базовые единицы вручную (ошибитесь в десятичных знаках, и вы отправите миллионную долю нужной суммы или в миллион раз больше), и держит сырой приватный ключ в памяти приложения. REST-версия — это единственный POST выше: сумма как десятичная строка, десятичные знаки обрабатываются на сервере, ключ зашифрован в покое за паролем.

Миграция не требует выходных на переписывание. Оба стиля — это простые вызовы, так что запустите их бок о бок: направьте новые платёжные потоки через REST, оставьте кастомные взаимодействия с контрактами на web3.js и выводите библиотеку из эксплуатации везде, где она больше не оправдывает свою сложность. Команды, использовавшие web3.js только для переводов и проверки баланса, обычно полностью убирают эту зависимость.

Каждая транзакция Ethereum сжигает gas, оплачиваемый в ETH отправляющим адресом, никогда получателем. Кошелёк, держащий тысячи USDT и ноль ETH, не может отправить ни одного токена, потому что у контракта ERC-20 нет способа покрыть собственную стоимость исполнения. Получение токенов ничего не стоит получателю.

Эта деталь спотыкает больше интеграций ERC-20, чем любая другая. Если ваши переводы через API идут с казначейского кошелька, этому кошельку нужен баланс ETH рядом с его токенами, и его пополнение принадлежит операционному чек-листу рядом с продлением сертификатов.

Сколько стоит gas

Обычный перевод ETH стоит ровно 21 000 gas — протокольная константа. Перевод ERC-20 выполняет код контракта и стоит кратно больше, с точной цифрой, варьирующейся по контракту токена. Цена за единицу плавает со спросом: с апгрейда London 2021 года комиссия делится на базовую комиссию, которую сеть сжигает, и приоритетные чаевые предлагающему блок, и оба растут при перегрузке. Практическое следствие: один и тот же перевод USDT стоит центы в тихое воскресенье и заметно больше во время популярного минта.

Что API обрабатывает за вас

Лимит gas, цена gas и лимиты EIP-1559 (maxFeePerGas, maxPriorityFeePerGas) — необязательные поля запроса: опустите их, и API заполнит их при построении вашей транзакции, либо закрепите их для конкретного запроса, когда хотите контроль. Две вещи остаются вашей ответственностью: поддержание ETH на отправляющих кошельках и решение о том, где мелкие переводы экономически оправданы — когда комиссии mainnet приближаются к сумме перевода, тот же вызов в Polygon или Arbitrum — на расстоянии смены пути.

Получение бесплатно

Депозитному адресу не нужен ETH, чтобы принимать токены. Gas становится вашей проблемой, только когда средства уходят — включая когда вы сметаете депозиты клиентов в казначейский кошелёк, что само по себе исходящая транзакция с каждого депозитного адреса.

После перехода на proof of stake время в Ethereum фиксировано, а не статистично. Блоки приходят в двенадцатисекундных слотах, 32 слота образуют эпоху в 6,4 минуты, а блок финализируется примерно через две эпохи — назовём это 13 минутами — как только две трети застейканного ETH его аттестовали (протокольные параметры по состоянию на середину 2026 года). Финализированный означает, что сеть не может откатить блок, не уничтожив большую долю всего застейканного ETH, что ставит его в другую категорию по сравнению с вероятностным расчётом Bitcoin.

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

USDT, USDC, DAI и другие устоявшиеся токены работают из коробки, с суммами в единицах токена вместо сырых базовых единиц. Запускаете собственный ERC-20? Передайте адрес контракта, и тот же эндпоинт отправит его. Никакого процесса листинга, никакого ожидания. Справочная информация о самом стандарте — в нашем руководстве по токену ERC-20.

• Это самая широко распространённая платформа смарт-контрактов, проверенная временем с 2015 года.
• DeFi-экосистема крупнейшая среди всех сетей, с тысячами dApp для интеграции.
• Ценообразование gas динамическое, основанное на спросе сети; вы можете оставить поля комиссии API или ограничить их для конкретного запроса параметрами EIP-1559.
• Работа над масштабированием продолжается, и Polygon и Arbitrum доступны через тот же API, когда комиссии mainnet начинают кусаться.

Паттерн маршрута ERC-20 повторяется по сетям EVM: /api/v2/polygon/transactions/erc20, /api/v2/arbitrum/transactions/erc20, и /api/v2/bsc/transactions/bep20 для BNB Smart Chain. Код, написанный для Ethereum, переносится редактированием пути. Когда gas mainnet становится слишком дорогим для мелких переводов, перенос их в Polygon — изменение в одну строку. Полный список сетей — на обзоре blockchain API.

Строительные блоки выше покрывают большинство продакшн-паттернов, которые мы видим: кассы, принимающие USDT или USDC, биржи, зачисляющие депозиты и обрабатывающие выводы в масштабе, токен-проекты, распределяющие через airdrop или графики вестинга, и подписные бизнесы, выставляющие счета в стейблкоинах каждый месяц. Все они сводятся к тем же двум вызовам: отправить транзакцию, получить вебхук.

Касса стейблкоинами для интернет-магазина

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

Выводы для торговой платформы

Пользователи запрашивают выплаты; ваша задача — надёжно отправлять множество переводов ERC-20. Поставьте каждый вывод в очередь в вашей базе данных со столбцом состояния, затем обрабатывайте очередь через POST /api/v2/ethereum/transactions/erc20 — один запрос на выплату, записывая ответ перед переходом к следующей. Правило, которое делает аудиторов счастливыми: HTTP-вызов, истёкший по таймауту, — не провалившаяся транзакция. Сверяйтесь с вашими записями и GET /api/v2/ethereum/transactions, который перечисляет каждую транзакцию, созданную через API, прежде чем что-либо повторно отправлять, иначе вы заплатите кому-то дважды. Также мониторьте баланс ETH казначейского кошелька, поскольку каждый исходящий перевод сжигает gas, и оповещайте задолго до того, как он иссякнет, а не когда очередь застопорится.

Здесь есть два уровня сбоев: HTTP-ошибки от API и ончейн-условия, которые должна поглотить ваша логика.

HTTP-сторона следует соглашению. 401 означает, что ключ отсутствует или неверен — проблема конфигурации, а не кандидат на повтор. Другие ответы 4xx говорят, что запрос неверен: некорректный адрес, неизвестный контракт, отсутствующее поле. Логируйте тело ответа и исправляйте вызывающую сторону. Повторы с задержкой принадлежат только ответам 5xx и сетевым таймаутам.

Сторона сети — вот где код платежей зарабатывает свою зарплату. Перевод с кошелька без достаточного количества ETH на gas завершается неудачей, даже если баланс токена достаточен, — мониторьте балансы gas проактивно вместо того, чтобы обнаруживать их пустыми в сообщении об ошибке. Перегрузка может отложить включение; это задержка, а не сбой, и ваш UI должен различать их. И правило из разбора вывода стоит повторить, потому что оно защищает от самой дорогой ошибки в этой области: никогда не отправляйте перевод повторно только потому, что HTTP-ответ так и не пришёл. Сначала подтвердите, что этого действительно не произошло.

Для депозитов выработайте привычку сверки. GET /api/v2/ethereum/webhooks/notifications перечисляет то, что было доставлено; ночная сверка с вашим реестром ловит всё, что поглотил баг или сбой, пока исправление ещё дёшево.

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

Структурируйте так, чтобы заголовок приходил из конфигурации: staging его задаёт, продакшен — нет, и между ними нет разницы в коде. Дайте staging также отдельный callback URL, иначе тестовые депозиты попадут в ваш продакшн-обработчик вебхуков. Запуск в продакшен тогда — это удаление одного заголовка, намеренно неэффектное.