Présentation de l’API Parsed Events Scan

Analyser selon les instructions d’un programme Solana

La requête suivante analyse l’historique du programme Pump.fun et renvoie les transactions analysées contenant une instruction buy ou sell :

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["buy", "sell"]
        }
      ]
    },
    "limit": 100
  }'

Avec cette requête, l’outil de démonstration Parsed Events Scan a examiné 261 enregistrements et trouvé 100 correspondances. Il a renvoyé les 100 événements les plus récents en 182 ms, pour un coût total de seulement 11 crédits :

Les noms d’instructions peuvent utiliser l’orthographe de n’importe quelle version de l’IDL du programme ou la forme snake_case. L’API Parsed Events Scan vérifie aussi bien les instructions de premier niveau que les instructions internes appelées par des appels interprogrammes (CPI).

Les programmes comportent souvent plusieurs versions d’une action donnée. Par exemple, l’IDL de Pump.fun contient les instructions buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell et sell_v2. L’API Scan vous permet de répertorier tous les noms d’instructions à rechercher.

Les achats et les ventes représentent une grande partie de l’activité de Pump.fun, les correspondances sont donc trouvées assez rapidement. Scan permet de réaliser davantage d’économies lorsque l’activité recherchée est rare. Les frais de créateur, par exemple, ne représentent qu’une petite fraction des transactions du programme :

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["collect_creator_fee"]
        }
      ]
    },
    "limit": 10
  }'

En utilisant l’outil de démonstration Parsed Events Scan pour trouver les dix réclamations les plus récentes, nous constatons que l’outil a examiné 3 402 transactions en 182 ms et que cette requête a coûté 14 crédits :

L’appel getTransactionsForAddress comparable coûterait 350 crédits, soit 25 fois plus que l’endpoint d’analyse.

Que faire si un programme Solana ne possède pas d’IDL avec des instructions nommées ?

Pour utiliser l’API Parsed Events Scan avec des programmes Solana dépourvus d’IDL, vous pouvez rechercher les correspondances à l’aide des préfixes des données d’instruction.

Chaque discriminateur peut contenir entre un et huit octets encodés en hexadécimal. Vous pouvez combiner des noms et des discriminateurs pour un même programme ; une instruction correspond si son nom ou son discriminateur correspond. Par exemple :

{
  "match": {
    "programs": [
      {
        "programId": "<PROGRAM_ADDRESS>",
        "discriminators": ["0x66063d1201daebea"]
      }
    ]
  }
}

Analyser plusieurs programmes Solana à la fois

Vous pouvez répertorier jusqu’à 20 programmes dans une seule requête à l’API Parsed Events Scan. Une transaction correspond lorsqu’elle appelle l’un de ces programmes.

Par exemple, cette requête analyse en une seule fois les transactions d’un portefeuille à la recherche de correspondances sur Jupiter, DFlow et Pump.fun :

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"]
      },
      { "programId": "DF1ow4tspfHX9JwWJsAb9epbkA8hmpSEAtxXy1V27QBH" },
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Analyser selon le mint du token

L’API Scan peut également trouver les transactions qui ont impliqué un mint de token donné en vérifiant les soldes de tokens avant et après chaque transaction pour l’adresse du mint. Par défaut, elle ne comptabilise que les soldes appartenant à l’adresse analysée.

Lorsque vous analysez un portefeuille pour un token, définissez tokenAccounts sur balanceChanged. Dans différents cas, un transfert de token entrant implique uniquement le compte de token du portefeuille, et non le portefeuille lui-même ; ces transactions sont donc exclues par défaut de l’historique du portefeuille.

Par exemple, cette requête trouve l’activité wSOL d’Ansem pendant le mois de septembre 2026 :

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "<ANSEM_WALLET_ADDRESS>",
    "match": {
      "mints": [{ "mint": "So11111111111111111111111111111111111111112" }]
    },
    "tokenAccounts": "balanceChanged",
    "time": {
      "gte": 1788220800,
      "lte": 1790812800
    }
  }'

L’API Scan a trouvé 53 transactions correspondantes après avoir examiné un total de 7 555 transactions :

Combiner programmes et mints

Les développeurs peuvent définir à la fois programs et mints pour affiner les résultats. Lorsqu’ils sont combinés, une transaction doit satisfaire les deux critères pour correspondre. Toutefois, pour limiter l’activité d’un programme à un seul token, l’adresse analysée compte davantage que les filtres.

Par exemple, analysez l’adresse de mint d’un token plutôt que le programme Pump.fun pour trouver toutes les transactions Pump.fun portant sur un token donné. Chaque achat ou vente répertorie le mint comme compte et correspond donc par défaut :

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

L’historique du mint contient uniquement l’activité de ce token, tandis que l’historique du programme contient les transactions de tous les tokens. Analyser ce dernier gaspillerait donc votre budget sur des transactions sans rapport.

Choisir une portée de correspondance

Par défaut, les instructions d’un programme et les soldes de tokens d’un mint ne sont comptabilisés que lorsqu’ils impliquent l’adresse analysée. Un solde de token implique l’adresse lorsque celle-ci possède le compte de token ou lorsqu’elle est le mint du solde. Une instruction implique l’adresse dans les cas suivants :

