> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrer des transactions améliorées aux événements analysés
> Passez de l'API des transactions améliorées aux événements analysés — correspondance des points de terminaison et des paramètres, correspondance des champs de réponse, code avant/après, et invite d'agent IA.
## Pourquoi migrer ?
L'[API des transactions améliorées](/docs/fr/enhanced-transactions/overview) 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](/docs/fr/parsed-events), qui décode les instructions via le catalogue IDL qui alimente également [Flux analysés](/docs/fr/parsed-streams).
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 :
| | Transactions améliorées | Événements analysés |
| ------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------- |
| Modèle de décodage | Types d'événements fixes, parseurs organisés | Catalogue IDL, plus de 3 600 programmes |
| Détails de l'instruction | Résumé de l'événement uniquement | Chaque instruction, arguments et comptes décodés, CPIs inclus |
| Programmes sans parseur | Sortie générique `UNKNOWN` | Données brutes et comptes toujours retournés par instruction |
| Interface de requête | REST | REST et GraphQL |
| Pagination | Curseurs de signature, erreurs de recherche en temps réel à gérer | `paginationToken` (curseurs de signature toujours disponibles) |
| Erreurs de programme décodées | Non | Oui (`decodedError`) |
| Charge utile brute de la transaction | Non | Optionnel (`includeRawTransaction`) |
| Statut | Hérité, mode maintenance | Bêta ouverte, développement actif |
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êtes `POST` à `https://mainnet.helius-rpc.com`, authentifiées avec le même paramètre de requête `api-key` que vous utilisez déjà :
| Transactions améliorées | Événements analysés |
| ------------------------------------------ | -------------------------------------------- |
| `POST /v0/transactions` | `POST /v1/parsed-events/transactions` |
| `GET /v0/addresses/{address}/transactions` | `POST /v1/parsed-events/transaction-history` |
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 :
```javascript Before (Enhanced Transactions) theme={"system"}
const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;
const response = await fetch(url);
const transactions = await response.json(); // flat array of enriched transactions
for (const tx of transactions) {
console.log(tx.signature, tx.type, tx.description);
}
```
```javascript After (Parsed Events) theme={"system"}
const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
limit: 100,
sortOrder: "desc",
}),
});
const page = await response.json(); // { data: [...], paginationToken }
for (const item of page.data) {
if (item.parserStatus !== "OK") continue;
console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
}
```
## Cartographie des paramètres
### Analyser les transactions
`POST /v0/transactions` → `POST /v1/parsed-events/transactions`
| Ancien | Nouveau |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `transactions` (corps) | `transactions` — inchangé |
| `commitment` | `commitment` — `confirmed` (par défaut) ou `finalized`; `processed` n'est pas pris en charge |
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 :
| Ancien paramètre de requête | Nouveau champ de corps |
| --------------------------- | ---------------------- |
| `{address}` (chemin) | `address` |
| `limit` | `limit` |
| `before-signature` | `beforeSignature` |
| `after-signature` | `afterSignature` |
| `sort-order` | `sortOrder` |
| `commitment` | `commitment` |
| `gt-time` | `time.gt` |
| `gte-time` | `time.gte` |
| `lt-time` | `time.lt` |
| `lte-time` | `time.lte` |
| `gt-slot` | `slot.gt` |
| `gte-slot` | `slot.gte` |
| `lt-slot` | `slot.lt` |
| `lte-slot` | `slot.lte` |
Trois valeurs par défaut changent en cours de route :
* `limit` par défaut à 100 au lieu de 10.
* `commitment` par défaut à `confirmed` au lieu de `finalized`; `processed` n'est pas pris en charge.
* `sortOrder` garde les mêmes valeurs `asc`/`desc` avec `desc` comme valeur par défaut.
Pour la pagination, préférez `paginationToken` de la réponse précédente à `beforeSignature` — voir [Simplifier la pagination](#étapes-de-migration) 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](/docs/fr/parsed-streams) 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 :
| Ancien champ | Nouveau champ |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | `parsed.summary.description` — `summary` est `null` lorsqu'aucun résumé au niveau des transactions ne s'applique |
| `type` (`TRANSFER`, `SWAP`, ...) | `parsed.summary.type` (`transfer`, `swap`, ...) — un ensemble plus petit ; détail par instruction déplacé vers `parsed.instructions[]` |
| `source` (`SYSTEM_PROGRAM`, `JUPITER`, ...) | `parsed.summary.parsedData.protocol`, ou par instruction comme `instructions[].programName` |
| `events` (`events.swap`, `events.nft`, ...) | `parsed.summary.parsedData` — charge utile structurée par type de résumé |
| `fee` / `feePayer` | `parsed.fee` / `parsed.feePayer` — inchangé |
| `signature` | `signature` (niveau de l'enveloppe) |
| `slot` | `parsed.slot` |
| `timestamp` | `parsed.blockTime` |
| `transactionError` | `parsed.error`, plus `parsed.decodedError` avec le nom d'erreur propre du programme lorsque les métadonnées sont disponibles |
| `nativeTransfers` | `parsed.nativeTransfers` — même forme (`fromUserAccount`, `toUserAccount`, `amount` en lamports) |
| `tokenTransfers` | `parsed.tokenTransfers` — mêmes champs de compte, mais `tokenAmount` (décimal pré-échelonné) devient `rawTokenAmount` (entier brut) plus `decimals` |
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](/docs/fr/parsed-events/parsed-response) pour chaque champ.
## Étapes de migration
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](#cartographie-des-paramètres).
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`.
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](/docs/fr/parsed-streams), qui filtre côté serveur au niveau de l'instruction.
Remplacez la boucle de curseur `before-signature` par `paginationToken`:
```javascript theme={"system"}
let paginationToken = null;
const results = [];
do {
const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
address: "YOUR_ADDRESS_HERE",
limit: 100,
...(paginationToken && { paginationToken }),
}),
});
const page = await response.json();
results.push(...page.data);
paginationToken = page.paginationToken;
} while (paginationToken);
```
La boucle se termine quand `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.
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 à `confirmed` alors que l'ancien point de terminaison était par défaut à `finalized`. Passez `commitment: "finalized"` explicitement si votre pipeline dépend de la finalité. `processed` n'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 une `parserError`. Gérez-la par élément au lieu de par requête.
* **Couverture du résumé.** `summary` est `null` pour les transactions sans action reconnue au niveau de la transaction. L'ancienne API retournait `type: "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.
```markdown theme={"system"}
Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.
## Background
Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md
## Step 1: Find the old call sites
Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses//transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
handlers for the "Failed to find events within the search period" error
## Step 2: Rewrite each call site
Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
("confirmed" default or "finalized") and includeRawTransaction.
Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
limit -> limit (default is now 100, not 10);
before-signature -> beforeSignature (prefer paginationToken, see below);
after-signature -> afterSignature; sort-order -> sortOrder;
commitment -> commitment (default is now "confirmed", not "finalized";
"processed" unsupported);
gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no server-side equivalent: filter returned items client-side
on parsed.summary?.type (lowercase: "swap", "transfer", ...) or on
parsed.instructions[] (programId / instructionName).
Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
parsed.summary?.description; type -> parsed.summary?.type;
source -> parsed.summary?.parsedData?.protocol or
parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
rawTokenAmount (raw integer string/number) plus decimals — divide by
10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
paginationToken is present, passing it back in the next request body.
Delete continuation-signature error handling for the old runtime type
search — it no longer exists.
## Step 3: Constraints and cleanup
- Keep the same Helius API key and host; only paths, methods, bodies, and
response handling change.
- Never hardcode an API key; keep reading it from the existing config or
environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
migration covers only the /v0/transactions and /v0/addresses REST calls.
## Step 4: Verify
- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
(e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
history for an address from both APIs — the old
GET /v0/addresses/{address}/transactions and the new
POST /v1/parsed-events/transaction-history — and prints whether the
signature sets, fees, and native transfer amounts match, listing any
differences. Read the API key from an environment variable and the address
from a CLI argument.
- Tell the user how to run it, for example:
HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs
- Summarize every call site changed and flag any you were unsure about.
```
L'invite est autonome — l'agent n'a pas besoin d'accéder à cette page. Pour les documents prêt-à-agent, la recherche MCP et les compétences, voir [Helius pour agents IA](/docs/fr/agents/overview).
## Prochaines étapes
Analysez votre première transaction, récupérez l'historique des adresses et parcourez les résultats.
Référence de champs pour les transactions analysées, transferts et instructions.
Le même décodage en temps réel via WebSocket, filtré côté serveur.
Historique des transactions brutes avec support de compte de jetons et filtres côté serveur.