helius-wallet-kit SDK und deren Behebung.
Einrichtung
Das Wallet-Modal ist ungestylt oder sieht fehlerhaft aus
Das Stylesheet des SDKs ist nicht geladen. Importiere es einmal in deinem Root-Layout:app/layout.tsx
Die Hook-Werte ändern sich nie (festgefahren auf loading)
useHeliusWallet() funktioniert nur innerhalb von HeliusWalletProvider, und der Provider muss eine Client-Komponente sein. Stelle sicher, dass der Provider deinen Komponentenbaum aus einer Datei mit "use client" am Anfang umschließt — siehe Einrichtung.
[HeliusWalletKit] WaaS bootstrap failed (…) in der Konsole
Der Provider konnte dein Projekt nicht über den API-Schlüssel auflösen. Überprüfe, ob:
NEXT_PUBLIC_HELIUS_API_KEYgesetzt und gültig ist.- Das Projekt sich auf einem kostenpflichtigen Plan mit aktivierten Embedded Wallets befindet.
- Wenn du den Schlüssel domänenbeschränkt hast, dein aktueller Ursprung in der zulässigen Liste ist — siehe Schlüssel sichern.
Anmeldung
Benutzer landen auf einem “Upgrade”-Bildschirm anstelle des Wallets
Embedded Wallets erfordern einen kostenpflichtigen Helius-Plan. Wenn der aufgelöste Plan kostenlos ist, zeigt der Provider eine Upgrade-Aufforderung an (und der Backend lehnt die Anfrage serverseitig ebenfalls ab). Upgrade das Projekt im Dashboard.Die falschen Anmeldemethoden erscheinen (z.B. Google wird angezeigt, externes Wallet fehlt)
Anmeldemethoden stammen aus deiner Projektkonfiguration im Dashboard unter WaaS → Konfiguration. Wenn ein Projekt keine konfiguriert hat, fällt das Modal auf eine organisationsweite Standardeinstellung zurück. Setze die gewünschten Methoden im Dashboard, oder übergebeauthMethods an den Provider config um pro Umgebung zu überschreiben — siehe Anmeldemethoden konfigurieren.
Passkey-Anmeldung schlägt fehl oder sagt, der Passkey sei nicht registriert
Passkeys sind an die Domäne und Authentifikator gebunden, auf denen sie erstellt wurden (eine WebAuthn-Beschränkung, keine von Helius). Ein Passkey oder Sicherheitsschlüssel, der auf einer anderen Site oder einem anderen Gerät registriert wurde, authentifiziert deine App nicht. Erstelle den Passkey auf der Domäne, die du testest — beachte, dass ein Passkey, der auflocalhost erstellt wurde, an localhost gebunden ist und nicht auf deine bereitgestellte Domäne übertragen wird.
Signierung und Senden
No wallet available beim Signieren
Du hast eine Signiermethode aufgerufen, bevor das Embedded Wallet bereitgestellt wurde. Setze die Signierung auf status === "authenticated" und einen nicht-null address:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Diese Send- oder Priority-Fee-Anfrage hatte kein Ziel: Der Provider hat keine Secure RPC URL beim Start aufgelöst (kostenpflichtige Pläne erhalten normalerweise automatisch eine) und kein Server-Route-Handler ist installiert. Installiere den Route-Handler unter /api/helius/[...path] und setze HELIUS_API_KEY:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
Transaktionshistorie ist nur über den Route-Handler verfügbar. Füge ihn wie oben gezeigt hinzu.
getPriorityFeeEstimate is not available
Devnet unterstützt keine Priority-Fee-Schätzungen — es ist eine Mainnet-Funktion. Überspringe das Nachschlagen auf Devnet; Sendungen funktionieren trotzdem ohne Priority-Fee.
Eine Transaktion landet nicht im Mainnet
Ohne den Route-Handler verwenden Sendungen standardmäßiges RPC anstelle von Helius Sender, sodass sie auf die optimierte Landung von Sender verzichten. Installiere den Route-Handler für die beste Mainnet-Landung. Wenn eine Sendung vollständig fehlschlägt, aktualisiere den Blockhash — ein veralteterrecentBlockhash läuft schnell ab.
Schlüssel und Zugang
RPC- oder API-Aufrufe werden abgelehnt (401 / 403) nach dem Sperren deines Schlüssels
Dein domänenbeschränkter Schlüssel enthält nicht den Ursprung, von dem aus du anrufst. Füge jeden verwendeten Ursprung hinzu — Produktion, Staging, Vorschau-Bereitstellungen undlocalhost für die Entwicklung — unter RPC Access Control. Siehe Schlüssel sichern.
Immer noch Probleme?
Discord
Frage die Community und das Helius-Team.
Support
Kontaktiere Helius-Support.