> ## 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.
# Comment utiliser preconfSubscribe
> Diffusez les transactions Solana avec la latence la plus basse possible grâce à la méthode WebSocket preconfSubscribe — abonnez-vous, filtrez, et décodez la charge utile.
**Utilisez [Sender Max](/docs/fr/sending-transactions/sender-max) (pourboire minimum : 0,001 SOL) pour
agir sur les préconfirmations.** Une préconfirmation est efficace uniquement si vous exécutez votre
transaction
en premier — Sender Max est le moyen le plus rapide pour y parvenir. Construisez avec Sender Max dès le
départ pour tirer pleinement parti des préconfirmations.
## Qu'est-ce que `preconfSubscribe` ?
`preconfSubscribe` est une méthode WebSocket Helius qui diffuse les [préconfirmations](/docs/fr/pre-confirmations/overview) — transactions livrées avant qu'elles ne soient collectées en entrées et fragmentées. C'est le signal de transaction à la latence la plus faible que Helius offre. Un abonnement fournit à la fois les préconfirmations Helius, émises au moment où le leader exécute la transaction et portant son statut d'exécution, et les [préconfirmations BAM](/docs/fr/pre-confirmations/overview#préconfirmations-bam) des validateurs exécutant le client Block Assembly Marketplace de Jito, émises lorsque le validateur s'engage à exécuter la transaction. L'accès nécessite un [plan Professionnel ou supérieur](/docs/fr/billing/plans) — voir [Tarification](#tarification).
Le flux n'est pas continu. La couverture évolue avec la part de mise en avant
pour Helius ou exécutant BAM, donc attendez-vous à des créneaux sans messages — gérez
ces lacunes avec souplesse. Voir [Couverture](/docs/fr/pre-confirmations/overview#couverture).
`preconfSubscribe` est servi depuis `wss://beta.helius-rpc.com` — le point de terminaison [Gatekeeper](/docs/fr/gatekeeper/overview) Helius — plutôt que `mainnet.helius-rpc.com`. Authentifiez-vous avec votre clé API en tant que paramètre de requête.
```
wss://beta.helius-rpc.com/?api-key=
```
Le nom d'hôte `beta` fait référence au déploiement de [Gatekeeper](/docs/fr/gatekeeper/overview),
non à la maturité des préconfirmations. Les préconfirmations sont lancées sur le
point de terminaison Gatekeeper en premier ; cela deviendra le point de terminaison standard à mesure que Helius
migre le trafic vers Gatekeeper.
## S'abonner
Envoyez une requête JSON-RPC avec la méthode `preconfSubscribe`. Le serveur répond avec un identifiant d'abonnement, puis diffuse une notification pour chaque transaction. Passez un [filtre](#filtrage) optionnel comme premier élément `params` pour ne recevoir que les transactions correspondantes ; omettez `params` pour recevoir le flux complet de Helius et BAM.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe"
}
```
### Réponse d'abonnement
```json theme={"system"}
{
"jsonrpc": "2.0",
"result": 24040,
"id": 1
}
```
Conservez l'`result` — c'est l'identifiant d'abonnement que vous utilisez pour [vous désabonner](#désabonnement). Après cet accusé de réception, les notifications sont diffusées sous forme de trames binaires (voir ci-dessous).
## Filtrage
Par défaut, `preconfSubscribe` diffuse chaque transaction des deux sources. Pour restreindre le flux, passez un objet filtre comme premier élément d'`params`. Le filtrage se fait côté serveur, vous ne payez donc que pour et ne recevez que les transactions qui vous intéressent.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [
{
"includeBam": true,
"failed": false,
"regionInclude": ["ewr", "fra"],
"accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"],
"accountExclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
"accountRequired": ["11111111111111111111111111111111"]
}
]
}
```
Chaque champ est facultatif — un champ manquant signifie "aucune contrainte" pour ce prédicat, donc un filtre vide (ou aucun `params`) correspond à chaque transaction des deux sources.
| Champ | Type | Sémantique |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `includeBam` | `boolean` | Par défaut `true`. `false` supprime les préconfirmations BAM pour que vous ne receviez que les préconfirmations Helius. |
| `failed` | `boolean` | Le filtrage par statut n'est pris en charge que pour les préconfirmations Helius et est ignoré pour les préconfirmations BAM. Pour Helius, `true` retourne uniquement les transactions échouées (annulées) ; `false` retourne uniquement les transactions réussies. Soit la valeur exclut les transactions Helius de statut inconnu. Omettez le champ pour recevoir tous les statuts. |
| `regionInclude` | `string[]` | Si non vide, la transaction doit provenir de **l'une de** ces [régions](#filtrage-de-lieu). |
| `accountInclude` | `string[]` | Si non vide, la transaction doit référencer **au moins un** de ces comptes. |
| `accountExclude` | `string[]` | La transaction est abandonnée si elle référence **any** de ces comptes. Prend la priorité sur `accountInclude`. |
| `accountRequired` | `string[]` | La transaction doit référencer **tous** ces comptes. |
Règles de filtrage :
* Tous les prédicats sont ANDés ensemble, évalués dans l'ordre `includeBam` → `failed` → `regionInclude` → `accountExclude` → `accountRequired` → `accountInclude`.
* Les préconfirmations BAM ignorent le filtre de statut `failed` et sont toujours livrées si elles correspondent aux filtres source, région et compte.
* Les comptes sont des clés publiques encodées en base58. Une valeur invalide retourne l'erreur JSON-RPC `-32602` (paramètres invalides).
* Chaque liste de comptes est limitée à **500** entrées.
Pour recevoir uniquement les préconfirmations Helius :
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [{ "includeBam": false }]
}
```
### Résolution de la table de consultation d'adresses (ALT)
Les filtres de compte correspondent à plus que les clés de compte statiques de la transaction — Helius résout les tables de consultation d'adresses v0 [address lookup tables](/docs/fr/glossary#table-de-recherche-dadresse-alt) côté serveur, donc `accountInclude`, `accountExclude`, et `accountRequired` correspondent également aux comptes qu'une transaction charge via une ALT.
Cela signifie que vous pouvez filtrer sur n'importe quel compte qu'une transaction touche, même lorsqu'il n'apparaît qu'à travers une table de consultation — pas besoin de maintenir des mappages ALT ou de résoudre les tables vous-même. Passez simplement la clé publique du compte et Helius gère la résolution avant que le filtre ne soit appliqué.
### Filtrage de lieu
Utilisez `regionInclude` pour ne recevoir que les transactions provenant de régions spécifiques. Passez un ou plusieurs codes régionaux ; une transaction est validée lorsque sa région d'origine correspond à l'un d'eux.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [{ "regionInclude": ["ewr", "fra"] }]
}
```
La région d'origine dépend de la source. Pour les préconfirmations Helius, c'est la région Helius qui a ingéré la transaction. Pour les préconfirmations BAM, c'est le point de terminaison BAM régional qui a émis la préconfirmation, pas où Helius l'a ingérée. Les points de terminaison de Singapour et Dallas de BAM correspondent à `sgp` et `dal`.
Codes régionaux valides :
| Code | Localisation |
| ----- | ------------------ |
| `slc` | Salt Lake City |
| `fra` | Francfort |
| `lon` | Londres |
| `pit` | Pittsburgh |
| `sgp` | Singapour |
| `ewr` | Newark |
| `tyo` | Tokyo |
| `ams` | Amsterdam |
| `dal` | Dallas |
| `dub` | Dublin |
| `mia` | Miami |
| `lax` | Los Angeles |
| `iad` | Ashburn |
| `sea` | Seattle |
| `hkg` | Hong Kong |
| `sqq` | Šiauliai, Lituanie |
Lorsque `regionInclude` est défini, les transactions qui ne portent pas d'informations régionales sont abandonnées. Un code de région non reconnu renvoie l'erreur JSON-RPC `-32602` (paramètres invalides).
## Charge utile de notification
Les notifications sont délivrées sous forme de trames WebSocket **binaires** (et non JSON). Les préconfirmations Helius et BAM partagent le même format. Chaque trame est un format de paquet binaire transportant une seule transaction :
| Octets | Champ | Type | Description |
| ------ | ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `version` | `u8` | Version du schéma de charge utile. Actuellement `1`. |
| 1–8 | `slot` | `u64` (little-endian) | Le créneau auquel appartient la transaction. |
| 9–16 | `tx_index` | `u64` (little-endian) | Index de la transaction dans le créneau. Toujours `0` pour les préconfirmations BAM — BAM classe les transactions par ID de séquence et position de groupe plutôt que par un index de créneau, et aucun n'est porté sur ce flux. |
| 17 | `status` | `u8` | Statut de la transaction : `0` = échoué, `1` = réussi, `2` = inconnu. Les préconfirmations Helius signalent le statut d'exécution sur une base de meilleure disponibilité, `2` lorsque ce n'est pas disponible. Les préconfirmations BAM signalent toujours `2`. |
| 18+ | `transaction` | `bytes` | La transaction au format filaire Solana. Voir [Décoder la transaction](#décoder-la-transaction). |
La charge utile n'a pas de champ source. Ne déduisez pas une origine BAM de `tx_index = 0` et `status = 2`, car les préconfirmations Helius peuvent porter les mêmes valeurs.
### Distinguer les deux sources
Comme il n'y a pas de champ source, vous ne pouvez pas identifier arbitrairement un message comme étant Helius ou BAM. L'octet `status` vous donne un classificateur à sens unique :
* **`status` est `0` ou `1`** — le message est une préconfirmation Helius et la transaction a été exécutée. BAM ne signale jamais ces valeurs.
* **`status` est `2`** — la source est ambigüe : soit une préconfirmation BAM, soit une préconfirmation Helius dont le statut d'exécution n'était pas disponible.
Aucun autre champ ne permet la discrimination. Les ID de séquence et positions de groupe de BAM ne sont pas portés sur ce flux, il n'y a donc pas de métadonnées de classement BAM auxquelles se référer, et `regionInclude` est un filtre d'abonnement plutôt qu'un champ de charge utile, donc il ne peut pas être lu par message.
Si vous avez besoin que chaque message d'un flux porte le même type de preuve, définissez `includeBam: false` — cela laisse uniquement les préconfirmations Helius, toutes émises à l'exécution par le leader. Il n'existe pas de filtre BAM uniquement.
**Seules les préconfirmations Helius portent un statut d'exécution.** Les préconfirmations
Helius signalent `0` (échoué) ou `1` (réussi) lorsque le validateur
le fournit, et `2` uniquement lorsqu'il n'est pas disponible. Les préconfirmations BAM signalent toujours
`2` (inconnu), donc `status` seul ne peut pas vous dire si une transaction issue de BAM
a réussi. Si votre stratégie dépend du statut d'exécution, définissez `includeBam: false` ou confirmez le résultat sur la chaîne.
**Lisez et vérifiez toujours le premier octet `version`.** Il est actuellement `1`. Si
Helius doit mettre à jour le format de la charge utile, la version augmentera — branchez-vous dessus pour que votre décodeur continue de fonctionner à travers les changements de schéma.
Une préconfirmation est un signal précoce, pas une garantie. La transaction n'a pas
encore atterri sur la chaîne et pourrait encore être abandonnée — et le statut d'exécution d'une préconfirmation Helius
reflète le résultat local du leader, qui n'est pas final jusqu'à la confirmation du bloc. Confirmez l'atterrissage par des vérifications d'engagement standard avant de le traiter comme final.
### Décoder la transaction
Les octets de la transaction sont transférés exactement comme le validateur les a sérialisés, dans le codage standard par fil pour la version de la transaction. Les transactions Legacy et v0 utilisent le formatage signatures-premier produit par `bincode`. La transaction v1 ([SIMD-0385](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0385-transaction-v1.md)) utilise une mise en page message-premier avec les signatures à la fin, donc `bincode` échoue sur les charges v1. Utilisez un décodeur qui gère chaque version :
* **Rust :** [`agave-transaction-view`](https://docs.rs/agave-transaction-view) analyse les transactions legacy, v0, et v1 sur place, sans copie intermédiaire. C'est l'option recommandée. [`wincode`](https://docs.rs/wincode), le sérialiseur compatible bincode utilisé par les SDK Solana actuels, décode également v1 en `VersionedTransaction`.
* **JavaScript / TypeScript :** assurez-vous que votre version de bibliothèque prend en charge la transaction v1. Les anciennes implémentations `VersionedTransaction.deserialize` ne gèrent que les versions legacy et v0. Utilisez `@solana/kit` 8.0+ ou `@solana/web3.js` v3. Voir [Support des transactions v1](/docs/fr/rpc/transaction-v1).
```rust theme={"system"}
use agave_transaction_view::transaction_view::TransactionView;
// `frame` is the full binary WebSocket message
let tx_bytes = &frame[18..];
let tx = TransactionView::try_new_unsanitized(tx_bytes)?;
println!("version: {:?}", tx.version()); // Legacy, V0, or V1
println!("signature: {}", tx.signatures()[0]);
for ix in tx.instructions_iter() {
println!("program index {}: {} bytes", ix.program_id_index, ix.data.len());
}
```
## Notifications en double
Les préconfirmations Helius et BAM sont dédupliquées par source, pas entre les sources. Une petite part de transactions parvient à Helius par les deux, vous pouvez donc recevoir la même signature deux fois, et les deux copies peuvent signaler des créneaux différents.
Dédupliquez par signature sur le client et rendez les actions déclenchées par les transactions idempotentes, afin qu'une seconde notification ne déclenche pas deux fois la même action. Confirmez l'exécution et l'atterrissage par des vérifications d'engagement standard.
## Exemple
```javascript theme={"system"}
const WebSocket = require('ws');
const ws = new WebSocket('wss://beta.helius-rpc.com/?api-key=');
ws.on('open', () => {
ws.send(JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'preconfSubscribe' // Helius and BAM preconfirmations by default
// Optional: txs from EWR/FRA touching a given account; Helius txs must be successful.
// BAM ignores the status filter; region and account filters still apply.
// params: [{ failed: false, regionInclude: ['ewr', 'fra'], accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
// Optional: Helius preconfirmations only
// params: [{ includeBam: false }]
}));
// Keep the connection alive
setInterval(() => ws.ping(), 30_000);
});
ws.on('message', (data, isBinary) => {
// The subscribe acknowledgement arrives as a JSON text frame
if (!isBinary) {
const msg = JSON.parse(data.toString());
if (msg.id === 1) console.log('Subscribed, ID:', msg.result);
return;
}
// Notifications arrive as binary frames:
// version (u8) | slot (u64 LE) | tx_index (u64 LE) | status (u8) | transaction bytes
const buf = Buffer.from(data);
const version = buf.readUInt8(0); // currently 1 — branch on this if it changes
if (version !== 1) return; // unknown schema version; update your decoder
const slot = buf.readBigUInt64LE(1);
const txIndex = buf.readBigUInt64LE(9); // always 0 for BAM preconfirmations
const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown (always 2 for BAM)
const txBytes = buf.subarray(18); // transaction in Solana wire format (legacy, v0, or v1)
console.log('Preconfirmation:', { version, slot, txIndex, status, bytes: txBytes.length });
// Decode txBytes with a decoder that supports transaction v1 (see "Decoding the transaction")
});
ws.on('error', console.error);
ws.on('close', () => process.exit(1));
```
## Désabonnement
Pour arrêter de recevoir des notifications, appelez `preconfUnsubscribe` avec l'identifiant d'abonnement retourné par `preconfSubscribe`.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 2,
"method": "preconfUnsubscribe",
"params": [24040]
}
```
```json theme={"system"}
{
"jsonrpc": "2.0",
"result": true,
"id": 2
}
```
## Tarification
Les préconfirmations nécessitent un **plan Professionnel ou supérieur** et coûtent **10 crédits par message** — un message par transaction diffusée — facturé à partir de votre plan. Voir [Crédits](/docs/fr/billing/credits) pour les détails.
La facturation se fait par message, pas par signature unique. Une transaction livrée par Helius et BAM compte deux fois. Définissez `includeBam: false` si vous ne voulez que les préconfirmations Helius.
Les préconfirmations sont un nouveau produit et la tarification est sujette à modification.
## Connexe
Ce que sont les préconfirmations et où elles se situent dans le pipeline de validation.
Diffusez les transactions confirmées avec un filtrage riche.
Paramètres de requête, champs de filtre, et disposition binaire de notification.