TON liteserver « not ready » : pourquoi et comment le corriger

Liteserver not ready : vous envoyez une requête toute simple — et vous recevez « not ready »

Vous écrivez un agent qui doit vérifier le solde d'un wallet ou appeler un get-method de contrat. Le code est bon, l'adresse est bonne, la config du liteserver vient tout droit du global-config.json officiel. Mais au lieu d'une réponse, vous récoltez régulièrement soit un not ready, soit rien du tout — la connexion reste suspendue puis meurt en timeout ADNL. Et ce n'est même pas systématique : le matin ça marche, sous charge non. Ça vous parle ? Ce n'est pas un bug dans votre code, et ce n'est pas non plus « TON qui est down ». C'est le comportement parfaitement prévisible des liteservers publics de la config globale. Voyons pourquoi le TON liteserver not ready apparaît, ce qui aide vraiment côté client — et ce qui n'aide pas.

Ce que signifient « not ready » et le timeout ADNL sur un liteserver TON

not ready, c'est une réponse directe du liteserver : « je ne suis pas encore synchronisé, je ne peux pas te répondre ». TON a deux niveaux de blockchain : la masterchain et la basechain (workchain 0), elle-même découpée en shardchains (shards). La masterchain, c'est le sommaire du livre ; les shards, ce sont les chapitres eux-mêmes, avec les transactions et l'état des comptes. Une node reçoit souvent la tête de la masterchain avant d'avoir rattrapé les blocs de shard correspondants. À cet instant, la masterchain a de l'avance sur la basechain, alors que l'état du compte, lui, vit dans le dernier bloc de shard — impossible donc de le vérifier pour le moment. La node répond honnêtement not ready plutôt que de vous servir des données périmées ou incomplètes.

Le timeout ADNL est le symptôme voisin de la même maladie. ADNL est le protocole de transport natif de TON, celui par lequel le liteserver dialogue avec le client (aucun HTTP là-dedans). Quand la node est surchargée, elle ne répond tout simplement pas à la requête ADNL dans la fenêtre impartie, et le client abandonne sur timeout, sans même avoir atteint votre logique métier.

Attention à ne pas mélanger les couches. not ready et le timeout ADNL vivent au niveau du protocole natif ADNL du liteserver. Ce n'est pas la même chose que le 429 Too Many Requests HTTP que renvoient les passerelles HTTP comme toncenter et tonapi.io en cas de dépassement de limite. Couches différentes, codes différents, causes différentes. Si c'est bien au 429 que vous vous heurtez, c'est une autre histoire : le fix du 429 chez toncenter. Quant au mème de « l'erreur 228 » qui circule dans les chats TON, c'est une blague de la communauté, pas un vrai code ; un liteserver ne répond jamais ça.

Pourquoi les liteservers publics de la config globale lâchent sous charge

La racine du problème est prosaïque. Les liteservers de ton.org/global-config.json sont partagés et limités. C'est une ressource publique sur laquelle tapent simultanément des milliers de développeurs, de bots, d'indexeurs et d'agents du monde entier. Une ressource pareille souffre de trois limites systémiques :

• Charge partagée. Vous partagez le pool avec tout l'écosystème. En pic, soit la node n'arrive plus à rattraper la tête du réseau (d'où le not ready), soit elle ne répond simplement plus à temps (timeout ADNL).
• Pas d'historique profond. Les nodes publiques ne conservent pas d'archive profonde. Si vous avez besoin d'une vieille transaction via son couple lt/hash, elle peut déjà ne plus s'y trouver — sur le travail avec l'historique, il existe un article dédié à lt et hash.
• Aucune garantie. C'est une ressource « en l'état ». Vous n'avez aucune priorité et personne ne vous promet de débit : aujourd'hui ça passe, demain non.

Autrement dit, not ready n'est pas un accident qu'on pourrait « attendre patiemment », mais le comportement attendu d'une ressource partagée sous charge. Et aucun code de votre côté ne fera se synchroniser plus vite la node surchargée de quelqu'un d'autre.

Correctifs côté client : retries, rotation d'endpoints et timeouts

Avant de toucher à l'infrastructure, tirez le maximum du client. Ces techniques marchent vraiment, mais elles ont un plafond — les nodes restent partagées.

1. Retries avec backoff exponentiel

not ready est souvent transitoire : 200 à 800 ms plus tard, le même liteserver a déjà appliqué le bloc de shard qui manquait. Une simple relance avec délai croissant élimine une part notable des erreurs.

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;
      // on retente sur 'not ready' et les timeouts ADNL, mais pas sur les erreurs métier
      await new Promise((r) => setTimeout(r, 200 * 2 ** i));
    }
  }
  throw lastErr;
}