• L’un de ses comptes est l’adresse
• L’un de ses comptes est un compte de token appartenant à l’adresse
• L’adresse est un mint et l’un des comptes de l’instruction est un compte de token pour ce mint
• L’adresse est le programme appelé

Définissez "scope": "transaction" sur un programme ou un mint pour le comptabiliser partout dans la transaction. Utilisez cette option lorsque l’adresse se contente de payer les frais, exécute une transaction multisig ou ne fait pas partie des comptes de l’instruction recherchée.

Par exemple, cette requête trouve les transactions d’un token qui ont également déplacé des USDC. Avec la portée par défaut, les soldes USDC devraient appartenir à l’adresse du mint et aucune correspondance ne serait trouvée :

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "mints": [
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "scope": "transaction" }
    ]
  },
  "returnShape": "signatures"
}

Les programmes acceptent la même portée de correspondance. Cette requête trouve les swaps Jupiter dont un relayeur a payé les frais.

Le relayeur signe uniquement les transactions en tant que payeur des frais. Il ne fait donc pas partie des comptes de l’instruction de routage, et aucune de ces transactions ne correspondrait avec la portée par défaut :

{
  "address": "<RELAYER_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"],
        "scope": "transaction"
      }
    ]
  },
  "returnShape": "signatures"
}

La même logique s’applique à un membre d’un multisig qui exécute une proposition. L’instruction exécutée par le multisig agit sur les comptes du coffre et non sur ceux du membre. Pour les trouver en analysant l’historique du membre, il faut donc utiliser la portée transaction.

Suivre le SOL natif

Le SOL natif n’a pas de soldes de tokens. L’analyse recherche donc les correspondances à partir des lamports.

Transmettez le mint du SOL natif (So11111111111111111111111111111111111111111), qui est différent du SOL wrappé. Une transaction correspond lorsque le solde SOL de l’adresse analysée a changé, sans compter les frais qu’elle a payés :

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "mints": [{ "mint": "So11111111111111111111111111111111111111111" }]
  },
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Cela détecte le SOL versé par un programme sans instruction de transfert, comme lors d’une vente Pump.fun. Cela détecte aussi les mouvements accessoires, tels que les pourboires Jito et les loyers payés pour des comptes ou remboursés à partir de ceux-ci.

Obtenir les transactions analysées, les signatures ou leur nombre

returnShape définit le contenu de la réponse pour les correspondances :

Par exemple, cette requête compte les achats Pump.fun d’un trader en septembre 2026 sans renvoyer les transactions :

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2"]
      }
    ]
  },
  "returnShape": "count",
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Pour le comptage, signatures et count ignorent limit et couvrent chaque correspondance dans la plage analysée par une requête. Pour compter sur un long historique, continuez à parcourir les pages et additionnez scan.matchedTransactions.

Les trois formats ont le même coût.

Contrôler la quantité d’historique analysée par chaque requête

Une analyse peut examiner jusqu’à 10 000 transactions par requête et renvoyer jusqu’à 100 correspondances.

Le champ budget.maxScannedTransactions contrôle cette limite, fixée par défaut à 10 000. Le champ limit contrôle le nombre de correspondances renvoyées par l’endpoint ; il accepte des valeurs comprises entre 1 et 100, avec 100 comme valeur par défaut.

Ces deux paramètres sont distincts, car les correspondances peuvent être rares. Une requête peut donc analyser des milliers de transactions et ne renvoyer que quelques correspondances.

Par défaut, les requêtes d’analyse incluent uniquement les transactions réussies.

Définissez status sur failed ou any pour inclure les transactions échouées. Celles-ci sont accompagnées des erreurs de programme décodées lorsque l’IDL du programme les définit.

Résumés d’analyse

Chaque réponse inclut un résumé scan :

{
  "data": [],
  "paginationToken": "460903064:422",
  "scan": {
    "stoppedOn": "budget",
    "scannedTransactions": 2000,
    "matchedTransactions": 0,
    "scannedThrough": {
      "slot": 460903064,
      "blockTime": 1792856105
    },
    "creditsCharged": 12
  }
}

Le résumé indique :

• Pourquoi l’analyse s’est arrêtée
• Combien de transactions elle a examinées
• Combien de transactions correspondaient
• Le dernier slot et la dernière heure de bloc examinés
• Combien de crédits la requête a utilisés

Fonctionnement de la pagination des analyses

Lorsqu’une analyse s’arrête, le champ scan.stoppedOn en indique la raison :

• windowEnd : l’analyse a atteint la fin de l’historique ou de la fenêtre
• limit : la réponse contient le nombre de correspondances demandé
• budget : la requête a atteint son budget d’analyse des transactions
• deadline : la requête a atteint sa limite de temps

Lorsque la réponse inclut un paginationToken, envoyez ce token dans la requête suivante et poursuivez même si le tableau data actuel est vide. Un résultat vide peut signifier que la requête a épuisé son budget avant de trouver une correspondance, et non qu’il n’en existe aucune plus loin.

