Skip to main content
El SDK wallet-kit se ejecuta en el navegador, por lo que tu apiKey de Helius está presente en el cliente: el proveedor la envía al bootstrap de la billetera (/waas/config) cuando se carga tu aplicación. Esto es normal en un SDK del lado del cliente. Esta página explica exactamente qué puede y qué no puede hacer esa clave, y cómo protegerla.

​
Qué puede —y qué no puede— hacer la clave

Comienza aquí, porque es la parte en la que es fácil equivocarse: la clave de API de Helius es una credencial de RPC/créditos, no una clave de billetera. Una clave filtrada no puede:
  • firmar transacciones ni mensajes,
  • mover fondos ni acceder a ellos, ni
  • interactuar con la billetera integrada de ningún usuario.
La firma de la billetera se autoriza mediante la clave de acceso o sesión del propio usuario final, y las claves privadas permanecen en los enclaves seguros de Turnkey, nunca en tu aplicación, tu servidor ni nada a lo que pueda acceder la clave de API. Exponer la clave no expone las billeteras. Lo que una clave filtrada sí puede hacer es consumir tus créditos de Helius (cuota de RPC). Ese es todo el alcance del daño: un problema de facturación, no de custodia. Las capas siguientes lo limitan y lo eliminan.
La exposición tampoco permite evadir la facturación. Las firmas de WaaS se contabilizan en el momento en que firma la billetera integrada, no en la capa de la clave de API. Una clave filtrada no puede generar firmas gratis ni facturar firmas desde el sitio de otra persona. La medición no depende de que la clave permanezca secreta.

​
Protégela

Estas capas van desde la que requiere menos esfuerzo hasta el límite de seguridad más sólido. La primera es el nivel básico obligatorio. Combina las demás según tu tolerancia al riesgo.

​
1. Restringe tu clave por dominio (obligatorio)

Limita la clave a los orígenes donde se ejecuta tu aplicación. Así, una clave extraída de tu paquete no servirá en ningún otro lugar.
1

Open RPC Access Control

En el panel, ve a tu clave en la sección RPCs y abre Access Control.
2

Add your domains to Allowed Domains

Agrega todos los orígenes desde los que se sirve tu aplicación: producción, staging y vista previa:
3

Use a separate key per environment

Usa una clave distinta para los entornos local, de staging y de producción. Así podrás rotar una sin interrumpir los demás.
Las listas de dominios permitidos detienen el uso indebido desde navegadores, no los scripts maliciosos. La comprobación lee el encabezado Origin/Referer de la solicitud. Un navegador lo establece correctamente, pero un cliente que no sea un navegador (por ejemplo, curl -H "Origin: yourdapp.com") puede falsificarlo. Esto se aplica a todas las claves de API del lado del cliente, no solo a Helius. La restricción por dominio detiene de forma confiable el caso más común: que tu clave aparezca en el sitio de otra persona. Sin embargo, para establecer un límite que no pueda falsificarse, usa una clave del lado del servidor restringida a tus IP/CIDR (paso 4).

​
2. URL de RPC seguras sin clave (automático)

El tráfico RPC no incluye tu clave. Durante el bootstrap, el SDK obtiene la URL de RPC segura sin clave de tu proyecto y la usa automáticamente para las llamadas connection. No necesitas configurar nada. Como estas URL no contienen ninguna clave, no hay nada que extraer de una solicitud RPC. Además, están limitadas a 5 RPS por IP, por lo que su protección no depende de las comprobaciones de origen. (Disponibles en los planes de pago. Cuando un proyecto no tiene una URL de RPC segura, RPC recurre al controlador de rutas del mismo origen descrito en el paso 3).

​
3. Mueve la clave al servidor, sin administrar servidores

Para mantener la clave fuera del navegador en las llamadas RPC, de envío y de historial de transacciones, canalízalas a través de tu propio endpoint, que inyecta la clave desde un secreto del lado del servidor. Así también puedes habilitar el envío optimizado con Sender y el historial de transacciones. Ambas opciones son 100 % serverless: no necesitas administrar ningún servidor.
  • Controlador de rutas de Next.js: se implementa como una función serverless (Vercel, Netlify o Cloudflare). Lee HELIUS_API_KEY desde el entorno del servidor.
    app/api/helius/[...path]/route.ts
  • Proxy de Cloudflare Worker: la opción totalmente serverless más sencilla. La clave permanece en un secreto de Worker y nunca llega al navegador.

    Helius RPC Proxy

    Proxy RPC de código abierto que puedes implementar en Cloudflare con un clic.

​
4. Agrega un límite de IP/CIDR que no pueda falsificarse

Para establecer un límite que un atacante no pueda falsificar, restringe una clave del lado del servidor a las direcciones IP o los rangos CIDR de tu backend. A diferencia de un encabezado Origin, la IP de origen no puede falsificarse en una conexión normal. Por lo tanto, cualquier curl que no provenga de tus servidores se rechazará de inmediato. Esto solo se aplica a una clave del lado del servidor. No puedes restringir por IP la clave del navegador porque tus usuarios se conectan desde IP impredecibles. El patrón más claro usa dos claves:
Las funciones serverless tienen IP de salida dinámicas, por lo que fijar un CIDR requiere una salida estable: un Cloudflare Worker con una IP de salida dedicada, Vercel Secure Compute o un NAT con IP fija delante. Sin una de estas opciones, aún obtienes la ventaja principal: la clave permanece en el servidor y nunca llega al navegador. Simplemente no agregas además el límite por IP.
Consulta Protege tus claves para ver la referencia completa de las reglas de control de acceso.

​
Comparación de las capas

Independientemente de las capas que elijas, nada de esto corresponde a las claves de billetera de tus usuarios. Esas claves nunca intervienen.

​
El bootstrap de la billetera

En la configuración de producción con controlador de rutas, el bootstrap de la billetera (/waas/config) también pasa por tu controlador de rutas con la clave del lado del servidor. Por lo tanto, tampoco se envía ninguna clave de Helius al navegador. En la configuración de prototipado, el navegador envía la clave para el bootstrap. Restringe esa clave por dominio (paso 1). En ambos casos, es la clave limitada a RPC: no puede interactuar con billeteras ni fondos.

​
Lista de verificación

Antes de publicar:
  • La clave del cliente está restringida por dominio a tus orígenes exactos
  • Usas claves separadas para los entornos local, de staging y de producción
  • La clave se lee desde una variable de entorno y nunca está escrita directamente en el código
  • (Opcional) Las llamadas RPC, de envío y de historial pasan por el controlador de rutas serverless o Cloudflare Worker
  • (Opcional) La clave del lado del servidor está restringida a tus IP/CIDR para establecer un límite que no pueda falsificarse

​
Próximos pasos

Protect your keys

Referencia completa del control de acceso: dominios, IP, CIDR y proxies.

Configuration

Configuración del proveedor y métodos de inicio de sesión en el panel.