Claves API de TON: ¿Cómo se obtiene una y cuándo la necesitas?

Si buscaste una clave API de TON, probablemente ya tengas una billetera, un script o un servicio backend que necesita comunicarse con The Open Network y te hayas topado con un obstáculo: el endpoint público funciona para una prueba rápida, pero necesitas algo que puedas autenticar, monitorear y escalar. Esta página responde primero a las preguntas prácticas —qué es la clave, cómo obtener una y cómo usarla— y luego te ayuda a decidir si un endpoint compartido con clave es suficiente o si tu carga de trabajo necesita un nodo TON dedicado.

Respuesta rápida: qué es una clave API de TON y qué no es

Una clave API de TON es una credencial emitida por un proveedor de RPC o API. La adjuntas a tus solicitudes y el proveedor la usa para identificar tu proyecto, aplicar los límites de velocidad y cuotas vinculados a tu plan, y darte visibilidad de uso. No es una clave de billetera, no firma transacciones y no te da acceso especial a la blockchain de TON en sí. Solo controla cómo llegas a la infraestructura del nodo que atiende tus solicitudes.

Esa distinción importa porque TON tiene dos estilos de acceso comunes:

• JSON-RPC sobre HTTP, donde envías llamadas a métodos como runGetMethod o sendBoc a un endpoint y te autenticas con un encabezado o parámetro de consulta.
• Wrappers de HTTP API, donde un proveedor expone rutas de estilo REST de nivel superior (estado de cuenta, historial de transacciones, metadatos de jetton) sobre el nodo sin procesar.

Ambos estilos pueden requerir una clave. Ninguno de los dos estilos te permite omitir el consenso o leer datos que el nodo no tiene.

Decide primero: ¿endpoint compartido con clave o nodo dedicado?

Antes de registrarte en cualquier cosa, adapta tu carga de trabajo al modelo de acceso. La mayoría de los equipos compran de más al principio y de menos en el lanzamiento, así que usa esto como un filtro rápido.

Si estás en la mitad superior de esa tabla, un endpoint compartido con clave es la opción pragmática. Si estás en la mitad inferior, lee la sección de nodo dedicado antes de comprometerte con un plan.

Cómo obtener una clave API de TON

El flujo exacto depende del proveedor, pero la forma es consistente:

1. Crea una cuenta con el proveedor de RPC que quieras usar.
2. Crea un proyecto o aplicación dentro del panel. Esta es la unidad que posee la clave y los contadores de uso.
3. Genera una clave API para ese proyecto. Algunos proveedores te dan una clave de inmediato; otros requieren que elijas un plan primero.
4. Elige tu red: TON mainnet o TON testnet. Mantenlas como claves separadas para que un script de testnet nunca pueda tocar datos de mainnet.
5. Restringe la clave si el proveedor lo admite: orígenes permitidos, listas de IP permitidas o ámbitos por método.
6. Guarda la clave en un gestor de secretos, no en tu repositorio. Trátala como cualquier otra credencial.

OnFinality emite claves a través del mismo modelo de proyecto. Puedes revisar la página de la red TON RPC para detalles del endpoint y la página de TON Testnet para acceso a testnet, luego consulta Precios de RPC para ver qué plan se ajusta a tu volumen de solicitudes esperado.

Enviar tu primera solicitud autenticada a TON

La superficie JSON-RPC de TON no es idéntica a las cadenas EVM, así que no asumas que los métodos eth_* funcionarán. Una llamada autenticada típica se ve así:

curl -s https://ton-mainnet.example-rpc-provider.com/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TON_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "runGetMethod",
    "params": {
      "address": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
      "method": "seqno",
      "stack": []
    }
  }'

Reemplaza el host con el endpoint que te dé tu proveedor. Las partes importantes son el encabezado X-API-Key (algunos proveedores usan un encabezado Authorization: Bearer o un parámetro de consulta ?api_key= en su lugar) y el sobre JSON-RPC. Si estás usando un wrapper de HTTP API en lugar de JSON-RPC sin procesar, la misma clave va en el mismo encabezado, pero la ruta y la forma del cuerpo serán diferentes.

Un cliente JavaScript mínimo usando fetch se ve así:

const res = await fetch(process.env.TON_RPC_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TON_API_KEY
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getMasterchainInfo",
    params: {}
  })
});

const data = await res.json();
if (data.error) throw new Error(JSON.stringify(data.error));
console.log(data.result);

Mantén la URL y la clave en variables de entorno. Rotar una clave filtrada debería ser un cambio de configuración, no un cambio de código.

Configuración de endpoint y red de TON de un vistazo

Siempre confirma la lista actual de métodos y el soporte de transporte con la documentación del proveedor, porque las herramientas de TON evolucionan y los wrappers agregan o renombran rutas con el tiempo. La página de la red TON de OnFinality es la referencia canónica de lo que se admite de nuestro lado.

