Skip to main content

Descripción general

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 o superior y cuesta 10 créditos por solicitud.

Parsed transfer objects

Devuelve registros de transferencia legibles con cuentas, cantidades, decimales y tipos de transferencia analizados.

Reconciliation ready

Modela SOL, WSOL, comisiones de Token-2022, acuñaciones, quemas y cambios de propietario de cuentas para conciliar los saldos con precisión.

Mint, time, and amount filters

Limita el historial de transferencias por dirección de mint, intervalo de tiempo de bloque o intervalo de cantidades sin procesar.

Counterparty filters

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 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 (consulta 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.

Inicio rápido

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.
string
requerido
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).
object
Objeto de configuración opcional para filtrado, paginación, compromiso, ordenamiento y comportamiento de SOL/WSOL.
string
Filtra por dirección de contraparte. Devuelve solo las transferencias hacia o desde esta dirección.
string
predeterminado:"any"
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
string
Filtra por dirección de mint del token. Usa So11111111111111111111111111111111111111111 para SOL nativo e So11111111111111111111111111111111111111112 para WSOL.
string
predeterminado:"merged"
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.
object
Filtros adicionales para cantidad, tiempo de bloque y slot.
number
predeterminado:"100"
Número máximo de transferencias que se devolverán. Intervalo: de 1 a 100.
string
Cursor de la respuesta anterior para la paginación.
string
predeterminado:"finalized"
Nivel de compromiso de los datos.
  • finalized
  • confirmed
number
Slot mínimo en el que se puede evaluar la solicitud
string
predeterminado:"desc"
Orden de los resultados.
  • desc: los más recientes primero
  • asc: los más antiguos primero

Respuesta

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.

Tipos de transferencia

El campo type identifica el comportamiento de transferencia representado por cada fila.

Tipos de transferencia e instrucciones

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.

Ejemplos

Filtrar por USDC

Transferencias entrantes de un remitente

Intervalo de cantidad y tiempo

Solicitud paginada

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. 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.

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

getTransactionsForAddress

Historial completo de transacciones con filtrado, ordenamiento y compatibilidad con cuentas de tokens.

API reference

Esquema completo de solicitud y respuesta para getTransfersByAddress.

Indexing guide

Recupera y sincroniza datos de transferencias en tu propio índice.

Historical data overview

Compara todos los métodos de datos históricos de Solana.