Swap non-custodial sur TON : l'agent IA ne touche pas vos clés

Qui détient la clé : la vraie question du swap non-custodial sur TON

Imaginez : vous chargez un agent IA de surveiller le cours et, quand l'USDT baisse, d'en racheter contre du GRAM. L'agent évalue le marché, trouve le bon moment, prépare l'ordre — et là surgit la question à laquelle on pense généralement trop tard. Pour que l'agent exécute réellement le swap, quelqu'un doit signer la transaction avec une clé privée. Qui détient cette clé ?

Si la réponse est « le service par lequel l'agent passe », vous venez de donner à du code tiers le droit de disposer de votre argent. Une injection de prompt, une fuite de log — et l'agent signe autre chose que ce que vous pensiez. Le vrai problème n'est pas « comment appeler un DEX », mais comment laisser l'agent assembler l'ordre tout en réservant strictement la signature au wallet d'un humain. Voyons comment réaliser un swap de tokens TON par un agent, en mode non-custodial.

Les deux moitiés d'un swap : le calcul est sûr, la signature ne l'est pas

Un swap sur un DEX se compose de deux parties fondamentalement différentes. La première est purement calculatoire et sans danger : obtenir le cours, calculer le slippage, assembler le corps de la transaction. La seconde est irréversible et dangereuse : signer ce corps avec une clé privée et l'envoyer sur le réseau. D'où deux modèles possibles :

• Le modèle custodial. L'agent (ou le serveur derrière lui) détient la clé et signe lui-même. Pratique — l'agent agit en autonomie. Mais la clé de signature se retrouve à côté d'un LLM, et un LLM est une machine non déterministe qu'un texte non fiable suffit à manipuler (descriptions de jettons, réponses d'autres outils, messages de l'utilisateur). C'est par exemple ainsi que fonctionne le @ton/mcp officiel de la TON Foundation : un agent-wallet avec une clé operator qui signe seul les envois et les swaps (schéma split-key : la clé operator chez l'agent, la clé owner chez l'utilisateur). Le modèle fonctionne et a de vrais atouts — dépense autonome, gestion des NFT et du DNS, statut de paquet officiel. Mais cela reste une confiance accordée au détenteur de la clé.
• Le modèle non-custodial. Le serveur ne fait que préparer la transaction et la renvoie non signée. C'est le wallet de l'utilisateur qui signe, via TonConnect. Le serveur ne voit jamais et ne stocke jamais la clé privée.

Pour un agent de trading qui tourne en continu, le second modèle élimine le risque principal : même si l'infrastructure est compromise, le pire qui puisse arriver, c'est un brouillon non signé, que vous validez de toute façon à la main ou via la politique de votre wallet. Cette alternative est détaillée dans la comparaison honnête entre TONNode et le @ton/mcp officiel.

Le modèle non-custodial de TONNode : le serveur renvoie une transaction non signée

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 et tout client MCP) appellent des outils externes. TONNode donne à l'agent 16 outils pour travailler avec TON, et les outils de swap, de cross-chain et de génération de wallet sont strictement non-custodiaux.

L'invariant clé : le serveur ne signe JAMAIS et ne détient jamais de fonds ni de clés privées. Pour le swap, cela signifie que l'outil final ne renvoie pas un « ordre exécuté » mais un message TonConnect non signé — un objet prêt à signer. Le serveur ne peut physiquement pas remplacer le destinataire des fonds après la signature, puisqu'il n'a pas cette signature.

Le swap dans TONNode, ce sont exactement deux outils :

• get_swap_quote — une cotation ferme,
• build_swap_tx — une transaction non signée, prête pour TonConnect.

Les deux passent par le protocole Omniston, qui agrège la liquidité de STON.fi et DeDust en même temps — la cotation est calculée sur les deux DEX et vous obtenez la meilleure des deux. Le swap se fait en paires GRAM⇄jetton. GRAM est le nouveau nom du Toncoin (renommé en juin 2026) ; le réseau, lui, s'appelle toujours TON. Autrement dit, le « GRAM » d'une cotation est la monnaie native du réseau.