Modos de fallo comunes y cómo depurarlos

La mayoría de los informes de "mi clave API de TON no funciona" caen en un pequeño número de categorías. Revísalos en orden.

Un hábito útil es registrar el código de estado HTTP y el objeto error de JSON-RPC por separado. Los proveedores a menudo devuelven un error JSON-RPC válido con un estado HTTP distinto de 200, y confundir ambos hace que la depuración sea más lenta.

Cuándo un endpoint compartido con clave deja de ser suficiente

Un endpoint compartido con clave es la opción predeterminada correcta para la mayoría de los equipos. Se convierte en la herramienta incorrecta cuando se cumple una de estas condiciones:

• Estás escaneando el historial. Rellenar transacciones o construir un índice implica lecturas largas y costosas que compiten con otros inquilinos.
• Necesitas latencia consistente. Los pools compartidos están bien en promedio pero son más ruidosos en la cola, lo que importa para trading o UX en tiempo real.
• Necesitas aislamiento. Las cargas de trabajo reguladas o cualquier cosa con límites estrictos de datos generalmente no pueden compartir infraestructura.
• Estás alcanzando límites repetidamente. Si estás ajustando el retroceso más de lo que estás lanzando funciones, el plan es el problema.

En ese punto, un nodo TON dedicado te da un nodo que atiende solo tu tráfico. Mantienes el mismo modelo de clave API, pero la capacidad detrás de él es tuya. OnFinality ejecuta nodos dedicados en muchas redes, y puedes comparar las ventajas y desventajas en Cómo elegir un proveedor de RPC antes de comprometerte.

Lista de verificación operativa antes de salir a producción

• Las claves se almacenan en un gestor de secretos, no en código ni en registros de CI.
• Las claves de mainnet y testnet son separadas y tienen nombres claros.
• Tienes una política de reintentos con retroceso exponencial y jitter para 429 y 5xx.
• Registras los IDs de solicitud para poder correlacionar fallos con el soporte del proveedor.
• Tienes un endpoint de respaldo o un plan de conmutación por error documentado.
• Monitoreas la tasa de errores y la latencia p95, no solo el tiempo de actividad.
• Conoces tu volumen mensual de solicitudes y qué nivel de Precios de RPC lo cubre.
• Has revisado la lista completa de redes RPC compatibles si planeas expandirte.

Puntos clave

• Una clave API de TON autentica tus solicitudes a un proveedor; no firma transacciones ni cambia lo que expone la blockchain.
• Los endpoints públicos están bien para prototipos; los endpoints con clave son el valor predeterminado normal en producción.
• TON usa su propia superficie de métodos JSON-RPC, así que no asumas que los nombres de métodos de EVM funcionarán.
• Mantén las claves de mainnet y testnet separadas, y guárdalas en un gestor de secretos.
• La mayoría de los errores de clave son errores de encabezado, desajustes de red o límites de velocidad; revísalos primero.
• Pasa a un nodo TON dedicado cuando necesites aislamiento, rendimiento predecible o lecturas históricas pesadas.

Preguntas frecuentes

¿Una clave API de TON es lo mismo que una clave privada de billetera?

No. Una clave privada de billetera firma transacciones y controla fondos. Una clave API de TON solo autentica tus solicitudes a un proveedor de RPC. Nunca las trates como intercambiables y nunca pegues una clave de billetera en una configuración de RPC.

¿Puedo usar una clave API de TON gratis?

Muchos proveedores ofrecen un nivel gratuito o de prueba con una clave, generalmente con límites de velocidad más bajos. Es una forma razonable de prototipar. Consulta los términos del plan actual del proveedor, incluidos los precios de RPC de OnFinality, antes de construir una dependencia de producción sobre un nivel gratuito.

¿Qué encabezado debo usar para una clave API de TON?

Depende del proveedor. Las opciones comunes son X-API-Key, Authorization: Bearer <key> o un parámetro de consulta. Usa lo que documente el proveedor y evita poner claves en URL que queden registradas por proxies.

¿Necesito una clave separada para TON testnet?

Sí, en la práctica. Testnet y mainnet son redes diferentes con estado diferente. Las claves separadas evitan que un script de prueba lea o escriba accidentalmente datos de mainnet.

¿Cómo sé si necesito un nodo TON dedicado en su lugar?

Si consistentemente alcanzas los límites de velocidad, necesitas aislamiento o ejecutas consultas históricas pesadas, un nodo dedicado suele ser la mejor opción. Comienza con la descripción general del nodo dedicado y compárala con tu carga de trabajo.

¿Dónde puedo encontrar los detalles actuales del endpoint de TON?

Usa la página de red del proveedor como fuente de verdad. Para OnFinality, comienza con la página de la red TON y la página de TON Testnet.