Appeler n'importe quel get-method d'un contrat TON sans SDK

Vous avez ouvert un explorateur juste pour connaître le seqno de votre wallet avant d'envoyer une transaction. Ou il vous faut le total_supply d'un jetton. Ou les données d'un listing NFT sur une marketplace. Et vous revoilà en train de lancer npm i @ton/ton, de monter un TonClient, de chercher un endpoint de liteserver qui fonctionne, de comprendre comment empaqueter une adresse dans beginCell().storeAddress(), puis de parser le BOC de sortie à la main. Trente lignes de code — pour un seul nombre que le contrat donne de toute façon gratuitement.

Le problème n'est pas TON. Le problème, c'est qu'entre vous et un simple appel read-only se dresse toute une couche de SDK qu'il faut installer, configurer et ne pas casser à la prochaine mise à jour. Et si vous branchez un agent IA sur TON (Claude, Cursor, ChatGPT/Codex), écrire cette couche à la main devient franchement absurde : l'agent devrait juste appeler la méthode.

Voici comment appeler n'importe quel get-method d'un contrat TON via run_get_method, sans une seule ligne de client SDK.

Qu'est-ce qu'un get-method de contrat TON, et pourquoi on dégaine généralement un SDK

Un get-method est une fonction read-only d'un smart contract. Un wallet expose seqno ; le master contract d'un jetton, get_jetton_data ; un contrat de vente NFT, get_sale_data ; un pool STON.fi/DeDust, get_pool_data. Le mot-clé, c'est read-only :

• la méthode ne modifie rien dans l'état du contrat ;
• elle n'exige aucune signature et ne consomme pas de gas côté utilisateur ;
• elle s'exécute sur un liteserver ou dans un émulateur TVM (TON Virtual Machine), pas via l'envoi d'une transaction.

Autrement dit, appeler un get-method n'est pas une transaction. Rien à signer, rien à payer, rien à attendre dans un bloc. C'est en substance une fonction « lis une valeur dans un contrat vivant ».

Mais pour l'appeler « à l'ancienne », il faut tout un attirail : un SDK (ton, tonweb, tonutils), votre propre client ADNL vers un liteserver ou un wrapper HTTP type toncenter, l'assemblage manuel des arguments d'entrée en cells et le décodage manuel du BOC de sortie. Beaucoup de pièces mobiles pour une seule lecture. Et chacune est un point de défaillance : les liteservers publics de la config globale sont partagés et limités — sous charge, ils répondent not ready ou partent en timeout ADNL ; les API HTTP publiques renvoient 429 Too Many Requests dès que la limite est dépassée (sans clé — environ une requête par seconde).

run_get_method : un outil pour n'importe quelle méthode read-only de n'importe quel contrat

run_get_method est un outil MCP qui appelle n'importe quel get-method read-only de n'importe quel contrat TON. Vous passez l'adresse du contrat, le nom de la méthode et la liste des arguments — l'outil exécute la méthode on-chain via la TVM et renvoie la pile de sortie.

Ce que vous n'avez pas à faire :

• installer et mettre à jour un SDK (ton/tonweb/tonutils) ;
• écrire votre propre client ADNL ;
• empaqueter les arguments en cells et parser le BOC de sortie à la main.

run_get_method fait partie des outils de lecture de TONNode — un serveur MCP hébergé pour TON. MCP (Model Context Protocol) est le standard par lequel les agents IA appellent des outils. L'ensemble complet des outils de lecture est disponible gratuitement en local via npx -y @tonnode/mcp (config publique, sans carte bancaire), ou via l'endpoint hébergé https://mcp.tonnode.io/mcp avec une clé Bearer. Vous pouvez essayer tout de suite, sans rien acheter.

Arguments et pile : passer l'entrée et décoder la sortie de la TVM

La TVM travaille avec une pile. Une analogie : vous posez sur la table quelques « cartes » portant les valeurs d'entrée, la méthode les prend, s'exécute, puis repose des « cartes » avec le résultat.

L'entrée est passée sous forme de valeurs sur la pile TVM. En général :

