Cómo crear un agente de trading en TON: leer, cotizar, swapear

El problema con el que arranca cualquier agente de trading en TON

Le pides a un agente de IA «swapea 50 USDT a GRAM cuando el precio baje» — y manda una transacción de 50 000 USDT en lugar de 50. ¿Por qué? Porque el USDT de TON tiene decimals = 6 (50 USDT = 50 000 000 unidades raw), y el agente calculó por defecto como si fuera un jetton normal de nueve ceros: puso en el monto 1000 veces más de lo debido. Un error de 1000x, con dinero real, en una transacción irreversible. El error inverso tiene exactamente la misma raíz: el agente ve un 1000000000 crudo en el balance y reporta convencido «tienes mil millones de USDT», cuando ahí hay 1000.

No son historias de terror inventadas: son justo las piedras con las que tropieza todo el que conecta un LLM al DeFi de TON directamente por RPC crudo — decimals confundidos, balances de jettons que no se pueden leer sin la dirección de la jetton wallet, claves privadas que se filtran por el contexto. A continuación, cómo montar un agente de trading en TON (trading agent TON) que lee balances, obtiene una cotización en firme y arma un swap sin tocar tus claves ni una sola vez. La herramienta: TONNode, servidor MCP hosted para TON.

Qué es un agente de trading en TON y para qué necesita MCP

Un agente de trading es un LLM (Claude, Cursor, Codex o cualquier otro cliente MCP) capaz de leer el estado de la red y preparar operaciones a petición del usuario: «muéstrame mi balance de USDT», «cuánto GRAM recibo por 500 USDT», «arma el swap». Por sí solo el modelo no ve la blockchain: necesita herramientas.

Y de eso se encarga justamente MCP (Model Context Protocol), el estándar con el que los agentes invocan herramientas externas. En lugar de enseñarle al modelo a componer peticiones ADNL crudas y a parsear celdas BOC, le entregas un conjunto de funciones tipadas: «dame el balance», «dame una cotización», «arma la transacción». TONNode se conecta como fuente de esas herramientas y le da al agente exactamente 16 funciones para trabajar con la red: lectura, swap, cross-chain y generación de wallet.

De esas, un agente de trading necesita cinco, y las cinco están disponibles incluso en el plan gratuito:

leer (get_balance, get_jetton_balance)
   -> precisar decimals (get_jetton_info)
      -> cotizar (get_swap_quote)
         -> armar el swap (build_swap_tx)
            -> la wallet firma vía TonConnect

El detalle clave del último paso: quien firma es la wallet del usuario, no el servidor. TONNode devuelve mensajes sin firmar, y al final del artículo veremos por qué eso es una cuestión de fondo y no un detalle.

Paso 1: el agente lee balances (get_balance, get_jetton_balance)

Antes de swapear nada, el agente tiene que saber de qué dispone. Dos herramientas:

• get_balance — el balance de GRAM en una dirección. GRAM es el Toncoin renombrado en junio de 2026; la red sigue llamándose TON.
• get_jetton_balance — el balance de un jetton: USDT, NOT, el que sea. La magia aquí es que la jetton wallet se calcula on-chain. Pasas la dirección del propietario y la dirección master del jetton, y TONNode deriva por sí mismo la dirección de la jetton wallet y lee su balance. No hace falta conocer esa dirección de antemano ni guardarla en ningún sitio.

El prompt al agente es literalmente así:

Revisa el balance de la wallet UQAbc...xyz:
¿cuánto GRAM tiene y cuánto USDT?

Por debajo, el modelo llama a get_balance para el balance nativo y a get_jetton_balance para el USDT. Solo hay un pero: lo que devuelven todavía no son montos «humanos», sino unidades raw. Y aquí empieza lo más importante. Sobre cómo obtener el balance de USDT con una sola llamada, sin bailes con direcciones de jetton wallet, hay un análisis aparte: /blog/usdt-balance-ton-one-call.

Los decimals lo deciden todo: get_jetton_info y por qué USDT = 6

