Documentación de la API RPC de Solana: Endpoints, Métodos y Ruta de Depuración

Solana no expone una API REST para datos de la cadena. Todo lo que tu aplicación lee o escribe pasa por un único endpoint JSON-RPC, lo que significa que el endpoint que eliges y los métodos que llamas determinan tu latencia, tu tasa de errores y tu factura. Esta página es una referencia práctica para esa interfaz: cómo se estructuran las solicitudes, qué métodos importan, cómo se comportan las suscripciones y cómo depurar los fallos que encontrarás una vez que llegue el tráfico real.

¿A qué endpoint de Solana deberías conectarte?

Comienza por emparejar el endpoint con la tarea. Un script rápido, una demo de hackathon o un panel de solo lectura normalmente pueden ejecutarse contra un endpoint público. Una billetera, un bot de trading, un indexador o cualquier cosa que distribuya muchas lecturas concurrentes sentirá la diferencia entre capacidad compartida y dedicada casi de inmediato.

OnFinality ejecuta RPC de Solana mainnet tanto sobre HTTP como WebSocket, por lo que puedes apuntar un único proveedor tanto a tus llamadas de solicitud/respuesta como a tus llamadas de suscripción. Si aún estás sopesando proveedores, la guía de selección de proveedor RPC cubre los criterios de evaluación con más profundidad.

Forma del endpoint y una primera solicitud

Un endpoint RPC de Solana es una única URL que acepta solicitudes HTTP POST con un cuerpo JSON. No hay una ruta por método; el nombre del método vive en el cuerpo. El endpoint público de Solana de OnFinality es:

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

Una llamada mínima para obtener el slot actual se ve así:

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

La respuesta sigue el sobre JSON-RPC 2.0: un campo jsonrpc, un id que hace eco de tu solicitud y un objeto result o error. Todos los métodos de Solana usan ese mismo sobre, así que una vez que tu cliente lo maneja correctamente puedes llamar a cualquier método sin cambiar el código de transporte.

Grupos de métodos que realmente llamarás

La lista de métodos de Solana es larga, pero las aplicaciones en producción se agrupan en unos pocos grupos. Saber a qué grupo pertenece un método te dice cuán costoso es y cómo falla.

Dos notas prácticas. Primero, getProgramAccounts es el método con más probabilidades de agotar el tiempo de espera en un endpoint compartido, porque puede escanear un gran conjunto de cuentas; delimítalo con filtros y un dataSlice siempre que sea posible. Segundo, los resultados de getLatestBlockhash expiran, así que obtén un blockhash fresco cerca del momento en que firmas en lugar de almacenarlo en caché durante minutos.

Construir una transacción con la API JSON-RPC

La mayoría de los equipos usan @solana/web3.js o un cliente similar en lugar de escribir JSON a mano. El cliente sigue hablando los mismos métodos RPC internamente, por lo que apuntarlo a tu endpoint es un cambio de una línea:

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

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

const balance = await connection.getBalance(
  new PublicKey("11111111111111111111111111111111")
);

console.log("lamports:", balance, "SOL:", balance / LAMPORTS_PER_SOL);

El nivel de commitment que pasas importa. processed es el más rápido pero puede revertirse; confirmed es el predeterminado habitual para saldos de cara al usuario; finalized es el más seguro para lógica de liquidación. Elige uno deliberadamente y mantenlo consistente en tus lecturas, porque mezclar niveles de commitment es una fuente común de estados de UI confusos.

Suscripciones WebSocket y cuándo usarlas

Sondear getSlot o getAccountInfo en un bucle consume solicitudes y aún se siente lento. La interfaz WebSocket de Solana envía actualizaciones en su lugar. El endpoint WebSocket público de OnFinality es:

wss://solana.api.onfinality.io/public-ws

Una solicitud de suscripción usa el mismo sobre JSON-RPC, enviado a través del socket:

const ws = new WebSocket("wss://solana.api.onfinality.io/public-ws");

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "logsSubscribe",
    params: [
      { mentions: ["YourProgramPublicKeyHere"] },
      { commitment: "confirmed" }
    ]
  }));
};

ws.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  if (payload.method === "logsNotification") {
    console.log("program log:", payload.params.result.value.logs);
  }
};

Las suscripciones son de larga duración, así que planifica la reconexión. Los endpoints compartidos pueden cerrar sockets inactivos o sobrecargados, y un socket caído que tu aplicación no nota se ve exactamente como una cadena estancada. Agrega un latido, reconéctate con retroceso exponencial y vuelve a suscribirte al reconectar. Si tu carga de trabajo depende de muchas suscripciones concurrentes, esa es una señal fuerte para pasar a un nodo dedicado donde el presupuesto de conexiones es tuyo.