2. Rotation des endpoints

Gardez plusieurs liteservers de la config dans un pool et basculez sur le suivant dès que celui en cours renvoie not ready ou part en timeout. Une node est à la traîne — sa voisine a peut-être déjà rattrapé son retard.

3. Un timeout plus généreux

Le timeout ADNL par défaut est parfois trop sévère pour une node publique surchargée. Un peu de marge (quelques secondes) réduit les coupures intempestives. Mais pousser le timeout à l'infini revient simplement à accumuler des requêtes suspendues ; ce n'est pas un traitement, c'est une anesthésie.

Autre technique utile : un healthcheck léger avant la vraie requête. get_masterchain_info (la tête de la masterchain) est parfait pour ça : c'est l'opération qui renvoie en premier un seqno frais dès que la node a rattrapé la tête du réseau, et elle ne répond not ready que lorsque la node n'a pas encore rattrapé la tête de la masterchain elle-même. Elle vous rend un seqno frais ? La node est opérationnelle, vous pouvez enchaîner get_account_state, get_balance, run_get_method.

Conclusion honnête : retries + rotation + timeouts font baisser la fréquence des erreurs, mais ne suppriment pas la cause. Les nodes publiques sont surchargées by design — vous frappez juste plus délicatement à une porte derrière laquelle la file d'attente reste la même. D'autres approches d'accès à TON sont réunies dans le panorama des alternatives à toncenter pour 2026.

La solution sans monter sa propre node : une clé hébergée TONNode sur notre liteserver

Il n'y a qu'une seule façon de supprimer radicalement le not ready : arrêter d'aller taper sur des nodes partagées. Monter et exploiter sa propre node TON coûte cher et reste pénible au quotidien : synchronisation, disque, mises à jour, monitoring. L'option intermédiaire consiste à ne plus passer par le pool commun mais à obtenir, via une clé, un débit garanti et un accès prioritaire.

