Punto final JSON-RPC de BSC: configuración de cadena, configuración de billetera y depuración

Si estás conectando una billetera, un script o un servicio backend a BNB Smart Chain, lo primero que necesitas es un punto final JSON-RPC funcional más la configuración correcta de la cadena. Si aciertas en esos dos aspectos, la mayoría de los problemas de "no se conecta" desaparecen. Si te equivocas, pasarás una tarde persiguiendo errores que en realidad son solo un ID de cadena incorrecto o un punto final obsoleto.

Esta página te da primero la configuración, luego los métodos y después la ruta de depuración. Está escrita para desarrolladores que ya saben qué es JSON-RPC y quieren los detalles específicos de BSC sin volver a leer una introducción genérica.

Configuración de la cadena de un vistazo

Usa estos valores al agregar BNB Smart Chain a una billetera, una configuración de framework o un cliente backend. Los valores de mainnet y testnet son diferentes, y mezclarlos es el error de configuración más común.

Mainnet admite transportes HTTP y WebSocket en el punto final de OnFinality, lo cual es importante si dependes de suscripciones como eth_subscribe para nuevos bloques o registros pendientes. Testnet es solo HTTP, por lo que el polling es el patrón correcto allí.

Si necesitas una red diferente o quieres comparar opciones, la página de redes RPC compatibles enumera lo que está disponible, y RPC de BNB Chain tiene el detalle específico de la red.

Elige el punto final adecuado para tu carga de trabajo

Antes de copiar una URL, decide qué tipo de tráfico estás enviando. El punto final que funciona para un prototipo de fin de semana no siempre es el que quieres detrás de un servicio en producción.

• Scripts de solo lectura y paneles. Un punto final público compartido suele ser suficiente. Estás enviando eth_call, eth_getBalance y eth_blockNumber a bajo volumen.
• Billeteras y dApps con usuarios reales. Quieres un rendimiento predecible y una URL que no cambie bajo tus pies. Una API RPC gestionada con un nombre de host estable es la opción predeterminada más segura.
• Indexadores, bots y backends que escanean registros. eth_getLogs sobre rangos amplios de bloques es la llamada común más pesada en BSC. Aquí es donde los puntos finales compartidos empiezan a fallar y un nodo dedicado se gana su lugar.
• Cualquier cosa que necesite suscripciones. Si dependes de push por WebSocket en lugar de polling, confirma que tu punto final realmente admite ws antes de construir sobre él.

Una forma rápida de enmarcarlo: si tu aplicación falla cuando el punto final te limita la tasa, has superado el nivel compartido. OnFinality ofrece tanto un servicio de API RPC gestionado como nodos dedicados cuando necesitas capacidad aislada. Puedes ver cómo se asignan a costos en la página de precios de RPC.

Configura una billetera o cliente

La mayoría de las billeteras aceptan una red personalizada. Los campos se asignan directamente a la tabla anterior. En código, los mismos valores van en el constructor de tu cliente.

Para un cliente viem apuntado a BSC mainnet:

import { createPublicClient, http } from 'viem';
import { bsc } from 'viem/chains';

const client = createPublicClient({
  chain: bsc,
  transport: http('https://bnb.api.onfinality.io/public'),
});

const block = await client.getBlockNumber();
console.log('Latest BSC block:', block);

Si prefieres JSON-RPC sin procesar, la misma llamada se ve así:

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

Ambos devuelven la altura del último bloque como una cadena hexadecimal. Si eso funciona, tu punto final y la configuración de la cadena son correctos y puedes pasar a los métodos que tu aplicación realmente necesita.

Los métodos JSON-RPC que llamarás con más frecuencia

BSC es compatible con EVM, por lo que el conjunto de métodos es la superficie estándar de JSON-RPC de Ethereum. En la práctica, un puñado de llamadas hace la mayor parte del trabajo.

Para eth_getLogs, mantén rangos de bloques modestos y pagina. Un rango de decenas de miles de bloques contra un punto final compartido a menudo fallará incluso cuando el punto final esté saludable, porque el nodo tiene que escanear mucho estado para responder.

Depurar los errores que realmente verás

La mayoría de los problemas de JSON-RPC de BSC se reducen a un pequeño conjunto de síntomas. Coincide el síntoma y luego aplica la solución.

