Warum migrieren?
Um den Transaktionsverlauf einer Adresse auf Solana abzurufen, sind normalerweise zwei Schritte nötig: Rufe zuerstgetSignaturesForAddress auf, um Signaturen aufzulisten. Rufe dann für jede Signatur einmal getTransaction auf, um die Details abzurufen. Für 1.000 Transaktionen sind das 1.001 HTTP requests.
getTransactionsForAddress ist eine exklusive RPC-Methode von Helius, die beide Schritte in einem Aufruf zusammenfasst. Sie gibt bis zu 1.000 vollständige Transaktionen pro request zurück und unterstützt Filter, bidirektionale Sortierung und token accounts. Diese Funktionen bieten die Standardmethoden nicht.
Das Ergebnis: etwa 10-mal weniger Credits, 1.000-mal weniger Roundtrips und kein clientseitiges Batching, keine Behandlung von rate limits und keine Wiederholungslogik für den Fan-out von
getTransaction.
Vorher und nachher
So sieht dieselbe Aufgabe mit beiden Mustern aus: die letzten 1.000 Transaktionen einer Adresse mit allen Details abrufen.getTransactionsForAddress gehört nicht zum standardmäßigen Solana RPC. Deshalb bietet @solana/web3.js keinen Connection-Helper dafür. Rufe die Methode wie oben gezeigt mit einem unverarbeiteten JSON-RPC request auf. Sie funktioniert über denselben Helius endpoint wie dein übriger RPC-Datenverkehr.
Parameterzuordnung
Jede Option des alten zweistufigen Ablaufs hat eine direkte Entsprechung. Die meisten Namen bleiben unverändert. Nur die Paginierung funktioniert anders.Aus getSignaturesForAddress
Aus getTransaction
Zwei Funktionen haben überhaupt keine Entsprechung im alten Ablauf:
filters— Grenze die Ergebnisse serverseitig nachblockTime,slot,status,tokenTransferodertokenAccountsein, statt alles abzurufen und in deinem Code zu filtern.sortOrder: "asc"— Gibt Ergebnisse chronologisch zurück, also die ältesten zuerst. Die Standardmethoden können das nur, wenn du den gesamten Verlauf abrufst und die Reihenfolge umkehrst.
Migrationsschritte
1
Confirm you're on a Helius endpoint
getTransactionsForAddress ist exklusiv für Helius verfügbar. Die Methode funktioniert unter https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY sowie im Devnet. Das ist derselbe endpoint, den deine bestehenden Aufrufe bereits verwenden, wenn du Helius-Kunde bist. Du musst weder den API key noch deinen Tarif ändern.2
Replace the two-step fetch with one call
Lösche den Aufruf von
getSignaturesForAddress und die getTransaction-Schleife. Sende einen einzigen getTransactionsForAddress request mit transactionDetails: "full". Übernimm dabei deine Werte für encoding, maxSupportedTransactionVersion und commitment wie in der Parameterzuordnung gezeigt.Wenn du nur Signaturen brauchst, etwa als Eingabe für eine bestehende Pipeline, verwende stattdessen transactionDetails: "signatures". Das kostet pauschal 10 Credits pro Aufruf.3
Update the response handling
Die Struktur der response ändert sich an drei Stellen:
- Die Ergebnisse stehen in
result.data, einem Array, und nicht direkt inresult. - Jeder Eintrag im vollständigen Modus ist
{ slot, transactionIndex, blockTime, transaction, meta }. Die Objektetransactionundmetahaben dieselbe Struktur wie die Rückgabe vongetTransaction. Du kannst deinen Parsing-Code daher unverändert übernehmen. - Einträge im Signaturmodus entsprechen der Ausgabe von
getSignaturesForAddress(signature,slot,err,memo,blockTime,confirmationStatus), ergänzt um das neue FeldtransactionIndex.
getTransaction für eine Signatur null zurückgeben. Bei getTransactionsForAddress ist jeder Eintrag in result.data eine vollständige Transaktion. Entferne die Behandlung von null-Werten für fehlende Details.4
Replace signature-based pagination
Ersetze die Cursor-Schleife mit Die Schleife endet, wenn
before durch paginationToken:paginationToken den Wert null hat. Du musst keine Signaturlisten mehr vergleichen oder die letzte Signatur selbst speichern.Wenn du until verwendet hast, um bei einer bekannten Signatur zu stoppen, ersetze es durch filters.signature: { gt: "KNOWN_SIGNATURE" }. Wenn du damit an einem bestimmten Zeitpunkt gestoppt hast, eignen sich filters.blockTime oder filters.slot meist besser.5
Optional: enable complete token history
Das alte Muster erfasst Aktivitäten von associated token accounts (ATA) überhaupt nicht, sofern du nicht zusätzlich
getTokenAccountsByOwner aufgerufen und die Signaturen für jedes token account abgerufen hast. Füge einen Filter hinzu, um diese Aktivitäten einzubeziehen:balanceChanged gibt Transaktionen zurück, die auf die Wallet verweisen oder den Kontostand eines zugehörigen token account ändern. Spam wird dabei herausgefiltert. Unter Associated token accounts findest du die Optionen none/balanceChanged/all und den Hinweis für Daten von vor 2022.6
Verify against the old output
Rufe den Verlauf für eine Beispieladresse auf beide Arten ab und vergleiche die Signaturmengen. Wenn
filters.tokenAccounts nicht gesetzt ist, also der Standardwert none gilt, gibt getTransactionsForAddress für denselben Bereich dieselben Transaktionen wie getSignaturesForAddress zurück. Führe danach das deployment durch und entferne den alten Codepfad.Zu prüfende Verhaltensunterschiede
Bei den meisten Migrationen kannst du die Methode direkt ersetzen. Prüfe vor dem Release dennoch diese Punkte:- Commitment.
processedwird nicht unterstützt. Verwendeconfirmedoderfinalized. Wenn dein alter Code den aktuellen Verlauf mitprocessedabgefragt hat, wechsle zuconfirmed. - Abrechnung. Responses mit vollständigen Transaktionen kosten 10 Credits pro 100 zurückgegebenen Transaktionen, mindestens jedoch 10 Credits. Responses mit ausschließlich Signaturen kosten pauschal 10 Credits. Das alte Muster kostete 1 Credit pro Aufruf. Es war pro request günstiger, aber pro abgerufener Transaktion deutlich teurer. Fehlgeschlagene responses sind kostenlos. Weitere Informationen findest du unter Abrechnung.
- Netzwerkunterstützung. Im Mainnet werden Daten unbegrenzt aufbewahrt. Das Devnet wird mit einer Aufbewahrungsdauer von 2 Wochen unterstützt. Das Testnet wird nicht unterstützt.
- Reservierte Adressen. Eine kleine Gruppe von Systemadressen wie Vote Program, System Program und sysvars wird an alternative Archivpfade weitergeleitet oder gibt keine Ergebnisse zurück. Wenn du diese Adressen indexierst, lies Einschränkungen und Sonderfälle.
- Mehrere Adressen. Wie beim alten Ablauf deckt ein request genau eine Adresse ab. Frage Adressen parallel ab und führe die Ergebnisse zusammen. Weitere Informationen findest du unter Mehrere Adressen.
Häufig gestellte Fragen
Ist getTransactionsForAddress eine standardmäßige Solana-RPC-Methode?
Nein. Die Methode ist exklusiv für Helius und über Helius RPC endpoints verfügbar. Der standardmäßige Solana RPC und andere Anbieter bieten nurgetSignaturesForAddress und getTransaction an. Deine anderen RPC-Aufrufe bleiben unverändert. Die Methode ist über denselben endpoint neben dem vollständigen standardmäßigen RPC-Funktionsumfang verfügbar.
Brauche ich getTransaction nach der Migration weiterhin?
Nur für einzelne Abfragen, bei denen du bereits eine Signatur, aber keinen Adresskontext hast. Das gilt beispielsweise, wenn du eine bestimmte Transaktion prüfst, die ein Benutzer eingefügt hat. Für jeden adressbasierten Verlauf wie Backfills, Indexierung oder Aktivitätsfeeds einer Wallet ersetztgetTransactionsForAddress beide Methoden.
Funktioniert die Methode mit @solana/web3.js?
Die Methode ist nicht in der KlasseConnection enthalten. Du kannst sie aber mit jedem HTTP-Client über deine Helius RPC URL aufrufen. Verwende fetch oder die entsprechende Funktion deiner Sprache mit einem standardmäßigen JSON-RPC-Body, wie in den Beispielen oben gezeigt. Für alles andere kannst du Connection weiterhin verwenden.
Gibt die Methode dieselben Transaktionen wie getSignaturesForAddress zurück?
Ja. Mit den Standardeinstellungen (filters.tokenAccounts: "none") gibt sie Transaktionen zurück, die auf die abgefragte Adresse verweisen. Das ist dieselbe Menge wie bei getSignaturesForAddress. Wenn du tokenAccounts auf balanceChanged oder all setzt, erhältst du mehr Ergebnisse. Dann werden Aktivitäten der associated token accounts der Wallet einbezogen, die die Standardmethode nicht erfassen kann.
Wie hoch sind die Kosten im Vergleich zum alten Muster?
Das Abrufen von 1.000 vollständigen Transaktionen kostet mitgetTransactionsForAddress 100 Credits. Mit getSignaturesForAddress + getTransaction sind es dagegen etwa 1.001 Credits und 1.001 requests. Responses mit ausschließlich Signaturen kosten pauschal 10 Credits pro Aufruf. Die vollständigen Preise findest du unter Helius Credits.
Lass einen AI-Agenten die Migration durchführen
Wenn du Claude Code, Cursor oder einen anderen Coding-Agenten verwendest, füge den folgenden Prompt in die Agentensitzung deines Repositorys ein. Der Agent findet das alte Muster in deiner Codebasis und schreibt es um.Nächste Schritte
getTransactionsForAddress guide
Vollständiges Tutorial zu Filtern, Sortierung, Paginierung und token accounts.
API reference
Vollständiges Schema für request und response.
Indexing guide
Verwende getTransactionsForAddress, um einen Solana-Index per Backfill zu füllen und zu synchronisieren.
Historical data overview
Vergleiche alle Methoden für historische Solana-Daten.