Zum Hauptinhalt springen

Übersicht

getTransfersByAddress ist eine exklusive RPC-Methode von Helius. Sie gibt geparste, menschenlesbare Token- und native SOL-Transferobjekte für eine Wallet-Adresse zurück. Sie ist nicht Teil des standardmäßigen Solana RPC. Die Methode konzentriert sich auf Transferaktivitäten. Daher gibt sie kompakte Transferdatensätze statt vollständiger Transaktions-payloads zurück. Jeder Datensatz ist mit geparsten Eigentümer- und Token-Konten, Mints, Rohbeträgen, Dezimalstellen, UI-Beträgen, Anweisungspositionen und Bestätigungsstatus normalisiert. So kannst du Kontostandsbewegungen abstimmen, ohne das Parsen von Solana-Token selbst neu zu implementieren. Diese Methode erfordert mindestens einen Developer-Tarif und kostet 10 Credits pro request.

Parsed transfer objects

Gibt menschenlesbare Transferdatensätze mit geparsten Konten, Beträgen, Dezimalstellen und Transfertypen zurück.

Reconciliation ready

Modelliert SOL, WSOL, Token-2022-Gebühren, Mints, Burns und Änderungen des Kontoeigentümers, damit du Kontostände präzise abstimmen kannst.

Mint, time, and amount filters

Grenze den Transferverlauf nach Mint-Adresse, Blockzeitraum oder Rohbetragsbereich ein.

Counterparty filters

Filtere Transfers mit with und direction nach Absender oder Empfänger.

Wann du diese Methode verwenden solltest

Verwende getTransfersByAddress für folgende Zwecke:
  • Wallet-Transferverlauf für Zahlungen oder Transferüberwachung
  • Portfolioaktivitäten und Analysen von Token-Bewegungen
  • Zuverlässige Kontostandsabstimmung für Hauptbücher und Buchhaltung
  • Transferspezifische Berichte nach Gegenpartei (wer was gesendet oder empfangen hat)
  • Normalisierte Verarbeitung von SOL/WSOL, Token-2022-Gebühren, Mints und Burns, ohne einen Parser zu schreiben
Verwende stattdessen getTransactionsForAddress, wenn du vollständige Transaktionsdaten, einen Verlauf nur mit Signaturen oder Aktivitäten ohne Transfers benötigst. Ein übliches Muster: Rufe die Transfers hier seitenweise ab und lade anschließend die zugrunde liegenden vollständigen Transaktionen mit gebündelten Aufrufen von getTransaction ab (siehe Vollständige Transaktionen für Transferzeilen abrufen).

Genauigkeit und Abstimmung

getTransfersByAddress wurde für Anwendungen entwickelt, die einen zuverlässigen Transferverlauf für Hauptbücher, Zahlungsverfolgung, Portfolioaktivitäten und Kontostandsabstimmung benötigen. Statt rohe Transaktions-payloads zurückzugeben und jeden Sonderfall deinem Parser zu überlassen, gibt die API normalisierte Transferobjekte zurück. Die response bildet ausdrücklich die Transferfälle ab, die eine Abstimmung des Solana-Verlaufs häufig erschweren:
  • Standardmäßige SPL-Token- und native SOL-Transfers.
  • Token-2022-Transfers mit einbehaltenen Gebühren, dargestellt als reguläre transfer-Zeilen mit separaten Gebührenfeldern.
  • Mints und Burns, dargestellt als Transfers mit einem null-Absender oder -Empfänger.
  • Verhalten beim Wrapping und Unwrapping von SOL, mit einem Standardmodus, der störende Lebenszykluszeilen vermeidet.
  • Änderungen des Eigentümers eines Token-Kontos über SetAuthority.
  • Auszahlungen einbehaltener Token-2022-Gebühren.
  • Abläufe über Zwischenkonten, die als zugrunde liegende Transferdatensätze zurückgegeben werden, statt sie zu einer geschätzten Nettobewegung zusammenzufassen.
Für unterstützte sichtbare Transferereignisse kannst du damit Kontostandsbewegungen abstimmen, ohne die Parsing-Logik für Solana-Token neu zu implementieren. Bekannte Ausschlüsse, etwa verborgene SOL-Bewegungen, die nur aus Kontostandsänderungen abgeleitet werden, findest du unter Einschränkungen.

Schnellstart

Request-Parameter

