Skip to main content

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

Utilisez getTransfersByAddress 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
Utilisez 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 transfer ordinaires 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é.
Pour les événements de transfert visibles pris en charge, cela vous permet de réconcilier le mouvement des soldes sans réimplémenter la logique d’analyse de token Solana. Les exclusions connues, telles que les mouvements de SOL cachés déduits uniquement des changements de solde, sont signalées dans Limitations.

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 par address
  • out : transferts envoyés par address
  • any : 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.
  • finalized
  • confirmed
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 premier
  • asc : le plus ancien en premier

Réponse

Détails du champ de réponse

  • fromUserAccount et toUserAccount sont toujours présents. Lorsqu’un côté n’existe pas, la valeur est null.
  • fromTokenAccount et toTokenAccount sont 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 : fromUserAccount est null, et ils ne peuvent être retournés que comme transferts entrants pour le destinataire.
  • Les transferts de burning sont unilatéraux : toUserAccount est null, 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 champ type 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 So11111111111111111111111111111111111111112 et réside dans un compte de token, comme USDC ou tout autre token SPL.
Les utilisateurs et applications wrappent le SOL lorsqu’ils ont besoin que le SOL se comporte comme un token SPL, généralement pour DeFi, les swaps, la comptabilité basée sur des comptes de tokens, ou les interfaces de programme acceptant uniquement les tokens SPL. Le wrapping alimente généralement un compte de token avec du SOL natif et le synchronise en WSOL. L’unwrapping ferme le compte de token WSOL et retourne le SOL à une destination en lamports. Ce cycle de vie peut créer un historique déroutant si vous essayez de répondre à une question simple comme “combien de SOL a été transféré entre ce portefeuille et quelqu’un d’autre ?” Un wrap ou unwrap déplace souvent le SOL entre des comptes contrôlés par le même propriétaire. Si ces lignes de cycle de vie sont montrées comme des transferts ordinaires par défaut, les applications peuvent comptabiliser deux fois l’activité ou montrer une comptabilité interne comme des paiements externes. Par défaut, 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 CloseAccount est représenté comme une ligne unwrap de SOL natif lorsque les lignes de cycle de vie de clôture de compte sont retournées.
Utilisez 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 instructions TransferCheckedWithFee 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.
  • harvestWithheldTokensToMint n’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.