• int — des entiers (par exemple un index, un montant en unités raw, un query id) ;
• une adresse en slice — l'adresse empaquetée dans un slice de cell ;
• cell — une cell de données arbitraire.

La sortie revient comme une pile de valeurs : int, slice, cell, tuple. L'agent la décode par positions — première valeur, deuxième, troisième. Par exemple, get_jetton_data renvoie dans l'ordre : total_supply (int), le flag mintable, admin (adresse en slice), content (cell) et le code du wallet (cell). La position détermine le sens — cela fait partie de la convention ABI du contrat lui-même.

Beaucoup de méthodes utiles (seqno, get_jetton_data) ne demandent aucune entrée — la pile d'arguments est vide. Les arguments apparaissent là où la méthode cherche quelque chose par clé : par exemple le calcul de l'adresse d'un jetton wallet à partir de l'adresse du propriétaire.

Nuance importante : run_get_method renvoie la pile brute en unités raw. Les nombres arrivent tels quels, sans conversion par les decimals, et les cells ne sont pas transformées en chaînes lisibles. C'est flexible, mais il faut savoir ce que vous lisez — on y revient dans la section sur get_jetton_info.

exit_code : savoir si la méthode a bien tourné

Chaque appel de get-method a un exit_code — le code de terminaison de la TVM. Décoder la pile de sortie n'a de sens que si l'appel a réussi. La règle pour les get-methods est contre-intuitive, et elle mérite d'être retenue :

• exit_code 0 et 1 — succès (les deux comptent comme une terminaison normale, donc pas de panique devant le 1) ;
• exit_code > 1 — erreur, la pile de sortie n'est pas fiable.

Codes d'erreur fréquents :

exit_code	Signification
2	stack underflow — moins d'arguments sur la pile que la méthode n'en attend
4	integer overflow / division par zéro
11	en général, appel d'une méthode inexistante (faute de frappe dans le nom)
13	out of gas

En pratique : vous recevez 2 — vérifiez que vous avez passé tous les arguments, et dans le bon ordre. Vous recevez 11 — vous vous êtes probablement trompé de nom de méthode, ou le contrat ne l'implémente pas. Vous recevez 13 — la méthode est lourde et a buté sur la limite de gas.

Exemples via un agent : seqno, get_jetton_data, get_sale_data

Le plus agréable, c'est quand run_get_method n'est pas appelé par un humain, mais par un agent. Vous formulez la tâche en langage courant, l'agent choisit lui-même l'adresse, le nom de la méthode et les arguments, récupère la pile et explique les champs.

seqno avant l'envoi. seqno est le numéro de la transaction sortante du wallet, on le lit avant d'assembler un transfert : sans lui, le message ne passera pas.

Prompt à l'agent : « Appelle seqno sur mon wallet UQD… et donne-moi le numéro courant. »

L'agent appelle run_get_method sans arguments, reçoit un unique int sur la pile de sortie et vous rend le nombre.

get_jetton_data — les métadonnées du master d'un jetton. La méthode renvoie total_supply, le flag mintable, l'adresse de l'admin et content.

Prompt à l'agent : « Appelle get_jetton_data sur ce master USDT et détaille les champs. »

L'agent déclenche run_get_method avec l'adresse du master et le nom get_jetton_data, lit la pile et explique les positions. Il y a ici une subtilité importante — on y vient plus bas.

get_sale_data — les données d'un listing NFT. Ce n'est pas un outil NFT à part : c'est toujours le même run_get_method, avec lequel vous lisez le get-method natif du contrat de vente de la marketplace. get_sale_data renvoie le prix, le vendeur, le statut de la vente — pratique pour savoir si le NFT est déjà parti ou encore en vente.

Prompt à l'agent : « Lis get_sale_data sur ce contrat de vente et donne-moi le prix en GRAM. »

