helius-wallet-kit SDKを統合する際の一般的な問題とその解決方法。
セットアップ
ウォレットモーダルがスタイルされていないか壊れているように見える
SDKのスタイルシートが読み込まれていません。ルートレイアウトで一度インポートしてください。app/layout.tsx
フックの値が変わらない（loadingで固まっている）
useHeliusWallet()は、HeliusWalletProvider内でのみ機能し、プロバイダーはクライアントコンポーネントである必要があります。プロバイダーがコンポーネントツリーを囲み、ファイルの先頭に"use client"があることを確認してください — セットアップを参照。
コンソールに[HeliusWalletKit] WaaS bootstrap failed (…)
プロバイダーがAPIキーからプロジェクトを解決できませんでした。以下を確認してください。
NEXT_PUBLIC_HELIUS_API_KEYが設定されており、有効である。- プロジェクトが埋め込みウォレットを有効にした有料プランである。
- ドメイン制限を行った場合、現在のオリジンが許可リストにある — キーのセキュリティ確保を参照。
サインイン
ユーザーが「アップグレード」画面に遷移し、ウォレットにアクセスできない
埋め込みウォレットは有料Heliusプランを必要とします。解決されたプランが無料の場合、プロバイダーはアップグレードのプロンプトを表示します（バックエンドもサーバー側でリクエストを拒否します）。プロジェクトをダッシュボードでアップグレードしてください。間違ったサインイン方法が表示される（例: Googleが表示され、外部ウォレットが欠落）
サインイン方法はダッシュボードのプロジェクト設定のWaaS → 設定から提供されます。プロジェクトに設定がない場合、モーダルは組織全体のデフォルトにフォールバックします。ダッシュボードで希望する方法を設定するか、authMethodsをプロバイダーconfigに渡して環境ごとに上書きしてください — サインイン方法の設定を参照。
パスキーサインインが失敗したり、パスキーが登録されていないと表示される
パスキーは作成されたドメインと認証装置にバインドされています（WebAuthnの制約であり、Heliusのものではありません）。別のサイトやデバイスで登録されたパスキーやセキュリティキーはアプリを認証しません。テストしているドメインでパスキーを作成してください —localhostで作成されたパスキーはlocalhostにバインドされており、デプロイされたドメインには引き継がれません。
署名と送信
署名時のNo wallet available
埋め込みウォレットがプロビジョニングを完了する前に署名メソッドを呼び出しました。署名は、status === "authenticated" および 非nullのaddressの両方でゲートしてください。
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
直接（セキュアRPC）モードで実行しており、この呼び出し — 送信または優先手数料リクエスト — はサーバールートハンドラーが必要です。/api/helius/[...path]にマウントし、HELIUS_API_KEYを設定してください。
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
トランザクション履歴はルートハンドラーを通してのみ利用可能です。上記のように追加してください。
getPriorityFeeEstimate is not available
Devnetは優先手数料見積もりをサポートしていません — これはメインネットの機能です。Devnetではルックアップをスキップします。送信は優先手数料なしでも動作します。
トランザクションがメインネットに到達しない
ルートハンドラーなしで送信は標準RPCを使用し、Helius Senderの最適化された着地を逃します。最適なメインネット着地のためにルートハンドラーをマウントしてください。送信が完全に失敗する場合は、ブロックハッシュをリフレッシュしてください — 古いrecentBlockhashはすぐに期限切れになります。
キーとアクセス
RPCまたはAPI呼び出しがキーのロック後に拒否される（401 / 403）
ドメイン制限されたキーに、呼び出し元のオリジンが含まれていません。RPCアクセス制御の下で、使用するすべてのオリジン — 本番、ステージング、プレビューデプロイ、開発用のlocalhost — を追加します — キーのセキュリティ確保を参照。
まだ解決しない場合
Discord
コミュニティとHeliusチームに質問してください。
サポート
Heliusサポートに連絡してください。