TONNode est un serveur MCP hébergé pour TON. MCP (Model Context Protocol) est le standard par lequel les agents IA (Claude, Cursor, ChatGPT/Codex, n'importe quel client MCP) appellent des outils. Au lieu que votre code parse la config globale et bricole des rustines autour du not ready, l'agent appelle un outil prêt à l'emploi, et derrière se trouve l'endpoint hébergé https://mcp.tonnode.io/mcp avec votre clé Bearer. C'est un débit garanti au lieu d'une file d'attente partagée.

Le paquet @tonnode/mcp — open source (MIT, disponible sur npm et GitHub tonnode/mcp) — fonctionne via le protocole natif ADNL de TON, sans couche HTTP intermédiaire. Vous ne troquez donc pas votre transport contre une passerelle HTTP lente : vous restez sur le même ADNL honnête — mais avec un accès prioritaire rattaché à votre clé.

Pour le diagnostic et la lecture au quotidien, ces outils vous serviront :

• get_masterchain_info — la tête de la masterchain, le healthcheck naturel.
• get_account_state — statut, flags et dernière transaction d'un compte.
• get_balance — le solde en GRAM.
• run_get_method — n'importe quel get-method read-only d'un contrat.

Si vous débutez tout juste avec MCP sur TON, passez d'abord par le guide MCP pour TON.

Comment se connecter : npx en local ou endpoint hébergé avec clé

Gratuitement, en local

Le jeu complet d'outils de lecture fonctionne en local, tel quel, sur la config publique, sans carte bancaire et sans clé :

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

C'est parfait pour le développement et les expérimentations locales. Mais gardez en tête que, sous le capot, le npx local tape sur ces mêmes liteservers partagés : il ne vous sauve donc pas du not ready sous charge — il vous sauve de la plomberie des dépendances et vous donne une interface d'outils unifiée.

Hébergé, avec clé

Pour quitter les nodes partagées, basculez le transport sur HTTP-MCP avec votre propre clé Bearer (l'appel des outils, lui, part vers notre node en ADNL) :

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

Ce que ça donne concrètement avec un agent

Une fois le serveur connecté, un prompt ordinaire suffit — l'agent choisira les outils tout seul :

D'abord get_masterchain_info pour le healthcheck. Ensuite get_account_state pour EQC… — montre-moi le statut et la dernière transaction. Puis get_balance sur la même adresse.

Sous le capot, ça donne une chaîne : get_masterchain_info (la node est vivante et a rattrapé la tête) → get_account_state (statut, flags, dernière transaction) → get_balance (solde GRAM). Fini les retries à tourner autour de la file d'attente des autres — la requête part sur un débit garanti. Au passage, GRAM est le Toncoin renommé (le changement de nom a eu lieu en juin 2026) ; le réseau, lui, s'appelle toujours TON.

La clé gratuite Hobby (60 requêtes/min) est délivrée dès la connexion, sans carte bancaire. Ensuite, au fil de votre croissance : Pro — 29 $/mois, 300 requêtes/min ; Scale — 199 $/mois, 1200 requêtes/min. Détail important : sur tous les plans, les 16 outils TONNode sont disponibles — vous payez uniquement le débit, pas la fonctionnalité.

Un liteserver dédié — sur demande, pas en self-service

Parfois le plan hébergé ne suffit pas et il vous faut un liteserver dédié (single-tenant) — uniquement pour votre trafic, sans aucun voisin. Cette option existe, mais soyons honnêtes : ce n'est pas du self-service. Il n'y a pas de bouton « activer le single-tenant » dans le dashboard — ça se met en place à la main : écrivez-nous, on discutera de la charge et de la configuration.

Et encore une mise au point honnête, sur la profondeur d'historique. La node d'archive TONNode est actuellement en cours de synchronisation et ne sert pas encore de requêtes. La « profondeur d'archive » est une ligne de roadmap, pas une fonctionnalité livrée. Si un historique profond depuis les origines de la chaîne vous est indispensable dès aujourd'hui, prévoyez-le séparément. Ce qui est déjà prêt et ce qui est prévu se trouve sur la roadmap.

En bref

• not ready = la node n'est pas synchronisée : la masterchain a de l'avance sur le shard, et l'état du compte, qui vit dans le dernier bloc de shard, n'est pas encore vérifiable.
• Les liteservers publics de la config globale sont partagés et limités : not ready, timeouts ADNL, pas d'historique profond. À ne pas confondre avec le HTTP 429 de toncenter/tonapi — autre couche.
• Les correctifs côté client (retries avec backoff, rotation d'endpoints, timeouts) réduisent la fréquence des erreurs, mais ne suppriment pas la cause.
• get_masterchain_info est votre healthcheck : il ne passe au rouge avec un not ready que lorsque la node n'a pas du tout rattrapé la tête de la masterchain.
• Le vrai traitement, c'est de quitter la ressource partagée pour un débit garanti.

Prenez une clé hébergée Hobby gratuite et arrêtez de récolter des « not ready » sur des nodes partagées → tonnode.io/dashboard?plan=hobby

Ensuite, à mesure que la charge grandit — les tarifs et la roadmap.