TON liteserver «not ready»: por qué ocurre y cómo quitarlo

Liteserver not ready: enviaste una petición de lo más simple y te llegó un «not ready»

Estás escribiendo un agente que tiene que consultar el saldo de una wallet o llamar a un get-method de un contrato. El código está bien, la dirección está bien, la config del liteserver viene del global-config.json oficial. Pero en vez de respuesta te llevas una y otra vez un not ready, o directamente nada: la conexión se queda colgada y muere por timeout de ADNL. Y encima no siempre se reproduce: por la mañana funciona, bajo carga no. ¿Te suena? No es un bug en tu código ni «TON está caído». Es el comportamiento predecible de los liteservers públicos de la config global. Vamos a ver por qué aparece el TON liteserver not ready, qué ayuda de verdad en el lado del cliente y qué no.

Qué significa «not ready» y el timeout ADNL en un liteserver de TON

not ready es la respuesta literal del liteserver: «todavía no estoy sincronizado, no puedo contestarte». En TON hay dos niveles de blockchain: la masterchain y la basechain (workchain 0), que se divide en shardchains o shards. La masterchain es como el índice de un libro, y los shards son los capítulos con las transacciones y el estado de las cuentas. A menudo el nodo recibe la cabeza de la masterchain antes de alcanzar los bloques de shard correspondientes. En ese momento la masterchain va por delante de la basechain, y el estado de la cuenta vive en el último bloque de shard, que todavía no se puede verificar. El nodo responde honestamente not ready en vez de devolverte datos obsoletos o incompletos.

El timeout de ADNL es el síntoma vecino de la misma enfermedad. ADNL es el protocolo de transporte nativo de TON, por el que el liteserver habla con el cliente (ahí no hay HTTP de ningún tipo). Cuando el nodo está sobrecargado, simplemente no responde a la petición ADNL dentro de la ventana asignada, y el cliente se cae por timeout sin llegar siquiera a la lógica de negocio.

Aquí es importante no mezclar capas. not ready y el timeout ADNL viven en el nivel del protocolo ADNL nativo del liteserver. No es lo mismo que el HTTP 429 Too Many Requests que devuelven las pasarelas HTTP como toncenter y tonapi.io cuando superas el límite. Capas distintas, códigos distintos, causas distintas. Si lo tuyo es precisamente el 429, esa es otra historia: análisis de cómo arreglar el 429 de toncenter. Y el meme del «error 228» de los chats de TON es una broma de la comunidad, no un código real: ningún liteserver responde eso.

Por qué los liteservers públicos de la config global se caen bajo carga

La raíz del problema es prosaica. Los liteservers de ton.org/global-config.json son compartidos y limitados. Es un recurso público al que acceden a la vez miles de desarrolladores, bots, indexadores y agentes de todo el mundo. Un recurso así tiene tres limitaciones sistémicas:

• Carga compartida. Compartes el pool con todo el ecosistema. En los picos de carga, el nodo o bien no consigue alcanzar la cabeza de la red (de ahí el not ready) o bien simplemente no responde a tiempo (timeout ADNL).
• Sin historial profundo. Los nodos públicos no guardan un archivo profundo. Si necesitas una transacción antigua por el par lt/hash, puede que ya no esté ahí. Sobre cómo trabajar con el historial tenemos un artículo aparte sobre lt y hash.
• Cero garantías. Es un recurso «tal cual». No tienes prioridad y nadie te garantiza throughput alguno: hoy tienes suerte, mañana no.

Es decir, not ready no es un accidente que se pueda «esperar a que pase», sino el comportamiento natural de un recurso compartido bajo carga. Y ningún código tuyo va a obligar a un nodo ajeno y sobrecargado a sincronizarse más rápido.

Fixes del lado del cliente: reintentos, rotación de endpoints y timeouts

Antes de tocar la infraestructura, exprime al máximo el cliente. Estas técnicas funcionan de verdad, pero tienen un techo: los nodos siguen siendo compartidos.

1. Reintentos con backoff exponencial

not ready suele ser transitorio: a los 200–800 ms el mismo liteserver ya ha aplicado el bloque de shard que necesitas. Un simple reintento con espera creciente elimina una parte notable de los errores.

async function withRetry<T>(fn: () => Promise<T>, tries = 4): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < tries; i++) {
    try {
      return await fn();
    } catch (e) {
      lastErr = e;
      // reintentamos 'not ready' y timeouts ADNL, pero no errores de negocio
      await new Promise((r) => setTimeout(r, 200 * 2 ** i));
    }
  }
  throw lastErr;
}

2. Rotación de endpoints

Mantén en el pool varios liteservers de la config y cambia al siguiente si el actual devuelve not ready o se va por timeout. Si un nodo va rezagado, el de al lado puede ir ya al día.

3. Timeout más alto

El timeout ADNL por defecto a veces es demasiado estricto para un nodo público sobrecargado. Un pequeño margen (unos segundos) reduce los cortes falsos. Pero si subes el timeout hasta el infinito, solo acumulas peticiones colgadas; eso no es una cura, es anestesia.

Otro truco útil: un healthcheck ligero antes de la petición real. Lo ideal es get_masterchain_info (la cabeza de la masterchain): esa operación es la primera en devolver un seqno fresco cuando el nodo ha alcanzado la cabeza de la red, y devuelve not ready solo cuando el nodo ni siquiera ha alcanzado la propia cabeza de la masterchain. Si devuelve un seqno fresco, el nodo está en forma y puedes hacer get_account_state, get_balance, run_get_method.

