Inicio rápido de JSON-RPC de BNB Smart Chain: configuración de endpoint, Chain ID y primeras llamadas

Si estás integrando BNB Smart Chain en una wallet, un servicio backend o un indexador, el camino más rápido es confirmar la configuración de la cadena, enviar una petición JSON-RPC y luego decidir cuánta capacidad de endpoint necesita realmente tu carga de trabajo. Esta página es un inicio rápido práctico y una referencia para ese flujo.

Configuración de la cadena de un vistazo

BNB Smart Chain (BSC) es una red compatible con EVM, por lo que la superficie JSON-RPC te resultará familiar si has trabajado con Ethereum. Los valores a continuación son los que necesitas para añadir la red a un cliente o wallet.

Mainnet es donde viven el tráfico de producción y el valor real. Testnet es para desarrollo, pruebas con fondos de faucet y comprobaciones de integración antes de lanzar. Mantén ambas separadas en tu configuración para no apuntar nunca una clave de staging a mainnet por accidente.

Decide cómo te conectarás antes de escribir código

La primera decisión real no es qué método llamar, sino cómo quieres llegar a la cadena. Esa elección da forma a tu configuración, tu manejo de fallos y tu presupuesto.

• Desarrollo local y scripts puntuales: normalmente basta con un endpoint público compartido. Obtienes una URL funcional de inmediato y puedes iterar sobre las formas de las peticiones sin aprovisionar nada.
• Una wallet o frontend de dApp: necesitas un endpoint HTTPS estable más un endpoint WebSocket si muestras saldos en vivo, transacciones pendientes o una UI basada en eventos. Los clientes de navegador no pueden ejecutar un nodo completo, por lo que una API RPC gestionada es la opción normal.
• Servicios backend, bots e indexadores: el volumen de peticiones, las consultas de logs y las lecturas de archive empiezan a importar. Aquí es donde comparas endpoints compartidos con nodos dedicados, y donde los rate limits y el comportamiento de eth_getLogs se convierten en factores decisivos.
• Cargas de trabajo de alto throughput o sensibles a la latencia: normalmente querrás infraestructura de nodos dedicados para que tu capacidad no se comparta con tráfico no relacionado.

Si aún estás sopesando proveedores, la guía de selección de proveedor de RPC cubre los criterios de evaluación con más profundidad. Si ya sabes que quieres endpoints gestionados de BSC, empieza por la página de RPC de BNB Smart Chain.

Primera petición: confirma que el endpoint está vivo

Antes de construir nada, confirma que el endpoint responde y reporta la cadena que esperas. Una llamada a chainId es la comprobación más barata.

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

Una respuesta correcta de mainnet devuelve 0x38, que es 56 en hexadecimal. Si obtienes un valor diferente, estás apuntando a la red equivocada. Si en su lugar obtienes un objeto de error, pasa a la sección de depuración a continuación.

Merece la pena ejecutar dos llamadas más durante la configuración:

# Último número de bloque
curl -s https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

# Cadena de versión del cliente
curl -s https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"web3_clientVersion","params":[]}'

eth_blockNumber confirma que el nodo está sincronizado y avanzando. web3_clientVersion te dice qué implementación de cliente te está sirviendo, lo cual es útil cuando comparas comportamiento entre endpoints.

Añadir BNB Smart Chain a una wallet o cliente

La mayoría de las wallets aceptan una red personalizada. Usa la configuración de la tabla anterior. Un objeto de configuración típico se ve así:

const bscMainnet = {
  chainId: "0x38", // 56
  chainName: "BNB Smart Chain Mainnet",
  nativeCurrency: {
    name: "BNB Chain Native Token",
    symbol: "BNB",
    decimals: 18,
  },
  rpcUrls: ["https://bnb.api.onfinality.io/public"],
  blockExplorerUrls: ["https://bscscan.com"],
};

Para testnet, cambia el chain ID a 0x61 (97), el endpoint de testnet y el explorador de testnet. Mantén el símbolo como tBNB para que tu UI no implique fondos reales.

Llamar a BSC desde JavaScript

Si prefieres una librería en lugar de curl en bruto, tanto viem como ethers funcionan contra BSC porque es compatible con EVM. Una lectura mínima con viem se ve así:

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

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

const blockNumber = await client.getBlockNumber();
const balance = await client.getBalance({
  address: "0x0000000000000000000000000000000000000000",
});

console.log(blockNumber, formatEther(balance));

Si usas ethers, el patrón es la misma idea: crea un provider apuntando al endpoint y luego llama a métodos de lectura. Lo importante es que la URL del endpoint y el chain ID concuerden.

Métodos que realmente usarás en BSC

Como BSC es compatible con EVM, se aplica el conjunto estándar de métodos JSON-RPC de Ethereum. La tabla a continuación agrupa los métodos que surgen con más frecuencia y señala dónde el comportamiento específico de BSC suele sorprender a la gente.

Dos de estos merecen atención adicional. Primero, eth_getLogs es el método con más probabilidades de alcanzar un límite, porque los rangos de bloques amplios y los topics amplios son costosos de servir. Si tu indexador consulta rangos grandes, espera tener que paginar y necesitar un endpoint que soporte tu patrón de consulta. Segundo, eth_subscribe requiere una conexión WebSocket, así que confirma que tu endpoint soporta ws antes de diseñar en torno a eventos en vivo.

