> ## Documentation Index > Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Обзор и руководство по getTransfersByAddress > Запрашивайте разобранные, удобочитаемые объекты переводов токенов и нативного SOL для адреса Solana с фильтрацией по минту, времени, сумме и контрагенту. ## Обзор [`getTransfersByAddress`](/docs/ru/api-reference/rpc/http/gettransfersbyaddress) — эксклюзивный RPC-метод Helius, который возвращает разобранные, удобочитаемые объекты переводов токенов и нативного SOL для адреса кошелька. Он не входит в стандартный RPC Solana. Метод ориентирован на операции перевода, поэтому вместо полных данных транзакций он возвращает краткие записи о переводах. Каждая запись нормализована и содержит разобранные аккаунты владельцев и токенов, минты, исходные суммы, количество десятичных знаков, суммы для пользовательского интерфейса, позиции инструкций и статус подтверждения. Благодаря этому вы можете сверять изменения баланса без повторной реализации разбора токенов Solana. Для этого метода требуется тариф [Developer](/docs/ru/billing/plans) или выше. Каждый запрос стоит 10 кредитов. Возвращайте удобочитаемые записи о переводах с разобранными аккаунтами, суммами, количеством десятичных знаков и типами переводов. Учитывайте SOL, WSOL, комиссии Token-2022, минты, сжигания и смену владельцев аккаунтов для точной сверки балансов. Ограничивайте историю переводов по адресу минта, диапазону времени блока или диапазону исходных сумм. Фильтруйте переводы по отправителю или получателю с помощью `with` и `direction`. ## Когда использовать этот метод Используйте `getTransfersByAddress`, если вам нужны: * История переводов кошелька для платежей или мониторинга переводов * Аналитика активности портфеля и перемещений токенов * Надежная сверка балансов для реестров и бухгалтерского учета * Отчеты о переводах по конкретным контрагентам: кто, что, кому отправил или от кого получил * Нормализованная обработка SOL/WSOL, комиссий Token-2022, минтов и сжиганий без написания собственного парсера Вместо этого используйте [`getTransactionsForAddress`](/docs/ru/rpc/gettransactionsforaddress), если вам нужны полные данные транзакций, история только с подписями или действия, не связанные с переводами. Распространенный подход: постранично получить переводы здесь, а затем запросить лежащие в их основе полные транзакции с помощью пакетных вызовов [`getTransaction`](/docs/ru/api-reference/rpc/http/gettransaction) (см. раздел [Получение полных транзакций для строк переводов](#получение-полных-транзакций-для-строк-переводов)). ## Точность и сверка `getTransfersByAddress` предназначен для приложений, которым нужна надежная история переводов для реестров, отслеживания платежей, анализа активности портфеля и сверки балансов. Вместо исходных данных транзакций, требующих самостоятельной обработки всех особых случаев, API возвращает нормализованные объекты переводов. В ответе явно моделируются случаи переводов, которые обычно усложняют сверку истории Solana: * Стандартные переводы токенов SPL и нативного SOL. * Переводы Token-2022 с удержанными комиссиями, представленные как обычные строки `transfer` с отдельными полями комиссий. * Минты и сжигания, представленные как переводы с отправителем или получателем `null`. * Обертывание и развертывание SOL с режимом по умолчанию, который исключает лишние строки жизненного цикла. * Смена владельца токен-аккаунта через SetAuthority. * Вывод удержанных комиссий Token-2022. * Потоки через промежуточные аккаунты, возвращаемые как исходные записи переводов без их объединения в предполагаемое чистое перемещение. Для поддерживаемых видимых событий перевода это позволяет сверять изменения баланса без повторной реализации логики разбора токенов Solana. Известные исключения, например скрытые перемещения SOL, определяемые только по изменениям баланса, перечислены в разделе [Ограничения](#ограничения). ## Быстрый старт ```javascript theme={"system"} const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "getTransfersByAddress", params: ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"] }) }); const data = await response.json(); console.log(data.result.data); ``` ## Параметры запроса Передайте адрес владельца кошелька, а не связанный токен-аккаунт (ATA). API находит операции перевода для токен-аккаунтов, принадлежащих этому кошельку. Закодированный в Base58 адрес кошелька владельца, для которого нужно запросить переводы. Передайте адрес владельца кошелька, а не связанный токен-аккаунт (ATA). Необязательный объект конфигурации для фильтрации, пагинации, уровня подтверждения, сортировки и управления поведением SOL/WSOL. Фильтрация по адресу контрагента. Возвращает только переводы на этот адрес или с него. Фильтрация по направлению перевода относительно `address`. * `in`: переводы, полученные `address` * `out`: переводы, отправленные `address` * `any`: входящие и исходящие переводы Фильтрация по адресу минта токена. Используйте `So11111111111111111111111111111111111111111` для нативного SOL и `So11111111111111111111111111111111111111112` для WSOL. Управляет представлением нативного SOL и WSOL. * `merged`: WSOL обрабатывается как нативный SOL. Строки жизненного цикла обертывания и развертывания исключаются, а значения минта WSOL заменяются на минт нативного SOL. * `separate`: WSOL сохраняется как отдельный минт, а строки жизненного цикла обертывания и развертывания включаются. Дополнительные фильтры по сумме, времени блока и слоту. Максимальное количество возвращаемых переводов. Диапазон: от 1 до 100. Курсор из предыдущего ответа для пагинации. Уровень подтверждения данных. * `finalized` * `confirmed` Минимальный слот, на котором можно обработать запрос Порядок результатов. * `desc`: сначала новые * `asc`: сначала старые ## Ответ ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "result": { "data": [ { "signature": "5GEX7Q3X5Q8yJGbKYoR7mtzQmG8tpoEwzjPgqVmn3y5xg3yKwqXcDdN5YVcc9V6vA4TuH5iM6FHRVhTxvz4AX2zG", "slot": 315073428, "blockTime": 1736159420, "type": "transfer", "fromUserAccount": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "toUserAccount": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", "fromTokenAccount": "HcvK3EJ74iM9g11cUgsaPvLSrhCvCwcrWxBNd87LsC1x", "toTokenAccount": "CBcYniR9G9CN3zGMnwNE4SWbqkYWvCFVreEob9xHnQCY", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "2500000", "decimals": 6, "uiAmount": "2.5", "confirmationStatus": "finalized", "transactionIdx": 35, "instructionIdx": 1, "innerInstructionIdx": 0 } ], "paginationToken": "315073428:35:1:0:splTransfer" } } ``` ### Подробное описание полей ответа * `fromUserAccount` и `toUserAccount` присутствуют всегда. Если одна из сторон отсутствует, используется значение `null`. * `fromTokenAccount` и `toTokenAccount` включаются только в тех случаях, когда конечные точки токен-аккаунтов имеют смысл для строки. Для переводов нативного SOL они полностью отсутствуют. * Переводы минта односторонние: `fromUserAccount` имеет значение `null`, и такие переводы могут возвращаться только как входящие для получателя. * Переводы сжигания односторонние: `toUserAccount` имеет значение `null`, и такие переводы могут возвращаться только как исходящие для владельца, выполняющего сжигание. ## Фильтры Используйте фильтры сравнения для запросов по числовому диапазону. Все поля сравнения необязательны и могут сочетаться. ```json theme={"system"} { "gt": 1000000, "gte": 1000000, "lt": 1000000000, "lte": 1000000000 } ``` | Фильтр | Тип | Описание | | - | - | - | | `amount` | `ComparisonFilter` | Исходная сумма перевода, а не сумма для пользовательского интерфейса. | | `blockTime` | `ComparisonFilter` | Временная метка блока в секундах Unix. | | `slot` | `ComparisonFilter` | Номер слота. | ## Типы переводов Поле `type` определяет поведение перевода, представленное каждой строкой. | Тип | Описание | `fromUserAccount` | `toUserAccount` | | - | - | - | - | | `transfer` | Стандартный перевод токена или SOL между двумя кошельками. | Отправитель | Получатель | | `mint` | Новые токены, выпущенные на кошелек. | `null` | Получатель | | `burn` | Токены, уничтоженные без возможности восстановления. | Отправитель | `null` | | `wrap` | SOL, обернутый в WSOL. По умолчанию исключается в `solMode: "merged"`. | `null` | Владелец | | `unwrap` | WSOL, развернутый обратно в нативный SOL, или рента, возвращенная при закрытии токен-аккаунта. По умолчанию исключается в `solMode: "merged"`. | Владелец | `null` или получатель лампортов | | `changeOwner` | Владелец токен-аккаунта изменен с помощью SetAuthority. | Прежний владелец | Новый владелец | | `withdrawWithheldFee` | Удержанные комиссии Token-2022, полученные из минта или аккаунтов. | `null` | Получатель комиссии | ### Типы переводов и инструкции | Тип перевода | Поддерживаемые инструкции | Видимость по умолчанию | | - | - | - | | `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Всегда | | `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Всегда | | `transfer` | `Token-2022::TransferCheckedWithFee`, с полями `feeAmount` и `feeUiAmount` | Всегда | | `mint` | `Token::MintTo`, `Token::MintToChecked` | Всегда | | `burn` | `Token::Burn`, `Token::BurnChecked` | Всегда | | `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` при использовании для обработки жизненного цикла WSOL | Только `solMode: "separate"` | | `unwrap` | `Token::CloseAccount` для WSOL с балансом больше нуля | Только `solMode: "separate"` | | `unwrap` | Возврат ренты через `Token::CloseAccount` для токен-аккаунтов, не относящихся к WSOL, или аккаунтов WSOL с нулевым балансом токенов | Только `solMode: "separate"` | | `changeOwner` | `Token::SetAuthority(AccountOwner)` | Всегда | | `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Всегда | ## Поведение SOL и wSOL В Solana SOL существует в двух формах, которые часто встречаются вместе в реальных действиях пользователей: * **Нативный SOL** — нативный актив блокчейна. Он хранится непосредственно в кошельке или аккаунте в виде лампортов. Один SOL равен 1 000 000 000 лампортов. * **Обернутый SOL (WSOL, часто записывается как wSOL)** — представление SOL в виде токена SPL. Он использует минт WSOL `So11111111111111111111111111111111111111112` и хранится в токен-аккаунте, как USDC или любой другой токен SPL. Пользователи и приложения обертывают SOL, когда им нужно, чтобы SOL вел себя как токен SPL, обычно для DeFi, обменов, учета на основе токен-аккаунтов или программных интерфейсов, которые принимают только токены SPL. При обертывании токен-аккаунт обычно пополняется нативным SOL, который затем синхронизируется в WSOL. При развертывании токен-аккаунт WSOL закрывается, а SOL возвращается получателю лампортов. Этот жизненный цикл может сделать историю запутанной, если вы пытаетесь ответить на простой вопрос: «Сколько SOL было перемещено между этим кошельком и другим пользователем?» При обертывании или развертывании SOL часто перемещается между аккаунтами одного владельца. Если по умолчанию показывать такие строки жизненного цикла как обычные переводы, приложения могут дважды учитывать действия или отображать внутренние учетные операции как внешние платежи. По умолчанию `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-2022 `TransferCheckedWithFee` представлены одной записью перевода с `type: "transfer"`. Сумма, зачисленная получателю, возвращается в `amount`; сведения об удержанной комиссии возвращаются в `feeAmount` и `feeUiAmount`. Для переводов с комиссиями со счета источника списывается `amount + feeAmount`, а получателю зачисляется `amount`. ```json theme={"system"} { "signature": "WcvF2eFxArpqRJySzDuiP6Xw8BMprWytMpYCxk2ExBt5C1WyxWzDWcCWXW8iKQVYR9AtdQxPE1uu1SMEZvbbhdr", "slot": 409259683, "blockTime": 1774635210, "type": "transfer", "fromUserAccount": "5aZZ4duJUKiMsJN9vRsoAn4SDX7agvKu7Q3QdFWRfWze", "toUserAccount": "FESSvM1cVUchc13XQY8e41oeYxMnyqQNYVZwoznfJsTo", "fromTokenAccount": "3VUYGjYktCzNhDVymNb3Z1iHewtfPFRvdA53qSWuxdXy", "toTokenAccount": "51cEFBA1virMuPqHXvNGs8FKKTMqeEVKzugv1hqPU2Zc", "mint": "CKfatsPMUf8SkiURsDXs7eK6GWb4Jsd6UDbs7twMCWxo", "amount": "48650000", "decimals": 5, "uiAmount": "486.5", "feeAmount": "13450000", "feeUiAmount": "134.5", "confirmationStatus": "finalized", "transactionIdx": 1315, "instructionIdx": 4, "innerInstructionIdx": 0 } ``` ## Примеры ### Фильтрация по USDC ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } ] } ``` ### Входящие переводы от отправителя ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "direction": "in" } ] } ``` ### Диапазон суммы и времени ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "So11111111111111111111111111111111111111112", "filters": { "amount": { "gte": 1000000000, "lt": 10000000000 }, "blockTime": { "gte": 1735718400, "lt": 1738396800 } } } ] } ``` ### Запрос с пагинацией ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "limit": 50, "paginationToken": "315069220:308:2:1:splTransfer" } ] } ``` ### Получение полных транзакций для строк переводов `getTransfersByAddress` возвращает разобранные строки переводов, а не полные данные транзакций. Если вам нужна полная транзакция для каждого перевода, сначала постранично получите переводы, удалите дубликаты по `signature`, а затем запросите полные транзакции с помощью пакетных вызовов [`getTransaction`](/docs/ru/api-reference/rpc/http/gettransaction). `getTransfersByAddress` не поддерживает пакетные запросы для нескольких адресов владельцев. Запрашивайте по одному адресу владельца, а затем группируйте полученные запросы `getTransaction` по подписи. Одна транзакция может создавать несколько строк переводов, поэтому перед получением транзакций всегда удаляйте повторяющиеся подписи. ```javascript theme={"system"} const API_KEY = "YOUR_API_KEY"; const RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${API_KEY}`; const OWNER_ADDRESS = "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"; async function rpc(method, params) { const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method, params }) }); const body = await response.json(); if (body.error) { throw new Error(body.error.message); } return body.result; } async function getAllTransfers(address) { const transfers = []; let paginationToken; do { const result = await rpc("getTransfersByAddress", [ address, { limit: 100, ...(paginationToken ? { paginationToken } : {}) } ]); transfers.push(...result.data); paginationToken = result.paginationToken; } while (paginationToken); return transfers; } async function getTransactionsInBatches(signatures, batchSize = 100) { const transactions = []; for (let i = 0; i < signatures.length; i += batchSize) { const batch = signatures.slice(i, i + batchSize).map((signature, index) => ({ jsonrpc: "2.0", id: `${i + index}`, method: "getTransaction", params: [ signature, { encoding: "jsonParsed", maxSupportedTransactionVersion: 1 } ] })); const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch) }); const results = await response.json(); for (const item of results) { if (item.error) { throw new Error(item.error.message); } transactions.push(item.result); } } return transactions; } const transfers = await getAllTransfers(OWNER_ADDRESS); const signatures = [...new Set(transfers.map((transfer) => transfer.signature))]; const transactions = await getTransactionsInBatches(signatures); console.log(`Fetched ${transfers.length} transfer rows`); console.log(`Fetched ${transactions.length} unique transactions`); ``` ## Ограничения * Неуспешные транзакции не включены в V1. * Скрытые перемещения SOL, определяемые только по изменениям баланса, не поддерживаются в V1. * `harvestWithheldTokensToMint` не поддерживается в V1, поскольку не указывает полученную сумму. * Потоки через промежуточные аккаунты не сокращаются. Если транзакция перемещает средства через промежуточные аккаунты, возвращаются исходные записи переводов. * Пакетные запросы для нескольких адресов владельцев не поддерживаются. Запрашивайте по одному владельцу. ## Дальнейшие действия Полная история транзакций с фильтрацией, сортировкой и поддержкой токен-аккаунтов. Полная схема запроса и ответа для getTransfersByAddress. Выполните историческую загрузку и синхронизируйте данные переводов с собственным индексом. Сравните все методы получения исторических данных Solana. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.