Как отправить ERC-20 токены: через кошелек, код и API

Вы можете отправить токены ERC-20 тремя способами: из приложения-кошелька, из собственного кода с помощью библиотеки вроде ethers.js или через REST API, которое подписывает и транслирует транзакцию за вас. Все три делают одно и то же внутри. Они вызывают функцию transfer в смарт-контракте токена, а отправитель платит комиссию сети в ETH, а не в токене. Это руководство охватывает каждый метод, ошибки, приводящие к потере средств, и то, что меняется при переходе от одного ручного перевода к тысячам автоматизированных.

TL;DR

• Перевод ERC-20 — это вызов контракта токена, а не обычный перевод стоимости, как ETH. Адрес получателя и сумма передаются в данных вызова.
• У кошелька-отправителя должен быть ETH на газ, даже если в нем много токенов. При нулевом ETH транзакция провалится.
• Никогда не transfer’ьте токены напрямую в контракт, у которого нет кода для их обработки. Для взаимодействия с контрактами используйте approve и transferFrom.
• В коде учитывайте десятичные знаки токена и токены, не возвращающие стандартный boolean. Оборачивайте вызовы в безопасную библиотеку.
• Если вы создаёте приложение, отправляющее токены от имени пользователей, REST API уберёт работу с нодой, нонсом и газом. Мы рассмотрим это ниже.

Table of Contents

• What actually happens when you send an ERC-20 token
• Before you send: a short checklist
• Method 1: Send from a wallet
• Method 2: Send with code (ethers.js)
• Method 3: Send through a REST API
• Common ways ERC-20 transfers go wrong
• Gasless transfers and meta-transactions
• Our perspective: treat a transfer as a workflow, not a call
• Automating transfers with Chaingateway
• Confirming that the transfer worked
• FAQ
• Sources

What actually happens when you send an ERC-20 token

Отправка ETH перемещает нативную стоимость между двумя аккаунтами. Отправка токена ERC-20 меняет реестр балансов, хранящийся внутри контракта токена. Ваш кошелек создаёт транзакцию, адресованную контракту токена, и этот контракт обновляет балансы отправителя и получателя.

Стандарт ERC-20 определяет методы, которые предоставляет каждый совместимый токен: totalSupply, balanceOf, transfer, transferFrom, approve и allowance. Этот общий интерфейс позволяет одному кошельку или одному коду работать с тысячами разных токенов. Оригинальная спецификация — EIP-20, опубликована в ноябре 2015 года.

Из этой архитектуры следуют несколько последствий:

• Поле to транзакции — это контракт токена, а не человек, которому вы платите. Реальный получатель закодирован в данных вызова.
• Данные вызова начинаются с селектора функции 0xa9059cbb (подпись transfer), за которым следуют адрес получателя и сумма, согласно документации ERC-20 на ethereum.org.
• ERC-20 — это стандарт токенов, а не то же самое, что Ethereum. ETH — нативная валюта сети. Токены вроде USDT — это контракты, работающие поверх неё. Если вам нужна более широкая картина по газу и ETH, см. наш обзор Ethereum.

Тот же формат существует и в других EVM-сетях. Наш пост о стандарте токенов ERC20 глубже раскрывает, как это работает, а руководство по адресам ERC20 объясняет формат адресов и проверку балансов.

Перед отправкой: краткий чек-лист

Большинство потерянных переводов происходит из-за пропущенной подготовки, а не технических сбоев. Сначала проверьте следующее.

1. У вас есть токен и нужная сумма. Подтвердите баланс через balanceOf или в кошельке.
2. У вас есть ETH на газ. Комиссия оплачивается нативной валютой сети, а не списывается из отправляемых токенов. В Polygon или BNB Chain работает та же логика с нативной монетой этой сети. Кошелёк с токенами, но без ETH, ничего не сможет отправить.
3. У вас есть точный адрес получателя. Копируйте и вставляйте его, а не набирайте вручную. Справочный центр MetaMask предупреждает об отравлении адресов, когда злоумышленник засеивает вашу историю похожим адресом.
4. Вы знаете сеть. Один и тот же формат адреса работает в нескольких EVM-сетях. Токен, отправленный в неверной сети, не придёт туда, где ждёт получатель.
5. Получатель может это принять. Отправка на адрес депозита биржи в неверной сети или на контракт, не умеющий работать с токенами, может означать безвозвратную потерю.
6. Сначала протестируйте небольшой суммой. Для нового получателя или новой интеграции отправьте малую сумму и подтвердите получение, прежде чем слать полную сумму.

Способ 1: Отправка из кошелька

Для разовых переводов кошелёк — самый простой путь. Руководство Etherscan по отправке ETH или токенов описывает тот же поток, за которым следуют большинство кошельков:

1. Откройте кошелёк и выберите отправку.
2. Выберите токен, который хотите отправить. Если кошелёк его не показывает, добавьте его, вставив адрес контракта токена.
3. Вставьте адрес получателя.
4. Введите сумму.
5. Проверьте сетевую комиссию. Кошелёк оценит её за вас.
6. Подтвердите, затем отслеживайте хэш транзакции в блок-эксплорере до подтверждения.

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

Способ 2: Отправка кодом (ethers.js)

Разработчикам, которым нужно автоматизировать переводы, можно вызывать контракт напрямую. Урок ethereum.org по отправке токенов с ethers.js показывает базовый паттерн. Отдельное руководство по ethers.js объясняет ключевое отличие от ETH: транзакция не отправляет значение, а вызывает функцию transfer токена с адресом назначения и суммой.

Шги выглядят так:

1. Создайте провайдера, подключенного к узлу Ethereum (своему или хостинговому эндпоинту).
2. Создайте подписанта из приватного ключа или кошелька, которым вы управляете.
3. Инициализируйте контракт токена с его адресом и минимальным ABI, содержащим transfer, balanceOf и decimals.
4. Преобразуйте сумму в удобном для человека формате в базовые единицы, используя количество знаков после запятой токена.
5. Вызовите transfer(recipient, amount) и дождитесь получения чека (receipt).

В том уроке по ethers.js отмечается, что библиотека может отправить транзакцию EIP-1559 без ручной настройки газа, выбирая лимит газа и стандартную приоритетную комиссию. Она также может управлять nonce, когда вы используете подписанта.

Правильно обрабатывайте знаки после запятой

Токены хранят суммы как целые числа. Токен с 18 знаками после запятой представляет 1.0 токена как 1000000000000000000 базовых единиц. Поле decimals является частью стандарта, но разные токены устанавливают разные значения, а текст EIP-20 рассматривает его как необязательные метаданные. Всегда считывайте decimals из контракта вместо того, чтобы предполагать 18. Жесткое кодирование неверного значения приведет к отправке суммы, отличающейся на порядки величины.

Не доверяйте возвращаемому значению слепо

Стандарт гласит, что transfer возвращает булево значение. Не каждый токен в дикой природе ведет себя так. Некоторые ничего не возвращают, а некоторые терпят неудачу неожиданными способами. Интерфейс IERC20 от OpenZeppelin является эталоном стандарта, а библиотека SafeERC20 от OpenZeppelin существует для обертки вызовов, чтобы странные токены не ломали вашу логику. Если ваш смарт-контракт перемещает токены, используйте её. Если ваш бэкенд отправляет токены, проверяйте статус чека транзакции и излученное событие Transfer вместо того, чтобы предполагать успех.

Лимиты газа

Обычный перевод ETH использует лимит газа 21 000, согласно рекомендациям MetaMask. Перевод токена — это вызов контракта, поэтому ему нужно больше газа. Оценивайте газ с помощью вызова оценки вашей библиотеки перед каждой отправкой, а не жестко кодируйте число, потому что стоимость зависит от кода контракта токена и состояния участвующих балансов.

Метод 3: Отправка через REST API

Запуск описанного выше пути кода подходит для скрипта. В продукте это превращается в список рутинных задач: эксплуатация или аренда доступа к узлам, управление ключами, отслеживание nonce, чтобы одновременные отправки не конфликтовали, оценка газа, повторная попытка зависших транзакций, декодирование логов для выяснения, прибыл ли платеж, и повторение всего этого для каждой цепочки.

Единый API снимает этот слой с вашей команды. С Chaingateway вы создаете кошельки, отправляете токены и читаете декодированные данные транзакций через обычные REST-вызовы. Вам не нужны web3.js или ethers.js в вашем стеке, и вам не нужно запускать узлы. Наша страница Ethereum API показывает, как отправка ERC-20 работает через REST. Запросы подписываются HMAC, а газ оценивается автоматически.

Тот же подход распространяется на Bitcoin, Tron, Solana, Polyggon, BNB Chain и Arbitrum, поэтому вторая сеть не означает вторую интеграцию. Если вы позже добавите USDT в Tron, прочитайте наше объяснение TRC10 vs TRC20. Для адресов BNB Chain см. руководство по адресам BEP20.

Когда подходит каждый метод

Ситуация	Кошелёк	Ваш собственный код	REST API
Разовый личный перевод	Лучший вариант	Избыточно	Избыточно
Редкий скрипт в одной сети	Медленно	Хорошо	Хорошо
Выплаты или выводы внутри приложения	Непрактично	Возможно, вы поддерживаете это	Лучшее решение
Несколько сетей и стандартов токенов	Вручную для каждой сети	Клиент для каждой сети	Один интерфейс
Обнаружение входящих платежей	Вручную	Вы создаете слушатели логов	Вебхуки

Распространенные ошибки при переводах ERC-20