Übergib die Adresse des Wallet-Eigentümers, nicht die eines zugehörigen Token-Kontos (ATA). Die API findet Transferaktivitäten für Token-Konten, die diesem Wallet gehören.
string
erforderlich
Base58-codierte Adresse des Eigentümer-Wallets, dessen Transfers abgefragt werden sollen. Übergib die Adresse des Wallet-Eigentümers, nicht die eines zugehörigen Token-Kontos (ATA).
object
Optionales Konfigurationsobjekt für Filterung, Paginierung, commitment, Sortierung und das Verhalten von SOL/WSOL.
string
Filtert nach der Adresse der Gegenpartei. Gibt nur Transfers an diese oder von dieser Adresse zurück.
string
Standard:"any"
Filtert nach der Transferrichtung relativ zu address.
  • in: von address empfangene Transfers
  • out: von address gesendete Transfers
  • any: eingehende und ausgehende Transfers
string
Filtert nach der Token-Mint-Adresse. Verwende So11111111111111111111111111111111111111111 für natives SOL und So11111111111111111111111111111111111111112 für WSOL.
string
Standard:"merged"
Steuert, wie natives SOL und WSOL dargestellt werden.
  • merged: WSOL wird wie natives SOL behandelt. Lebenszykluszeilen für Wrapping und Unwrapping werden ausgeschlossen. WSOL-Mint-Werte werden in den Mint-Wert von nativem SOL umgeschrieben.
  • separate: WSOL bleibt als separater Mint erhalten. Lebenszykluszeilen für Wrapping und Unwrapping werden eingeschlossen.
object
Zusätzliche Filter für Betrag, Blockzeit und slot.
number
Standard:"100"
Maximale Anzahl der zurückzugebenden Transfers. Bereich: 1 bis 100.
string
Cursor aus der vorherigen response für die Paginierung.
string
Standard:"finalized"
commitment-Stufe der Daten.
  • finalized
  • confirmed
number
Der minimale slot, für den der request ausgewertet werden kann
string
Standard:"desc"
Sortierung der Ergebnisse.
  • desc: neueste zuerst
  • asc: älteste zuerst

Response

Details zu den response-Feldern

  • fromUserAccount und toUserAccount sind immer vorhanden. Wenn eine Seite nicht existiert, lautet der Wert null.
  • fromTokenAccount und toTokenAccount sind nur enthalten, wenn Endpunkte von Token-Konten für die Zeile relevant sind. Bei nativen SOL-Transfers fehlen sie vollständig.
  • Mint-Transfers sind einseitig: fromUserAccount ist null. Sie können nur als eingehende Transfers für den Empfänger zurückgegeben werden.
  • Burn-Transfers sind einseitig: toUserAccount ist null. Sie können nur als ausgehende Transfers für den verbrennenden Eigentümer zurückgegeben werden.

Filter

Verwende Vergleichsfilter für numerische Bereichsabfragen. Alle Vergleichsfelder sind optional und können kombiniert werden.

Transfertypen

Das Feld type gibt das in jeder Zeile dargestellte Transferverhalten an.

Transfertypen und Anweisungen

Verhalten von SOL und wSOL

SOL existiert auf Solana in zwei Formen, die bei echten Benutzeraktivitäten häufig gemeinsam auftreten:
  • Natives SOL ist der native Vermögenswert der Blockchain. Es liegt direkt als Lamports in einem Wallet oder Konto. Ein SOL entspricht 1.000.000.000 Lamports.
  • Wrapped SOL (WSOL, oft als wSOL geschrieben) ist eine SPL-Token-Darstellung von SOL. Es verwendet den WSOL-Mint So11111111111111111111111111111111111111112 und liegt wie USDC oder jedes andere SPL-Token in einem Token-Konto.
