Construire un agent de trading TON : lire, coter, swapper

Le problème auquel se heurte tout agent de trading sur TON

Vous demandez à un agent IA de « swapper 50 USDT en GRAM quand le prix baisse » — et il envoie une transaction de 50 000 USDT au lieu de 50. Parce que l'USDT sur TON a decimals = 6 (50 USDT = 50 000 000 unités raw), et que l'agent a calculé par défaut comme pour un jetton ordinaire à neuf zéros — d'où un montant 1000 fois trop élevé. Une erreur d'un facteur 1000, de l'argent réel, une transaction irréversible. L'erreur miroir a la même racine : l'agent voit un solde brut de 1000000000 et annonce avec aplomb « vous avez un milliard d'USDT », alors qu'il y en a 1000.

Ce ne sont pas des histoires pour faire peur, mais exactement les pièges dans lesquels tombe quiconque branche un LLM à la DeFi de TON directement via du RPC brut : decimals confondus, impossibilité de lire le solde d'un jetton sans l'adresse du jetton-wallet, clé privée qui fuit par le contexte. Voici comment construire un agent de trading TON (trading agent TON) qui lit les soldes, prend une cotation ferme et construit un swap sans jamais toucher à vos clés. L'outil : TONNode, un serveur MCP hébergé pour TON.

Qu'est-ce qu'un agent de trading sur TON et pourquoi a-t-il besoin de MCP

Un agent de trading, c'est un LLM (Claude, Cursor, Codex ou n'importe quel autre client MCP) qui, à la demande de l'utilisateur, sait lire l'état du réseau et préparer des opérations : « montre mon solde USDT », « combien de GRAM vais-je recevoir pour 500 USDT », « construis le swap ». À lui seul, le modèle ne voit pas la blockchain — il lui faut des outils.

C'est précisément le rôle de MCP (Model Context Protocol) — le standard par lequel les agents appellent des outils externes. Au lieu d'apprendre au modèle à composer des requêtes ADNL brutes et à parser des cellules BOC, vous lui donnez un jeu de fonctions typées : « donne le solde », « donne une cotation », « construis la transaction ». TONNode se branche comme source de ces outils et fournit à l'agent exactement 16 fonctions pour travailler avec le réseau : lecture, swap, cross-chain, génération de wallet.

L'agent de trading en utilise cinq, toutes disponibles même sur le plan gratuit :

lire (get_balance, get_jetton_balance)
   -> vérifier les decimals (get_jetton_info)
      -> coter (get_swap_quote)
         -> construire le swap (build_swap_tx)
            -> le wallet signe via TonConnect

Détail clé de la dernière étape : c'est le wallet de l'utilisateur qui signe, pas le serveur. TONNode renvoie des messages non signés — pourquoi c'est un point de principe, nous le verrons à la fin.

Étape 1 : l'agent lit les soldes (get_balance, get_jetton_balance)

Avant de swapper quoi que ce soit, l'agent doit savoir de quoi il dispose. Deux outils :

• get_balance — le solde GRAM d'une adresse. GRAM, c'est le Toncoin renommé en juin 2026 ; le réseau lui-même s'appelle toujours TON.
• get_jetton_balance — le solde d'un jetton : USDT, NOT, n'importe quel autre. La magie ici, c'est que le jetton-wallet est calculé on-chain. Vous passez l'adresse du propriétaire et l'adresse master du jetton, et TONNode dérive lui-même l'adresse du jetton-wallet et lit son solde. Pas besoin de connaître cette adresse à l'avance ni de la stocker quelque part.

Le prompt envoyé à l'agent ressemble littéralement à ceci :

Vérifie le solde du wallet UQAbc...xyz :
combien de GRAM et combien d'USDT dessus ?

Sous le capot, le modèle appelle get_balance pour le solde natif et get_jetton_balance pour l'USDT. Un seul hic : ce qui revient, ce ne sont pas encore des montants « humains », mais des unités raw. Et c'est là que commence le plus important. Sur la façon d'obtenir le solde USDT en un seul appel, sans jongler avec les adresses de jetton-wallet, il existe une analyse dédiée : /blog/usdt-balance-ton-one-call.

Les decimals décident de tout : get_jetton_info et pourquoi USDT = 6