Par exemple, cette boucle collecte les transactions Pump.fun de la dernière heure.

Notez que la limite time et le plafond de la requête l’empêchent de parcourir tout l’historique :

const PUMP_PROGRAM = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const ONE_HOUR_AGO = Math.floor(Date.now() / 1000) - 3600;
const MAX_REQUESTS = 50;

let paginationToken;
let requests = 0;

async function scanHistory() {
  const response = await fetch(
    `https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=${process.env.HELIUS_API_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        address: PUMP_PROGRAM,
        match: {
          programs: [{ programId: PUMP_PROGRAM, instructions: ["buy", "sell"] }],
        },
        time: { gte: ONE_HOUR_AGO },
        limit: 100,
        ...(paginationToken && { paginationToken }),
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

do {
  const page = await scanHistory();
  requests++;

  for (const transaction of page.data) {
    console.log(transaction.signature);
  }

  paginationToken = page.paginationToken;
} while (paginationToken && requests < MAX_REQUESTS);

Des résultats analysés sans pipeline côté client

Chaque élément de data utilise le même format TransactionResult que l’endpoint Parsed Events Parse Transactions. Les résultats peuvent inclure des instructions décodées, des transferts, des modifications de comptes, des événements, des résumés de transactions et des données analysées propres au protocole, lorsqu’elles sont disponibles. Si votre application a également besoin de la charge utile de la transaction Solana d’origine, définissez rawTransaction sur "json", "jsonParsed" ou "base64".

La principale différence réside dans l’endroit où s’exécute le workflow de traitement de l’historique.

Votre application définit la recherche une seule fois, tandis que l’API Parsed Events Scan gère la pagination de l’historique, la recherche des correspondances et l’analyse avant de renvoyer les transactions pertinentes.

Utiliser les derniers SDK Helius

Nos SDK TypeScript et Rust prennent tous deux en charge notre API Parsed Events et le nouvel endpoint d’analyse.

Le SDK TypeScript expose les analyses sous la forme helius.parsedEvents.scan(). Le type de réponse suit la valeur returnShape transmise :

const { scan } = await helius.parsedEvents.scan({
  address: "<WALLET_ADDRESS>",
  match: {
    programs: [{ programId: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", instructions: ["buy", "sell"] }],
  },
  returnShape: "count",
});

console.log(scan.matchedTransactions, scan.stoppedOn);

Le SDK Rust propose également scan, scan_signatures et scan_count sur helius.parsed_events(), qui acceptent tous le même ScanRequest.

Tarification de l’API Parsed Events Scan

Chaque requête à l’API Parsed Events Scan coûte 10 crédits, plus 1 crédit pour chaque page d’historique analysée. Une page d’historique contient jusqu’à 1 000 transactions.

Par exemple, une requête utilisant le budget par défaut de 10 000 transactions coûte au maximum 20 crédits. La réponse indique le coût exact dans scan.creditsCharged.

À titre de comparaison, l’analyse coûte dix fois moins cher que la pagination du même historique avec getTransactionsForAddress, qui coûte 100 crédits par page de 1 000 transactions maximum.

Contrôler l’utilisation

Pour contrôler l’utilisation, choisissez l’adresse la plus ciblée possible et ajoutez des limites de slot ou de temps lorsque vous le pouvez. Moins de transactions sans rapport signifie davantage de correspondances utiles dans chaque requête.

Remplacer l’API Enhanced Transactions par l’API Parsed Events

L’API Enhanced Transactions reste disponible en mode maintenance, mais ne reçoit plus de nouveaux types de parseurs ni de nouvelles fonctionnalités. Parsed Events lui succède et utilise le catalogue d’IDL de Helius pour décoder les instructions de milliers de programmes Solana. Si ce n’est pas encore fait, migrez vers l’API Parsed Events.

Quelle est la différence ?

L’API Enhanced Transactions classe l’activité dans un ensemble fixe de types de transactions, tels que les swaps, les transferts et les ventes de NFT. L’API Parsed Events Scan permet quant à elle d’effectuer des recherches plus précises par instruction de programme, discriminateur brut, mint de token ou combinaison de ces critères. Helius applique ces filtres lors de l’analyse de l’historique de l’adresse et traite uniquement les transactions correspondantes.

L’API Parsed Events offre aux développeurs une couverture plus étendue des programmes et davantage de contrôle sur les requêtes historiques, sans avoir à maintenir un outil d’analyse côté client.

Démarrer

Utilisez l’API Parsed Events Scan lorsque vous connaissez l’activité onchain dont vous avez besoin, mais que vous ne souhaitez pas créer et maintenir un outil d’analyse de l’historique côté client. Consultez la référence de l’API Scan Transaction History pour découvrir le schéma complet des requêtes, les champs de réponse, les limites, les erreurs et d’autres exemples.

Pour continuer à explorer les possibilités de l’API Scan, découvrez le nouvel outil Scan dans votre tableau de bord Helius. Essayez d’analyser des adresses par programme, par mint et à l’aide de filtres.