Vous n'écrivez aucun client. L'agent appelle un seul outil. Les autres méthodes courantes — get_wallet_data (données d'un jetton wallet), get_pool_data (pools STON.fi/DeDust) — s'appellent exactement de la même façon : nom de la méthode, adresse, arguments si besoin.

get_jetton_data ou get_jetton_info : quand il faut une réponse lisible par un humain

C'est ici que se cache le piège principal. run_get_method renvoie une pile brute : get_jetton_data vous donnera total_supply sous forme d'un entier gigantesque en unités raw, et content comme une cell dont il faut encore extraire le nom et le symbole. Pas de « USDT », pas de « 6 decimals », pas de joli nombre — c'est la sortie bas niveau de la TVM. Si vous avez justement besoin d'un accès bas niveau au master contract ou d'un champ non standard, c'est l'outil qu'il vous faut.

Mais si la tâche est simplement de connaître le nom, le symbole et les decimals d'un jetton sous forme prête à l'emploi, ne vous infligez pas le décodage de cells. Il existe pour ça un outil dédié — get_jetton_info : il renvoie le nom, le symbole, les decimals et l'émission déjà décodés.

Pourquoi c'est critique : les decimals servent à convertir les unités raw en montants réels. L'USDT sur TON a decimals = 6 ; la plupart des jettons, 9. Si vous prenez le total_supply du get_jetton_data brut sans le diviser par 10^decimals, vous obtiendrez un nombre faux d'un facteur un million ou un milliard. Plus de détails sur ce piège dans l'analyse des decimals des jettons TON.

La règle est simple :

• il vous faut les champs bruts du contrat (émission, admin, content, une méthode custom quelconque) → run_get_method + get_jetton_data ;
• il vous faut une réponse lisible et prête à l'emploi sur le jetton (nom, symbole, decimals) → get_jetton_info.

Ne confondez pas les nombres raw de get_jetton_data avec la réponse prête de get_jetton_info.

Deux garde-fous utiles : parse_address et get_account_state

Avant d'appeler une méthode, mieux vaut mettre de l'ordre dans l'adresse et vérifier que le contrat est bien en vie :

• parse_address — normalise une adresse entre les formats EQ/UQ/raw, hors ligne, sans toucher au réseau. TON a plusieurs formats d'adresse, et toutes les méthodes ne les acceptent pas tous ; pratique pour convertir le EQ… fourni par l'utilisateur au bon format avant de le glisser dans les arguments.
• get_account_state — vérifie le statut, les flags et la dernière transaction du contrat. Si le compte n'est pas déployé (uninit) ou est gelé, n'importe quel get-method échouera de façon prévisible — il revient moins cher de vérifier l'état en amont que de tomber sur un exit_code obscur.

Brancher et appeler sans écrire une seule ligne de client

Deux chemins. Le premier — gratuit en local, tous les outils de lecture via la config publique, sans carte bancaire :

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

Le paquet @tonnode/mcp est open source (MIT), disponible sur npm et GitHub (tonnode/mcp), et parle le protocole ADNL natif de TON, sans couche HTTP intermédiaire. Le chemin gratuit a droit à son propre article — MCP pour TON gratuitement.

Le second — l'endpoint hébergé, avec un débit garanti et votre propre clé :

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

Les 16 outils sont disponibles sur tous les plans — vous ne payez que le débit. La clé gratuite Hobby (60 requêtes/min) est délivrée dès la connexion, sans carte bancaire.

Une fois branché, tous les outils de lecture — dont run_get_method, get_jetton_info, parse_address, get_account_state — sont exposés à l'agent comme des outils ordinaires. Un appel ressemble à une phrase banale dans le chat : « appelle get_pool_data sur ce pool DeDust », « lis le seqno de ce wallet » — et l'agent choisit lui-même run_get_method, les arguments, puis explique les champs. Et si la tâche est de connaître un solde USDT, il existe un raccourci en une seule commande : le solde USDT sur TON en un appel.

---

Prenez une clé Hobby gratuite et appelez run_get_method directement depuis votre agent → tonnode.io/dashboard?plan=hobby. La clé est délivrée dès la connexion, sans carte bancaire, 60 requêtes par minute — largement de quoi lire des contrats.

Pas envie de vous inscrire du tout ? Lancez en local : npx -y @tonnode/mcp. La liste complète des outils et leurs paramètres se trouve sur tonnode.io/mcp.

Lire l'état de la blockchain, ce n'est plus assembler un client. C'est formuler une requête.