helius-wallet-kit SDK und wie du sie behebst.
Einrichtung
Das Wallet-Modal ist unformatiert oder sieht fehlerhaft aus
Das Stylesheet des SDK wurde nicht geladen. Importiere es einmal in dein Root-Layout:app/layout.tsx
Die Hook-Werte ändern sich nie (bleiben bei loading hängen)
useHeliusWallet() funktioniert nur innerhalb von HeliusWalletProvider. Außerdem muss der Provider eine Client-Komponente sein. Stelle sicher, dass der Provider deinen Komponentenbaum umschließt und aus einer Datei kommt, in der "use client" ganz oben steht – siehe Einrichtung.
[HeliusWalletKit] WaaS bootstrap failed (…) in der Konsole
Der Provider konnte dein Projekt nicht über den API key ermitteln. Prüfe Folgendes:
NEXT_PUBLIC_HELIUS_API_KEYist festgelegt und gültig.- Das Projekt nutzt einen kostenpflichtigen Tarif, bei dem eingebettete Wallets aktiviert sind.
- Wenn du den Key auf bestimmte Domains beschränkt hast, muss deine aktuelle Origin in der Zulassungsliste stehen – siehe API key absichern.
Anmeldung
Nutzer gelangen zu einer Aufforderung zum Upgrade statt zur Wallet
Eingebettete Wallets erfordern einen kostenpflichtigen Helius-Tarif. Wenn für das Projekt der kostenlose Tarif ermittelt wird, zeigt der Provider eine Aufforderung zum Upgrade an. Auch das Backend lehnt den request serverseitig ab. Führe im Dashboard ein Upgrade für das Projekt durch.Es werden die falschen Anmeldemethoden angezeigt (z. B. Google, aber keine externe Wallet)
Die Anmeldemethoden stammen aus deiner Projektkonfiguration im Dashboard unter WaaS → Configuration. Wenn für ein Projekt keine Methoden konfiguriert sind, verwendet das Modal einen organisationsweiten Standard. Lege die gewünschten Methoden im Dashboard fest oder übergibauthMethods an den Provider config, um sie je Umgebung zu überschreiben – siehe Anmeldemethoden konfigurieren.
Die Anmeldung mit einem Passkey schlägt fehl oder meldet, dass der Passkey nicht registriert ist
Passkeys sind an die Domain und den Authenticator gebunden, auf denen sie erstellt wurden. Das ist eine WebAuthn-Einschränkung und keine Einschränkung von Helius. Ein Passkey oder Sicherheitsschlüssel, der auf einer anderen Website oder einem anderen Gerät registriert wurde, kann deine App nicht authentifizieren. Erstelle den Passkey auf der Domain, die du testest. Beachte, dass ein auflocalhost erstellter Passkey an localhost gebunden ist und nicht für deine bereitgestellte Domain übernommen wird.
Signieren und Senden
No wallet available beim Signieren
Du hast eine Signiermethode aufgerufen, bevor die Bereitstellung der eingebetteten Wallet abgeschlossen war. Starte das Signieren erst, wenn status === "authenticated" erfüllt und address nicht null ist:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Für diesen request zum Senden oder zum Ermitteln einer Prioritätsgebühr gab es kein Ziel: Der Provider hat bei der Initialisierung keine sichere RPC-URL ermittelt. Kostenpflichtige Tarife erhalten normalerweise automatisch eine. Außerdem ist kein serverseitiger Route Handler eingebunden. Binde den Route Handler unter /api/helius/[...path] ein und lege HELIUS_API_KEY fest:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
Der Transaktionsverlauf ist nur über den Route Handler verfügbar. Füge ihn wie oben gezeigt hinzu.
getPriorityFeeEstimate is not available
Devnet unterstützt keine Schätzungen für Prioritätsgebühren. Diese Funktion ist nur im Mainnet verfügbar. Überspringe die Abfrage im Devnet. Transaktionen lassen sich auch ohne Prioritätsgebühr senden.
Eine Transaktion kommt nicht im Mainnet an
Ohne den Route Handler verwenden Sendevorgänge Standard-RPC statt Helius Sender. Dadurch entfällt die optimierte Zustellung von Sender. Binde den Route Handler ein, damit Transaktionen im Mainnet bestmöglich ankommen. Wenn das Senden vollständig fehlschlägt, aktualisiere den Blockhash. Ein veralteterrecentBlockhash läuft schnell ab.
API key und Zugriff
RPC- oder API-Aufrufe werden abgelehnt (401 / 403), nachdem du deinen API key eingeschränkt hast
Dein auf bestimmte Domains beschränkter API key enthält nicht die Origin, von der du den Aufruf sendest. Füge jede verwendete Origin hinzu – für Produktion, Staging, Preview deployment undlocalhost während der Entwicklung – unter RPC Access Control. Siehe API key absichern.
Kommst du immer noch nicht weiter?
Discord
Frage die Community und das Helius-Team.
Support
Kontaktiere den Helius-Support.