API HTTP de Solana: ¿Cómo se conecta, firma y depura llamadas JSON-RPC?

La API HTTP de Solana es la interfaz JSON-RPC que utiliza tu aplicación para comunicarse con un nodo de Solana a través de HTTPS. Cada consulta de saldo de billetera, lectura de cuenta, envío de transacción y consulta de bloque pasa por una solicitud POST a un endpoint RPC. Si estás construyendo sobre Solana, esta es la capa que depurarás con más frecuencia.

Esta página se centra en el lado práctico: la estructura de la solicitud, los métodos que realmente llamarás, cómo los niveles de compromiso cambian los resultados y cómo leer los errores que devuelve. También te ayuda a decidir si un endpoint compartido es suficiente o si tu carga de trabajo necesita un nodo dedicado de Solana.

¿Con qué endpoint deberías empezar?

Comienza con el endpoint público oficial de OnFinality para Solana mainnet:

https://solana.api.onfinality.io/public

Ese endpoint es adecuado para desarrollo local, scripts y lecturas de bajo volumen. Pasa a un endpoint dedicado o privado cuando encuentres alguna de estas señales:

• Estás enviando transacciones a un ritmo constante y ves respuestas 429 intermitentes.
• Necesitas acceso consistente al estado histórico de cuentas o escaneos grandes de getProgramAccounts.
• Ejecutas indexadores, bots o backends que consultan las mismas cuentas cada pocos segundos.
• Necesitas suscripciones WebSocket para cambios de cuenta o slot junto con llamadas HTTP.

Si tu carga de trabajo es intensiva en lecturas y a ráfagas, un plan RPC compartido normalmente es suficiente. Si tu carga de trabajo es continua y sensible a la latencia, un nodo dedicado de Solana te da capacidad aislada. Puedes comparar opciones en la página de precios de RPC y ver la lista completa de redes RPC compatibles.

La estructura de la solicitud

Cada llamada a la API HTTP de Solana es un POST JSON-RPC 2.0. El cuerpo tiene cuatro campos: jsonrpc, id, method y params.

curl https://solana.api.onfinality.io/public \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBalance",
    "params": [
      "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"
    ]
  }'

La respuesta devuelve un objeto result en caso de éxito, o un objeto error con un code y un message en caso de fallo. El id que envías se devuelve, lo cual importa cuando agrupas solicitudes.

Algunas cosas que suelen confundir:

• params siempre es un array, incluso para un solo argumento.
• Algunos métodos toman un objeto de opciones como segundo elemento, por ejemplo {"commitment": "confirmed"}.
• El encabezado Content-Type debe ser application/json.

Métodos que llamarás con más frecuencia

No necesitas memorizar la lista completa de métodos. La mayoría de las aplicaciones de Solana usan un conjunto pequeño repetidamente.

getProgramAccounts merece una advertencia. Puede ser costoso en programas grandes y suele ser la primera llamada que expira o recibe limitación de tasa en endpoints compartidos. Si dependes de él, planifica un nodo dedicado o una fuente de datos indexada.

Los niveles de compromiso cambian lo que recibes

Solana no tiene un único estado "confirmado". Eliges un nivel de compromiso por solicitud, y esto cambia tanto el resultado como la latencia.

Para una billetera que muestra un saldo, confirmed suele ser lo correcto. Para cualquier cosa que mueva fondos o active lógica de negocio irreversible, espera a finalized. Si mezclas niveles de compromiso entre llamadas, puedes obtener lecturas inconsistentes, por ejemplo un saldo que aparece antes de la transacción que lo modificó.

Leer errores en lugar de adivinar

Cuando falla una llamada a la API HTTP de Solana, el objeto de error te dice dónde buscar. La siguiente tabla asigna síntomas comunes a la causa probable y el siguiente paso.

Un hábito útil es registrar el objeto de error completo, no solo el mensaje. El campo data a menudo contiene logs de la transacción fallida, lo que normalmente apunta directamente al error del programa.

Construir y enviar una transacción

La API HTTP no firma transacciones por ti. Construyes y firmas localmente, luego envías los bytes firmados. Un flujo mínimo en JavaScript se ve así:

import { Connection, PublicKey, Transaction, SystemProgram } from "@solana/web3.js";

const connection = new Connection("https://solana.api.onfinality.io/public", "confirmed");

const from = new PublicKey("<YOUR_WALLET_PUBLIC_KEY>");
const to = new PublicKey("<RECIPIENT_PUBLIC_KEY>");

const { blockhash } = await connection.getLatestBlockhash("confirmed");

const tx = new Transaction().add(
  SystemProgram.transfer({ fromPubkey: from, toPubkey: to, lamports: 1_000_000 })
);
tx.recentBlockhash = blockhash;
tx.feePayer = from;

// Sign with your wallet adapter or keypair, then:
const signature = await connection.sendRawTransaction(tx.serialize());
await connection.confirmTransaction(signature, "confirmed");

Dos detalles importan aquí. Primero, siempre obtén un blockhash nuevo inmediatamente antes de enviar, porque los blockhashes expiran. Segundo, confirma la firma en lugar de asumir que el envío equivale al éxito.

