Обзор
getTransfersByAddress — эксклюзивный RPC-метод Helius, который возвращает разобранные, удобочитаемые объекты переводов токенов и нативного SOL для адреса кошелька. Он не входит в стандартный RPC Solana.
Метод ориентирован на операции перевода, поэтому вместо полных данных транзакций он возвращает краткие записи о переводах. Каждая запись нормализована и содержит разобранные аккаунты владельцев и токенов, минты, исходные суммы, количество десятичных знаков, суммы для пользовательского интерфейса, позиции инструкций и статус подтверждения. Благодаря этому вы можете сверять изменения баланса без повторной реализации разбора токенов Solana.
Для этого метода требуется тариф Developer или выше. Каждый запрос стоит 10 кредитов.
Parsed transfer objects
Возвращайте удобочитаемые записи о переводах с разобранными аккаунтами, суммами, количеством десятичных знаков и типами переводов.
Reconciliation ready
Учитывайте SOL, WSOL, комиссии Token-2022, минты, сжигания и смену владельцев аккаунтов для точной сверки балансов.
Mint, time, and amount filters
Ограничивайте историю переводов по адресу минта, диапазону времени блока или диапазону исходных сумм.
Counterparty filters
Фильтруйте переводы по отправителю или получателю с помощью
with и direction.Когда использовать этот метод
ИспользуйтеgetTransfersByAddress, если вам нужны:
- История переводов кошелька для платежей или мониторинга переводов
- Аналитика активности портфеля и перемещений токенов
- Надежная сверка балансов для реестров и бухгалтерского учета
- Отчеты о переводах по конкретным контрагентам: кто, что, кому отправил или от кого получил
- Нормализованная обработка SOL/WSOL, комиссий Token-2022, минтов и сжиганий без написания собственного парсера
getTransactionsForAddress, если вам нужны полные данные транзакций, история только с подписями или действия, не связанные с переводами. Распространенный подход: постранично получить переводы здесь, а затем запросить лежащие в их основе полные транзакции с помощью пакетных вызовов getTransaction (см. раздел Получение полных транзакций для строк переводов).
Точность и сверка
getTransfersByAddress предназначен для приложений, которым нужна надежная история переводов для реестров, отслеживания платежей, анализа активности портфеля и сверки балансов. Вместо исходных данных транзакций, требующих самостоятельной обработки всех особых случаев, API возвращает нормализованные объекты переводов.
В ответе явно моделируются случаи переводов, которые обычно усложняют сверку истории Solana:
- Стандартные переводы токенов SPL и нативного SOL.
- Переводы Token-2022 с удержанными комиссиями, представленные как обычные строки
transferс отдельными полями комиссий. - Минты и сжигания, представленные как переводы с отправителем или получателем
null. - Обертывание и развертывание SOL с режимом по умолчанию, который исключает лишние строки жизненного цикла.
- Смена владельца токен-аккаунта через SetAuthority.
- Вывод удержанных комиссий Token-2022.
- Потоки через промежуточные аккаунты, возвращаемые как исходные записи переводов без их объединения в предполагаемое чистое перемещение.
Быстрый старт
Параметры запроса
Передайте адрес владельца кошелька, а не связанный токен-аккаунт (ATA). API находит операции перевода для токен-аккаунтов, принадлежащих этому кошельку.string
обязательно
Закодированный в Base58 адрес кошелька владельца, для которого нужно запросить переводы. Передайте адрес владельца кошелька, а не связанный токен-аккаунт (ATA).
object
Необязательный объект конфигурации для фильтрации, пагинации, уровня подтверждения, сортировки и управления поведением SOL/WSOL.
string
Фильтрация по адресу контрагента. Возвращает только переводы на этот адрес или с него.
string
по умолчанию:"any"
Фильтрация по направлению перевода относительно
address.in: переводы, полученныеaddressout: переводы, отправленныеaddressany: входящие и исходящие переводы
string
Фильтрация по адресу минта токена. Используйте
So11111111111111111111111111111111111111111 для нативного SOL и So11111111111111111111111111111111111111112 для WSOL.string
по умолчанию:"merged"
Управляет представлением нативного SOL и WSOL.
merged: WSOL обрабатывается как нативный SOL. Строки жизненного цикла обертывания и развертывания исключаются, а значения минта WSOL заменяются на минт нативного SOL.separate: WSOL сохраняется как отдельный минт, а строки жизненного цикла обертывания и развертывания включаются.
object
Дополнительные фильтры по сумме, времени блока и слоту.
number
по умолчанию:"100"
Максимальное количество возвращаемых переводов. Диапазон: от 1 до 100.
string
Курсор из предыдущего ответа для пагинации.
string
по умолчанию:"finalized"
Уровень подтверждения данных.
finalizedconfirmed
number
Минимальный слот, на котором можно обработать запрос
string
по умолчанию:"desc"
Порядок результатов.
desc: сначала новыеasc: сначала старые
Ответ
Подробное описание полей ответа
fromUserAccountиtoUserAccountприсутствуют всегда. Если одна из сторон отсутствует, используется значениеnull.fromTokenAccountиtoTokenAccountвключаются только в тех случаях, когда конечные точки токен-аккаунтов имеют смысл для строки. Для переводов нативного SOL они полностью отсутствуют.- Переводы минта односторонние:
fromUserAccountимеет значениеnull, и такие переводы могут возвращаться только как входящие для получателя. - Переводы сжигания односторонние:
toUserAccountимеет значениеnull, и такие переводы могут возвращаться только как исходящие для владельца, выполняющего сжигание.
Фильтры
Используйте фильтры сравнения для запросов по числовому диапазону. Все поля сравнения необязательны и могут сочетаться.Типы переводов
Полеtype определяет поведение перевода, представленное каждой строкой.
Типы переводов и инструкции
Поведение SOL и wSOL
В Solana SOL существует в двух формах, которые часто встречаются вместе в реальных действиях пользователей:- Нативный SOL — нативный актив блокчейна. Он хранится непосредственно в кошельке или аккаунте в виде лампортов. Один SOL равен 1 000 000 000 лампортов.
- Обернутый SOL (WSOL, часто записывается как wSOL) — представление SOL в виде токена SPL. Он использует минт WSOL
So11111111111111111111111111111111111111112и хранится в токен-аккаунте, как USDC или любой другой токен SPL.
getTransfersByAddress использует solMode: "merged". В этом режиме:
- При запросе по
So11111111111111111111111111111111111111111нативный SOL и WSOL обрабатываются как единый актив SOL. - Строки переводов WSOL нормализуются до минта нативного SOL, чтобы упростить сверку истории, выраженной в SOL.
- Строки жизненного цикла обертывания и развертывания исключаются, поскольку они обычно отражают перемещение между аккаунтами одного владельца, а не платеж другому пользователю.
- Переводы SOL и WSOL между разными владельцами по-прежнему представлены как переводы.
- Рента, возвращенная из
CloseAccount, представлена как строкаunwrapнативного SOL, если возвращаются строки жизненного цикла закрытия аккаунта.
solMode: "separate", если вам нужно представить WSOL как отдельный минт токена SPL или просмотреть записи жизненного цикла обертывания и развертывания. В этом режиме WSOL сохраняет минт So11111111111111111111111111111111111111112, а записи обертывания и развертывания возвращаются с type: "wrap" или type: "unwrap".
При закрытии аккаунтов WSOL в solMode: "separate" записи unwrap для минта WSOL представляют оставшийся баланс токенов WSOL, возвращенный в виде SOL. Рента, возвращенная из закрытого токен-аккаунта, представлена отдельной строкой unwrap нативного SOL.
Комиссии за переводы Token-2022
Инструкции Token-2022TransferCheckedWithFee представлены одной записью перевода с type: "transfer". Сумма, зачисленная получателю, возвращается в amount; сведения об удержанной комиссии возвращаются в feeAmount и feeUiAmount.
Для переводов с комиссиями со счета источника списывается amount + feeAmount, а получателю зачисляется amount.
Примеры
Фильтрация по USDC
Входящие переводы от отправителя
Диапазон суммы и времени
Запрос с пагинацией
Получение полных транзакций для строк переводов
getTransfersByAddress возвращает разобранные строки переводов, а не полные данные транзакций. Если вам нужна полная транзакция для каждого перевода, сначала постранично получите переводы, удалите дубликаты по signature, а затем запросите полные транзакции с помощью пакетных вызовов getTransaction.
getTransfersByAddress не поддерживает пакетные запросы для нескольких адресов владельцев. Запрашивайте по одному адресу владельца, а затем группируйте полученные запросы getTransaction по подписи. Одна транзакция может создавать несколько строк переводов, поэтому перед получением транзакций всегда удаляйте повторяющиеся подписи.
Ограничения
- Неуспешные транзакции не включены в V1.
- Скрытые перемещения SOL, определяемые только по изменениям баланса, не поддерживаются в V1.
harvestWithheldTokensToMintне поддерживается в V1, поскольку не указывает полученную сумму.- Потоки через промежуточные аккаунты не сокращаются. Если транзакция перемещает средства через промежуточные аккаунты, возвращаются исходные записи переводов.
- Пакетные запросы для нескольких адресов владельцев не поддерживаются. Запрашивайте по одному владельцу.
Дальнейшие действия
getTransactionsForAddress
Полная история транзакций с фильтрацией, сортировкой и поддержкой токен-аккаунтов.
API reference
Полная схема запроса и ответа для getTransfersByAddress.
Indexing guide
Выполните историческую загрузку и синхронизируйте данные переводов с собственным индексом.
Historical data overview
Сравните все методы получения исторических данных Solana.