helius-wallet-kit, et comment les résoudre.
Configuration
La fenêtre modale du portefeuille est non stylée ou semble cassée
La feuille de style du SDK n’est pas chargée. Importez-la une fois dans votre mise en page racine :app/layout.tsx
Les valeurs du hook ne changent jamais (bloquées sur loading)
useHeliusWallet() fonctionne uniquement à l’intérieur de HeliusWalletProvider, et le fournisseur doit être un composant client. Assurez-vous que le fournisseur entoure votre arbre de composants depuis un fichier avec "use client" en haut — voir Configuration.
[HeliusWalletKit] WaaS bootstrap failed (…) dans la console
Le fournisseur n’a pas pu résoudre votre projet à partir de la clé API. Vérifiez que :
NEXT_PUBLIC_HELIUS_API_KEYest défini et valide.- Le projet est sur un plan payant avec des portefeuilles intégrés activés.
- Si vous avez restreint la clé par domaine, votre origine actuelle est dans la liste autorisée — voir Sécuriser votre clé.
Connexion
Les utilisateurs arrivent sur un écran de “mise à niveau” au lieu du portefeuille
Les portefeuilles intégrés nécessitent un plan Helius payant. Lorsque le plan résolu est gratuit, le fournisseur affiche une demande de mise à niveau (et le backend rejette également la requête côté serveur). Mettez à niveau le projet dans le tableau de bord.Les mauvaises méthodes de connexion apparaissent (par exemple, Google s’affiche, le portefeuille externe manque)
Les méthodes de connexion proviennent de la configuration de votre projet dans le tableau de bord sous WaaS → Configuration. Si un projet n’a aucune méthode configurée, la fenêtre modale revient à un défaut à l’échelle de l’organisation. Définissez les méthodes souhaitées dans le tableau de bord, ou passezauthMethods au fournisseur config pour remplacer par environnement — voir Configurer les méthodes de connexion.
La connexion par clé de sécurité échoue ou indique que la clé de sécurité n’est pas enregistrée
Les clés de sécurité sont liées au domaine et à l’authentificateur sur lesquels elles ont été créées (une contrainte WebAuthn, pas une de Helius). Une clé de sécurité enregistrée sur un autre site ou appareil ne permettra pas d’authentifier votre application. Créez la clé de sécurité sur le domaine que vous testez — notez qu’une clé de sécurité créée surlocalhost est liée à localhost et ne sera pas transférée à votre domaine déployé.
Signature et envoi
No wallet available lors de la signature
Vous avez appelé une méthode de signature avant que le portefeuille intégré ait terminé son approvisionnement. Restreignez la signature sur status === "authenticated" et un address non nul :
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Cette requête send ou priority-fee n’avait nulle part où aller : le fournisseur n’a résolu aucune URL RPC sécurisée lors de l’initialisation (les plans payants en obtiennent normalement une automatiquement) et aucun gestionnaire de route serveur n’est monté. Montez le gestionnaire de route à /api/helius/[...path] et définissez HELIUS_API_KEY :
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
L’historique des transactions n’est disponible qu’à travers le gestionnaire de route. Ajoutez-le comme indiqué ci-dessus.
getPriorityFeeEstimate is not available
Le Devnet ne prend pas en charge les estimations de frais prioritaires — c’est une fonctionnalité du mainnet. Ignorez la recherche sur devnet ; les envois fonctionnent toujours sans frais prioritaires.
Une transaction n’aboutit pas sur le mainnet
Sans le gestionnaire de route, les envois utilisent le RPC standard plutôt que Helius Sender, donc ils renoncent à l’optimisation d’atterrissage de Sender. Montez le gestionnaire de route pour un meilleur atterrissage sur le mainnet. Si un envoi échoue complètement, rafraîchissez le blockhash — unrecentBlockhash obsolète expire rapidement.
Clés et accès
Les appels RPC ou API sont rejetés (401 / 403) après avoir verrouillé votre clé
Votre clé restreinte par domaine n’inclut pas l’origine à partir de laquelle vous appelez. Ajoutez chaque origine que vous utilisez — production, staging, déploiements de prévisualisation, etlocalhost pour le développement — sous Contrôle d’accès RPC. Voir Sécuriser votre clé.
Toujours bloqué ?
Discord
Demandez à la communauté et à l’équipe Helius.
Support
Contactez le support Helius.