Ruta de depuración para errores comunes de RPC de Solana

Cuando algo se rompe, el texto del error generalmente apunta a la capa. Usa esta tabla para dirigir la solución.

Un hábito útil es registrar el objeto error JSON-RPC sin procesar, no solo un mensaje amigable. Solana devuelve datos de error estructurados, incluidos registros para fallos de simulación, y ese detalle suele ser suficiente para identificar la instrucción que falla.

Lista de verificación para preparación en producción

Antes de apuntar usuarios reales a un endpoint, confirma estos elementos:

• Los niveles de commitment son explícitos en cada ruta de lectura y confirmación.
• Los reintentos usan retroceso, no bucles ajustados, para que un momento lento no se convierta en un pico autoinfligido.
• La frescura del blockhash se maneja en el momento de firmar, no se almacena en caché.
• La reconexión WebSocket está implementada y probada matando el socket a propósito.
• Las lecturas pesadas están delimitadas con filtros, dataSlice y agrupación donde la API lo permita.
• Se configura un endpoint de respaldo para que un problema de un solo proveedor no derribe la aplicación.
• Se mide el volumen de solicitudes para que puedas saber si la capacidad compartida aún es suficiente.

Si varios de estos son difíciles de satisfacer en un endpoint compartido, ese es el punto para considerar nodos dedicados o revisar precios de RPC para comparar opciones.

Devnet, mainnet y moverse entre ellos

Devnet refleja la superficie de la API de mainnet, por lo que el código que funciona contra mainnet generalmente funciona contra RPC de Solana Devnet con una URL diferente y un keypair financiado por faucet. Mantén el endpoint en configuración en lugar de codificado, y mantén un keypair separado por entorno. El error de migración más común es un ID de programa o mint de token que se actualizó en un entorno pero no en el otro.

OnFinality expone Solana mainnet y devnet como entradas de red separadas, por lo que puedes registrar ambas y cambiar por configuración. Consulta la página de la red Solana para obtener los detalles actuales del endpoint y el soporte de transporte, y redes RPC compatibles para la lista completa.

Puntos clave

• Solana expone una única interfaz JSON-RPC para lecturas, escrituras y suscripciones; el nombre del método vive en el cuerpo de la solicitud, no en la URL.
• Empareja el endpoint con la carga de trabajo: público para prototipos, gestionado para tráfico constante, dedicado para aplicaciones con alto fan-out o muchas suscripciones.
• getProgramAccounts y los WebSockets de larga duración son las dos áreas con más probabilidades de sacarte de un endpoint compartido.
• La mayoría de los errores en producción se remontan a niveles de commitment, blockhashes obsoletos o caídas de socket no detectadas, no a la API en sí.
• OnFinality sirve RPC de Solana sobre HTTP y WebSocket, con opciones de nodo dedicado cuando la capacidad compartida no es suficiente.

Preguntas frecuentes

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

Sí. Cuando la gente dice "API RPC de Solana" se refiere a la interfaz JSON-RPC 2.0 servida sobre HTTP y WebSocket. No hay una API REST separada para datos de la cadena.

¿Necesito una clave API para llamar a un endpoint RPC de Solana?

Los endpoints públicos normalmente funcionan sin clave, lo cual está bien para uso de bajo volumen. Los endpoints gestionados y dedicados usan claves o URLs privadas para que tu tráfico esté aislado y sea medible.

¿Por qué mi transacción falla con "Blockhash not found"?

El blockhash con el que firmaste expiró antes de que la transacción se confirmara. Obtén un blockhash fresco justo antes de firmar y reintenta con retroceso.

¿Debería sondear o usar suscripciones WebSocket?

Usa suscripciones para cualquier cosa que necesite reaccionar a eventos on-chain, y reserva el sondeo para comprobaciones ocasionales. Las suscripciones reducen el volumen de solicitudes y generalmente se sienten más rápidas, pero requieren manejo de reconexión.

¿Cuándo debería pasar de un endpoint público a un nodo dedicado?

Cuando veas limitación de tasa, cuando getProgramAccounts o lecturas pesadas similares agoten el tiempo de espera, cuando necesites muchas suscripciones WebSocket concurrentes o cuando necesites estado histórico que los nodos estándar podan. Un nodo dedicado te da capacidad aislada para esos casos.