Skip to main content
Le SDK wallet-kit s’exécute dans le navigateur, donc votre apiKey Helius est présent côté client : le fournisseur l’envoie au bootstrap du portefeuille (/waas/config) lors du chargement de votre application. Cela est attendu pour un SDK côté client. Cette page explique exactement ce que cette clé peut et ne peut pas faire, et comment la sécuriser.

​
Ce que la clé peut — et ne peut pas — faire

Commencez ici, car c’est la partie qu’il est facile de mal comprendre : la clé API Helius est un identifiant de RPC/crédits, pas une clé de portefeuille. Une clé divulguée ne peut pas :
  • signer des transactions ou des messages,
  • déplacer ou accéder à des fonds, ou
  • toucher tout portefeuille intégré de l’utilisateur.
La signature de portefeuille est autorisée par le passkey ou la session propre à l’utilisateur final, et les clés privées résident dans les enclaves sécurisées de Turnkey — jamais dans votre application, votre serveur, ou quoi que ce soit que la clé API peut atteindre. Exposer la clé n’expose pas les portefeuilles. Ce qu’une clé divulguée peut faire, c’est consommer vos crédits Helius (quota RPC). C’est tout le rayon d’impact — une question de facturation, pas une question de garde — et les couches ci-dessous le limitent et le ferment.
L’exposition n’est pas non plus un contournement de facturation. Les signatures WaaS sont comptabilisées au moment où le portefeuille intégré signe, pas au niveau de la clé API — une clé divulguée ne peut pas créer des signatures gratuites ou facturer des signatures depuis le site de quelqu’un d’autre. Le comptage ne dépend pas du secret de la clé.

​
Sécuriser la clé

Ces couches vont du moindre effort à la barrière la plus difficile. La première est la base requise ; empilez le reste selon vos besoins en matière de tolérance au risque.

​
1. Restreindre la clé par domaine (requis)

Verrouillez la clé aux origines sur lesquelles votre application s’exécute, afin qu’une clé extraite de votre bundle soit inutile ailleurs.
1

Ouvrir le contrôle d'accès RPC

Dans le tableau de bord, allez à votre clé sous la section RPCs et ouvrez Contrôle d’accès.
2

Ajouter vos domaines aux domaines autorisés

Ajoutez chaque origine depuis laquelle votre application est servie — production, staging, et aperçu:
3

Utiliser une clé distincte par environnement

Conservez une clé distincte pour le local, le staging, et la production afin de pouvoir en faire tourner une sans affecter les autres.
Les listes d’autorisation de domaine empêchent une mauvaise utilisation à partir du navigateur, pas un script déterminé. Le contrôle lit l’en-tête de la demande Origin/Referer — un navigateur le définit honnêtement, mais un client non-navigateur (par ex. curl -H "Origin: yourdapp.com") peut le falsifier. Cela est vrai pour chaque clé API côté client, pas seulement pour Helius. La restriction de domaine empêche de manière fiable le cas commun — votre clé apparaissant sur le site de quelqu’un d’autre — mais pour une barrière qui ne peut pas être falsifiée, utilisez une clé côté serveur verrouillée à vos IPs/CIDRs (étape 4).

​
2. URL RPC sécurisées sans clé (automatique)

Le trafic RPC ne transporte pas du tout votre clé. Le SDK résout l’URL RPC sécurisée sans clé de votre projet au démarrage et l’utilise pour les appels connection automatiquement — rien à configurer. Étant donné que ces URL ne contiennent aucune clé, il n’y a rien dans une demande RPC à extraire, et elles sont limitées à 5 RPS par IP — leur protection ne dépend donc pas des contrôles d’Origine. (Disponible sur les plans payants ; lorsqu’un projet n’a pas d’URL RPC sécurisée, RPC revient au gestionnaire de route de même origine à l’étape 3.)

​
3. Déplacer la clé côté serveur — sans serveur

Pour garder la clé hors du navigateur pour les appels RPC, d’envoi, et d’historique des transactions, redirigez-les via votre propre point de terminaison qui injecte la clé à partir d’un secret côté serveur. C’est aussi ainsi que vous optez pour Atterrissage optimisé pour l’expéditeur et un historique des transactions. Les deux options sont 100% sans serveur — pas de serveur à gérer :
  • Gestionnaire de routes Next.js — déployé en tant que fonction sans serveur (Vercel, Netlify, Cloudflare). Lit HELIUS_API_KEY depuis l’environnement du serveur.
    app/api/helius/[...path]/route.ts
  • Proxy Cloudflare Worker — l’option la plus propre et entièrement sans serveur : la clé réside dans un secret Worker et n’atteint jamais le navigateur.

    Proxy RPC Helius

    Proxy RPC open-source que vous déployez sur Cloudflare en un clic.

​
4. Ajouter une barrière IP/CIDR non-falsifiable

Pour qu’une barrière ne puisse pas être falsifiée par un attaquant, verrouillez une clé côté serveur aux adresses IP ou plages CIDR de votre backend. Contrairement à un en-tête Origin, l’IP source d’une demande ne peut pas être falsifiée via une connexion normale — donc un curl venant d’un autre endroit que vos serveurs est rejeté sans condition. Cela s’applique uniquement à une clé côté serveur — vous ne pouvez pas restreindre par IP la clé du navigateur, car vos utilisateurs se connectent depuis des IPs imprévisibles. Le modèle clair est deux clés :
Les fonctions sans serveur ont des IPs de sortie dynamiques, donc épingler un CIDR nécessite une sortie stable — un Worker Cloudflare avec une IP de sortie dédiée, Vercel Secure Compute, ou un NAT à IP fixe devant. Sans cela, vous obtenez toujours le principal avantage (la clé est coté serveur, jamais dans le navigateur) ; vous n’ajoutez juste pas la barrière IP par-dessus.
Voir Protéger vos clés pour la référence complète des règles de contrôle d’accès.

​
Comparaison des couches

Quelle que soit la couche choisie, rien de tout cela ne concerne les clés de portefeuille de vos utilisateurs — celles-ci ne sont jamais en jeu.

​
Le bootstrap du portefeuille

Dans la configuration du gestionnaire de routes (production), le bootstrap du portefeuille (/waas/config) passe également par votre gestionnaire de routes avec la clé côté serveur — donc aucune clé Helius n’est envoyée au navigateur pour cela non plus. Dans la configuration de prototypage, le navigateur envoie la clé pour le bootstrap ; restreignez-la par domaine (étape 1). Dans tous les cas, c’est la clé étendue pour RPC — elle ne peut toucher les portefeuilles ou les fonds.

​
Liste de vérification

Avant d’expédier :
  • La clé client est restreinte par domaine à vos origines exactes
  • Clés séparées pour local / staging / production
  • La clé est lue à partir d’une variable d’environnement, jamais codée en dur
  • (Optionnel) RPC, envoi, et historique routés via le gestionnaire de routes sans serveur ou Worker Cloudflare
  • (Optionnel) Clé côté serveur verrouillée à vos IPs/CIDRs pour une barrière non-falsifiable

​
Prochaines étapes

Protéger vos clés

Référence complète de contrôle d’accès : domaines, IPs, CIDRs, et proxys.

Configuration

Configuration du fournisseur et méthodes de connexion au tableau de bord.