Los balances y montos en TON se guardan en unidades raw: enteros, sin parte fraccionaria. Para obtener un monto legible por humanos hay que dividir el número crudo entre 10^decimals. Y ahí está la trampa: cada jetton tiene su propio número de decimals.

• USDT tiene decimals = 6. Es decir, 1 USDT = 1 000 000 unidades raw.
• La mayoría de los jettons en TON tienen decimals = 9 (como GRAM). Es decir, 1 jetton = 1 000 000 000 unidades raw.

Confundir 6 con 9 es equivocarse en el monto exactamente 1000 veces. Ese «mil millones de USDT» del principio del artículo. Para un agente de trading esto no es cosmética, es la raíz de la confianza: si confunde órdenes de magnitud, no se le puede dejar armar operaciones.

Por eso en el pipeline se intercala get_jetton_info, que devuelve los metadatos del jetton: nombre, símbolo, emisión y — lo más importante — decimals. La lógica correcta dentro del agente:

raw       = get_jetton_balance(...)   // por ejemplo, 1000000000
decimals  = get_jetton_info(...)      // para USDT → 6
human     = raw / 10 ** decimals      // 1000000000 / 1e6 = 1000 USDT

El mismo raw con decimals = 9 habría dado 1 token: la diferencia es colosal. No hardcodees los decimals en el prompt ni dejes que el modelo los «adivine» de memoria: con un jetton nuevo se equivocará. Que los consulte con get_jetton_info cada vez y recalcule sobre el dato real. En detalle sobre esta trampa y por qué le cuesta dinero a la gente: /blog/jetton-decimals-ton.

Paso 2: cotización en firme vía Omniston (get_swap_quote)

Balances leídos y convertidos a las unidades correctas: ahora el agente necesita un precio. En DeFi el «precio aproximado de cabeza» no funciona: la liquidez está repartida entre varios DEX, el tipo de cambio se mueve y el agente debe apoyarse en una cotización actual, no en una suposición.

get_swap_quote da una cotización en firme para un swap GRAM ⇄ jetton a través del protocolo Omniston, que agrega a la vez la liquidez de los dos DEX más grandes de TON: STON.fi y DeDust. El agente no tiene que consultar pools por su cuenta, comparar precios ni calcular el slippage: Omniston devuelve la mejor ruta a partir de la liquidez combinada.

Dame una cotización: ¿cuánto GRAM recibo por 50 USDT ahora mismo?

El modelo llama a get_swap_quote con el monto 50000000 (esas mismas unidades raw del paso anterior) y recibe números concretos: cuánto entra, cuánto sale, por qué ruta y con qué slippage. Este es el punto de decisión: si el agente tiene una condición («swapea solo si el precio es mejor que X»), compara la cotización con el umbral y o bien sigue adelante, o bien espera a la siguiente iteración. Importante: una cotización todavía no es una operación. No se mueve ningún fondo, no se firma nada. Es lectura pura del mercado.

Paso 3: armar el swap sin firmar (build_swap_tx) y firmar en la wallet

El usuario ve la cotización y dice «sí, swapeamos». El agente llama a build_swap_tx y recibe una transacción sin firmar del swap, lista para TonConnect.

Subrayo lo de «sin firmar». El servidor arma el mensaje correcto — dirección del destinatario, payload, monto, parámetros de la ruta — y lo devuelve tal cual. Desde ahí, el mensaje va a la wallet del usuario (Tonkeeper, MyTonWallet, cualquiera compatible con TonConnect), el usuario ve exactamente qué está firmando y confirma él mismo. La firma la pone la clave privada del usuario, que vive en su wallet, no en el servidor.

get_balance / get_jetton_balance   →  leer lo que hay
        ↓
get_jetton_info                     →  precisar decimals, recalcular
        ↓
get_swap_quote (Omniston)           →  cotización en firme
        ↓
build_swap_tx                       →  transacción sin firmar
        ↓
wallet del usuario (TonConnect)     →  firma y envío

Cada paso es una llamada de herramienta explícita e independiente. El agente no «se toma libertades» con el dinero: él prepara, y la decisión y la firma quedan del lado de la persona. El escenario completo de un swap no custodial, de la cotización a la firma, está desglosado paso a paso aquí: /blog/agent-swap-ton-noncustodial.

