Guide de Développement Helius

Construisez des applications Solana haute performance avec Helius - le fournisseur d'infrastructure RPC et API leader avec 99,99 % de disponibilité, des nœuds edge mondiaux et des APIs pensées pour les développeurs.

Aperçu

Helius fournit :

• Infrastructure RPC : Nœuds distribués mondialement avec ultra-basse latence
• DAS API : Données NFT et tokens unifiées (compressées et standards)
• Transactions Améliorées : Données de transactions analysées et lisibles
• API Priority Fee : Recommandations de frais en temps réel
• Webhooks : Monitoring blockchain événementiel
• ZK Compression : APIs compressées de comptes et tokens
• LaserStream : Streaming de données temps réel basé sur gRPC
• Sender API : Atterrissage optimisé des transactions

Démarrage Rapide

Installation

# Installer Helius SDK
npm install helius-sdk

# Ou avec pnpm (recommandé)
pnpm add helius-sdk

Obtenir Votre Clé API

1. Visitez dashboard.helius.dev
2. Créez un compte ou connectez-vous
3. Générez une clé API
4. Stockez-la en sécurité (ne la commitez jamais sur git)

Configuration de l'Environnement

# Fichier .env
HELIUS_API_KEY=your_api_key_here

Configuration de Base

import { createHelius } from "helius-sdk";

const helius = createHelius({
  apiKey: process.env.HELIUS_API_KEY!,
});

// URLs d'endpoints RPC
const MAINNET_RPC = `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`;
const DEVNET_RPC = `https://devnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`;

Infrastructure RPC

Endpoints

Utilisation avec @solana/kit

import { createSolanaRpc, createSolanaRpcSubscriptions } from "@solana/kit";

const rpc = createSolanaRpc(
  `https://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`
);

const rpcSubscriptions = createSolanaRpcSubscriptions(
  `wss://mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`
);

// Effectuer des appels RPC
const slot = await rpc.getSlot().send();
const balance = await rpc.getBalance(address).send();

Méthodes RPC Exclusives Helius

// getProgramAccountsV2 - gère efficacement les grands ensembles de données
const accounts = await helius.rpc.getProgramAccountsV2({
  programAddress: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  cursor: null, // Commencer depuis le début
  limit: 100,
});

// getTransactionsForAddress - filtrage avancé
const transactions = await helius.rpc.getTransactionsForAddress({
  address: "wallet_address",
  before: null,
  until: null,
  limit: 100,
  source: "JUPITER", // Filtrer par source
  type: "SWAP", // Filtrer par type
});

DAS API (Digital Asset Standard)

Accès unifié aux NFTs, tokens et assets compressés.

Méthodes Principales

// Obtenir un seul asset
const asset = await helius.getAsset({
  id: "asset_id_here",
});

// Obtenir les assets par propriétaire
const assets = await helius.getAssetsByOwner({
  ownerAddress: "wallet_address",
  page: 1,
  limit: 100,
  displayOptions: {
    showFungible: true,
    showNativeBalance: true,
  },
});

// Obtenir les assets par collection
const collection = await helius.getAssetsByGroup({
  groupKey: "collection",
  groupValue: "collection_address",
  page: 1,
  limit: 100,
});

// Rechercher les assets avec filtres
const results = await helius.searchAssets({
  ownerAddress: "wallet_address",
  tokenType: "fungible",
  burnt: false,
  page: 1,
  limit: 50,
});

// Obtenir un lot d'assets
const batch = await helius.getAssetBatch({
  ids: ["asset1", "asset2", "asset3"],
});

// Obtenir la preuve d'un asset (pour les NFTs compressés)
const proof = await helius.getAssetProof({
  id: "compressed_nft_id",
});

Référence des Méthodes DAS

API Transactions Améliorées

Obtenez des données de transactions analysées et lisibles.

// Analyser les transactions par signature
const parsed = await helius.enhanced.getTransactions({
  transactions: ["sig1", "sig2", "sig3"],
});

// Obtenir l'historique de transactions amélioré
const history = await helius.enhanced.getTransactionsByAddress({
  address: "wallet_address",
  type: "SWAP", // Optionnel : filtrer par type
});

Types de Transactions