HTTP versus WebSocket

HTTP es solicitud-respuesta. WebSocket es una conexión persistente que envía actualizaciones. Usa HTTP para lecturas y envío de transacciones. Usa WebSocket cuando necesites reaccionar a cambios sin sondeo.

const subId = connection.onAccountChange(
  new PublicKey("<ACCOUNT_PUBLIC_KEY>"),
  (accountInfo) => {
    console.log("Account changed:", accountInfo.lamports);
  },
  "confirmed"
);

OnFinality expone el transporte WebSocket para Solana junto con HTTP, para que puedas mantener ambos en el mismo proveedor. Si tu aplicación consulta la misma cuenta cada pocos segundos, cambiar a una suscripción normalmente reduce la carga y mejora el tiempo de reacción.

Cuándo dejar un endpoint público

Un endpoint público es un punto de partida, no un plan de producción. La decisión suele reducirse a tres preguntas:

1. ¿Tu tráfico es continuo u ocasional? El tráfico continuo necesita capacidad aislada.
2. ¿Dependes de llamadas costosas como getProgramAccounts o lecturas históricas? Esas necesitan margen.
3. ¿Necesitas un comportamiento predecible bajo carga? Los endpoints compartidos son de mejor esfuerzo por naturaleza.

Si respondes sí a más de una, considera un nodo dedicado. La infraestructura dedicada le da a tu aplicación su propia capacidad, lo que elimina el problema del vecino ruidoso y hace que el comportamiento de los límites de tasa sea predecible. OnFinality proporciona tanto acceso a la API RPC como opciones de nodos dedicados, para que puedas empezar compartido y escalar sin cambiar tu integración.

Para devnet y pruebas, usa la página RPC de Solana Devnet para configurar un endpoint separado y que el tráfico de pruebas nunca compita con producción.

Comprobaciones operativas antes de lanzar

Antes de dirigir usuarios reales a tu configuración de API HTTP de Solana, confirma estos aspectos básicos:

• Tu endpoint es configurable mediante una variable de entorno, no está codificado.
• Tienes un endpoint o proveedor de respaldo para conmutación por error.
• Registras IDs de solicitud y códigos de error para soporte.
• Monitoreas getSlot o getHealth de forma programada para detectar bloqueos a tiempo.
• Agrupas lecturas independientes en lugar de dispararlas una a una.
• Manejas respuestas 429 con retroceso exponencial.

Una sonda de estado simple se ve así:

curl -s https://solana.api.onfinality.io/public \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

Si getHealth devuelve "ok", el nodo está respondiendo. Combínalo con una comprobación de slot para confirmar que el nodo realmente está avanzando.

Puntos clave

• La API HTTP de Solana es JSON-RPC sobre HTTPS: envía un cuerpo JSON por POST, obtén un resultado JSON o un error.
• params siempre es un array, y opciones como el compromiso van en un segundo elemento.
• El nivel de compromiso cambia tanto la latencia como la seguridad; usa finalized para acciones irreversibles.
• Las llamadas costosas como getProgramAccounts son las primeras en fallar en endpoints compartidos.
• Usa HTTP para lecturas y envío, WebSocket para suscripciones.
• Pasa a un nodo dedicado cuando el tráfico sea continuo o sensible a la latencia.

Preguntas frecuentes

¿La API HTTP de Solana es lo mismo que JSON-RPC?

Sí. Cuando la gente dice API HTTP de Solana, se refiere a la interfaz JSON-RPC servida sobre HTTPS. El transporte es HTTP, el formato de carga útil es JSON-RPC 2.0.

¿Cuál es el nivel de compromiso predeterminado?

Si no pasas una opción de compromiso, la mayoría de los métodos usan finalized por defecto. Muchas aplicaciones establecen explícitamente confirmed para lecturas más rápidas.

¿Por qué recibo respuestas 429?

Un 429 significa que alcanzaste un límite de tasa, lo cual es común en endpoints públicos compartidos. Reduce el volumen de solicitudes, agrupa lecturas o pasa a un nodo dedicado.

¿Puedo usar el mismo endpoint para mainnet y devnet?

No. Mainnet y devnet son clústeres separados con endpoints separados. Mantenlos en configuraciones separadas para que el tráfico de pruebas nunca toque producción.

¿Necesito WebSocket si ya uso HTTP?

Solo si necesitas actualizaciones push. Si consultas la misma cuenta repetidamente, una suscripción WebSocket suele ser más eficiente.

¿Cómo depuro una transacción fallida?

Ejecuta simulateTransaction y lee los logs en el campo data del error. El código de error del programa normalmente identifica la causa.

Próximos pasos

Si aún estás evaluando, comienza con el endpoint público anterior y mide tus patrones de solicitud durante una semana. Si ves límites de tasa, tiempos de espera en consultas grandes o necesitas suscripciones WebSocket, revisa precios de RPC y la página de la red Solana para elegir un plan que se ajuste a tu carga de trabajo. Para equipos con tráfico continuo, un nodo dedicado elimina el techo de capacidad compartida y mantiene predecibles tus llamadas a la API HTTP de Solana.