Créer un wallet TON par programmation (v4, v5, highload)

Vous lancez une campagne de 500 codes promo, et chaque paiement doit partir de son propre wallet TON. Ou bien vous écrivez un agent IA qui crée un wallet « chaud » à la volée, reçoit un dépôt et en fait quelque chose. La première chose que l'on trouve sur Internet, c'est une pile d'exemples SDK : importez @ton/ton, comprenez la différence entre WalletContractV4 et WalletContractV5R1, appelez mnemonicNew() à la main, dérivez les clés, calculez l'adresse, et n'oubliez pas le subwallet_id du highload. Une demi-journée part dans du code d'infrastructure qui n'a rien à voir avec votre vrai problème. Et si c'est un agent IA qui crée les wallets, il doit savoir le faire lui-même — sans que vous lui codiez la cryptographie en dur.

Voici comment créer un wallet TON par programmation (generate wallet / création de wallet sur TON) en un seul appel de l'outil generate_wallet, comment s'y retrouver entre les versions v3r2, v4, v5r1 et highload_v3, et comment ne pas perdre le premier dépôt à cause de l'erreur classique de l'adresse bounceable.

Pourquoi créer un wallet TON par programmation (et pas via le SDK)

La création manuelle via le SDK fonctionne très bien — jusqu'à la première mise en production. À l'échelle, les problèmes remontent à la surface :

• Les versions. Sur TON, il n'existe pas « un » wallet mais plusieurs contrats : v3r2, v4, v5r1, highload. Chacun a sa propre logique et sa propre adresse pour une même clé. Trompez-vous de version et vous obtenez la mauvaise adresse.
• Les formats d'adresse. Un même wallet existe sous forme EQ et sous forme UQ. Confondez les deux au moment de communiquer l'adresse de dépôt, et les fonds « rebondissent » vers l'expéditeur (on y revient plus bas).
• L'agent IA. On ne peut pas « donner une bibliothèque » à un agent (Claude, Cursor, ChatGPT/Codex) — il lui faut un outil qu'il appelle d'après sa description. Via MCP (Model Context Protocol), l'agent invoque generate_wallet comme une fonction ordinaire et reçoit une réponse structurée prête à l'emploi. La logique des versions, des clés et des formats vit côté serveur MCP.
• Stack polyglotte. Vous ne voulez pas maintenir un SDK TON en Go, Python et Node en parallèle — MCP offre une interface unique pour tous.

generate_wallet est l'un des 16 outils de TONNode, le serveur MCP hébergé pour TON. Il fait exactement une chose : créer un nouveau wallet et vous remettre tout ce qu'il faut pour en être propriétaire. Si vous découvrez l'approche, commencez par le guide MCP pour TON.

generate_wallet en un appel : ce qui est réellement renvoyé

generate_wallet crée un nouveau wallet TON et renvoie tout le nécessaire pour le détenir et le restaurer :

• la mnémonique (seed phrase) — une suite de mots lisible par un humain, dont tout le reste se dérive de façon déterministe ;
• la clé privée — pour signer les transactions ;
• la clé publique ;
• l'adresse du wallet — dans les formats TON standard.

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

Crée un nouveau wallet TON en version v5r1 via generate_wallet
et montre-moi l'adresse et la mnémonique.

