Présentation
getTransfersByAddress est une méthode RPC exclusive à Helius qui renvoie des objets de transfert de token et de SOL natif analysés et lisibles pour une adresse de portefeuille. Ce n’est pas une partie du RPC standard de Solana.
Elle est axée sur l’activité de transfert, donc elle renvoie des enregistrements de transfert concis au lieu de charges utiles de transaction complètes. Chaque enregistrement est normalisé avec des comptes propriétaires et de token analysés, des mints, des montants bruts, des décimales, des montants UI, des positions d’instruction et un statut de confirmation, afin que vous puissiez réconcilier le mouvement de solde sans réimplémenter l’analyse des tokens Solana.
Cette méthode nécessite un plan Développeur ou supérieur et coûte 10 crédits par demande.
Objets de transfert analysés
Retournent des enregistrements de transfert lisibles humainement avec des comptes, montants, décimales, et types de transfert analysés.
Prêts pour la réconciliation
Modélisez les frais SOL, WSOL, Token-2022, les mints, burning, et changements de propriétaires de compte pour que les soldes puissent être réconciliés précisément.
Filtres par mint, temps et montant
Réduisez l’historique de transfert par adresse de mint, plage de temps de bloc ou plage de montants bruts.
Filtres par contrepartie
Filtrez les transferts par expéditeur ou destinataire avec
with et direction.Quand l’utiliser
UtilisezgetTransfersByAddress quand vous avez besoin de :
- Historique de transfert de portefeuille pour les paiements ou la surveillance des transferts
- Analyse de l’activité de portefeuille et du mouvement des tokens
- Réconciliation de solde fiable pour les registres comptables
- Rapports de transfert spécifiques par contrepartie (qui a envoyé ou reçu quoi)
- Gestion normalisée du SOL/WSOL, frais Token-2022, mint, et burning sans écrire d’analyseur
getTransactionsForAddress à la place quand vous avez besoin de données de transaction complètes, d’un historique des signatures uniquement, ou d’activités non liées aux transferts. Un modèle courant est de parcourir les transferts ici, puis de récupérer les transactions complètes sous-jacentes avec des appels groupés getTransaction (voir Récupérer les transactions complètes pour les lignes de transfert).
Précision et réconciliation
getTransfersByAddress est conçu pour les applications qui ont besoin d’un historique de transfert fiable pour les registres, le suivi des paiements, l’activité des portefeuilles et la réconciliation des soldes. Plutôt que de retourner des charges utiles de transaction brutes et de laisser chaque cas limite à votre analyseur, l’API retourne des objets de transfert normalisés.
La réponse modélise explicitement les cas de transfert qui rendent souvent l’historique de Solana difficile à réconcilier :
- Transferts de SOL natif et de token SPL standard.
- Transferts Token-2022 avec frais retenus, représentés comme des lignes
transferordinaires avec des champs de frais séparés. - Mints et burnings, représentés comme des transferts avec un expéditeur ou destinataire
null. - Comportement de wrapping et unwrapping du SOL, avec un mode par défaut conçu pour éviter les lignes de cycle de vie bruyantes.
- Changements de propriétaires de compte de token via SetAuthority.
- Retraits de frais retenus de Token-2022.
- Flux de comptes intermédiaires, retournés comme les enregistrements de transfert sous-jacents plutôt que d’être regroupés en un mouvement net deviné.
Démarrage rapide
Paramètres de requête
Passez l’adresse propriétaire du portefeuille, pas un compte de token associé (ATA). L’API trouve l’activité de transfert pour les comptes de token détenus par ce portefeuille.string
requis
Adresse de portefeuille propriétaire encodée en Base58 pour interroger les transferts. Passez l’adresse propriétaire du portefeuille, pas un compte de token associé (ATA).
object
Objet de configuration optionnel pour le filtrage, la pagination, l’engagement, le tri, et le comportement SOL/WSOL.
string
Filtrer par adresse de contrepartie. Ne renvoie que les transferts vers ou depuis cette adresse.
string
défaut:"any"
Filtrer par direction de transfert par rapport à
address.in: transferts reçus paraddressout: transferts envoyés paraddressany: transferts entrants et sortants
string
Filtrer par adresse de mint de token. Utilisez
So11111111111111111111111111111111111111111 pour SOL natif et So11111111111111111111111111111111111111112 pour WSOL.string
défaut:"merged"
Contrôle comment le SOL natif et le WSOL sont représentés.
merged: le WSOL est traité comme SOL natif. Les lignes de cycle de vie de wrapping et unwrapping sont exclues, et les valeurs de mint WSOL sont réécrites au mint de SOL natif.separate: le WSOL est préservé comme un mint distinct, et les lignes de cycle de vie de wrapping et unwrapping sont incluses.
object
Filtres supplémentaires pour le montant, le temps de bloc, et le slot.
number
défaut:"100"
Nombre maximal de transferts à retourner. Plage : 1 à 100.
string
Curseur de la réponse précédente pour la pagination.
string
défaut:"finalized"
Niveau d’engagement des données.
finalizedconfirmed
number
Le slot minimal auquel la demande peut être évaluée
string
défaut:"desc"
Ordre des résultats.
desc: le plus récent en premierasc: le plus ancien en premier
Réponse
Détails du champ de réponse
fromUserAccountettoUserAccountsont toujours présents. Lorsqu’un côté n’existe pas, la valeur estnull.fromTokenAccountettoTokenAccountsont inclus uniquement lorsque les points de terminaison des comptes de token sont significatifs pour la ligne. Ils sont complètement omis pour les transferts de SOL natif.- Les transferts de mint sont unilatéraux :
fromUserAccountestnull, et ils ne peuvent être retournés que comme transferts entrants pour le destinataire. - Les transferts de burning sont unilatéraux :
toUserAccountestnull, et ils ne peuvent être retournés que comme transferts sortants pour le propriétaire brûlant.
Filtres
Utilisez des filtres de comparaison pour les requêtes de plage numérique. Tous les champs de comparaison sont optionnels et peuvent être combinés.Types de transferts
Le champtype identifie le comportement de transfert représenté par chaque ligne.
Types de transferts et instructions
Comportement SOL et wSOL
Le SOL existe sur Solana sous deux formes qui apparaissent souvent ensemble dans l’activité réelle des utilisateurs :- SOL natif est l’actif natif de la chaîne. Il vit directement dans un portefeuille ou un compte sous forme de lamports. Un SOL équivaut à 1 000 000 000 de lamports.
- Wrapped SOL (WSOL, souvent écrit wSOL) est une représentation de token SPL du SOL. Il utilise le mint WSOL
So11111111111111111111111111111111111111112et réside dans un compte de token, comme USDC ou tout autre token SPL.
getTransfersByAddress utilise solMode: "merged". Dans ce mode :
- Le SOL natif et le WSOL sont traités comme un seul actif SOL lors de la requête par
So11111111111111111111111111111111111111111. - Les lignes de transfert WSOL sont normalisées au mint de SOL natif pour faciliter la réconciliation de l’historique en SOL.
- Les lignes de cycle de vie de wrapping et unwrapping sont exclues car elles représentent généralement un mouvement entre des comptes contrôlés par le même propriétaire, pas un paiement à un autre utilisateur.
- Les transferts de SOL et WSOL entre différents propriétaires sont toujours représentés comme des transferts.
- Le loyer récupéré par
CloseAccountest représenté comme une ligneunwrapde SOL natif lorsque les lignes de cycle de vie de clôture de compte sont retournées.
solMode: "separate" lorsque vous avez besoin que le WSOL soit un mint distinct de token SPL ou que vous souhaitez inspecter les enregistrements de cycle de vie de wrapping et unwrapping. Dans ce mode, le WSOL conserve le mint So11111111111111111111111111111111111111112, et les enregistrements de wrapping/unwrapping sont retournés avec type: "wrap" ou type: "unwrap".
Pour les fermetures de comptes WSOL dans solMode: "separate", les enregistrements unwrap pour le mint WSOL représentent le solde de token WSOL restant retourné comme SOL. Le loyer remboursé du compte de token fermé est retourné comme une ligne unwrap de SOL natif séparée.
Frais de transfert Token-2022
Les instructionsTransferCheckedWithFee de Token-2022 sont représentées comme un enregistrement de transfert avec type: "transfer". Le montant de destination est retourné dans amount ; les détails des frais retenus sont retournés dans feeAmount et feeUiAmount.
Pour les transferts avec frais, la source est débitée amount + feeAmount, tandis que la destination est créditée amount.
Exemples
Filtrer par USDC
Transferts entrants d’un expéditeur
Plage de montant et de temps
Requête paginée
Récupérer les transactions complètes pour les lignes de transfert
getTransfersByAddress retourne des lignes de transfert analysées, pas des charges utiles de transaction complètes. Si vous avez besoin de la transaction complète pour chaque transfert, parcourez d’abord les transferts, dédupliquez par signature, puis récupérez les transactions complètes avec des appels groupés getTransaction.
getTransfersByAddress n’est pas batchable pour plusieurs adresses propriétaires. Interrogez une adresse propriétaire à la fois, puis regroupez les demandes getTransaction résultantes par signature. Une seule transaction peut émettre plusieurs lignes de transfert, donc dédupliquez toujours les signatures avant de récupérer les transactions.
Limitations
- Les transactions échouées ne sont pas incluses dans la V1.
- Les mouvements de SOL cachés déduits uniquement des changements de solde ne sont pas pris en charge dans la V1.
harvestWithheldTokensToMintn’est pas pris en charge dans la V1 car il n’indique pas le montant collecté.- Les flux de comptes intermédiaires ne sont pas réduits. Si une transaction déplace des fonds via des comptes intermédiaires, les enregistrements de transfert sous-jacents sont retournés.
- Non batchable pour plusieurs adresses propriétaires. Interrogez un propriétaire à la fois.
Étapes suivantes
getTransactionsForAddress
Historique des transactions complètes avec filtrage, tri, et support des comptes de token.
Référence API
Schéma complet de la demande et de la réponse pour getTransfersByAddress.
Guide d'indexation
Remplissez et synchronisez les données de transfert dans votre propre index.
Aperçu des données historiques
Comparez toutes les méthodes de données historiques de Solana.