helius-wallet-kit, e como corrigi-los.
Configuração
O modal da carteira está sem estilo ou parece quebrado
A folha de estilos do SDK não está carregada. Importe-a uma vez no layout raiz:app/layout.tsx
Os valores do hook nunca mudam (presos em loading)
useHeliusWallet() só funciona dentro de HeliusWalletProvider, e o provedor deve ser um componente cliente. Certifique-se de que o provedor envolve sua árvore de componentes a partir de um arquivo com "use client" no topo — veja Configuração.
[HeliusWalletKit] WaaS bootstrap failed (…) no console
O provedor não conseguiu resolver seu projeto a partir da chave da API. Verifique se:
NEXT_PUBLIC_HELIUS_API_KEYestá definida e válida.- O projeto está em um plano pago com carteiras incorporadas habilitadas.
- Se você restringiu a chave por domínio, sua origem atual está na lista permitida — veja Protegendo sua chave.
Login
Usuários chegam a uma tela de “atualização” em vez da carteira
Carteiras incorporadas exigem um plano Helius pago. Quando o plano resolvido é gratuito, o provedor exibe um aviso de atualização (e o backend também rejeita a solicitação no servidor). Atualize o projeto no dashboard.Os métodos de login errados aparecem (por exemplo, Google aparece, carteira externa está ausente)
Os métodos de login vêm da configuração do seu projeto no dashboard em WaaS → Configuração. Se um projeto não tiver configurações, o modal usa um padrão para toda a organização. Defina os métodos que deseja no dashboard ou passeauthMethods para o provedor config para substituir por ambiente — veja Configurar métodos de login.
O login por chave de acesso falha ou indica que a chave não está registrada
Chaves de acesso estão vinculadas ao domínio e autenticador em que foram criadas (uma restrição do WebAuthn, não do Helius). Uma chave de acesso ou chave de segurança registrada em outro site ou dispositivo não autenticará seu aplicativo. Crie a chave de acesso no domínio que você está testando — note que uma chave criada emlocalhost está vinculada a localhost e não será transferida para seu domínio implantado.
Assinatura e envio
No wallet available ao assinar
Você chamou um método de assinatura antes que a carteira incorporada terminasse de provisionar. Garanta a assinatura em ambos status === "authenticated" e um address não nulo:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Você está executando no modo direto (Secure RPC), e esta chamada — um pedido de envio ou taxa de prioridade — precisa do manipulador de rota do servidor. Monte-o em /api/helius/[...path] e defina HELIUS_API_KEY:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
O histórico de transações está disponível apenas através do manipulador de rota. Adicione-o conforme mostrado acima.
getPriorityFeeEstimate is not available
Devnet não suporta estimativas de taxa de prioridade — é um recurso da mainnet. Pule a busca no devnet; envios ainda funcionam sem uma taxa de prioridade.
Uma transação não é concluída na mainnet
Sem o manipulador de rota, os envios usam RPC padrão em vez do Helius Sender, então eles não aproveitam o pouso otimizado do Sender. Monte o manipulador de rota para melhor pouso na mainnet. Se um envio falhar completamente, atualize o blockhash — umrecentBlockhash expirado expira rapidamente.
Chaves e acesso
Chamadas de RPC ou API são rejeitadas (401 / 403) após bloquear sua chave
Sua chave restrita por domínio não inclui a origem da qual você está chamando. Adicione todas as origens que você usa — produção, staging, implantações de pré-visualização elocalhost para desenvolvimento — sob Controle de Acesso RPC. Veja Protegendo sua chave.
Ainda com problemas?
Discord
Pergunte à comunidade e à equipe Helius.
Suporte
Entre em contato com o suporte Helius.