• SWAP - Swaps DEX (Jupiter, Raydium, Orca)
• NFT_SALE - Ventes de NFT sur marketplace
• NFT_LISTING - Listes de NFT
• NFT_BID - Offres sur NFT
• TOKEN_MINT - Mint de tokens
• TRANSFER - Transferts de SOL/tokens
• STAKE - Opérations de staking
• UNKNOWN - Transactions non reconnues

API Priority Fee

Obtenez les recommandations de priority fees en temps réel.

// Obtenir une estimation de priority fee
const feeEstimate = await helius.getPriorityFeeEstimate({
  transaction: serializedTransaction, // Base64 encodée
  // OU
  accountKeys: ["account1", "account2"], // Comptes dans la transaction
  options: {
    priorityLevel: "HIGH", // LOW, MEDIUM, HIGH, VERY_HIGH
    includeAllPriorityFeeLevels: true,
    lookbackSlots: 150,
  },
});

console.log(feeEstimate.priorityFeeEstimate); // microLamports

Utiliser les Priority Fees dans les Transactions

import { getSetComputeUnitPriceInstruction } from "@solana-program/compute-budget";

// Obtenir l'estimation
const { priorityFeeEstimate } = await helius.getPriorityFeeEstimate({
  accountKeys: [payer.address, recipient.address],
  options: { priorityLevel: "HIGH" },
});

// Ajouter à la transaction
const priorityFeeIx = getSetComputeUnitPriceInstruction({
  microLamports: BigInt(priorityFeeEstimate),
});

// Ajouter en début aux instructions de transaction
const tx = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(payer.address, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
  (tx) => prependTransactionMessageInstructions([priorityFeeIx], tx),
  (tx) => appendTransactionMessageInstruction(mainInstruction, tx),
);

Webhooks

Notifications d'événements blockchain en temps réel.

Types de Webhooks

Créer un Webhook

// Créer un webhook amélioré
const webhook = await helius.webhooks.createWebhook({
  webhookURL: "https://your-server.com/webhook",
  transactionTypes: ["NFT_SALE", "SWAP"],
  accountAddresses: ["address1", "address2"],
  webhookType: "enhanced",
});

// Créer un webhook raw
const rawWebhook = await helius.webhooks.createWebhook({
  webhookURL: "https://your-server.com/raw-webhook",
  accountAddresses: ["address1"],
  webhookType: "raw",
});

Gérer les Webhooks

// Obtenir tous les webhooks
const webhooks = await helius.webhooks.getAllWebhooks();

// Obtenir un webhook spécifique
const webhook = await helius.webhooks.getWebhookByID({
  webhookID: "webhook_id",
});

// Mettre à jour un webhook
await helius.webhooks.updateWebhook({
  webhookID: "webhook_id",
  webhookURL: "https://new-url.com/webhook",
  accountAddresses: ["address1", "address2", "address3"],
});

// Supprimer un webhook
await helius.webhooks.deleteWebhook({
  webhookID: "webhook_id",
});

Payload de Webhook (Enhanced)

interface EnhancedWebhookPayload {
  accountData: AccountData[];
  description: string;
  events: Record<string, unknown>;
  fee: number;
  feePayer: string;
  nativeTransfers: NativeTransfer[];
  signature: string;
  slot: number;
  source: string;
  timestamp: number;
  tokenTransfers: TokenTransfer[];
  type: string;
}

API ZK Compression

Travailler avec les comptes compressés et les tokens (Light Protocol).

// Obtenir un compte compressé
const account = await helius.zk.getCompressedAccount({
  address: "compressed_account_address",
});

// Obtenir les comptes tokens compressés par propriétaire
const tokens = await helius.zk.getCompressedTokenAccountsByOwner({
  owner: "wallet_address",
});

// Obtenir le solde compressé
const balance = await helius.zk.getCompressedBalance({
  address: "compressed_account_address",
});

// Obtenir une preuve de validité
const proof = await helius.zk.getValidityProof({
  hashes: ["hash1", "hash2"],
});

// Obtenir les signatures de compression
const sigs = await helius.zk.getCompressionSignaturesForOwner({
  owner: "wallet_address",
  limit: 100,
});

Méthodes ZK Compression

Envoi de Transactions

Envoi de Transactions Intelligentes

// Envoyer avec retry automatique et optimisation
const signature = await helius.tx.sendSmartTransaction({
  transaction: signedTransaction,
  skipPreflight: false,
  maxRetries: 3,
});