L'agent appelle l'outil avec le paramètre de version et renvoie une structure de ce type (valeurs fictives ; les clés Ed25519 sur TON sont de l'hex brut, sans le préfixe Ethereum 0x) :

{
  "version": "v5r1",
  "mnemonic": ["word1", "word2", "...", "word24"],
  "public_key": "e3f1a2…",
  "private_key": "9b7c4d…",
  "address": {
    "bounceable": "EQ…",
    "non_bounceable": "UQ…",
    "raw": "0:abcd…"
  }
}

Aucun SDK, aucune dérivation manuelle. Ensuite, c'est à vous de décider où stocker tout cela. Point essentiel : le serveur ne conserve ni cette mnémonique ni ces clés — on en parle plus bas dans la section sur le non-custodial.

Versions de wallet v3r2, v4, v5r1 et highload_v3 — laquelle choisir

generate_wallet prend en charge quatre versions de contrat de wallet. Ce n'est pas « plus récent = meilleur » : chacune a sa niche.

v5r1 (W5) — le choix par défaut pour les nouveaux projets

La version la plus récente. Elle prend en charge les extensions et les scénarios gasless — un relayeur tiers peut payer les frais à la place de l'utilisateur. C'est une propriété du contrat v5 lui-même, pas un service de TONNode : le serveur se contente de créer ce type de wallet, il ne fournit aucun relayeur gasless. Si vous construisez un agent moderne à partir de zéro et que vous n'avez pas spécifiquement besoin de highload — prenez v5r1.

v4 — la version à plugins

La génération grand public précédente. Elle prend en charge les plugins : on peut attacher au wallet des contrats-extensions (par exemple pour les abonnements et les paiements différés). Longtemps le standard de facto, largement supportée par les wallets et les services. À prendre si vous dépendez du modèle de plugins de v4.

v3r2 — le wallet de base, tout simple

Un contrat minimal, sans extensions ni plugins. Prévisible et économe en gas. Parfait pour les adresses utilitaires dont toute la logique se résume à « recevoir et envoyer ».

highload_v3 — pour les paiements de masse

Une classe à part. Un wallet conçu pour un débit élevé : un seul message externe peut transporter de nombreux transferts. C'est celui que vous prenez pour les paiements par lots, les drops, les distributions de récompenses, les passerelles de paiement, les retraits d'exchange. En contrepartie de cette efficacité, il repose sur un modèle de comptabilité des messages bien particulier (query_id / expiration) : il demande donc à être manipulé avec soin — voir la section sur la conservation des paramètres.

Version	Quand la choisir
v5r1	Nouveaux projets, extensions, gasless
v4	Besoin de plugins (abonnements, etc.), compatibilité maximale
v3r2	Wallet utilitaire simple, sans fioritures
highload_v3	Paiements de masse/par lots, débit élevé

Exemple de prompt pour les paiements :

Génère un wallet highload_v3 pour des paiements par lots et
renvoie la mnémonique, les clés et l'adresse.

Premier dépôt : pourquoi envoyer sur l'adresse non-bounceable UQ

L'erreur la plus fréquente — et la plus rageante — après la création d'un wallet, c'est de perdre le premier dépôt. La mécanique est la suivante : un wallet fraîchement créé n'est pas encore déployé sur la blockchain — le contrat n'existe physiquement pas à cette adresse tant qu'un premier transfert n'est pas venu y déployer le code.

Sur TON, une adresse porte un drapeau « bounceable » :

• EQ (bounceable) — s'il n'y a pas de contrat actif à l'adresse, le réseau renvoie (« bounce ») le transfert à l'expéditeur. Pour un wallet neuf, c'est exactement votre cas.
• UQ (non-bounceable) — le transfert « reste collé » à l'adresse, même si le contrat n'est pas encore déployé. Précisément ce qu'il faut pour le premier dépôt.

La règle est simple : le premier transfert d'approvisionnement d'un wallet neuf s'envoie sur l'adresse UQ. Sur EQ, il reviendra à l'expéditeur, et vous vous demanderez pourquoi le solde reste vide. Une fois que le wallet a émis sa première transaction sortante et s'est déployé, vous pouvez utiliser la forme bounceable en toute sérénité.

Comment obtenir la forme UQ de façon fiable ? Avec l'outil hors-ligne parse_address — il convertit et valide les formats EQ/UQ/raw sans interroger le réseau :

Via parse_address, convertis cette adresse en forme
non-bounceable UQ pour le premier dépôt

Après l'approvisionnement, vérifiez l'état via get_account_state — il indique le statut du compte (uninitialized / active), les drapeaux et la dernière transaction :

Vérifie get_account_state pour UQ… — le wallet est-il déployé
et quel est le solde

Tant que le contrat n'est pas actif, l'état vous dira que le dépôt n'a pas encore « réveillé » le wallet. Pour une analyse détaillée des formats, voir l'article sur les formats d'adresse EQ/UQ/raw.

Wallet highload : notez vous-même le subwallet_id et le timeout

Un avertissement à part pour ceux qui ont choisi highload_v3. Ici, la mnémonique seule ne suffit pas à recréer correctement un wallet fonctionnel et à reproduire son comportement. En plus de la clé, le contrat highload possède deux paramètres fixés à la création et inclus dans ses initial data (state init) :

• subwallet_id — l'identifiant de sous-wallet (permet d'obtenir plusieurs adresses distinctes à partir d'une même seed phrase) ;
• timeout — la fenêtre de vie des messages externes, sur laquelle repose la logique de query_id et d'expiration.

Important : generate_wallet renvoie la mnémonique, les clés et l'adresse — mais subwallet_id et timeout, c'est vous qui les choisissez et les fixez comme paramètres de construction du wallet highload. C'est à vous qu'il revient de noter les valeurs avec lesquelles le wallet a été créé.

Le wallet highload détermine quels messages sont encore « vivants » à partir du timeout. Si vous restaurez le wallet uniquement à partir de la seed phrase, sans subwallet_id ni timeout :

• vous obtiendrez la mauvaise adresse — subwallet_id et timeout font tous deux partie du state init, donc modifier l'un ou l'autre change les initial data du contrat, et par conséquent son adresse ;
• vous ne reproduirez pas la logique correcte d'expiration et de déduplication des messages — et vous risquez de casser le suivi des transferts sortants.

Règle pratique : pour highload_v3, stockez subwallet_id et timeout à côté de la mnémonique, dans un seul et même enregistrement de wallet. Ce ne sont pas des métadonnées optionnelles — c'est une partie de l'identité du wallet.

# pseudo-enregistrement du secret
mnemonic:      "word1 word2 … word24"
version:       "highload_v3"
subwallet_id:  <la valeur que vous avez définie à la création>
timeout:       <la valeur que vous avez définie à la création>

Pour v3r2/v4/v5r1, cette exigence n'existe pas — la mnémonique et la connaissance de la version suffisent.

Non-custodial : le serveur ne stocke ni ne signe les clés

La grande question, quand un wallet est créé « quelque part sur un serveur » : qui possède les clés au final ? Ici, la réponse est sans ambiguïté.

generate_wallet est strictement non-custodial :

• le serveur ne stocke jamais les clés privées, la mnémonique ni les fonds ;
• le serveur ne signe jamais de transactions à votre place ;
• le wallet généré — mnémonique, clés, adresse — vous est remis en intégralité dans la réponse et n'est pas conservé côté serveur.

Pas de base de données remplie de seed phrases d'autrui, pas de clé opérateur qui signe quoi que ce soit à votre place. Au fond, generate_wallet est une surcouche pratique autour d'une génération déterministe : la cryptographie s'exécute, le résultat part chez vous, et il ne reste rien au serveur. C'est la différence de principe avec les wallets d'agents custodial, où le service détient la clé (ou une partie) et signe lui-même les transactions. On analyse cette différence en détail dans custodial contre non-custodial en MCP.

Conclusion pratique : enregistrez immédiatement la réponse de generate_wallet dans votre propre stockage sécurisé. Le serveur ne pourra pas vous « ressortir » ce wallet une seconde fois — il ne s'en souvient pas, et le récupérer « via le support » sera impossible. C'est une fonctionnalité, pas un bug.

Comment se connecter et créer son premier wallet

La connexion prend une minute. Vous lancez le paquet @tonnode/mcp en local via npx, gratuitement ; l'ensemble des outils de lecture est accessible sans clé.

Config du client MCP (Claude Desktop, Cursor, n'importe quel client MCP) :

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

Le paquet @tonnode/mcp est open source (MIT), disponible sur npm et GitHub (tonnode/mcp), et fonctionne via le protocole natif ADNL de TON, sans couche HTTP intermédiaire entre votre agent et le réseau. Redémarrez le client — et les 16 outils, dont generate_wallet, parse_address et get_account_state, deviennent disponibles pour l'agent. Pour le brancher sur un client précis, suivez le guide de connexion de Claude et Cursor à TON.

generate_wallet fait partie des 16 outils et est disponible sur tous les plans, y compris le plan gratuit Hobby — 60 requêtes par minute, sans carte bancaire. La clé gratuite est délivrée immédiatement après connexion. Vous ne payez que pour le débit, jamais pour l'accès aux outils.

Ensuite, trois outils couvrent l'intégralité du scénario « créer puis approvisionner en sécurité » :

1. generate_wallet — créer le wallet dans la version voulue, récupérer mnémonique, clés, adresse.
2. parse_address — obtenir la forme UQ de l'adresse pour le premier dépôt (hors-ligne).
3. get_account_state — vérifier que le dépôt a bien déployé le contrat.

Exemple de prompt complet pour l'agent :

Crée un wallet v5r1 via generate_wallet. Ensuite, via
parse_address, donne-moi son adresse UQ pour le premier dépôt.
Une fois les coins envoyés, vérifie avec get_account_state
que le wallet est bien déployé.

Quand une clé hosted devient nécessaire

Le lancement local via npx utilise la config publique et convient parfaitement au développement. S'il vous faut un débit garanti sous charge (ces fameux paiements de masse en highload, par exemple), branchez l'endpoint hosted avec votre propre clé :

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

En résumé

• generate_wallet crée un wallet TON en un seul appel et renvoie la mnémonique, les clés privée/publique et l'adresse — un appel avec choix de version, pas un assemblage SDK à la main.
• La version par défaut pour un nouveau projet, c'est v5r1 ; pour les paiements de masse — highload_v3 ; v4 — pour les plugins ; v3r2 — quand il faut un wallet simple.
• Envoyez le premier dépôt sur l'adresse non-bounceable UQ, sinon il rebondira ; parse_address donne la forme UQ, et get_account_state vérifie l'état.
• Pour le highload, fixez vous-même subwallet_id et timeout et conservez-les avec la mnémonique — les deux font partie du state init et influent sur l'adresse.
• Le serveur est non-custodial : il ne stocke ni les clés ni les fonds, et ne signe aucune transaction à votre place — les clés sont à vous.

Prenez une clé Hobby gratuite et créez votre premier wallet via generate_wallet en deux minutes — tonnode.io/dashboard?plan=hobby.