Контракт токена может развернуть кто угодно, и любой контракт может что-то отправить на ваш адрес. Vilna ведёт балансы токенов по общему проверенному списку и доверенному набору проекта. Фильтр уведомлений по умолчанию тоже использует эти метки наряду с действиями самого выбранного адреса. На этой странице - что это за две метки, что они включают, как читать каталог и как добавить свой контракт.
is_verified - общий список is_trusted - выбор проекта Балансы следуют за метками Метки участвуют в фильтре шума
Запись каталога со status: supported значит, что Vilna получила из сети имя, символ и число десятичных знаков токена и может следить за его переводами. О том, настоящий ли это токен, статус не говорит ничего. Для токенов со знакомым именем, контрактов-двойников и спама метаданные можно получить тем же способом. Если бы каждый распознанный токен давал балансы и оповещения, любой посторонний мог бы заставить вашу интеграцию реагировать, просто отправив вам что угодно.
Поэтому у токена две независимые метки:
is_verified- общий список Vilna, одинаковый для всех проектов. Он ведётся вручную для одного конкретного контракта в одной конкретной сети. Имя, символ или большой объём переводов его не дают.is_trusted- выбор вашего проекта: одним вызовом ставится, другим снимается.
Достаточно любой из них. Нативная монета каждой сети (ETH, BNB, BTC, TRX) всегда в области проекта без метки.
Балансы. Vilna ведёт балансы нативных монет и всех токенов в области проекта: проверенных и тех, которым вы доверились. Чтение баланса или движение токена через ваш адрес область не расширяет. У токена вне области строк баланса нет вовсе.
Уведомления. У каждой подписки есть is_noise_filtered, по умолчанию включённый. С ним уведомление приходит, только если один из выбранных адресов сам даёт основание: он действовал сам (отправитель, вызывающий, создатель или владелец), и тогда токены в транзакции не важны, а незнакомые просто остаются в теле уведомления; либо на этом адресе двинулась нативная монета, проверенный или доверенный токен. Действие, доверенный токен или комиссия другого адреса сами по себе не делают выбранный адрес подходящим под этот фильтр. С выключенным фильтром уведомляет любая активность, задевшая выбранный адрес, включая незнакомые токены; доверия это не даёт и балансов не включает. Подробно фильтр разобран в руководстве о событиях.
Сети Solana распознают токены для каталога, и на этом всё: ни балансов, ни уведомлений, какие бы метки ни стояли.
GET /tokens возвращает каталог. Параметр scope определяет, какую его часть вы видите:
Используйте scope=project для нативных, проверенных и доверенных токенов проекта, а scope=all (по умолчанию) - для полного каталога. Уточняйте выбор сетью chain_gid, поиском search или тегом tag_id. Совпадение в поиске не даёт доверия. Схема CatalogAsset, все фильтры, ограничения и примеры запросов доступны на странице операции выше.
Статус supported означает полученные метаданные, pending - известный идентификатор токена без полного набора метаданных, unsupported - отсутствие поддержки. Имя, символ и decimals гарантированы при supported; до этого они могут быть известны частично.
Серверного фильтра «только проверенные» нет. Чтобы получить их список, запросите scope=project и оставьте записи с is_verified: true, либо отфильтруйте по этому полю весь каталог.
Используйте decimals точного gid, а не символ, общий для разных контрактов и сетей. Сохраняйте точность строк базовых единиц через BigInt или библиотеку точной десятичной арифметики; преобразование в Number может потерять единицы. Суммы аутентифицированного счёта - строки, в отличие от структурированных сумм транзакций. Правила представления сумм описаны в руководстве по счетам.
Например, одна единица токена с decimals: 6 представляется так:
{ "base": "1000000", "formatted": "1.0" }Два вызова. Первый помещает контракт в каталог и получает его метаданные из сети, второй отмечает его доверенным для вашего проекта.
POST /tokens/{chain_gid}/{asset_path} без тела. В ответе запись со status: supported; контракт, получивший статус pending или unsupported, получает 422. Токен, уже известный каталогу, возвращается с 200.
POST /tokens/{chain_gid}/{asset_path}/actions/trust добавляет его в выбор проекта. 404 - токена ещё нет в каталоге; 422 - он есть, но не supported.
Для изменений нужен ключ проекта с api:asset:write, для чтения каталога - api:asset:read. Регистрация токена и добавление в доверенные - отдельные действия с отдельными Idempotency-Key; сохраните каждый ключ и исходные параметры до отправки. Схемы и примеры запросов доступны на страницах операций выше.
При потере ответа повторяйте с тем же ключом и исходными параметрами. Отзыв доверия (untrust) - отдельное действие со своим ключом. При недоступном повторе сверяйте состояние каталога и доверия, не заменяя ключ автоматически. См. Идемпотентность.
С этого момента токен учитывается в ваших подписках, а балансы для всех адресов проекта, текущих и будущих, инициализируются в фоне. За прошлые транзакции ничего не приходит: доверие к токену не создаёт очереди уведомлений задним числом.
POST /tokens/{chain_gid}/{asset_path}/actions/untrust снимает выбор и отвечает 204. Если других меток, удерживающих токен в области, нет, его балансы останавливаются, и он уходит из выдач с scope=project; в полном каталоге (scope=all) он остаётся. Повторное доверие начинает балансы заново, а не продолжает старые.
asset_path - это часть идентификатора CAIP-19 после сети:
| Актив | chain_gid | asset_path |
|---|---|---|
| ETH | eip155:1 | slip44:60 |
| USDT в Ethereum | eip155:1 | erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7 |
| USDT в Tron | tron:728126428 | trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
Тег токенов - именованная группа токенов внутри проекта, которой управляют через GET /token-tags. Теги не меняют доверия; они нужны, чтобы GET /tokens?tag_id=… возвращал одну группу за раз, например принимаемые вами стейблкоины.