// Estimer les unités de compute
const computeUnits = await helius.tx.getComputeUnits({
  transaction: serializedTransaction,
});

Motif de Transaction Optimisée

import { createHelius } from "helius-sdk";
import {
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getBase64EncodedWireTransaction,
} from "@solana/kit";
import {
  getSetComputeUnitLimitInstruction,
  getSetComputeUnitPriceInstruction,
} from "@solana-program/compute-budget";

async function sendOptimizedTransaction(
  helius: ReturnType<typeof createHelius>,
  rpc: Rpc,
  signer: KeyPairSigner,
  instruction: IInstruction
) {
  // 1. Obtenir le priority fee
  const { priorityFeeEstimate } = await helius.getPriorityFeeEstimate({
    accountKeys: [signer.address],
    options: { priorityLevel: "HIGH" },
  });

  // 2. Obtenir le blockhash
  const { value: blockhash } = await rpc.getLatestBlockhash().send();

  // 3. Construire la transaction avec budget de compute
  const tx = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayer(signer.address, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
    (tx) => prependTransactionMessageInstructions([
      getSetComputeUnitLimitInstruction({ units: 200_000 }),
      getSetComputeUnitPriceInstruction({ microLamports: BigInt(priorityFeeEstimate) }),
    ], tx),
    (tx) => appendTransactionMessageInstruction(instruction, tx),
  );

  // 4. Signer
  const signedTx = await signTransactionMessageWithSigners(tx);

  // 5. Envoyer via Helius
  const signature = await helius.tx.sendSmartTransaction({
    transaction: getBase64EncodedWireTransaction(signedTx),
  });

  return signature;
}

Souscriptions WebSocket

Streaming de données temps réel via WebSocket.

// S'abonner aux changements de compte
const accountSub = await helius.ws.accountNotifications({
  account: "account_address",
  commitment: "confirmed",
  callback: (notification) => {
    console.log("Account changed:", notification);
  },
});

// S'abonner aux logs
const logsSub = await helius.ws.logsNotifications({
  filter: { mentions: ["program_id"] },
  commitment: "confirmed",
  callback: (logs) => {
    console.log("Logs:", logs);
  },
});

// S'abonner aux confirmations de signature
const sigSub = await helius.ws.signatureNotifications({
  signature: "transaction_signature",
  commitment: "confirmed",
  callback: (status) => {
    console.log("Confirmed:", status);
  },
});

// Se désabonner
await accountSub.unsubscribe();

LaserStream (gRPC)

LaserStream est un service de streaming gRPC nouvelle génération - un remplacement direct pour Yellowstone qui ajoute la relecture historique, la reconnexion automatique et les endpoints multi-régions.

Fonctionnalités

• Ultra-basse latence : Se connecte directement aux leaders Solana pour recevoir les shreds à mesure qu'ils sont produits
• Relecture historique : Rejouer les blocs et transactions passés
• Reconnexion automatique : Basculement automatique et récupération
• Clusters de nœuds redondants : Infrastructure haute disponibilité
• Endpoints régionaux : Couverture mondiale pour latence minimale
• Streaming de blocs, transactions et comptes

Endpoints

Infrastructure Atlas

Les endpoints Atlas fournissent la base pour les WebSockets Améliorés et le streaming haute performance :

// Endpoints Atlas WebSocket
const ATLAS_MAINNET_WS = "wss://atlas-mainnet.helius-rpc.com";
const ATLAS_DEVNET_WS = "wss://atlas-devnet.helius-rpc.com";

WebSockets Améliorés (Nouveau)

Les WebSockets Améliorés sont maintenant alimentés par l'infrastructure LaserStream, offrant :

• 1,5–2× plus rapides que les WebSockets standards
• Fiabilité gRPC dans un wrapper WebSocket
• Mêmes filtres et types d'événements que les WebSockets réguliers

// Se connecter à un WebSocket Amélioré
const ws = new WebSocket(
  `wss://atlas-mainnet.helius-rpc.com/?api-key=${process.env.HELIUS_API_KEY}`
);

ws.on("open", () => {
  // S'abonner aux changements de compte
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "accountSubscribe",
    params: [accountAddress, { commitment: "confirmed" }],
  }));
});

