TON JSON-RPC: Endpoint, métodos y cómo usarlo

Guía rápida de decisión: ¿qué configuración de TON RPC se adapta a tu aplicación?

Antes de conectar un cliente, decide qué modelo de acceso a TON RPC se ajusta a tu carga de trabajo. La elección afecta la latencia, los límites de tasa y cuánta infraestructura gestionas.

Si necesitas un endpoint gestionado con rendimiento predecible, OnFinality ofrece endpoints TON RPC y TON Testnet RPC con soporte JSON-RPC HTTPS. Para cargas de trabajo de producción, un servicio gestionado elimina la carga operativa de ejecutar tu propio nodo. Consulta precios de RPC para más detalles.

¿Qué es TON JSON-RPC?

TON JSON-RPC es una interfaz JSON-RPC 2.0 para The Open Network (TON), una blockchain de capa 1 no EVM. A diferencia del JSON-RPC de Ethereum, la interfaz de TON no es compatible con EVM y utiliza su propio conjunto de métodos. Proporciona un único endpoint HTTPS donde puedes llamar métodos para leer datos de la blockchain, ejecutar métodos get de contratos inteligentes y enviar transacciones.

Los nodos TON se comunican internamente mediante el protocolo binario ADNL, que no es directamente accesible desde aplicaciones web. TON JSON-RPC actúa como un puente, traduciendo solicitudes HTTP JSON-RPC estándar en llamadas a nodos y devolviendo resultados en un formato familiar.

Endpoint y autenticación de TON JSON-RPC

El endpoint principal de TON JSON-RPC es proporcionado por TON Center:

• Mainnet: https://toncenter.com/api/v2/jsonRPC
• Testnet: https://testnet.toncenter.com/api/v2/jsonRPC

Todos los métodos de la API están disponibles a través de este único endpoint. Te autenticas enviando una clave API en el encabezado X-API-Key. Sin una clave, las solicitudes se limitan a 1 solicitud por segundo. Con una clave, los límites son más altos pero aún se aplican.

Ejemplo de solicitud:

curl -X POST "https://toncenter.com/api/v2/jsonRPC" \
  -H "X-API-Key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getMasterchainInfo",
    "params": {}
  }'

Respuesta:

{
  "ok": true,
  "result": {
    "last": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 123456,
      "root_hash": "...",
      "file_hash": "..."
    },
    "state_root_hash": "...",
    "init": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 0,
      "root_hash": "...",
      "file_hash": "..."
    }
  },
  "@extra": "...",
  "jsonrpc": "2.0",
  "id": "1"
}

Métodos comunes de TON JSON-RPC

TON JSON-RPC expone un conjunto de métodos que se asignan a la API v2 de TON Center. Estos son los más utilizados:

Para una lista completa, consulta la documentación oficial de TON.

Usar TON JSON-RPC con JavaScript

Puedes llamar a TON JSON-RPC desde cualquier lenguaje. Aquí tienes un ejemplo en JavaScript usando fetch:

const endpoint = "https://toncenter.com/api/v2/jsonRPC";
const apiKey = "TU_CLAVE_API";

async function callTonRpc(method, params = {}) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method,
      params
    })
  });
  return response.json();
}

// Obtener saldo de una dirección
const balance = await callTonRpc("getAddressBalance", {
  address: "EQD..."
});
console.log(balance.result);

TON JSON-RPC vs API REST

TON Center ofrece endpoints REST y JSON-RPC. La API REST utiliza URLs separadas para cada método (por ejemplo, /getAddressBalance), mientras que JSON-RPC utiliza un único endpoint con un campo method. JSON-RPC es útil cuando deseas agrupar múltiples llamadas o prefieres una interfaz consistente.

TON RPC público vs gestionado vs dedicado

Al usar TON JSON-RPC, tienes tres opciones principales:

1. Endpoints públicos – Gratuitos pero con límites de tasa (1 RPS sin clave). Buenos para pruebas y aplicaciones de bajo tráfico.
2. Servicios RPC gestionados – Proporcionan endpoints confiables con límites de tasa más altos, monitoreo y soporte. OnFinality ofrece TON RPC como servicio gestionado.
3. Nodos dedicados – Obtienes tu propio nodo TON, control total sobre la configuración y sin límites de tasa compartidos. Ideal para alto rendimiento o casos de uso personalizados.

Solución de problemas comunes de TON JSON-RPC

• 401 No autorizado: Verifica tu clave API y asegúrate de que sea válida.
• 403 Prohibido: Tu clave API puede no tener permiso para el método solicitado.
• 429 Demasiadas solicitudes: Has superado el límite de tasa. Espera o mejora tu plan.
• 422 Entidad no procesable: Los parámetros de tu solicitud son inválidos. Verifica la firma del método.
• 500 Error interno del servidor: El nodo puede estar experimentando problemas. Inténtalo de nuevo más tarde.
• 504 Tiempo de espera de la puerta de enlace: La solicitud tardó demasiado. Considera usar un nodo dedicado para consultas pesadas.

Conclusiones clave

• TON JSON-RPC es una interfaz JSON-RPC 2.0 para The Open Network, que utiliza un único endpoint HTTPS.
• La autenticación se realiza mediante el encabezado X-API-Key; sin una clave, estás limitado a 1 RPS.
• Los métodos comunes incluyen getMasterchainInfo, getAddressBalance y runGetMethod.
• Elige RPC público, gestionado o dedicado según tu carga de trabajo y necesidades de confiabilidad.
• Para producción, considera un servicio gestionado como el TON RPC de OnFinality para evitar límites de tasa y carga operativa.

Preguntas frecuentes

¿Es TON JSON-RPC compatible con Ethereum JSON-RPC? No. TON es una blockchain no EVM, por lo que sus métodos JSON-RPC son diferentes. No puedes usar eth_getBalance u otros métodos EVM.

¿Cómo obtengo una clave API de TON? Puedes obtener una clave de TON Center registrando tu aplicación. Proveedores gestionados como OnFinality también proporcionan claves API con sus endpoints.

¿Puedo usar WebSocket con TON JSON-RPC? TON JSON-RPC se basa en HTTP. Para actualizaciones en tiempo real, TON ofrece una API de Streaming separada con soporte WebSocket.

¿Cuál es el límite de tasa para TON JSON-RPC? Sin una clave API, el límite es de 1 solicitud por segundo. Con una clave, los límites son más altos pero varían según el proveedor.

¿Cómo envío una transacción usando TON JSON-RPC? Debes serializar tu transacción en una bolsa de celdas y usar el método sendBoc. Esto es más complejo que las transacciones EVM.

Para más detalles, explora redes RPC compatibles y precios de RPC.