Benutzer und Anwendungen wrappen SOL, wenn es sich wie ein SPL-Token verhalten soll. Das ist in der Regel für DeFi, Swaps, die auf Token-Konten basierende Buchhaltung oder Programmschnittstellen nötig, die nur SPL-Token akzeptieren. Beim Wrapping wird ein Token-Konto üblicherweise mit nativem SOL finanziert und mit WSOL synchronisiert. Beim Unwrapping wird das WSOL-Token-Konto geschlossen und das SOL an ein Lamport-Ziel zurückgegeben. Dieser Lebenszyklus kann den Verlauf unübersichtlich machen, wenn du nur eine einfache Frage beantworten möchtest: „Wie viel SOL wurde zwischen diesem Wallet und einer anderen Person übertragen?“ Beim Wrapping oder Unwrapping wird SOL oft zwischen Konten verschoben, die demselben Eigentümer gehören. Wenn diese Lebenszykluszeilen standardmäßig als reguläre Transfers erscheinen, können Anwendungen Aktivitäten doppelt zählen oder interne Buchungen als externe Zahlungen anzeigen. Standardmäßig verwendet getTransfersByAddress den Modus solMode: "merged". In diesem Modus gilt:
  • Natives SOL und WSOL werden bei einer Abfrage nach So11111111111111111111111111111111111111111 als ein SOL-Vermögenswert behandelt.
  • WSOL-Transferzeilen werden auf den Mint von nativem SOL normalisiert. So lässt sich ein in SOL angegebener Verlauf leichter abstimmen.
  • Lebenszykluszeilen für Wrapping und Unwrapping werden ausgeschlossen, weil sie in der Regel Bewegungen zwischen Konten desselben Eigentümers darstellen und keine Zahlung an einen anderen Benutzer.
  • SOL- und WSOL-Transfers zwischen verschiedenen Eigentümern werden weiterhin als Transfers dargestellt.
  • Von CloseAccount zurückerhaltene Miete wird als native SOL-Zeile vom Typ unwrap dargestellt, wenn Lebenszykluszeilen für das Schließen von Konten zurückgegeben werden.
Verwende solMode: "separate", wenn du WSOL als separaten SPL-Token-Mint benötigst oder Lebenszyklusdatensätze für Wrapping und Unwrapping untersuchen möchtest. In diesem Modus behält WSOL den Mint So11111111111111111111111111111111111111112. Wrapping- und Unwrapping-Datensätze werden mit type: "wrap" oder type: "unwrap" zurückgegeben. Beim Schließen von WSOL-Konten im Modus solMode: "separate" stellen unwrap-Datensätze für den WSOL-Mint den verbleibenden WSOL-Token-Kontostand dar, der als SOL zurückgegeben wird. Die vom geschlossenen Token-Konto zurückerstattete Miete wird als separate native SOL-Zeile vom Typ unwrap zurückgegeben.

Token-2022-Transfergebühren

Token-2022-Anweisungen vom Typ TransferCheckedWithFee werden als ein Transferdatensatz mit type: "transfer" dargestellt. Der Zielbetrag wird in amount zurückgegeben. Details zur einbehaltenen Gebühr werden in feeAmount und feeUiAmount zurückgegeben. Bei Transfers mit Gebühren wird die Quelle mit amount + feeAmount belastet, während dem Ziel amount gutgeschrieben wird.

Beispiele

Nach USDC filtern

Eingehende Transfers von einem Absender

Betrags- und Zeitraum

Paginierter request

Vollständige Transaktionen für Transferzeilen abrufen

getTransfersByAddress gibt geparste Transferzeilen zurück, keine vollständigen Transaktions-payloads. Wenn du für jeden Transfer die vollständige Transaktion benötigst, rufe zuerst alle Transfers seitenweise ab, entferne Duplikate anhand von signature und rufe dann die vollständigen Transaktionen mit gebündelten Aufrufen von getTransaction ab. getTransfersByAddress kann nicht für mehrere Eigentümeradressen gebündelt werden. Frage jeweils eine Eigentümeradresse ab und bündele anschließend die resultierenden getTransaction-requests nach Signatur. Eine einzelne Transaktion kann mehrere Transferzeilen erzeugen. Entferne daher vor dem Abrufen der Transaktionen immer doppelte Signaturen.

Einschränkungen

  • Fehlgeschlagene Transaktionen sind in V1 nicht enthalten.
  • Verborgene SOL-Bewegungen, die nur aus Kontostandsänderungen abgeleitet werden, werden in V1 nicht unterstützt.
  • harvestWithheldTokensToMint wird in V1 nicht unterstützt, da die Anweisung den eingezogenen Betrag nicht angibt.
  • Abläufe über Zwischenkonten werden nicht reduziert. Wenn eine Transaktion Guthaben über Zwischenkonten verschiebt, werden die zugrunde liegenden Transferdatensätze zurückgegeben.
  • Kann nicht für mehrere Eigentümeradressen gebündelt werden. Frage jeweils nur einen Eigentümer ab.

Nächste Schritte

getTransactionsForAddress

Vollständiger Transaktionsverlauf mit Filterung, Sortierung und Unterstützung für Token-Konten.

API reference

Vollständiges request- und response-Schema für getTransfersByAddress.

Indexing guide

Führe einen backfill aus und synchronisiere Transferdaten mit deinem eigenen Index.

Historical data overview

Vergleiche alle Methoden für historische Solana-Daten.