Перейти к основному содержанию

Обзор

getTransactionsForAddress объединяет поиск сигнатур транзакций и получение полных данных транзакций в один эффективный вызов. Вместо отдельных запросов к getSignaturesForAddress, а затем к getTransaction для каждой сигнатуры, вы получаете всё в одном запросе. Метод поддерживает:
  • Сортировку в обоих направлениях (сначала старые или сначала новые)
  • Фильтрацию по времени и слотам с помощью операторов диапазона
  • Фильтрацию по статусу транзакции (успешные/неудачные)
  • Фильтрацию по токен-аккаунтам (none, balanceChanged, all)
  • Пагинацию на основе курсора через paginationToken
  • Четыре уровня детализации: signatures, none, accounts, full
Когда вызову getTransactionsForAddress нужно читать данные из архива, он учитывается в архивном лимите: 10% от RPS вашего плана (например, 5 RPS на плане Разработчик). При превышении возвращается HTTP 429 с сообщением archival rate limit exceeded. Его также нельзя отправлять в пакетном запросе JSON-RPC: отправляйте каждый вызов отдельным запросом. См. Аутентификация и лимиты.

Зачем использовать этот метод

Проблема N+1

Со стандартными методами Solana RPC получение истории транзакций требует нескольких вызовов:
  1. Вызвать getSignaturesForAddress, чтобы получить список сигнатур транзакций
  2. Вызвать getTransaction для каждой сигнатуры, чтобы получить полные данные транзакции
Для кошелька со 100 транзакциями это 101 вызов API. Для 1 000 транзакций — 1 001 вызов. Это увеличивает задержку, сложность и расходы. getTransactionsForAddress решает эту проблему, возвращая полные данные транзакций в одном вызове — до 100 полных транзакций или 1 000 сигнатур за запрос.

Дополнительные возможности

Помимо эффективности, метод предоставляет возможности, недоступные в стандартном RPC:
  • Сортировка в обоих направлениях: запрашивайте сначала старые (asc), чтобы проследить адрес с его первой транзакции
  • Фильтрация по времени: получайте транзакции за определённый период с помощью filters.blockTime и операторов диапазона
  • Фильтрация по слотам: запрашивайте транзакции из определённых диапазонов блоков с помощью filters.slot и операторов диапазона
  • Фильтрация по статусу: получайте только успешные или только неудачные транзакции
  • Включение токен-аккаунтов: учитывайте транзакции связанных токен-аккаунтов

Поддержка токен-аккаунтов

Стандартный getSignaturesForAddress возвращает только транзакции, которые напрямую ссылаются на запрашиваемый адрес. При этом упускается важная категория: переводы токенов. Когда токены отправляются на кошелёк, транзакция ссылается на Associated Token Account (ATA) кошелька, а не на сам адрес кошелька. Поэтому стандартные методы дают неполную картину. getTransactionsForAddress с tokenAccounts: "all" автоматически включает транзакции всех токен-аккаунтов, принадлежащих адресу, и даёт полную историю транзакций.
Установите tokenAccounts: "none" (значение по умолчанию), если вам нужны только транзакции, напрямую ссылающиеся на адрес.

Параметры

string
обязательно
Запрашиваемый адрес Solana (публичный ключ в кодировке base-58, 32 байта)
object

Ответ

result в ответе — объект, содержащий массив data и необязательный paginationToken:
paginationToken присутствует только тогда, когда доступны дополнительные результаты. Передайте его в следующем запросе, чтобы получить следующую страницу.

При transactionDetails: "signatures" или "none"

object

При transactionDetails: "accounts"

Те же поля, что и в режиме signatures, а также:
string[]
Массив публичных ключей base-58, участвующих в транзакции, включая адреса, загруженные из lookup-таблиц.

При transactionDetails: "full"

object

Примеры кода

Базовый запрос

Получить последние сигнатуры для адреса (режим по умолчанию):

Получить полные транзакции

Получить до 100 полных транзакций:

Получить только сигнатуры

Получить до 1000 сигнатур без полных данных транзакций:

Сначала старые, с фильтром по времени

Получить транзакции за определённый период, отсортированные от старых к новым:

Только успешные транзакции

Фильтр, возвращающий только успешные транзакции:

Запрос с пагинацией

Используйте пагинацию на основе курсора, чтобы получить больше результатов:

Пример на TypeScript

Сценарии использования

Анализ запуска токена

Найдите самые ранние транзакции минта токена, чтобы определить первых минтеров и ранних держателей. Используйте sortOrder: "asc", чтобы начать с самого начала:

История пополнения кошелька

Отследите, откуда поступили средства кошелька, запросив его полную историю транзакций:

Анализ неудачных транзакций

Отлаживайте сбои транзакций, отфильтровав только неудачные транзакции:

Лента транзакций кошелька

Создайте историю транзакций с пагинацией для интерфейса кошелька:

Анализ торговых паттернов

Отфильтруйте успешные сделки в определённом временном окне:

Аудит для комплаенса

Соберите полную историю транзакций для соответствия регуляторным требованиям:

Пагинация

Для адресов с большим количеством транзакций используйте paginationToken из ответа, чтобы получить следующую страницу. Токен — строка в формате "slot:txIndex", которая указывает серверу, откуда продолжить.

Получение более новых транзакций (по умолчанию)

При sortOrder: "desc" (по умолчанию) транзакции возвращаются от новых к старым. paginationToken продолжает выдачу к более старым транзакциям:

Получение сначала более старых транзакций

При sortOrder: "asc" транзакции возвращаются от старых к новым. paginationToken продолжает выдачу к более новым транзакциям:

Полный пример пагинации

Получить все сигнатуры для адреса:

Рекомендации

  1. Используйте режим signatures для подсчёта: если нужно только посчитать или перечислить транзакции, используйте transactionDetails: "signatures" (по умолчанию) — это быстрее и даёт более высокие лимиты (до 1000).
  2. Фильтруйте заранее: применяйте фильтры blockTime, slot или status, чтобы уменьшить объём просматриваемых данных и ускорить ответы.
  3. Реализуйте пагинацию: для адресов с большим количеством транзакций всегда используйте пагинацию с paginationToken из ответа.
  4. Кешируйте результаты: после финализации данные транзакций не меняются. Кешируйте исторические результаты, чтобы избежать лишних запросов.
  5. Не превышайте архивный лимит: для вызовов, читающих из архива, лимит составляет 10% от RPS вашего плана. Распределяйте последовательные запросы так, чтобы не превышать его, и используйте экспоненциальную задержку при 429.

Частые ошибки

Сравнение со стандартными методами