Cómo llamar cualquier get-method de un contrato TON sin SDK

Abriste el explorador solo para consultar el seqno de tu wallet antes de enviar una transacción. O necesitas el total_supply de un jetton. O los datos de un listado NFT en un marketplace. Y ahí estás otra vez: npm i @ton/ton, levantar un TonClient, buscar un endpoint de liteserver que funcione, averiguar cómo empaquetar la dirección con beginCell().storeAddress() y, encima, parsear el BOC de salida a mano. Treinta líneas de código para un solo número que el contrato entrega gratis de todos modos.

El problema no es TON. El problema es que entre tú y una simple llamada read-only hay toda una capa de SDK que hay que instalar, configurar y no romper con la próxima actualización. Y si estás conectando a TON un agente de IA (Claude, Cursor, ChatGPT/Codex), escribir esa capa a mano es directamente absurdo: el agente debería simplemente llamar al método.

A continuación, cómo llamar cualquier get-method de un contrato TON con run_get_method, sin una sola línea de cliente SDK.

Qué es un get-method de un contrato TON y por qué suele arrastrar un SDK

Un get-method es una función read-only de un smart contract. La wallet expone seqno, el contrato maestro de un jetton expone get_jetton_data, el contrato de venta de un NFT expone get_sale_data, un pool de STON.fi/DeDust expone get_pool_data. La palabra clave es read-only:

• el método no cambia nada en el estado del contrato;
• no requiere firma y no gasta gas del usuario;
• se ejecuta en un liteserver o en el emulador de la TVM (TON Virtual Machine), no mediante el envío de una transacción.

Es decir, llamar a un get-method no es una transacción. No hay nada que firmar, nada que pagar, nada que esperar en un bloque. En esencia es una función del tipo «lee un valor del contrato en vivo».

Pero para llamarla «a la antigua» necesitas todo un andamiaje: un SDK (ton, tonweb, tonutils), tu propio cliente ADNL hacia un liteserver o un wrapper HTTP tipo toncenter, el ensamblado manual de los argumentos de entrada en celdas y el parseo manual del BOC de salida. Muchas piezas móviles para una sola lectura. Y cada una es un punto de fallo: los liteservers públicos del config global son compartidos y limitados, y bajo carga responden not ready o con timeout de ADNL; las API HTTP públicas, al superar el límite, devuelven 429 Too Many Requests (sin clave, aproximadamente una petición por segundo).

run_get_method: una sola herramienta para cualquier método read-only de cualquier contrato

run_get_method es una herramienta MCP que llama a cualquier get-method read-only de cualquier contrato TON. Pasas la dirección del contrato, el nombre del método y la lista de argumentos — la herramienta ejecuta el método on-chain vía TVM y devuelve el stack de salida.

Lo que no necesitas para eso:

• instalar y actualizar un SDK (ton/tonweb/tonutils);
• escribir tu propio cliente ADNL;
• empaquetar argumentos en celdas a mano ni parsear el BOC de salida.

run_get_method forma parte del set de lectura de TONNode, un servidor MCP hosted para TON. MCP (Model Context Protocol) es el estándar con el que los agentes de IA invocan herramientas. Todo el set de lectura está disponible gratis en local vía npx -y @tonnode/mcp (config pública, sin tarjeta), o a través del endpoint hosted https://mcp.tonnode.io/mcp con una clave Bearer. Puedes probarlo ahora mismo sin comprar nada.

Argumentos y stack: cómo pasar la entrada y leer la salida de la TVM

La TVM trabaja con un stack. Una analogía: pones sobre la mesa varias «tarjetas» con los valores de entrada, el método las toma, hace su trabajo y devuelve otras «tarjetas» con el resultado.

La entrada se pasa como valores en el stack de la TVM. Normalmente son:

• int — enteros (por ejemplo, un índice, una cantidad en unidades raw, un query id);
• una dirección como slice — la dirección empaquetada en un slice de celda;
• cell — una celda de datos arbitraria.

La salida vuelve como un stack de valores: int, slice, cell, tuple. El agente lo lee por posiciones — primer valor, segundo, tercero. Por ejemplo, get_jetton_data devuelve en orden: total_supply (int), el flag mintable, admin (dirección como slice), content (cell) y el código de la wallet (cell). La posición determina el significado — es parte del convenio ABI del propio contrato.

Muchos métodos útiles (seqno, get_jetton_data) no requieren entrada alguna: el stack de argumentos va vacío. Los argumentos aparecen cuando el método busca algo por clave: por ejemplo, calcular la dirección de la jetton wallet a partir de la dirección del dueño.

Un matiz importante: run_get_method devuelve el stack crudo en unidades raw. Los números llegan tal cual, sin conversión por decimals y sin transformar las celdas en cadenas legibles. Es flexible, pero exige entender qué estás leyendo — volveremos a esto en la sección sobre get_jetton_info.

exit_code: cómo saber si el método terminó bien

Cada llamada a un get-method tiene un exit_code, el código de terminación de la TVM. Solo tiene sentido leer el stack de salida si la llamada fue exitosa. La regla para los get-methods es contraintuitiva y vale la pena memorizarla:

• exit_code 0 y 1 son éxito (ambos cuentan como terminación normal, así que no te asustes con el uno);
• exit_code > 1 es error, y no puedes confiar en el stack de salida.

Códigos de error frecuentes:

exit_code	Qué significa
2	stack underflow — se pasaron menos argumentos de los que el método espera
4	integer overflow / división por cero
11	normalmente, llamada a un método inexistente (typo en el nombre)
13	out of gas

