helius-wallet-kit y cómo solucionarlos.
Configuración
El modal de la billetera no tiene estilos o se ve mal
La hoja de estilos del SDK no está cargada. Impórtala una vez en tu layout raíz:app/layout.tsx
Los valores del hook nunca cambian (se quedan en loading)
useHeliusWallet() solo funciona dentro de HeliusWalletProvider, y el proveedor debe ser un componente de cliente. Asegúrate de que el proveedor envuelva tu árbol de componentes desde un archivo que tenga "use client" al principio. Consulta Configuración.
[HeliusWalletKit] WaaS bootstrap failed (…) en la consola
El proveedor no pudo identificar tu proyecto a partir de la clave de API. Comprueba lo siguiente:
NEXT_PUBLIC_HELIUS_API_KEYestá configurada y es válida.- El proyecto tiene un plan de pago con las billeteras integradas habilitadas.
- Si restringiste la clave por dominio, tu origen actual está en la lista de permitidos. Consulta Protege tu clave.
Inicio de sesión
Los usuarios llegan a una pantalla de “actualización” en lugar de a la billetera
Las billeteras integradas requieren un plan de pago de Helius. Cuando el plan identificado es gratuito, el proveedor muestra un aviso para actualizarlo (y el backend también rechaza la solicitud del lado del servidor). Actualiza el proyecto en el panel de control.Aparecen métodos de inicio de sesión incorrectos (p. ej., aparece Google o falta la billetera externa)
Los métodos de inicio de sesión provienen de la configuración de tu proyecto en el panel de control, en WaaS → Configuration. Si un proyecto no tiene ninguno configurado, el modal usa de forma predeterminada la configuración general de la organización. Configura los métodos que quieras en el panel de control o pasaauthMethods al proveedor config para sobrescribirlos según el entorno. Consulta Configura los métodos de inicio de sesión.
El inicio de sesión con passkey falla o indica que la passkey no está registrada
Las passkeys están vinculadas al dominio y al autenticador donde se crearon (es una restricción de WebAuthn, no de Helius). Una passkey o clave de seguridad registrada en otro sitio o dispositivo no podrá autenticar tu aplicación. Crea la passkey en el dominio que estás probando. Ten en cuenta que una passkey creada enlocalhost está vinculada a localhost y no se transferirá a tu dominio desplegado.
Firma y envío
No wallet available al firmar
Llamaste a un método de firma antes de que la billetera integrada terminara de aprovisionarse. Permite la firma solo cuando status === "authenticated" se cumpla y address no sea nulo:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Esta solicitud de envío o comisión de prioridad no tenía un destino: el proveedor no identificó ninguna URL de Secure RPC durante el inicio (los planes de pago normalmente reciben una de forma automática) y no hay ningún controlador de ruta del servidor montado. Monta el controlador de ruta en /api/helius/[...path] y configura HELIUS_API_KEY:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
El historial de transacciones solo está disponible mediante el controlador de ruta. Agrégalo como se muestra arriba.
getPriorityFeeEstimate is not available
Devnet no admite estimaciones de comisiones de prioridad; es una función de mainnet. Omite la consulta en devnet. Los envíos siguen funcionando sin una comisión de prioridad.
Una transacción no se confirma en mainnet
Sin el controlador de ruta, los envíos usan RPC estándar en lugar de Helius Sender, por lo que no aprovechan la inclusión optimizada de Sender. Monta el controlador de ruta para obtener la mejor inclusión posible en mainnet. Si un envío falla por completo, actualiza el blockhash: unrecentBlockhash obsoleto caduca rápidamente.
Claves y acceso
Las llamadas RPC o API se rechazan (401 / 403) después de restringir tu clave
Tu clave restringida por dominio no incluye el origen desde el que haces la llamada. Agrega todos los orígenes que uses —producción, staging, despliegues de vista previa elocalhost para desarrollo— en RPC Access Control. Consulta Protege tu clave.
¿Aún tienes problemas?
Discord
Pregunta a la comunidad y al equipo de Helius.
Support
Contacta al equipo de soporte de Helius.