Livraison de Shreds (Beta)

Pour les équipes visant une latence de quelques millisecondes, Helius offre un flux UDP de shreds bruts directement depuis les validateurs.

API Staking

Stakez du SOL avec le validateur Helius par programme.

// Créer une transaction de stake
const stakeTx = await helius.staking.createStakeTransaction({
  payerAddress: "wallet_address",
  amount: 1_000_000_000, // 1 SOL en lamports
});

// Créer une transaction d'unstake
const unstakeTx = await helius.staking.createUnstakeTransaction({
  payerAddress: "wallet_address",
  stakeAccountAddress: "stake_account",
});

// Obtenir les comptes de stake
const stakeAccounts = await helius.staking.getHeliusStakeAccounts({
  ownerAddress: "wallet_address",
});

Espaces de Noms SDK

Gestion des Erreurs

try {
  const assets = await helius.getAssetsByOwner({ ownerAddress: "..." });
} catch (error) {
  if (error.response?.status === 401) {
    console.error("Invalid API key");
  } else if (error.response?.status === 429) {
    console.error("Rate limited - upgrade plan or reduce requests");
  } else if (error.response?.status >= 500) {
    console.error("Helius server error - retry later");
  }
}

Codes d'Erreur Communs

Limites de Débit et Tarification

Coûts de Crédit

• RPC Standard : 1 crédit/appel
• DAS API : 1-10 crédits/appel
• Webhooks : 1 crédit/événement livré
• Gestion des webhooks : 100 crédits/opération

Bonnes Pratiques

Sécurité des Clés API

• Ne jamais commiter les clés API sur git
• Utiliser les variables d'environnement
• Rotationner les clés régulièrement
• Utiliser des clés séparées pour dev/prod

Performance

• Traiter les requêtes par lot quand c'est possible (getAssetBatch, getAssetProofBatch)
• Utiliser la pagination basée sur curseur pour les grands ensembles de données
• Mettre en cache les données fréquemment consultées
• Utiliser les niveaux de commitment appropriés

Fiabilité

• Implémenter la logique de retry avec backoff exponentiel
• Gérer les rate limits gracieusement
• Utiliser plusieurs endpoints régionaux pour le failover
• Surveiller la livraison des webhooks et gérer les retries

Ressources

• Documentation Helius
• Tableau de Bord Helius
• GitHub SDK Helius
• Discord Helius
• Statut Helius

Structure de Skill

helius/
├── SKILL.md                    # Ce fichier
├── resources/
│   ├── rpc-methods.md          # Référence RPC complète
│   ├── das-api.md              # Référence DAS API
│   ├── enhanced-apis.md        # Transactions améliorées et priority fees
│   ├── webhooks.md             # Configuration des webhooks
│   ├── zk-compression.md       # API ZK compression
│   └── sdk-reference.md        # Référence des espaces de noms SDK
├── examples/
│   ├── basic-rpc/              # Appels RPC basiques
│   ├── fetch-nfts/             # Exemples DAS API
│   ├── send-transactions/      # Envoi de transactions
│   ├── webhooks/               # Configuration des webhooks
│   └── streaming/              # Données temps réel
├── templates/
│   └── helius-setup.ts         # Template de démarrage
└── docs/
    └── troubleshooting.md      # Problèmes courants

Vérification

• Un appel RPC/SDK réel a été émis (mainnet, devnet ou validateur local) et le payload de réponse est capturé dans la transcription, pas seulement paraphrasé
• Chaque transaction a été simulée (simulateTransaction ou équivalent) avant toute étape de signature/envoi ; les logs de simulation sont joints
• Pour toute transaction signée/envoyée, la signature résultante est enregistrée et confirmée on-chain (statut retourné par getSignatureStatuses ou URL d'explorateur)
• Le slippage, le priority-fee et les limites d'unités de compute ont été définis explicitement avec des valeurs numériques concrètes, pas laissés aux défauts de la librarie
• Les adresses de comptes, les mints et les ID de programmes utilisés dans l'exécution correspondent aux adresses helius-rpc documentées pour le cluster ciblé (pas de mélange mainnet/devnet)
• Le chemin d'échec a été exercé au moins une fois (solde insuffisant, oracle obsolète, blockhash expiré, etc.) et la gestion d'erreur de l'agent a produit un message lisible