Depurar los errores que realmente encontrarás

La mayoría de los problemas tempranos de integración con BSC caen en un pequeño número de categorías. Relaciona el síntoma con la causa probable antes de cambiar código.

Algunos de estos merecen ampliarse. Las respuestas de rate limit no son un bug en tu código, son una señal de capacidad. Si las ves bajo carga normal, tu patrón de peticiones ha superado un endpoint compartido. Los errores de nonce normalmente significan que tu seguimiento local del nonce se ha desviado de la cadena, así que vuelve a leer el nonce pendiente antes de difundir. Y los errores de revert de eth_call son comportamiento normal del contrato, no un fallo de RPC, así que decodifícalos en lugar de reintentar a ciegas.

Cuándo basta con un endpoint compartido y cuándo no

Un endpoint público compartido es un buen valor por defecto para desarrollo, lecturas de bajo volumen y prototipos. Te lleva rápidamente a una integración funcional y te permite validar las formas de las peticiones antes de comprometerte con infraestructura.

El panorama cambia en cuanto tienes tráfico de producción. Las señales de que has superado un endpoint compartido incluyen:

• Respuestas frecuentes de rate limit durante la operación normal.
• Consultas eth_getLogs que necesitan rangos de bloques amplios o lookbacks largos.
• Lecturas de archive contra estado histórico.
• Suscripciones WebSocket que deben permanecer conectadas durante largos periodos.
• La necesidad de aislar tu tráfico para que la carga de otro inquilino no pueda afectar tu latencia.

En ese punto, las opciones prácticas son una API RPC gestionada con límites más altos o infraestructura de nodos dedicados que tú controlas. OnFinality ofrece ambas para BNB Smart Chain, así que puedes empezar en un endpoint compartido y pasar a capacidad dedicada sin cambiar el código de tu aplicación, solo tu configuración. Consulta Precios de RPC para ver en qué se diferencian los niveles y Redes RPC compatibles para la lista completa de cadenas.

Checklist de preparación para producción

Antes de apuntar usuarios reales a tu integración con BSC, confirma lo siguiente:

1. Los endpoints de mainnet y testnet están separados en tu configuración, sin secretos compartidos.
2. Tienes un endpoint de respaldo o una estrategia de reintentos para fallos transitorios.
3. Las consultas eth_getLogs están paginadas y acotadas.
4. Los clientes WebSocket se reconectan con backoff exponencial.
5. Monitorizas la altura de bloque y las tasas de error, no solo los códigos de estado HTTP.
6. Tu manejo de nonce vuelve a leer desde el nodo antes de reenviar.
7. Has decidido si necesitas acceso a archive y capacidad dedicada.

Una sonda de monitorización simple puede detectar la mayoría de los problemas a tiempo. Sondea eth_blockNumber de forma programada y alerta si deja de avanzar o si las tasas de error suben:

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

Si el número de bloque se estanca o el endpoint empieza a devolver errores, esa es tu señal para investigar antes de que los usuarios lo noten.

Puntos clave

• BNB Smart Chain mainnet usa el chain ID 56 (0x38) y testnet usa 97 (0x61).
• BSC es compatible con EVM, por lo que se aplican los métodos JSON-RPC estándar de Ethereum.
• Confirma el endpoint con eth_chainId y eth_blockNumber antes de construir.
• eth_getLogs y eth_subscribe son los métodos con más probabilidades de alcanzar los límites del endpoint.
• Las respuestas de rate limit son una señal de capacidad, no un bug de código.
• Los endpoints compartidos sirven para desarrollo; las cargas de trabajo de producción a menudo necesitan capacidad dedicada.
• OnFinality ofrece acceso a la API RPC de BNB Smart Chain y nodos dedicados si quieres infraestructura gestionada.

Preguntas frecuentes

¿Cuál es el chain ID de BNB Smart Chain?

Mainnet es 56, que es 0x38 en hexadecimal. Testnet es 97, o 0x61.

¿Es BSC JSON-RPC lo mismo que Ethereum JSON-RPC?

En gran medida sí, porque BSC es compatible con EVM. Se aplican los mismos nombres de métodos, aunque los endpoints individuales pueden diferir en qué métodos y rangos de bloques soportan.

¿Por qué falla mi llamada eth_getLogs en BSC?

Los rangos de bloques amplios y los filtros de topics amplios son costosos de servir, por lo que muchos endpoints limitan el rango. Reduce el rango y pagina tus consultas.

¿Necesito un endpoint WebSocket para BSC?

Solo si quieres actualizaciones push como nuevos bloques o logs. Las lecturas estándar funcionan por HTTP. Confirma que tu endpoint soporta ws antes de diseñar en torno a suscripciones.

¿Cuándo debería dejar de usar un endpoint público?

Cuando veas rate limits bajo carga normal, necesites datos de archive, ejecutes consultas de logs amplias o quieras aislamiento de tráfico. En ese punto, compara niveles de API RPC gestionada y nodos dedicados.