get_swap_quote : une cotation ferme via Omniston (STON.fi + DeDust)

Première étape : savoir combien vous allez réellement recevoir. get_swap_quote renvoie une cotation ferme : le montant attendu en sortie et le taux. Comme Omniston interroge STON.fi et DeDust simultanément sous le capot, l'agent n'a pas besoin de parcourir les pools et de comparer à la main — il voit directement le résultat agrégé.

Récupère une cotation pour swapper 100 USDT → GRAM.
Utilise get_swap_quote. Affiche le montant attendu en sortie et le taux.

Une subtilité importante, à l'origine de nombreuses cotations mal calculées : la cotation raisonne en unités raw (les plus petites fractions indivisibles du token), pas en nombres « humains ». Avant de calculer le montant d'un swap de jetton, il faut donc connaître ses decimals.

get_jetton_info : pourquoi les decimals avant un swap (USDT = 6)

Voici l'erreur classique qui casse les swaps : l'agent prend « 100 USDT » et met 100 dans le champ montant. Mais on-chain, un jetton n'a pas de notion de « 100 » — il n'y a que des unités raw. C'est le paramètre decimals qui définit combien d'unités raw vaut un token, et le montant se calcule comme quantité × 10^decimals.

• Pour USDT sur TON, decimals = 6 → 100 USDT font 100 × 10^6 = 100 000 000 unités raw.
• Pour la plupart des jettons, decimals = 9 → 100 tokens font 100 000 000 000 unités raw.

Si vous collez naïvement neuf zéros à « 100 USDT » (comme pour GRAM), vous demandez un swap 1000 fois plus gros que prévu. Il est très facile de se tromper ici de trois ordres de grandeur. C'est pourquoi get_jetton_info est une étape obligatoire : il renvoie le nom, le symbole, les decimals et l'offre totale du jetton.

Avant le swap, récupère les decimals du jetton d'entrée via get_jetton_info,
et calcule seulement ensuite le montant en unités raw.

Le sujet est creusé plus en détail dans l'article sur la connexion des agents IA à TON via MCP.

Outils auxiliaires : parse_address et get_jetton_balance

Deux outils auxiliaires méritent aussi d'être appelés avant d'assembler la transaction :

• parse_address — vérification et conversion d'adresse hors ligne (EQ/UQ/raw). Une assurance bon marché contre une coquille dans l'adresse du jetton ou du destinataire, avant de construire quoi que ce soit.
• get_jetton_balance — le solde d'un jetton à partir de l'adresse principale du wallet. L'adresse du jetton-wallet est calculée on-chain à l'intérieur de l'outil : il faut donc passer l'adresse principale, pas celle du jetton-wallet. Erreur fréquente : fournir l'adresse du jetton-wallet ; inutile, donnez la principale.

build_swap_tx : un message non signé pour TonConnect

Une fois la cotation obtenue et les montants calculés dans les bonnes unités raw, build_swap_tx assemble la transaction elle-même. Et c'est là tout le sens du non-custodial : l'outil renvoie un message TonConnect NON SIGNÉ. Ce n'est pas un ordre envoyé, c'est un brouillon : adresse du contrat, montant, payload. Le serveur vous a remis « l'enveloppe » sans la sceller — le sceau (la signature), c'est votre wallet qui l'appose.

Le message part ensuite vers un wallet compatible TonConnect (Tonkeeper et autres), l'utilisateur voit exactement ce qu'il signe et confirme. À aucune étape la clé privée ne quitte le wallet ni n'atteint le serveur TONNode.

Assemble la transaction de swap sur la dernière cotation via build_swap_tx.
Renvoie le message TonConnect non signé — je le signerai dans mon wallet.

Le flux complet : de la cotation à la signature dans le wallet

La séquence typique d'un swap de jetton ressemble à ceci :

