Pourquoi migrer ?
L’API des transactions améliorées est un produit hérité en mode maintenance : il fonctionne encore, mais ne reçoit pas de nouveaux types de parseurs ni de nouvelles fonctionnalités. Son successeur est Événements analysés, qui décode les instructions via le catalogue IDL qui alimente également Flux analysés. La différence réside dans la façon dont les transactions sont décodées. Les transactions améliorées classifient une transaction dans une liste fixe de types d’événements (TRANSFER, SWAP, NFT_SALE, …) et renvoient un résumé préconstruit pour les types qu’elles connaissent. Les événements analysés décodent chaque instruction contre l’IDL du programme — plus de 3 600 programmes — en arguments et comptes nommés, et construisent le résumé par-dessus :
Les événements analysés sont en bêta ouverte sur les plans payants. L’API peut encore changer avant la disponibilité générale ; les transactions améliorées continuent de fonctionner entre-temps, vous pouvez donc migrer à votre rythme.
Cartographie des points de terminaison
Les deux méthodes d’événements analysés sont des requêtesPOST à https://mainnet.helius-rpc.com, authentifiées avec le même paramètre de requête api-key que vous utilisez déjà :
Le point de terminaison historique déplace toutes les entrées des paramètres de chaîne de requête vers un corps JSON. Les corps de requête rejettent les champs inconnus, donc les fautes de frappe échouent bruyamment au lieu d’être silencieusement ignorées.
Avant et après
La même tâche — récupérer l’historique analysé d’un portefeuille — dans les deux APIs :Cartographie des paramètres
Analyser les transactions
POST /v0/transactions → POST /v1/parsed-events/transactions
Nouvelles options sans ancien équivalent :
includeRawTransaction renvoie la charge utile de la transaction Solana originale avec le résultat analysé.
Historique des transactions
GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Chaque paramètre de requête devient un champ de corps JSON :
Trois valeurs par défaut changent en cours de route :
limitpar défaut à 100 au lieu de 10.commitmentpar défaut àconfirmedau lieu definalized;processedn’est pas pris en charge.sortOrdergarde les mêmes valeursasc/descavecdesccomme valeur par défaut.
paginationToken de la réponse précédente à beforeSignature — voir Simplifier la pagination ci-dessous.
Le vieux paramètre type n’a pas d’équivalent dans Événements analysés — il n’y a pas de filtre de type de transaction côté serveur. Filtrez côté client sur parsed.summary.type (swap, transfer, add_liquidity, …), ou sur les instructions décodées elles-mêmes, ce qui est plus précis que les anciens types fixes. Pour les flux en temps réel spécifiques à un type, Flux analysés filtre côté serveur au niveau de l’instruction.
Cartographie des champs de réponse
Les transactions améliorées renvoient un tableau plat de transactions enrichies. Les événements analysés enveloppent chaque résultat dans une enveloppe —{ signature, parserStatus, parsed } — et les réponses historiques enveloppent le tableau dans un objet de page avec paginationToken. Les champs analysés se mappent comme suit :
Et le plus grand changement est un nouveau champ sans ancien équivalent :
parsed.instructions[] contient chaque instruction de haut niveau et interne dans l’ordre d’exécution, avec decoded.args et decoded.accounts nommés à partir de l’IDL du programme. Là où les transactions améliorées vous donnaient un résumé des événements par transaction, les événements analysés vous donnent le résumé et la liste complète des instructions décodées. Voir Réponse analysée pour chaque champ.
Étapes de migration
1
Échanger les points de terminaison
Orientez les appels d’analyse des transactions vers
POST /v1/parsed-events/transactions et les appels d’historique vers POST /v1/parsed-events/transaction-history. Même hôte, même paramètre de requête api-key. Les requêtes historiques passent de GET avec des paramètres de requête à POST avec un corps JSON — déplacez chaque paramètre selon le tableau ci-dessus.2
Mettre à jour le traitement des réponses
Détachez la nouvelle enveloppe : vérifiez
parserStatus === "OK", puis lisez les champs depuis parsed au lieu du niveau supérieur. Renommez timestamp en blockTime, lisez description et type depuis summary (protégeant pour null), et divisez rawTokenAmount par 10^decimals là où l’ancien code lisait tokenAmount.3
Remplacer le filtrage des types
Là où l’ancien code passait
type=..., filtrez les éléments retournés côté client sur parsed.summary.type ou sur parsed.instructions[] — par exemple, “instructions où programId est Jupiter et instructionName est route” remplace type=SWAP par quelque chose que vous pouvez réellement vérifier. Si le filtre de type existait pour alimenter un flux en temps réel, déplacez ce consommateur vers Flux analysés, qui filtre côté serveur au niveau de l’instruction.4
Simplifier la pagination
Remplacez la boucle de curseur La boucle se termine quand
before-signature par paginationToken:paginationToken est absent. Les anciennes erreurs de recherche en temps réel (“Échec de la recherche d’événements dans la période de recherche”) et leur gestion des signatures de continuation disparaissent complètement — supprimez ce code.5
Vérifier par rapport à l'ancienne sortie
Pour une adresse échantillon, récupérez la même page depuis les deux APIs et comparez les ensembles de signatures, les frais et les montants des transferts. Puis déployez et supprimez le chemin de code ancien. Les transactions améliorées continuent de fonctionner pendant que vous migrez — il n’y a pas de coupure forcée.
Différences de comportement à revoir
- Valeurs par défaut des engagements. L’historique est par défaut à
confirmedalors que l’ancien point de terminaison était par défaut àfinalized. Passezcommitment: "finalized"explicitement si votre pipeline dépend de la finalité.processedn’est pas pris en charge. - Erreurs par élément. Une signature qui ne peut pas être analysée n’échoue plus à la requête — elle revient comme un élément avec
parserStatus: "ERROR"et uneparserError. Gérez-la par élément au lieu de par requête. - Couverture du résumé.
summaryestnullpour les transactions sans action reconnue au niveau de la transaction. L’ancienne API retournaittype: "UNKNOWN"dans ce cas ; la nouvelle API vous donne toujours chaque instruction décodée avec laquelle travailler. - Accès. Les événements analysés sont en bêta ouverte sur les plans payants, et l’API peut encore changer avant la disponibilité générale.
Laisser un agent IA faire la migration
Si vous utilisez Claude Code, Cursor ou un autre agent de codage, collez l’invite ci-dessous dans la session de l’agent de votre dépôt. Il trouve les sites d’appel des transactions améliorées et les réécrit.Prochaines étapes
Démarrage rapide des événements analysés
Analysez votre première transaction, récupérez l’historique des adresses et parcourez les résultats.
Réponse analysée
Référence de champs pour les transactions analysées, transferts et instructions.
Flux analysés
Le même décodage en temps réel via WebSocket, filtré côté serveur.
getTransactionsForAddress
Historique des transactions brutes avec support de compte de jetons et filtres côté serveur.