Dos de estos merecen una mirada más cercana. Primero, los errores de nonce: cuando reenvías una transacción, lee el nonce de la cuenta con la etiqueta de bloque pending, no latest, o seguirás colisionando con tu propia transacción en vuelo. Segundo, la limitación: un 429 no es un error en tu código, es una señal de capacidad. Reintenta con retroceso exponencial para ráfagas ocasionales, pero si ocurre en tráfico normal, el nivel compartido es el nivel incorrecto para esa carga de trabajo.

Para un recorrido más profundo del comportamiento del nonce, consulta qué es un nonce en transacciones blockchain.

Una sonda de monitoreo mínima

Antes de culpar a tu aplicación, confirma que el punto final está saludable. Una sonda corta que verifica la altura del bloque y la latencia te dirá si el problema es el punto final o tu código.

async function probe(url) {
  const start = Date.now();
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [],
    }),
  });
  const { result } = await res.json();
  const height = parseInt(result, 16);
  console.log('height', height, 'roundtrip', Date.now() - start, 'ms');
}

probe('https://bnb.api.onfinality.io/public');

Ejecuta esto en un horario y registra la altura. Una altura que deja de avanzar es una señal clara, y un tiempo de ida y vuelta que se desvía hacia arriba te dice que el punto final está bajo presión antes de que tus usuarios lo noten.

Cuándo dejar un punto final compartido

No hay un número único que diga "cambia ahora", pero las señales son consistentes. Estás listo para capacidad dedicada cuando:

• Sufres limitación en tráfico normal, no en ráfagas.
• eth_getLogs sobre los rangos que necesitas sigue agotando el tiempo.
• Necesitas suscripciones WebSocket y quieres que estén aisladas de otros inquilinos.
• Quieres un punto final privado y estable en lugar de una URL pública compartida.
• Tus requisitos de cumplimiento o confiabilidad significan que no puedes depender de un nivel compartido de mejor esfuerzo.

Un nodo dedicado de BNB Chain te da rendimiento aislado y un punto final privado. La contrapartida es el costo y el hecho de que ahora posees más de la superficie operativa. Si prefieres no ejecutar el nodo tú mismo, una opción dedicada gestionada mantiene el aislamiento sin el mantenimiento. Compara las formas en nodos dedicados y revisa precios de RPC antes de comprometerte.

Puntos clave

• BSC mainnet usa el ID de cadena 56 y BNB; testnet usa el ID de cadena 97 y tBNB. Mezclarlos es el error de configuración más común.
• Mainnet admite HTTP y WebSocket; testnet es solo HTTP, por lo que las suscripciones necesitan un punto final compatible con ws.
• eth_getLogs sobre rangos amplios es la llamada común más pesada y la principal razón por la que fallan los puntos finales compartidos.
• Un 429 es una señal de capacidad, no un error de código. Reintenta con retroceso para ráfagas, pero cambia a capacidad dedicada si ocurre en tráfico normal.
• Una sonda simple de altura de bloque separa los problemas del punto final de los problemas de la aplicación en segundos.

Preguntas frecuentes

¿Cuál es el ID de cadena de BSC mainnet? 56. El ID de cadena de testnet es 97. Siempre confirma a cuál está apuntando tu billetera o cliente antes de depurar cualquier otra cosa.

¿Puedo usar el mismo punto final para mainnet y testnet? No. Son redes separadas con URLs e ID de cadena separados. Usa la URL de mainnet para el ID de cadena 56 y la URL de testnet para el ID de cadena 97.

¿Por qué falla eth_getLogs en BSC? Generalmente porque el rango de bloques es demasiado amplio para que el nodo lo escanee rápidamente. Reduce el rango, pagina tus consultas o usa un nodo dedicado con más margen.

¿BSC admite suscripciones WebSocket? Mainnet sí en el punto final de OnFinality, que admite HTTP y WebSocket. Testnet es solo HTTP, así que haz polling allí en lugar de usar eth_subscribe.

¿Cómo sé si necesito un nodo dedicado? Si ves limitación en tráfico normal, tiempos de espera repetidos de eth_getLogs o necesitas capacidad WebSocket aislada, un nodo dedicado es el siguiente paso correcto. De lo contrario, un punto final compartido gestionado suele ser suficiente.

¿Dónde encuentro las URL actuales del punto final? Usa las páginas RPC de BNB Chain y RPC de BNB Chain Testnet para las URL y configuraciones actuales, y la página de redes RPC compatibles para todo lo demás.