> ## 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. # Descripción general y tutorial de getTransfersByAddress > Consulta objetos analizados y legibles de transferencias de tokens y SOL nativo para una dirección de Solana, con filtros por mint, tiempo, cantidad y contraparte. ## Descripción general [`getTransfersByAddress`](/docs/es/api-reference/rpc/http/gettransfersbyaddress) es un método RPC exclusivo de Helius que devuelve objetos analizados y legibles de transferencias de tokens y SOL nativo para la dirección de una billetera. No forma parte del RPC estándar de Solana. Se centra en la actividad de transferencias, por lo que devuelve registros de transferencia concisos en lugar de cargas útiles de transacciones completas. Cada registro se normaliza con cuentas de propietarios y tokens analizadas, mints, cantidades sin procesar, decimales, cantidades de interfaz de usuario, posiciones de instrucciones y estado de confirmación. Así puedes conciliar los movimientos de saldo sin volver a implementar el análisis de tokens de Solana. Este método requiere un [plan Developer](/docs/es/billing/plans) o superior y cuesta 10 créditos por solicitud. Devuelve registros de transferencia legibles con cuentas, cantidades, decimales y tipos de transferencia analizados. Modela SOL, WSOL, comisiones de Token-2022, acuñaciones, quemas y cambios de propietario de cuentas para conciliar los saldos con precisión. Limita el historial de transferencias por dirección de mint, intervalo de tiempo de bloque o intervalo de cantidades sin procesar. Filtra las transferencias por remitente o destinatario con `with` y `direction`. ## Cuándo usarlo Usa `getTransfersByAddress` cuando necesites: * Historial de transferencias de una billetera para pagos o monitoreo de transferencias * Actividad de portafolios y análisis del movimiento de tokens * Conciliación de saldos confiable para libros contables y contabilidad * Informes de transferencias específicos de una contraparte (quién envió o recibió qué) * Manejo normalizado de SOL/WSOL, comisiones de Token-2022, acuñaciones y quemas sin escribir un analizador Usa [`getTransactionsForAddress`](/docs/es/rpc/gettransactionsforaddress) en su lugar cuando necesites datos completos de transacciones, un historial solo de firmas o actividad que no sea de transferencias. Un patrón común consiste en paginar las transferencias aquí y luego obtener las transacciones completas subyacentes mediante llamadas por lotes a [`getTransaction`](/docs/es/api-reference/rpc/http/gettransaction) (consulta [Obtener transacciones completas para filas de transferencias](#obtener-transacciones-completas-para-filas-de-transferencias)). ## Precisión y conciliación `getTransfersByAddress` está diseñado para aplicaciones que necesitan un historial de transferencias confiable para libros contables, seguimiento de pagos, actividad de portafolios y conciliación de saldos. En lugar de devolver cargas útiles de transacciones sin procesar y dejar cada caso extremo a tu analizador, la API devuelve objetos de transferencia normalizados. La respuesta modela explícitamente los casos de transferencia que suelen dificultar la conciliación del historial de Solana: * Transferencias estándar de tokens SPL y SOL nativo. * Transferencias de Token-2022 con comisiones retenidas, representadas como filas `transfer` normales con campos de comisión separados. * Acuñaciones y quemas, representadas como transferencias con un remitente o destinatario `null`. * Comportamiento de envoltura y desenvoltura de SOL, con un modo predeterminado diseñado para evitar filas de ciclo de vida innecesarias. * Cambios de propietario de cuentas de tokens mediante SetAuthority. * Retiros de comisiones retenidas de Token-2022. * Flujos de cuentas intermediarias, devueltos como los registros de transferencia subyacentes en lugar de condensarse en un movimiento neto estimado. Para los eventos de transferencia visibles compatibles, esto te permite conciliar los movimientos de saldo sin volver a implementar la lógica de análisis de tokens de Solana. Las exclusiones conocidas, como los movimientos de SOL ocultos que solo se infieren a partir de cambios de saldo, se describen en [Limitaciones](#limitaciones). ## Inicio 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 la solicitud Proporciona la dirección del propietario de la billetera, no una cuenta de tokens asociada (ATA). La API busca la actividad de transferencias de las cuentas de tokens que pertenecen a esa billetera. Dirección de la billetera propietaria codificada en Base58 cuyas transferencias quieres consultar. Proporciona la dirección del propietario de la billetera, no una cuenta de tokens asociada (ATA). Objeto de configuración opcional para filtrado, paginación, compromiso, ordenamiento y comportamiento de SOL/WSOL. Filtra por dirección de contraparte. Devuelve solo las transferencias hacia o desde esta dirección. Filtra por dirección de transferencia con respecto a `address`. * `in`: transferencias recibidas por `address` * `out`: transferencias enviadas por `address` * `any`: transferencias entrantes y salientes Filtra por dirección de mint del token. Usa `So11111111111111111111111111111111111111111` para SOL nativo e `So11111111111111111111111111111111111111112` para WSOL. Controla cómo se representan SOL nativo y WSOL. * `merged`: WSOL se trata como SOL nativo. Se excluyen las filas del ciclo de vida de envoltura y desenvoltura, y los valores de mint de WSOL se sustituyen por el mint de SOL nativo. * `separate`: WSOL se conserva como un mint distinto y se incluyen las filas del ciclo de vida de envoltura y desenvoltura. Filtros adicionales para cantidad, tiempo de bloque y slot. Número máximo de transferencias que se devolverán. Intervalo: de 1 a 100. Cursor de la respuesta anterior para la paginación. Nivel de compromiso de los datos. * `finalized` * `confirmed` Slot mínimo en el que se puede evaluar la solicitud Orden de los resultados. * `desc`: los más recientes primero * `asc`: los más antiguos primero ## Respuesta ```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" } } ``` ### Detalles de los campos de respuesta * `fromUserAccount` e `toUserAccount` siempre están presentes. Cuando uno de los lados no existe, el valor es `null`. * `fromTokenAccount` e `toTokenAccount` solo se incluyen cuando los extremos de las cuentas de tokens son relevantes para la fila. Se omiten por completo en las transferencias de SOL nativo. * Las transferencias de acuñación son unilaterales: `fromUserAccount` es `null` y solo pueden devolverse como transferencias entrantes para el destinatario. * Las transferencias de quema son unilaterales: `toUserAccount` es `null` y solo pueden devolverse como transferencias salientes para el propietario que realiza la quema. ## Filtros Usa filtros de comparación para consultas de intervalos numéricos. Todos los campos de comparación son opcionales y pueden combinarse. ```json theme={"system"} { "gt": 1000000, "gte": 1000000, "lt": 1000000000, "lte": 1000000000 } ``` | Filtro | Tipo | Descripción | | ----------- | ------------------ | ------------------------------------------------------------------------------ | | `amount` | `ComparisonFilter` | Cantidad de transferencia sin procesar, no la cantidad de interfaz de usuario. | | `blockTime` | `ComparisonFilter` | Marca de tiempo del bloque en segundos Unix. | | `slot` | `ComparisonFilter` | Número de slot. | ## Tipos de transferencia El campo `type` identifica el comportamiento de transferencia representado por cada fila. | Tipo | Descripción | `fromUserAccount` | `toUserAccount` | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------- | | `transfer` | Transferencia estándar de tokens o SOL entre dos billeteras. | Remitente | Destinatario | | `mint` | Nuevos tokens acuñados para una billetera. | `null` | Destinatario | | `burn` | Tokens destruidos permanentemente. | Remitente | `null` | | `wrap` | SOL envuelto en WSOL. Se excluye de forma predeterminada en `solMode: "merged"`. | `null` | Propietario | | `unwrap` | WSOL desenvuelto de nuevo en SOL nativo, o renta recuperada al cerrar una cuenta de tokens. Se excluye de forma predeterminada en `solMode: "merged"`. | Propietario | `null` o destino de lamports | | `changeOwner` | La propiedad de la cuenta de tokens cambió mediante SetAuthority. | Propietario anterior | Propietario nuevo | | `withdrawWithheldFee` | Comisiones retenidas de Token-2022 cobradas de un mint o de cuentas. | `null` | Destinatario de la comisión | ### Tipos de transferencia e instrucciones | Tipo de transferencia | Instrucciones incluidas | Visibilidad predeterminada | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Siempre | | `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Siempre | | `transfer` | `Token-2022::TransferCheckedWithFee`, con los campos `feeAmount` e `feeUiAmount` | Siempre | | `mint` | `Token::MintTo`, `Token::MintToChecked` | Siempre | | `burn` | `Token::Burn`, `Token::BurnChecked` | Siempre | | `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` cuando se usan para gestionar el ciclo de vida de WSOL | Solo `solMode: "separate"` | | `unwrap` | `Token::CloseAccount` en WSOL con un saldo superior a cero | Solo `solMode: "separate"` | | `unwrap` | Recuperación de renta mediante `Token::CloseAccount` para cuentas de tokens que no son WSOL, o cuentas WSOL con saldo de tokens igual a cero | Solo `solMode: "separate"` | | `changeOwner` | `Token::SetAuthority(AccountOwner)` | Siempre | | `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Siempre | ## Comportamiento de SOL y wSOL SOL existe en Solana en dos formas que suelen aparecer juntas en la actividad real de los usuarios: * **SOL nativo** es el activo nativo de la cadena. Se almacena directamente en una billetera o cuenta como lamports. Un SOL equivale a 1,000,000,000 lamports. * **SOL envuelto (WSOL, a menudo escrito wSOL)** es una representación de SOL como token SPL. Usa el mint de WSOL `So11111111111111111111111111111111111111112` y se almacena en una cuenta de tokens, como USDC o cualquier otro token SPL. Los usuarios y las aplicaciones envuelven SOL cuando necesitan que se comporte como un token SPL, normalmente para DeFi, intercambios, contabilidad basada en cuentas de tokens o interfaces de programas que solo aceptan tokens SPL. Para envolver SOL, normalmente se financia una cuenta de tokens con SOL nativo y se sincroniza con WSOL. Al desenvolverlo, se cierra la cuenta de tokens WSOL y se devuelve el SOL a un destino de lamports. Ese ciclo de vida puede generar un historial confuso si intentas responder una pregunta sencilla como "¿cuánto SOL se transfirió entre esta billetera y otra persona?" Envolver o desenvolver SOL suele moverlo entre cuentas controladas por el mismo propietario. Si esas filas del ciclo de vida se muestran como transferencias normales de forma predeterminada, las aplicaciones pueden contar la actividad dos veces o mostrar operaciones contables internas como pagos externos. De forma predeterminada, `getTransfersByAddress` usa `solMode: "merged"`. En este modo: * SOL nativo y WSOL se tratan como un solo activo SOL al consultar por `So11111111111111111111111111111111111111111`. * Las filas de transferencias de WSOL se normalizan al mint de SOL nativo para facilitar la conciliación del historial denominado en SOL. * Se excluyen las filas del ciclo de vida de envoltura y desenvoltura porque suelen representar movimientos entre cuentas controladas por el mismo propietario, no un pago a otro usuario. * Las transferencias de SOL y WSOL entre distintos propietarios siguen representándose como transferencias. * La renta recuperada de `CloseAccount` se representa como una fila `unwrap` de SOL nativo cuando se devuelven filas del ciclo de vida de cierre de cuentas. Usa `solMode: "separate"` cuando necesites tratar WSOL como un mint de token SPL distinto o quieras inspeccionar los registros del ciclo de vida de envoltura y desenvoltura. En este modo, WSOL conserva el mint `So11111111111111111111111111111111111111112` y los registros de envoltura y desenvoltura se devuelven con `type: "wrap"` o `type: "unwrap"`. Para los cierres de cuentas WSOL en `solMode: "separate"`, los registros `unwrap` del mint de WSOL representan el saldo restante de tokens WSOL devuelto como SOL. La renta reembolsada de la cuenta de tokens cerrada se devuelve como una fila `unwrap` separada de SOL nativo. ## Comisiones de transferencia de Token-2022 Las instrucciones `TransferCheckedWithFee` de Token-2022 se representan como un solo registro de transferencia con `type: "transfer"`. La cantidad de destino se devuelve en `amount`; los detalles de la comisión retenida se devuelven en `feeAmount` e `feeUiAmount`. En las transferencias con comisiones, se debita `amount + feeAmount` del origen, mientras que se acredita `amount` al destino. ```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 } ``` ## Ejemplos ### Filtrar por USDC ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } ] } ``` ### Transferencias entrantes de un remitente ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "direction": "in" } ] } ``` ### Intervalo de cantidad y tiempo ```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 } } } ] } ``` ### Solicitud paginada ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "limit": 50, "paginationToken": "315069220:308:2:1:splTransfer" } ] } ``` ### Obtener transacciones completas para filas de transferencias `getTransfersByAddress` devuelve filas de transferencias analizadas, no cargas útiles de transacciones completas. Si necesitas la transacción completa de cada transferencia, primero pagina las transferencias, elimina duplicados según `signature` y luego obtén las transacciones completas mediante llamadas por lotes a [`getTransaction`](/docs/es/api-reference/rpc/http/gettransaction). `getTransfersByAddress` no admite procesamiento por lotes para varias direcciones de propietarios. Consulta una dirección de propietario a la vez y luego agrupa por lotes las solicitudes `getTransaction` resultantes según la firma. Una sola transacción puede generar varias filas de transferencias, así que siempre elimina las firmas duplicadas antes de obtener las transacciones. ```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`); ``` ## Limitaciones * Las transacciones fallidas no se incluyen en V1. * Los movimientos de SOL ocultos que solo se infieren a partir de cambios de saldo no son compatibles con V1. * `harvestWithheldTokensToMint` no es compatible con V1 porque no indica la cantidad cobrada. * Los flujos de cuentas intermediarias no se reducen. Si una transacción mueve fondos mediante cuentas intermediarias, se devuelven los registros de transferencia subyacentes. * No admite procesamiento por lotes para varias direcciones de propietarios. Consulta un propietario a la vez. ## Próximos pasos Historial completo de transacciones con filtrado, ordenamiento y compatibilidad con cuentas de tokens. Esquema completo de solicitud y respuesta para getTransfersByAddress. Recupera y sincroniza datos de transferencias en tu propio índice. Compara todos los métodos de datos históricos de Solana.