Les soldes et les montants sur TON sont stockés en unités raw — des entiers sans partie fractionnaire. Pour obtenir un montant lisible par un humain, il faut diviser le nombre brut par 10^decimals. Et voilà le piège : chaque jetton a son propre nombre de decimals.

• Pour USDT, decimals = 6. Donc 1 USDT = 1 000 000 unités raw.
• Pour la plupart des jettons sur TON, decimals = 9 (comme GRAM). Donc 1 jetton = 1 000 000 000 unités raw.

Confondre 6 et 9, c'est se tromper sur le montant d'un facteur 1000 tout rond. Le fameux « milliard d'USDT » du début de l'article. Pour un agent de trading, ce n'est pas un détail cosmétique, c'est le fondement même de la confiance : s'il confond les ordres de grandeur, on ne peut pas le laisser construire des transactions.

C'est pourquoi on insère dans le pipeline get_jetton_info — il renvoie les métadonnées du jetton : nom, symbole, émission totale et — le plus important — decimals. La bonne logique côté agent :

raw       = get_jetton_balance(...)   // par exemple, 1000000000
decimals  = get_jetton_info(...)      // pour USDT → 6
human     = raw / 10 ** decimals      // 1000000000 / 1e6 = 1000 USDT

Le même raw avec decimals = 9 aurait donné 1 token — la différence est colossale. Ne hardcodez pas les decimals dans le prompt et ne laissez pas le modèle les « deviner » de mémoire : sur un nouveau jetton, il se trompera. Faites-lui tirer la valeur de get_jetton_info à chaque fois et recalculer sur cette base. Analyse détaillée de ce piège et de ce qu'il coûte concrètement aux gens : /blog/jetton-decimals-ton.

Étape 2 : cotation ferme via Omniston (get_swap_quote)

Les soldes sont lus et convertis dans les bonnes unités — l'agent a maintenant besoin d'un prix. En DeFi, le prix « à la louche » ne fonctionne pas : la liquidité est éclatée entre plusieurs DEX, le cours bouge, et l'agent doit s'appuyer sur une cotation à jour, pas sur une intuition.

get_swap_quote fournit une cotation ferme pour un swap GRAM ⇄ jetton via le protocole Omniston, qui agrège la liquidité des deux plus gros DEX de TON à la fois — STON.fi et DeDust. L'agent n'a pas besoin d'interroger lui-même les pools, de comparer les prix ni de calculer le slippage : Omniston renvoie la meilleure route sur la liquidité combinée.

Donne-moi une cotation : combien de GRAM vais-je recevoir pour 50 USDT, là, tout de suite ?

