Перевод NFT через API: шаги, параметры и подводные камни
Как работает API для перевода NFT: проверка владения, параметры запроса, газ, подписание, подтверждение и частые ошибки в Ethereum и Solana, с практическим чек-листом.
API для передачи NFT позволяет вашему бэкенду перемещать токен из одного кошелька в другой с помощью одного HTTP-запроса, вместо того чтобы вашей команде приходилось писать вызовы контрактов, подписывать транзакции и управлять нодами вручную. Под капотом каждая передача по-прежнему является ончейн-транзакцией: задача API — проверить владение, сформировать правильный вызов для стандарта токена, оценить комиссии, подписать, отправить транзакцию и сообщить вам, что произошло. Это руководство проведет вас через каждый из этих шагов, параметры, необходимые для каждого запроса, и ошибки, которые отнимают у разработчиков больше всего времени.
Краткое содержание
- Передача NFT меняет владельца, записанного в контракте токена. В сетях типа Ethereum это вызов
transferFromилиsafeTransferFrom; в Solana — инструкция токена или Metaplex. - Запрос требует четырех вещей: кошелек отправителя, адрес получателя, адрес контракта (или минта) и ID токена. ERC-1155 также требует указания количества.
- Проверяйте владение перед отправкой, оценивайте комиссии перед подписанием и подтверждайте успех в сети (чекви и событие Transfer), а не только по HTTP-ответу.
- Самые частые сбои: неверная сеть, контракты получателей, которые не могут принимать NFT, отсутствие нативного газа и устаревшее владение.
- Унифицированный API устраняет необходимость настраивать инфраструктуру для каждой сети отдельно. Наш также поддерживает вебхуки для подтверждения, чтобы вам не приходилось опрашивать сеть.
Оглавление
- Что на самом деле делает API для передачи NFT
- Какие стандарты и сети может охватывать API передачи
- Как передать NFT через API: пошагово
- Что нужно для запроса на передачу
- Комиссии: оценка и оплата
- Меры безопасности
- Частые ошибки и их значение
- Подтверждение передач через вебхуки вместо опроса
- Наш взгляд
- Перемещение NFT с Chaingateway
- Чек-лист перед запуском
- FAQ
- Источники
Что на самом деле делает API для передачи NFT
NFT — это запись в смарт-контракте (или, в случае Solana, в токен-аккаунте), указывающая, какой адрес владеет каким токеном. Передача означает изменение этой записи, и делать это может только владелец или тот, кого владелец уполномочил.
Стандарт ERC-721 определяет это на уровне контракта. Каждый токен идентифицируется по ID токена, а передача переводит владение с одного адреса на другой, когда она инициируется владельцем, утвержденным адресом или оператором. Затем контракт генерирует событие Transfer — сигнал, за которым следят большинство индексаторов и систем уведомлений.
API находится поверх этого. Хороший API берет на себя пять задач:
- Проверка владения: подтверждение того, что кошелек отправителя в данный момент владеет токеном.
- Формирование вызова: кодирование правильной функции для стандарта и сети.
- Оценка комиссий: расчет газа или сетевых комиссий и проверка способности кошелька их оплатить.
- Подписание и трансляция: подписание ключом кошелька и отправка транзакции.
- Отчет о статусе: возврат хеша транзакции и уведомление о том, когда передача завершена.
Альтернатива — запуск собственного узла, хранение web3-библиотек для каждой цепочки и самостоятельная реализация кодирования. Это работает для одной цепочки и одной коллекции. Стоимость возрастает, когда вы добавляете вторую сеть.
Какие стандарты и цепочки может охватывать API перевода
Не каждый NFT представляет собой один и тот же тип объекта, поэтому API должен понимать более одного диалекта.
| Стандарт / модель | Цепочки | Как работает перевод |
|---|---|---|
| ERC-721 | Ethereum, Polygon, Arbitrum и другие EVM-цепочки | Один идентификатор токена на токен; transferFrom или safeTransferFrom |
| ERC-1155 | Ethereum и EVM-цепочки | Мульти-токен контракт; перевод включает количество для каждого идентификатора токена, с пакетными переводами |
| SPL-токен с предложением один + метаданные Metaplex | Solana | Перевод через программу токенов; метаданные хранятся отдельно |
ERC-1155 заслуживает более детального изучения, если вы работаете с игровыми предметами или билетами. Один контракт содержит как взаимозаменяемые, так и невзаимозаменяемые типы, его интерфейс включает одиночные и безопасные пакетные переводы, и каждый перевод несет количество для идентификатора токена. Токен с предложением в один ведет себя как классический NFT, но издание с предложением 500 — это другой случай: вы должны отправить количество, а не только идентификатор.
Solana работает иначе. Обычно она не развертывает отдельный контракт для каждой коллекции. Используется её Программа токенов с предложением минта в один, а Metaplex Token Metadata хранит детали NFT. Поэтому в Solana вы переводите по адресу минта, а не по контракту плюс идентификатор токена, и должны ожидать, что получателю понадобится токен-аккаунт для этого минта.
Когда вы оцениваете любого провайдера, спрашивайте, какие из этих трех моделей он поддерживает на каких цепочках. Blockchain API Chaingateway охватывает Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain и Arbitrum, и поддерживает основные стандарты токенов, включая ERC-721, поэтому один и тот же паттерн интеграции применяется ко всем сетям, которые вы добавите позже.
Как перевести NFT через API, пошагово
Поток одинаков независимо от провайдера. Разница лишь в том, сколько из этого вам придется написать самостоятельно.
1. Проверьте владение
Перед построением транзакции убедитесь, что отправитель действительно владеет токеном. Для ERC-721 это означает запрос к контракту о том, кто владеет идентификатором токена. Для ERC-1155 — проверку баланса этого идентификатора для адреса. Для Solana — проверку токен-аккаунта, содержащего минт.
Делайте это непосредственно перед отправкой, а не из кэшированной строки базы данных. NFT могут быть проданы или перемещены за секунды между вашей последней синхронизацией и запросом, и перевод из кошелька, который больше не владеет токеном, просто завершится ошибкой и всё равно может стоить комиссии в некоторых режимах сбоя.
2. Проверьте авторизацию
Стандарт позволяет инициировать перевод владельцу, утвержденному адресу или оператору. Если ваш сервис перемещает NFT из пользовательских кошельков, которыми вы не управляете, вам сначала нужно утверждение. Если ваш сервис хранит ключи для созданных им кошельков (как в кастодиальных потоках), отправляющий кошелек является владельцем, и утверждение не требуется.
3. Постройте и оцените
Выберите функцию и закодируйте аргументы. Затем оцените комиссию. В EVM-цепочках это означает лимит газа, умноженный на цену газа; в Solana — небольшую комиссию за подпись плюс, возможно, ренту за новый токен-аккаунт. API с автоматической оценкой газа делает это за вас, поэтому вам не нужно жестко кодировать лимит газа, который провалится, когда получатель — контракт с дополнительной логикой.
Также убедитесь, что в кошельке достаточно нативной монеты. Адрес с десятью NFT и нулем ETH не сможет переместить ни один из них.
4. Подпишите и отправьте
Транзакция должна быть подписана закрытым ключом владельца. Либо вы подписываете локально и отправляете сырую транзакцию, либо API подписывает за кошелек, которым оно управляет. Управляемые кошельки проще для бэкенд-процессов, так как ваши серверы никогда не работают с сырыми ключами.
5. Подтвердите
Хеш транзакции означает, что сеть приняла вашу отправку, а не то, что перевод прошел успешно. Дождитесь получения чека (receipt) со статусом успеха и события Transfer с ожидаемым отправителем, получателем и ID токена. Для высокоценных NFT дождитесь нескольких подтверждений, прежде чем обновлять свою базу данных или выпускать что-либо в обмен.
Что нужно в запросе на перевод
Как бы ни назывались поля провайдера, запрос несет одну и ту же информацию.
| Параметр | Зачем он нужен | Примечания |
|---|---|---|
| Сеть / блокчейн | Один и тот же адрес существует во многих EVM-сетях | Mainnet против testnet — первое, что стоит проверить, когда токен «исчезает» |
| Кошелек отправителя | Определяет, кто подписывает и платит | Должен владеть токеном и иметь нативный газ |
| Адрес получателя | Назначение | Проверяйте формат и контрольную сумму; никогда не принимайте свободный текст без проверок |
| Адрес контракта или минта | Идентифицирует коллекцию | Контракт в EVM, минт в Solana |
| ID токена | Идентифицирует отдельный токен | Не используется в Solana, где минт — это и есть токен |
| Количество | Количество для перемещения | Обязательно для ERC-1155; единица для ERC-721 |
| Настройки комиссии | Лимит и цена газа или приоритетная комиссия | Позвольте API оценить, если у вас нет причины не делать этого |
| Идемпотентность или ссылка | Предотвращает двойную отправку при повторной попытке | Храните свою ссылку против хеша транзакции |
Последняя строка важнее, чем кажется. Если ваш запрос истек по таймауту, вы не знаете, была ли транзакция отправлена. Слепой повтор может отправить вторую транзакцию, которая для уникального NFT просто упадет с ошибкой, но для выпуска ERC-1155 может переместить лишние копии. Сначала проверьте предыдущую попытку.
Комиссии: оценка и оплата
В EVM-сетях отправитель платит газ нативной монетой цепи, а стоимость варьируется в зависимости от загрузки сети и сложности вызова. Обычный transferFrom дешевле минта или продажи на маркетплейсе, но контракт-получатель с тяжелой функцией-приемником может поднять цену.
Практические правила:
- Оценивайте газ непосредственно перед отправкой и добавляйте небольшой буфер вместо использования фиксированного числа.
- Держите минимальный нативный баланс на каждом кошельке, отправляющем NFT, и настраивайте алерты, когда он падает ниже порога.
- Если вы переводите от имени пользователей, решите заранее, кто платит: вы (пополняете кошелек) или пользователь (списываете с баланса). Неожиданности здесь превращаются в тикеты в поддержку.
- В Solana помните, что получателю может понадобиться новый токен-аккаунт, что имеет разовую стоимость.
Меры безопасности
Переводы NFT необратимы. Нет чарджбэков и нет службы поддержки в цепи, поэтому защита живет в вашем коде.
Защитите путь подписания. Аутентифицируйте каждый вызов API. Chaingateway подписывает запросы с помощью HMAC, поэтому запрос, измененный в пути или отправленный кем-то без секрета, будет отклонен. Храните секрет в хранилище, ротируйте его и никогда не отправляйте его в браузер или мобильное приложение.
Проверяйте получателя. Проверяйте формат адреса и сеть. Предлагайте шаг подтверждения для высокоценных предметов. Там, где политика это требует, проверяйте адреса перед отправкой.
Учитывайте контракты-получатели. Спецификация ERC-721 описывает safeTransferFrom как проверку, когда адрес назначения является контрактом, того, что он реализует интерфейс получателя, и отмену транзакции, если это не так. Использование безопасного варианта защищает вас от блокировки токена в контракте, который не может его переместить. Обычный transferFrom оставляет эту ответственность вызывающему.
Ограничьте риски. Храните в горячем кошельке только те NFT, которые нужны для ближайших переводов, а остальные — в кошельке с более строгими ограничениями. Применяйте лимиты на запрос и суточные лимиты на своем уровне.
Логируйте всё. Записывайте, кто запросил перевод, параметры, хеш и результат. Когда клиент оспаривает перевод, блокчейн доказывает, что произошло, а ваши логи — кто об этом просил.
Распространенные ошибки и их значение
| Симптом | Вероятная причина | Исправление |
|---|---|---|
| Транзакция отменяется | Отправитель не владеет токеном или не одобрен | Повторно проверьте владение и одобрение непосредственно перед отправкой |
| Отменяется только для некоторых получателей | Получатель — контракт без функции приема | Используйте другой адрес или убедитесь, что контракт поддерживает NFT |
| ”Недостаточно средств” | Нет нативной монеты для оплаты комиссии | Пополните кошелек отправителя |
| Транзакция застряла в ожидании | Слишком низкая цена газа или пропуск в nonce | Замените на транзакцию с более высокой комиссией, используя тот же nonce |
| Токен не виден у получателя | Не та сеть или метаданные не обновлены | Проверьте сеть и событие Transfer; кошельки могут кэшировать данные |
| Перемещено неверное количество | Неверная обработка количества ERC-1155 | Всегда передавайте явное количество и проверяйте баланс после |
Большинство из них выявляются двумя привычками: проверкой владения и баланса в первую очередь, и рассмотрением ончейн-чека как единственного доказательства успеха.
Подтверждение переводов через вебхуки вместо опроса
Опрос хеша транзакции каждые несколько секунд работает в прототипе и тратит запросы в продакшене. Вебхуки меняют модель: провайдер вызывает ваш эндпоинт, когда перевод замайнен, с декодированными данными об отправителе, получателе и токене. Проверяйте подпись на каждом входящем вызове, отвечайте быстро и обрабатывайте события идемпотентно, так как доставки могут повторяться. Если вы хотите понять, как такие события выглядят на уровне логов, наш разбор события ERC-20 Transfer охватывает структуру и топики, а событие ERC-721 следует тому же шаблону с индексированным ID токена.
Наша перспектива
Большинство команд недооценивают переводы NFT, потому что «счастливый путь» — это один вызов функции. Работа заключается во всем, что вокруг: в какой сети, чей газ, что происходит при повторной попытке, как вы узнаете результат. Мы создали Chaingateway, чтобы разработчик не нес ответственность за эту поверхность атаки. Один REST API заменяет эндпоинты для конкретных цепочек и ваши собственные ноды, ответы приходят уже декодированными, так что вам не нужно парсить логи вручную, газ оценивается автоматически, а запросы подписываются HMAC.
Наш совет — проектируйте сначала для случаев сбоев. Решите, кто платит комиссии, что считается подтверждением и как распознается повторная попытка, и сам вызов перевода станет легкой частью. Для более широкого контекста о том, где подходит каждый тип провайдера, см. наше сравнение типов блокчейн API.
— Bitblade
Перемещение NFT с Chaingateway
Если вы создаёте приложение, которое создаёт кошельки, отправляет токены и NFT, а также реагирует на события в цепочке, Blockchain API Chaingateway даёт вам одну интеграцию для Ethereum, Solana, Polygon, BNB Chain, Arbitrum, Tron и Bitcoin. В сочетании с уведомлениями через вебхуки вы можете отправить перевод и узнать, когда он будет зачислен. Тарифы начинаются от 49 € в месяц (Plus), Pro — 99 €, Premium — 249 € и Enterprise — 499 € в месяц; при годовой оплате — 490 €, 990 €, 2490 € и 4990 € соответственно. Подробности о том, что включает каждый план, см. на странице цен, а начать можно с бесплатного пробного периода, чтобы протестировать переводы в вашей цепочке.
Если ваш стек ориентирован на конкретную сеть, на выделенных страницах Ethereum API и Solana API показано, как работает отправка токенов в каждой из них.
Чек-лист перед запуском
Прежде чем позволить реальным пользователям инициировать переводы NFT, пройдитесь по этому списку в тестовой сети:
- Переведите принадлежащий вам токен на обычный кошелёк и подтвердите получение и событие
Transfer. - Переведите на контракт, который не может принимать NFT, и убедитесь, что ваш код корректно обрабатывает ошибку.
- Попробуйте выполнить перевод с кошелька, у которого нет нативной монеты, и убедитесь, что ошибка понятна.
- Отправьте один и тот же запрос дважды и убедитесь, что ваша проверка идемпотентности блокирует второй.
- Отключите свою конечную точку вебхука на минуту, восстановите её и убедитесь, что события не потеряны и не обработаны дважды.
- Проверьте, кто может вызывать конечную точку, с какими лимитами и где хранится секрет.
Источники
Рекомендуем
Часто задаваемые вопросы
Да. Хостинговый блокчейн API подключается к узлам за вас, формирует и транслирует транзакцию и возвращает её хеш. Вам всё равно нужно управлять ключами кошелька или использовать управляемый кошелёк, а также держать нативную монету для оплаты комиссий.
Оба меняют владельца согласно ERC-721. Безопасная версия дополнительно проверяет, что контракт-получатель реализует интерфейс получателя, и отменяет транзакцию, если нет, что предотвращает застревание токенов, согласно спецификации ERC-721. Для автоматизированных потоков безопасная версия обычно является лучшим выбором по умолчанию.
Да, на практике. Переводы ERC-1155 несут количество для каждого ID токена и поддерживают пакетные переводы, как описано в стандарте ERC-1155. Ваш запрос должен включать количество, и вы должны проверить баланс после этого.
Проверьте чек транзакции на успех и найдите соответствующее событие Transfer с правильным отправителем, получателем и ID токена. Вебхук может доставить это на ваш бэкенд сразу после майнинга, поэтому вам не нужно опрашивать сеть.
Не вами. Только новый владелец может вернуть его. Поэтому вы должны проверять адреса, подтверждать сеть и добавлять шаг подтверждения для ценных токенов перед отправкой.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.