No custodial: por qué el servidor nunca guarda las claves del agente

No es una frase de marketing, es una frontera arquitectónica. En TONNode, las herramientas de swap, cross-chain y generación de wallet son estrictamente no custodiales:

• El servidor nunca firma transacciones.
• El servidor nunca guarda claves privadas ni fondos.
• Todo lo que entrega hacia fuera son mensajes TonConnect sin firmar.

¿Por qué importa esto precisamente para un agente de trading? Porque el agente, por definición, trabaja con dinero y, por definición, puede equivocarse: entender mal la petición, confundir el monto, entrar en un bucle. Si las claves vivieran en el servidor y fuera él quien firmara, un error del agente significaría perder fondos sin que te enteres. En el esquema no custodial, la última línea de defensa eres tú: ninguna transacción sale hasta que tu wallet la confirma.

Compáralo con el @ton/mcp oficial de la TON Foundation — es una agent wallet custodial: guarda la clave operator y firma por sí misma (esquema split-key, donde la clave operator la tiene el agente y la clave owner el usuario). Tiene sus puntos fuertes — gasto autónomo sin intervención humana, soporte de NFT y DNS, estatus oficial de la Foundation. Pero el modelo de confianza es otro: ahí el agente sí puede mover fondos de verdad. TONNode elige a conciencia la frontera opuesta: el servidor no firma absolutamente nada. La comparación desarrollada de ambos enfoques: /blog/custodial-vs-noncustodial-mcp.

Cómo conectarlo y por dónde empezar en 5 minutos

Buena noticia: para montar el pipeline de trading no hace falta pagar. Pero conviene no confundir las dos vías gratuitas: traen conjuntos de herramientas distintos.

La config pública local ofrece el conjunto completo de lectura (8 herramientas: get_masterchain_info, get_balance, get_account_state, get_transactions, run_get_method, get_jetton_balance, parse_address, get_jetton_info). Se instala vía npx, sin clave:

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

El paquete @tonnode/mcp es open source (MIT), está en npm y GitHub (tonnode/mcp) y funciona por el protocolo nativo ADNL de TON, sin capas HTTP entre el agente y la red. Pegas la config en Claude Desktop, Cursor o cualquier cliente MCP — y el agente ya sabe leer balances y llamar a get_jetton_info.

En cambio, las cotizaciones — get_swap_quote y build_swap_tx — pertenecen al grupo SWAP y van por el endpoint hosted. Punto clave: con la clave gratuita Hobby están disponibles las 16 herramientas, incluidas la cotización y el armado del swap. Es decir, todo el pipeline de trading (lectura → cotización → swap) se monta gratis, pero precisamente con la clave hosted de Hobby, no con la config pública local. La config para el endpoint hosted:

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

TONNode tiene exactamente 16 herramientas, y en todos los planes están disponibles las 16 — pagas solo por el volumen de peticiones, no por la funcionalidad:

• Hobby — gratis para siempre, 60 peticiones/min, sin tarjeta.
• Pro — $29/mes, 300 peticiones/min.
• Scale — $199/mes, 1200 peticiones/min.

Para arrancar y rodar el pipeline de trading, la clave gratuita Hobby sobra: 60 peticiones por minuto son muchas llamadas consecutivas de un agente. No hace falta tarjeta, la clave se entrega nada más iniciar sesión.

Consigue tu clave Hobby gratis (60 req/min, sin tarjeta): tonnode.io/dashboard?plan=hobby

Lista completa de las 16 herramientas: tonnode.io/mcp · Planes: tonnode.io/pricing

---

Monta el pipeline con cinco herramientas — get_balance, get_jetton_balance, get_jetton_info, get_swap_quote, build_swap_tx — mantén los decimals bajo control y deja la firma a la wallet. Así consigues un agente de trading que lee balances de forma honesta, obtiene una cotización en firme y prepara un swap con montos reales, sin acceder ni un segundo a claves ajenas. Exactamente así debe funcionar un agente de trading en TON.