1. parse_address — vérifier et normaliser l'adresse du jetton et du destinataire (hors ligne).
2. get_jetton_info — récupérer les decimals (6 pour USDT, le plus souvent 9), le nom, le symbole.
3. get_jetton_balance — s'assurer que le solde suffit (adresse principale, pas le jetton-wallet).
4. get_swap_quote — obtenir une cotation ferme via Omniston (STON.fi + DeDust).
5. build_swap_tx — assembler la transaction TonConnect non signée.
6. Le wallet de l'utilisateur signe via TonConnect — la signature reste côté utilisateur.

Au niveau du prompt, cela se formule très naturellement :

Je veux échanger 50 GRAM contre de l'USDT.
Vérifie d'abord l'adresse du jetton USDT via parse_address,
récupère ses decimals via get_jetton_info,
vérifie le solde via get_jetton_balance,
prends une cotation get_swap_quote et assemble la transaction build_swap_tx.
N'envoie pas la transaction — renvoie-moi le message non signé pour TonConnect.

L'agent découpera lui-même cela en appels d'outils, et vous obtiendrez en sortie un brouillon que vous signerez dans votre propre wallet. Notez que la dernière étape n'est pas un outil TONNode. C'est le wallet qui signe, et c'est exactement là que passe la frontière non-custodiale. Si vous construisez un agent de trading complet, jetez un œil à l'analyse des délais et de la latence du trading sur TON — ce flux y est intégré dans la boucle de décision. Et pour les opérations au-delà de TON, TONNode propose cinq outils cross-chain non-custodiaux fondés sur un escrow atomique HTLC.

Brancher les outils de swap sur Claude, Cursor ou ChatGPT

Les outils de swap sont disponibles sur tous les plans, y compris le plan gratuit Hobby (60 requêtes/min) — Hobby est une clé hosted. Vous ne payez que le débit : le jeu de 16 outils est identique sur toutes les clés.

En local et gratuitement — pour la lecture. Le paquet @tonnode/mcp est open source (MIT), parle le protocole natif ADNL de TON sans intermédiaire HTTP et se lance en une commande. La config publique donne le jeu complet des outils de lecture :

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

L'endpoint hosted — pour le swap et le reste. Votre propre clé (le Hobby gratuit suffit), un débit garanti et les 16 outils, dont get_swap_quote et build_swap_tx :

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

Cette config se place dans les réglages MCP de votre client — Claude Desktop, Cursor, ChatGPT/Codex ou n'importe quel autre agent compatible MCP. Une fois la clé hosted branchée, les outils get_swap_quote et build_swap_tx deviennent automatiquement disponibles pour l'agent. La clé tn_live_… est délivrée dès la connexion, sans carte bancaire.

L'essentiel en bref

• Le swap dans TONNode, ce sont deux outils : get_swap_quote (cotation ferme) et build_swap_tx (transaction non signée pour TonConnect).
• Les deux passent par Omniston — l'agrégateur de liquidité de STON.fi et DeDust.
• La signature reste toujours chez l'utilisateur. Le serveur ne détient aucune clé privée et ne signe rien — contrairement au @ton/mcp officiel, qui est custodial.
• Avant de swapper un jetton, récupérez ses decimals via get_jetton_info (USDT = 6, la plupart = 9), sinon le montant en unités raw sera faux.
• Les outils de swap fonctionnent avec n'importe quelle clé hosted, y compris le Hobby gratuit.

Le swap non-custodial sur TON pour un agent, c'est une discipline de séparation des rôles : le serveur calcule et assemble, le wallet signe. Chez TONNode, cela tient en deux outils au-dessus d'Omniston, plus get_jetton_info pour des decimals corrects — et aucune clé privée ne quitte jamais l'utilisateur.

Le plus simple est de commencer avec la clé gratuite. Obtenez une clé Hobby sans carte bancaire et branchez les outils de swap en quelques minutes : tonnode.io/dashboard?plan=hobby. Envie de voir d'abord le jeu d'outils complet ? Passez par la page des outils.