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
UsagetTransfersByAddress 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
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
transfernormales 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.
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 poraddressout: transferencias enviadas poraddressany: 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.
finalizedconfirmed
number
Slot mínimo en el que se puede evaluar la solicitud
string
predeterminado:"desc"
Orden de los resultados.
desc: los más recientes primeroasc: los más antiguos primero
Respuesta
Detalles de los campos de respuesta
fromUserAccountetoUserAccountsiempre están presentes. Cuando uno de los lados no existe, el valor esnull.fromTokenAccountetoTokenAccountsolo 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:
fromUserAccountesnully solo pueden devolverse como transferencias entrantes para el destinatario. - Las transferencias de quema son unilaterales:
toUserAccountesnully 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 campotype 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
So11111111111111111111111111111111111111112y se almacena en una cuenta de tokens, como USDC o cualquier otro token SPL.
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
CloseAccountse representa como una filaunwrapde SOL nativo cuando se devuelven filas del ciclo de vida de cierre de cuentas.
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 instruccionesTransferCheckedWithFee 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.
harvestWithheldTokensToMintno 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.