Conclusión honesta: reintentos + rotación + timeouts bajan la frecuencia de errores, pero no eliminan la causa. Los nodos públicos están sobrecargados by design: solo estás llamando con más educación a una puerta detrás de la cual sigue la misma cola. Otros enfoques de acceso a TON están recopilados en el repaso de alternativas a toncenter para 2026.

La solución sin nodo propio: clave hosted de TONNode en nuestro liteserver

El not ready se elimina de raíz de una sola manera: dejando de ir a los nodos compartidos. Montar y mantener tu propio nodo de TON es caro y tedioso: sincronización, disco, actualizaciones, monitorización. La opción intermedia es no ir al pool compartido, sino conseguir, mediante una clave, throughput garantizado y acceso prioritario.

TONNode es un servidor MCP hosted para TON. MCP (Model Context Protocol) es el estándar con el que los agentes de IA (Claude, Cursor, ChatGPT/Codex, cualquier cliente MCP) llaman a herramientas. En vez de que tu código parsee la config global y baile alrededor del not ready, el agente llama a una herramienta ya lista y, detrás de ella, está el endpoint hosted https://mcp.tonnode.io/mcp con tu clave Bearer. Es throughput garantizado en lugar de la cola compartida.

El paquete @tonnode/mcp es open source (MIT, está en npm y en GitHub tonnode/mcp) y funciona por el protocolo ADNL nativo de TON, sin capas HTTP intermedias. Es decir, no cambias el transporte por una pasarela HTTP lenta: te quedas en el mismo ADNL honesto, pero con acceso prioritario asociado a tu clave.

Para diagnóstico y lectura del día a día te servirán:

• get_masterchain_info — la cabeza de la masterchain, el healthcheck natural.
• get_account_state — estado, flags y última transacción de la cuenta.
• get_balance — saldo en GRAM.
• run_get_method — cualquier get-method read-only de un contrato.

Si estás dando tus primeros pasos con MCP en TON, arranca por la guía de MCP para TON.

Cómo conectarlo: npx en local o endpoint hosted con clave

Gratis en local

El set completo de herramientas de lectura funciona en local desde el primer momento, con la config pública, sin tarjeta y sin clave:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Es genial para desarrollo y experimentos locales. Pero ten en cuenta: el npx local por debajo sigue yendo a los mismos liteservers compartidos, así que no te salva del not ready bajo carga. Lo que sí te ahorra es el lío de dependencias, y te da una interfaz única de herramientas.

Hosted con clave

Para dejar atrás los nodos compartidos, cambia el transporte a HTTP-MCP con tu clave Bearer (la llamada a las herramientas en sí va a nuestro nodo por ADNL):

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

Cómo se ve trabajando con el agente

Una vez conectado, al agente le basta con un prompt normal; las herramientas las elige él solo:

Primero get_masterchain_info como healthcheck. Después get_account_state para EQC… — muéstrame el estado y la última transacción. Luego get_balance de la misma dirección.

Por debajo es una cadena: get_masterchain_info (el nodo está vivo y ha alcanzado la cabeza) → get_account_state (estado, flags, última transacción) → get_balance (saldo en GRAM). Sin reintentos dando vueltas a la cola de otros: la petición va directa a throughput garantizado. Por cierto, GRAM es el Toncoin renombrado (el cambio de nombre fue en junio de 2026); la red se sigue llamando TON.

La clave gratuita Hobby (60 peticiones/min) la obtienes nada más iniciar sesión, sin tarjeta. Y a medida que crezcas: Pro — $29/mes, 300 peticiones/min; Scale — $199/mes, 1200 peticiones/min. Detalle importante: en todos los planes están disponibles las 16 herramientas de TONNode — pagas solo por el throughput, no por la funcionalidad.

Liteserver dedicado propio: bajo pedido, no self-serve

A veces el plan hosted se queda corto y hace falta un liteserver dedicado (single-tenant): solo para tu tráfico, sin vecinos de ningún tipo. Esa opción existe, pero seamos honestos: no es autoservicio. No hay un botón «activar single-tenant» en el dashboard — se gestiona a mano: escríbenos y hablamos de carga y configuración.

Y una advertencia honesta más sobre la profundidad del historial. El nodo de archivo de TONNode se está sincronizando ahora mismo y todavía no atiende peticiones. La «profundidad de archivo» es un punto del roadmap, no una función terminada. Si hoy mismo necesitas historial profundo desde el inicio de la red, planifícalo aparte. Qué está listo y qué está en camino: en el roadmap.

En resumen

• not ready = el nodo no está sincronizado: la masterchain va por delante del shard, y el estado de la cuenta en el último bloque de shard todavía no se puede verificar.
• Los liteservers públicos de la config global son compartidos y limitados: not ready, timeouts ADNL, sin historial profundo. No lo confundas con el HTTP 429 de toncenter/tonapi — es otra capa.
• Los fixes de cliente (reintentos con backoff, rotación de endpoints, timeouts) reducen la frecuencia de errores, pero no eliminan la causa.
• get_masterchain_info es tu healthcheck: se pone en rojo con not ready solo cuando el nodo ni siquiera ha alcanzado la cabeza de la masterchain.
• La cura real es salir del recurso compartido hacia throughput garantizado.

Consigue la clave hosted gratuita Hobby y deja de comerte «not ready» en los nodos compartidos → tonnode.io/dashboard?plan=hobby

Y a medida que crezca tu carga: precios y roadmap.