Le modèle appelle get_swap_quote avec le montant 50000000 (les fameuses unités raw de l'étape précédente) et reçoit des chiffres concrets : combien en entrée, combien en sortie, par quelle route, avec quel slippage. C'est le point de décision : si l'agent a une condition (« swappe seulement si le cours est meilleur que X »), il compare la cotation au seuil et soit continue, soit attend l'itération suivante. Important : une cotation n'est pas encore une opération. Aucun fonds ne bouge, rien n'est signé. C'est de la pure lecture du marché.

Étape 3 : construction du swap non signé (build_swap_tx) et signature dans le wallet

L'utilisateur a vu la cotation et dit « oui, on swappe ». L'agent appelle build_swap_tx et reçoit une transaction de swap non signée, prête pour TonConnect.

J'insiste sur le mot « non signée ». Le serveur assemble un message correct — adresse du destinataire, payload, montant, paramètres de route — et le renvoie tel quel. Le message part ensuite dans le wallet de l'utilisateur (Tonkeeper, MyTonWallet, n'importe quel wallet compatible TonConnect), l'utilisateur voit exactement ce qu'il signe et confirme lui-même. La signature est apposée par la clé privée de l'utilisateur, qui vit dans son wallet, pas sur le serveur.

get_balance / get_jetton_balance    →  lire ce qu'on possède
        ↓
get_jetton_info                     →  vérifier les decimals, recalculer
        ↓
get_swap_quote (Omniston)           →  cotation ferme
        ↓
build_swap_tx                       →  transaction non signée
        ↓
wallet utilisateur (TonConnect)     →  signature et envoi

Chaque étape est un appel d'outil distinct et explicite. L'agent ne prend aucune initiative de son propre chef avec l'argent : il prépare, et la décision comme la signature restent à l'humain. Le scénario complet du swap non-custodial, de la cotation à la signature, est décortiqué étape par étape ici : /blog/agent-swap-ton-noncustodial.

Non-custodial : pourquoi le serveur ne détient jamais les clés de l'agent

Ce n'est pas une formule marketing, c'est une frontière architecturale. Chez TONNode, les outils de swap, de cross-chain et de génération de wallet sont strictement non-custodiaux :

• Le serveur ne signe jamais de transactions.
• Le serveur ne conserve jamais de clés privées ni de fonds.
• Tout ce qu'il renvoie vers l'extérieur, ce sont des messages TonConnect non signés.

Pourquoi est-ce crucial précisément pour un agent de trading ? Parce qu'un agent, par définition, manipule de l'argent et, par définition, peut se tromper — mal comprendre la demande, confondre un montant, partir en boucle. Si les clés vivaient sur le serveur et qu'il signait lui-même, une erreur de l'agent signifierait une perte de fonds à votre insu. Dans le schéma non-custodial, le dernier rempart, c'est vous : aucune transaction ne part tant que votre wallet ne l'a pas confirmée.

Comparez avec le @ton/mcp officiel de la TON Foundation — c'est un agent-wallet custodial : il détient une clé operator et signe lui-même (schéma split-key, où la clé operator est chez l'agent et la clé owner chez l'utilisateur). Il a ses points forts — dépense autonome sans intervention humaine, gestion des NFT et du DNS, statut officiel de la Foundation. Mais le modèle de confiance est différent : dans ce schéma, l'agent peut réellement déplacer des fonds. TONNode choisit délibérément la frontière opposée : le serveur ne signe rien du tout. Comparaison détaillée des deux approches : /blog/custodial-vs-noncustodial-mcp.

Comment se brancher et par où commencer en 5 minutes

Bonne nouvelle : pour assembler le pipeline de trading, pas besoin de payer. Mais attention à ne pas confondre les deux parcours gratuits — leur jeu d'outils n'est pas le même.

La config publique locale donne le jeu complet de lecture (8 outils : get_masterchain_info, get_balance, get_account_state, get_transactions, run_get_method, get_jetton_balance, parse_address, get_jetton_info). Elle s'installe via npx, sans clé :

{
  "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 natif ADNL de TON sans couche HTTP intermédiaire entre l'agent et le réseau. Collez la config dans Claude Desktop, Cursor ou n'importe quel client MCP — et l'agent sait déjà lire les soldes et appeler get_jetton_info.

En revanche, les cotations elles-mêmes — get_swap_quote et build_swap_tx — appartiennent au groupe SWAP et passent par l'endpoint hébergé. Point clé : avec la clé gratuite Hobby, les 16 outils sont disponibles, cotation et construction de swap comprises. Autrement dit, tout le pipeline de trading (lecture → cotation → swap) s'assemble gratuitement — mais bien via la clé hébergée Hobby, pas via la config publique locale. La config pour l'endpoint hébergé :

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

TONNode compte exactement 16 outils, et les 16 sont disponibles sur tous les plans — vous ne payez que le débit, jamais les fonctionnalités :

• Hobby — gratuit pour toujours, 60 requêtes/min, sans carte bancaire.
• Pro — 29 $/mois, 300 requêtes/min.
• Scale — 199 $/mois, 1200 requêtes/min.

Pour démarrer et roder le pipeline de trading, la clé gratuite Hobby suffit largement : 60 requêtes par minute, c'est beaucoup d'appels d'agent consécutifs. Pas de carte requise, la clé est délivrée dès la connexion.

Obtenir la clé Hobby gratuite (60 req/min, sans carte) : tonnode.io/dashboard?plan=hobby

La liste complète des 16 outils : tonnode.io/mcp · Tarifs : tonnode.io/pricing

---

Assemblez le pipeline de cinq outils — get_balance, get_jetton_balance, get_jetton_info, get_swap_quote, build_swap_tx — gardez les decimals sous contrôle et laissez la signature au wallet. Vous obtiendrez un agent de trading qui lit honnêtement les soldes, prend une cotation ferme et prépare un swap sur des montants réels, sans avoir eu accès une seule seconde aux clés de qui que ce soit. C'est exactement ainsi que doit fonctionner un agent de trading sur TON.