Отправка токенов на контракт

Функция transfer не предназначена для депозита в смарт-контракты. Если у контракта нет логики для реакции на входящие токены, они остаются на его балансе без возможности вывода. Страница ethereum.org ERC-20 описывает этот риск, включая токены, отправленные на собственный контракт токена, и сообщает о миллионах долларов, потерянных таким образом по состоянию на июнь 2024 года. Если вы пишете контракты, добавьте функцию, позволяющую восстановить ошибочно отправленные токены. Если вам нужно, чтобы контракт получал токены от пользователя, стандартный паттерн таков: пользователь вызывает approve для контракта, затем контракт вызывает transferFrom.

Нулевой ETH для газа

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

Неправильная сеть или неправильный адрес

Блокчейны не отменяют транзакции. Проверяйте сеть и адрес перед подтверждением и используйте небольшой тестовый перевод для всего нового.

Путаница между токеном и сетью

USDT, например, существует в нескольких сетях. Когда кто-то говорит, что у него есть USDT, спрашивайте, в какой сети. Адрес может выглядеть одинаково в каждой, но средства находятся только в одной цепочке.

Переводы без газа и мета-транзакции

Растущий вариант для онбординга — позволить пользователю подписать сообщение, а кто-то другой отправит транзакцию и оплатит газ. EIP-3009, Transfer With Authorization определяет функции, позволяющие держателю делегировать оплату газа и выполнять переводы через подписи EIP-712. Это поддерживают только токены, чьи контракты это реализуют, поэтому проверяйте перед проектированием потока вокруг этого. Для стартапа это может убрать барьер первого перевода — приобретение ETH.

Наша перспектива: относитесь к переводу как к рабочему процессу, а не как к вызову

Мы видим ту же закономерность в командах, которые впервые интегрируют отправку токенов. Сам вызов transfer занимает полдня. Недели уходят на всё, что вокруг: понимание того, когда платёж действительно зачислился, обработка неудачной или застрявшей транзакции, оценка комиссий и безопасное хранение ключей.

Наш взгляд заключается в том, что отправка и получение должны идти вместе. Поток выплат без событий подтверждения заставляет вас опрашивать сеть, а поток депозитов без декодированных данных — разбирать необработанные логи. Именно поэтому мы создали создание кошельков, переводы токенов, оценку газа, декодированные данные транзакций и вебхук-уведомления за одним API, подписанным с помощью HMAC. Вы получаете один контракт с вашей инфраструктурой вместо одного на каждую сеть, и вам не нужно запускать ноды.

Наш практический совет: начните с небольшого перевода на тестовой настройке, проверьте десятичные знаки и квитанции, подпишитесь на события для подтверждения, и только потом увеличивайте объёмы.

— Bitblade

Автоматизация переводов с Chaingateway

Если вы создаёте выплаты, выводы или депозиты в приложении, вы можете попробовать наш Blockchain API и связать его с Chaingateway Webhooks, чтобы получать уведомления о зачислении платежей. Тарифы на нашей странице цен начинаются от 49 EUR в месяц для Plus, Pro — 99 EUR в месяц, Premium — 249 EUR в месяц и Enterprise — 499 EUR в месяц. При годовой оплате: 490 EUR для Plus, 990 EUR для Pro, 2490 EUR для Premium и 4990 EUR для Enterprise. Платный доступ предоставляется после бесплатного пробного периода.

Подтверждение того, что перевод прошёл успешно

Отправка транзакции — это не то же самое, что завершение платежа. После отправки:

1. Сразу сохраните хеш транзакции.
2. Проверьте статус квитанции. Замайненная транзакция всё равно может завершиться неудачей.
3. Найдите событие Transfer из контракта токена с ожидаемым отправителем, получателем и суммой. Событие является частью интерфейса ERC-20.
4. Подождите столько подтверждений, сколько требует ваша политика рисков, прежде чем выпускать товары или зачислять баланс.
5. Периодически сверяйтесь с balanceOf, чтобы отловить всё, что мог пропустить ваш слушатель.

Опрос сети подходит для небольшого скрипта. Для продакшена подписка на уведомления означает, что ваша система реагирует на события, а не спрашивает их снова и снова.

Источники

• Стандарт токена ERC-20, ethereum.org
• EIP-20: Стандарт токена ERC-20
• Как отправлять токены из кошелька MetaMask, Центр помощи MetaMask
• Как отправлять ETH или токены, Информационный центр Etherscan
• Отправка токенов с использованием ethers.js, ethereum.org
• Ethers.js: Как отправлять токены ERC-20, Центр помощи MetaMask
• IERC20.sol, OpenZeppelin Contracts
• ERC-3009: Перевод с авторизацией

Рекомендуем

• Ethereum API – Отправка токенов ERC-20 через REST, без web3.js
• Стандарт токена ERC20