> ## 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. # Visão Geral e Tutorial de getTransfersByAddress > Consulta objetos transferidos de tokens e SOL nativo, de um endereço Solana, em formato legível com filtros por mint, tempo, quantia e contraparte. ## Visão Geral [`getTransfersByAddress`](/docs/pt-BR/api-reference/rpc/http/gettransfersbyaddress) é um método RPC exclusivo do Helius que retorna objetos de transferência de tokens e SOL nativo em formato legível para um endereço de carteira. Não faz parte do RPC padrão do Solana. Focado em atividades de transferência, ele retorna registros concisos de transferências ao invés de cargas de transação completas. Cada registro é normalizado com contas de proprietário e de token analisadas, mints, quantias brutas, decimais, quantias UI, posições de instruções e status de confirmação, para que você possa reconciliar o movimento de saldo sem reimplementar a análise de token do Solana. Este método requer um [Plano Desenvolvedor](/docs/pt-BR/billing/plans) ou superior e custa 10 créditos por solicitação. Retorna registros de transferência legíveis com contas analisadas, quantias, decimais e tipos de transferência. Modela taxas SOL, WSOL, Token-2022, mints, queimas e alterações de proprietário de conta para que os saldos possam ser reconciliados com precisão. Restringe o histórico de transferências pelo endereço do mint, intervalo de tempo do bloco ou intervalo de quantia bruta. Filtra transferências por remetente ou destinatário com `with` e `direction`. ## Quando usar isso Use `getTransfersByAddress` quando precisar de: * Histórico de transferências de carteira para pagamentos ou monitoramento de transferências * Análise de atividade de portfólio e movimento de token * Reconciliação de saldo confiável para livros e contabilidade * Relatórios de transferência específicos de contraparte (quem enviou ou recebeu o quê) * Manipulação normalizada de taxas SOL/WSOL, Token-2022, mint e queima sem escrever um analisador Use [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) em vez disso quando precisar de dados completos de transação, histórico apenas de assinaturas ou atividades não relacionadas a transferências. Um padrão comum é percorrer transferências aqui e, em seguida, buscar as transações completas subjacentes com chamadas em lote [`getTransaction`](/docs/pt-BR/api-reference/rpc/http/gettransaction) (veja [Buscar transações completas para linhas de transferência](#fetch-full-transactions-for-transfer-rows)). ## Precisão e reconciliação `getTransfersByAddress` é projetado para aplicativos que precisam de histórico de transferências confiável para livros, rastreamento de pagamentos, atividade de portfólio e reconciliação de saldos. Em vez de retornar cargas de transação brutas e deixar todos os casos de borda para o seu analisador, a API retorna objetos de transferência normalizados. A resposta modela explicitamente os casos de transferência que tornam o histórico do Solana difícil de reconciliar: * Transferências padrão de token SPL e SOL nativo. * Transferências Token-2022 com taxas retidas, representadas como linhas `transfer` comuns com campos de taxas separados. * Mints e queimas, representados como transferências com um remetente ou destinatário `null`. * Comportamento de empacotamento e desempacotamento de SOL, com um modo padrão projetado para evitar linhas de ciclo de vida ruidosas. * Alterações de proprietário de conta de token via SetAuthority. * Retiradas de taxas retidas Token-2022. * Fluxos de contas intermediárias, retornados como os registros de transferência subjacentes em vez de serem colapsados em um movimento líquido estimado. Para eventos de transferência visíveis suportados, isso permite reconciliação do movimento de saldo sem reimplementação da lógica de análise de token do Solana. Exclusões conhecidas, como movimentos ocultos de SOL inferidos apenas a partir de mudanças de saldo, são mencionadas em [Limitações](#limitations). ## Início Rápido ```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); ``` ## Parâmetros de solicitação Passe o endereço do proprietário da carteira, não uma conta de token associada (ATA). A API encontra atividades de transferência para contas de token de propriedade dessa carteira. Endereço de carteira do proprietário codificado em Base58 para consultar transferências. Passe o endereço do proprietário da carteira, não uma conta de token associada (ATA). Objeto de configuração opcional para filtragem, paginação, compromisso, ordenação e comportamento SOL/WSOL. Filtra por endereço de contraparte. Retorna apenas transferências para ou deste endereço. Filtra por direção de transferência em relação a `address`. * `in`: transferências recebidas por `address` * `out`: transferências enviadas por `address` * `any`: transferências de entrada e saída Filtra por endereço de mint de token. Use `So11111111111111111111111111111111111111111` para SOL nativo e `So11111111111111111111111111111111111111112` para WSOL. Controla como SOL nativo e WSOL são representados. * `merged`: WSOL é tratado como SOL nativo. Linhas de ciclo de vida de empacotar e desempacotar são excluídas, e valores de mint WSOL são reescritos para o mint nativo de SOL. * `separate`: WSOL é preservado como um mint distinto, e linhas de ciclo de vida de empacotar e desempacotar são incluídas. Filtros adicionais para quantia, tempo de bloco e slot. Número máximo de transferências a serem retornadas. Intervalo: 1 a 100. Cursor da resposta anterior para paginação. Nível de compromisso dos dados. * `finalized` * `confirmed` O slot mínimo em que a solicitação pode ser avaliada Ordenação de resultados. * `desc`: mais recente primeiro * `asc`: mais antigo primeiro ## Resposta ```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" } } ``` ### Detalhes dos campos da resposta * `fromUserAccount` e `toUserAccount` estão sempre presentes. Quando um lado não existe, o valor é `null`. * `fromTokenAccount` e `toTokenAccount` são incluídos apenas quando pontos terminais de conta de token são significativos para a linha. Eles são completamente omitidos para transferências de SOL nativo. * Transferências de mint são unilaterais: `fromUserAccount` é `null`, e só podem ser retornadas como transferências de entrada para o destinatário. * Transferências de queima são unilaterais: `toUserAccount` é `null`, e só podem ser retornadas como transferências de saída para o proprietário queimador. ## Filtros Use filtros de comparação para consultas de intervalo numérico. Todos os campos de comparação são opcionais e podem ser combinados. ```json theme={"system"} { "gt": 1000000, "gte": 1000000, "lt": 1000000000, "lte": 1000000000 } ``` | Filtro | Tipo | Descrição | | ----------- | ------------------ | ------------------------------------------------- | | `amount` | `ComparisonFilter` | Quantia de transferência bruta, não a quantia UI. | | `blockTime` | `ComparisonFilter` | Carimbo de tempo do bloco em segundos Unix. | | `slot` | `ComparisonFilter` | Número do slot. | ## Tipos de transferência O campo `type` identifica o comportamento de transferência representado por cada linha. | Tipo | Descrição | `fromUserAccount` | `toUserAccount` | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------- | | `transfer` | Transferência padrão de token ou SOL entre duas carteiras. | Remetente | Destinatário | | `mint` | Novos tokens criados em uma carteira. | `null` | Destinatário | | `burn` | Tokens destruídos permanentemente. | Remetente | `null` | | `wrap` | SOL empacotado em WSOL. Excluído por padrão em `solMode: "merged"`. | `null` | Proprietário | | `unwrap` | WSOL desembrulhado de volta para SOL nativo, ou aluguel recuperado do fechamento de uma conta de token. Excluído por padrão em `solMode: "merged"`. | Proprietário | `null` ou destino lamport | | `changeOwner` | Propriedade de conta de token alterada com SetAuthority. | Antigo proprietário | Novo proprietário | | `withdrawWithheldFee` | Taxas retidas Token-2022 coletadas de um mint ou contas. | `null` | Destinatário da taxa | ### Tipos de transferência e instruções | Tipo de transferência | Instruções cobertas | Visibilidade padrão | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Sempre | | `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Sempre | | `transfer` | `Token-2022::TransferCheckedWithFee`, com campos `feeAmount` e `feeUiAmount` | Sempre | | `mint` | `Token::MintTo`, `Token::MintToChecked` | Sempre | | `burn` | `Token::Burn`, `Token::BurnChecked` | Sempre | | `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` quando usado para manuseio de ciclo de vida WSOL | `solMode: "separate"` apenas | | `unwrap` | `Token::CloseAccount` em WSOL com saldo maior que zero | `solMode: "separate"` apenas | | `unwrap` | `Token::CloseAccount` recuperação de aluguel para contas de token não-WSOL, ou contas WSOL com saldo zero de token | `solMode: "separate"` apenas | | `changeOwner` | `Token::SetAuthority(AccountOwner)` | Sempre | | `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Sempre | ## Comportamento SOL e wSOL SOL existe no Solana em duas formas que geralmente aparecem juntas em atividades reais dos usuários: * **SOL Nativo** é o ativo nativo da blockchain. Ele vive diretamente em uma carteira ou conta como lamports. Um SOL é 1.000.000.000 lamports. * **SOL Empacotado (WSOL, frequentemente escrito wSOL)** é uma representação de token SPL do SOL. Ele usa o mint WSOL `So11111111111111111111111111111111111111112` e vive em uma conta de token, como o USDC ou qualquer outro token SPL. Usuários e aplicativos empacotam SOL quando precisam que o SOL se comporte como um token SPL, geralmente para DeFi, trocas, contabilidade baseada em conta de token ou interfaces de programa que aceitam apenas tokens SPL. O empacotamento geralmente financia uma conta de token com SOL nativo e a sincroniza com WSOL. O desembrulho fecha a conta de token WSOL e retorna o SOL a um destino de lamports. Esse ciclo de vida pode criar um histórico confuso se você está tentando responder a uma pergunta simples como "quanto SOL foi movido entre esta carteira e outra pessoa?" Um empacotamento ou desembrulho frequentemente move SOL entre contas controladas pelo mesmo proprietário. Se essas linhas de ciclo de vida forem mostradas como transferências comuns por padrão, aplicativos podem contar duas vezes a atividade ou mostrar contabilidade interna como pagamentos externos. Por padrão, `getTransfersByAddress` usa `solMode: "merged"`. Neste modo: * SOL nativo e WSOL são tratados como um ativo SOL ao consultar por `So11111111111111111111111111111111111111111`. * Linhas de transferência de WSOL são normalizadas para o mint nativo de SOL para que o histórico denominado em SOL seja mais fácil de reconciliar. * Linhas de ciclo de vida de empacotar e desempacotar são excluídas porque geralmente representam movimento entre contas controladas pelo mesmo proprietário, não um pagamento a outro usuário. * Transferências de SOL e WSOL entre diferentes proprietários ainda são representadas como transferências. * Aluguel recuperado de `CloseAccount` é representado como uma linha `unwrap` de SOL nativo quando linhas de ciclo de vida de fechamento de conta são retornadas. Use `solMode: "separate"` quando você precisar do WSOL como um mint de token SPL distinto ou quiser inspecionar registros de ciclo de vida de empacotar e desempacotar. Neste modo, WSOL mantém o mint `So11111111111111111111111111111111111111112`, e registros de empacotar/desempacotar são retornados com `type: "wrap"` ou `type: "unwrap"`. Para fechamentos de contas WSOL em `solMode: "separate"`, registros `unwrap` para o mint WSOL representam o saldo restante do token WSOL retornado como SOL. O aluguel reembolsado da conta de token fechada é retornado como uma linha separada `unwrap` de SOL nativo. ## Taxas de transferência Token-2022 Instruções `TransferCheckedWithFee` Token-2022 são representadas como um registro de transferência com `type: "transfer"`. O valor de destino é retornado em `amount`; detalhes de taxa retida são retornados em `feeAmount` e `feeUiAmount`. Para transferências com taxas, a origem é debitada `amount + feeAmount`, enquanto o destino é creditado `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 } ``` ## Exemplos ### Filtrar por USDC ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } ] } ``` ### Transferências de entrada de um remetente ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "direction": "in" } ] } ``` ### Intervalo de quantia e tempo ```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 } } } ] } ``` ### Solicitação paginada ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "limit": 50, "paginationToken": "315069220:308:2:1:splTransfer" } ] } ``` ### Buscar transações completas para linhas de transferência `getTransfersByAddress` retorna linhas de transferência analisadas, não cargas de transação completas. Se você precisar da transação completa para cada transferência, percorra as transferências primeiro, elimine duplicatas por `signature` e, em seguida, busque as transações completas com chamadas em lote [`getTransaction`](/docs/pt-BR/api-reference/rpc/http/gettransaction). `getTransfersByAddress` não é agrupável em várias endereços de proprietário. Consulte um endereço de proprietário por vez e, em seguida, agrupe as solicitações `getTransaction` resultantes por assinatura. Uma única transação pode emitir várias linhas de transferência, então sempre elimine assinaturas duplicadas antes de buscar transações. ```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: 0 } ] })); 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`); ``` ## Limitações * Transações falhas não estão incluídas na V1. * Movimentos ocultos de SOL inferidos apenas a partir de alterações de saldo não são suportados na V1. * `harvestWithheldTokensToMint` não é suportado na V1 porque não indica a quantia coletada. * Fluxos de contas intermediárias não são reduzidos. Se uma transação movimenta fundos através de contas intermediárias, os registros de transferência subjacentes são retornados. * Não agrupável em vários endereços de proprietário. Consulte um proprietário por vez. ## Próximos passos Histórico completo de transações com filtragem, ordenação e suporte a conta de token. Esquema completo de solicitação e resposta para getTransfersByAddress. Preencha e sincronize dados de transferência em seu próprio índice. Compare todos os métodos de dados históricos do Solana.