En la práctica: si recibes 2, revisa que pasaste todos los argumentos y en el orden correcto. Si recibes 11, lo más probable es un typo en el nombre del método o que el contrato no lo implementa. Si recibes 13, el método es pesado y chocó contra el límite de gas.

Ejemplos vía agente: seqno, get_jetton_data, get_sale_data

Lo mejor es cuando quien llama a run_get_method no es una persona, sino un agente. Formulas la tarea con palabras; el agente elige por sí mismo la dirección, el nombre del método y los argumentos, recibe el stack y te explica los campos.

seqno antes de enviar. El seqno es el número de transacción saliente de la wallet; se lee antes de armar una transferencia: sin él, el mensaje no pasa.

Prompt al agente: «Llama a seqno en mi wallet UQD… y dime el número actual».

El agente invoca run_get_method sin argumentos, recibe un único int en el stack de salida y te entrega el número.

get_jetton_data — metadatos del contrato maestro del jetton. El método devuelve total_supply, el flag mintable, la dirección del admin y content.

Prompt al agente: «Ejecuta get_jetton_data en este contrato maestro de USDT y desglosa los campos».

El agente llama a run_get_method con la dirección del contrato maestro y el nombre get_jetton_data, lee el stack y explica las posiciones. Aquí hay un matiz importante — lo vemos más abajo.

get_sale_data — datos de un listado NFT. No es una herramienta NFT aparte, sino el mismo run_get_method: lees el get-method propio del contrato de venta del marketplace. get_sale_data devuelve el precio, el vendedor y el estado de la operación — útil para saber si el NFT ya se vendió o sigue en venta.

Prompt al agente: «Lee get_sale_data de este contrato de venta y dime el precio en GRAM».

No escribes ningún cliente. El agente llama a una sola herramienta. Otros métodos habituales — get_wallet_data (datos de la jetton wallet), get_pool_data (pools de STON.fi/DeDust) — se invocan exactamente igual: nombre del método, dirección y, si hace falta, argumentos.

get_jetton_data o get_jetton_info: cuándo necesitas una respuesta legible

Aquí está la trampa principal. run_get_method devuelve el stack crudo: get_jetton_data te dará el total_supply como un entero gigantesco en unidades raw, y content como una celda de la que todavía hay que extraer el nombre y el símbolo. Nada de «USDT», «6 decimals» ni un número bonito — es salida de bajo nivel de la TVM. Si necesitas justamente acceso de bajo nivel al contrato maestro o un campo no estándar, esta es tu herramienta.

Pero si lo que necesitas es simplemente el nombre, el símbolo y los decimals del jetton, no te compliques parseando celdas. Para eso existe una herramienta aparte: get_jetton_info — devuelve nombre, símbolo, decimals y la emisión ya parseados.

Por qué esto es crítico: los decimals hacen falta para convertir unidades raw en cantidades reales. USDT en la red TON tiene decimals = 6; la mayoría de los jettons, 9. Si tomas el total_supply crudo de get_jetton_data y no lo divides entre 10^decimals, obtendrás un número que difiere del real por un factor de un millón o mil millones. Más sobre esta trampa en el desglose de los decimals de los jettons en TON.

La regla es simple:

• necesitas los campos crudos del contrato (emisión, admin, content, un método custom arbitrario) → run_get_method + get_jetton_data;
• necesitas una respuesta legible y lista sobre el jetton (nombre, símbolo, decimals) → get_jetton_info.

No confundas los números raw de get_jetton_data con la respuesta lista de get_jetton_info.

Dos apoyos útiles: parse_address y get_account_state

Antes de llamar al método conviene poner orden con la dirección y confirmar que el contrato siquiera está vivo:

• parse_address — normaliza la dirección entre los formatos EQ/UQ/raw, offline, sin tocar la red. TON tiene varios formatos y no todos los métodos aceptan cualquiera de ellos; es cómodo convertir el EQ… del usuario al formato adecuado antes de pasarlo como argumento.
• get_account_state — comprueba el estado, los flags y la última transacción del contrato. Si la cuenta no está desplegada (uninit) o está congelada, cualquier get-method fallará de forma predecible — sale más barato verificar el estado antes que cazar un exit_code incomprensible.

Cómo conectarlo y llamarlo sin una sola línea de cliente

Hay dos caminos. El primero: gratis en local, todo el set de lectura con la config pública, sin tarjeta:

{
  "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 intermedias. Sobre la vía gratuita hay un desglose aparte: MCP para TON gratis.

El segundo: el endpoint hosted con capacidad garantizada y tu propia clave:

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

En todos los planes están disponibles las 16 herramientas — solo pagas por la capacidad. La clave gratuita Hobby (60 peticiones/min) se emite justo después de iniciar sesión, sin tarjeta.

Tras conectarlo, todo el set de lectura — incluidos run_get_method, get_jetton_info, parse_address y get_account_state — queda disponible para el agente como herramientas normales. La llamada parece una frase normal del chat: «ejecuta get_pool_data en este pool de DeDust», «lee el seqno de esta wallet» — y el agente elegirá por su cuenta run_get_method y los argumentos, y te explicará los campos. Y si la tarea es conocer un saldo de USDT, hay un camino directo de un solo comando: saldo de USDT en TON con una sola llamada.

---

Consigue tu clave gratuita Hobby y llama a run_get_method directamente desde tu agente → tonnode.io/dashboard?plan=hobby. La clave se emite justo después de iniciar sesión, sin tarjeta, 60 peticiones por minuto — más que de sobra para leer contratos.

¿No quieres ni registrarte? Lánzalo en local: npx -y @tonnode/mcp. La lista completa de herramientas y sus parámetros está en tonnode.io/mcp.

Leer el estado de la blockchain ya no significa montar un cliente. Significa formular la petición.