Inicio rápido de RPC de BNB Smart Chain: Endpoint, Chain ID y primeras llamadas

BNB Smart Chain habla JSON-RPC estándar de Ethereum. Si te has conectado antes a cualquier cadena EVM, se aplican las mismas bibliotecas cliente, los mismos nombres de métodos y la misma estructura de solicitud. Lo que cambia son el chain ID, el token nativo, el explorador y algunos detalles operativos sobre tiempos de bloque y consultas de logs. Este inicio rápido te lleva de cero a una conexión funcional y luego explica cómo mantener esa conexión saludable a medida que crece tu carga de trabajo.

Configuración de la cadena que necesitas antes de la primera solicitud

Obtén estos valores correctamente y la mayoría de los problemas de conexión desaparecerán. Son los mismos valores que pegas en una billetera, una configuración de Hardhat o un cliente viem.

Usa mainnet cuando estés desplegando en producción y testnet cuando estés iterando en contratos o probando flujos de billetera. El BNB de testnet no tiene valor monetario y se distribuye a través de faucets, así que trátalo solo como un entorno de pruebas.

Elige el endpoint adecuado para tu etapa

Antes de escribir código, decide qué tipo de endpoint se ajusta al trabajo. La elección incorrecta es la razón más común por la que un inicio rápido se convierte en una sesión de depuración.

• Nodo local. Control total y sin terceros, pero tú te encargas del tiempo de sincronización, el disco y las actualizaciones. Razonable para trabajo de protocolo, pesado para equipos de aplicaciones.
• Endpoint público. La forma más rápida de probar una sola solicitud. Bien para un script o una demo, no para una aplicación en producción con tráfico real.
• API RPC gestionada. Un endpoint alojado con una URL estable, nodos monitoreados y un panel de control. Aquí es donde aterrizan la mayoría de los equipos de aplicaciones. El servicio API RPC de OnFinality cubre BNB Smart Chain junto con muchas otras redes.
• Nodo dedicado. Un nodo reservado para tu carga de trabajo cuando necesitas rendimiento predecible, acceso a archive o consultas pesadas de logs y trace. Consulta nodos dedicados.

Si no estás seguro de qué nivel se ajusta, comienza con un endpoint gestionado y observa tus patrones de solicitud durante una semana antes de comprometerte con capacidad dedicada.

Configura una billetera o cliente en un solo paso

La mayoría de las billeteras aceptan una red personalizada. Pega los valores de la tabla anterior. Para un cliente JavaScript, viem es una forma compacta de confirmar que la conexión funciona.

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

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

const chainId = await client.getChainId()
const blockNumber = await client.getBlockNumber()
console.log({ chainId, blockNumber })

Si chainId devuelve 56, tu transporte está apuntando a mainnet. Si devuelve algo más, estás en el endpoint incorrecto o en el objeto de cadena incorrecto.

Tus primeras llamadas JSON-RPC con curl

Todos los métodos EVM funcionan de la misma manera. Estas tres llamadas cubren las comprobaciones que ejecutarás con más frecuencia: confirmar la cadena, leer el último bloque y leer un balance.

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

# Ú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":[]}'

# Balance de una dirección (hex wei)
curl -s https://bnb.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}'

eth_chainId devuelve 0x38, que es 56 en decimal. eth_blockNumber devuelve una altura de bloque en hexadecimal. eth_getBalance devuelve wei como una cadena hexadecimal, así que divide por 10^18 para obtener BNB.

Leer logs y eventos sin agotar el tiempo de espera

eth_getLogs es la llamada que hace tropezar a la mayoría de los equipos en BNB Smart Chain. La cadena produce bloques rápidamente, por lo que un rango de bloques amplio puede devolver un conjunto de resultados grande y agotar el tiempo de espera o ser rechazado por el límite de rango de un proveedor.

Reglas prácticas:

1. Mantén los rangos de bloques estrechos y pagina por altura de bloque en lugar de pedir todo a la vez.
2. Filtra por dirección de contrato y topic cuando puedas. Un filtro de topic reduce drásticamente el conjunto de resultados.
3. Para backfills e indexadores, usa un endpoint con capacidad de archive para que el estado histórico esté disponible.
4. Almacena en caché los resultados por rango de bloques para que un reintento no vuelva a consultar los mismos datos.

const logs = await client.getLogs({
  address: '0xYourContract',
  fromBlock: 40_000_000n,
  toBlock: 40_000_500n,
})

Si necesitas transmisión continua de eventos en lugar de sondeo, usa una suscripción WebSocket donde el endpoint lo admita, y reconéctate con retroceso exponencial cuando el socket se caiga.

Configuración de testnet y notas sobre faucets

Testnet usa chain ID 97 y el token tBNB. Apunta tu cliente al endpoint de testnet y actualiza el objeto de cadena para que los enlaces del explorador y el chain ID coincidan.

import { bscTestnet } from 'viem/chains'

const testClient = createPublicClient({
  chain: bscTestnet,
  transport: http('https://bnb-testnet.api.onfinality.io/public'),
})

Los faucets distribuyen pequeñas cantidades de tBNB para despliegues de contratos y pruebas de transacciones. Como la disponibilidad de los faucets cambia con el tiempo, consulta la documentación actual de la testnet de BNB Chain para encontrar un faucet que funcione en lugar de codificar uno. El estado de testnet puede restablecerse o podarse, así que nunca lo trates como almacenamiento duradero. Para detalles del endpoint, consulta la página de RPC de BNB Chain Testnet.

Modos de fallo y cómo interpretarlos

La mayoría de los fallos de inicio rápido se reducen a un pequeño conjunto de síntomas. Relaciona el síntoma con la causa probable antes de cambiar el código.

Cuando una llamada falla, registra el objeto de error JSON-RPC completo. Los campos code y message generalmente te dicen si el problema es tu solicitud, el endpoint o la cadena.

Lista de verificación para producción

Un inicio rápido demuestra que la conexión funciona. Producción necesita algunas cosas más.

• Endpoints redundantes. Configura una URL primaria y una de respaldo para que un problema en un solo endpoint no derribe tu aplicación.
• Reintentos con retroceso. Trata los errores transitorios como esperados y reintenta lecturas idempotentes.
• Monitoreo. Rastrea la tasa de éxito de solicitudes, la latencia y los códigos de error por método para que puedas ver regresiones temprano.
• Acceso a archive. Si consultas estado histórico o rellenas logs, confirma que el endpoint lo admita.
• Planificación de velocidad. Estima las solicitudes máximas por segundo y ajusta el nivel a ese número. Consulta precios de RPC para ver cómo los niveles se asignan al uso.
• Gestión de claves. Mantén las claves API fuera del código del lado del cliente y rótalas si se filtran.

Una sonda de salud simple te mantiene honesto sobre la calidad del endpoint:

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

Ejecuta esto en un horario y alerta cuando el código de estado o la latencia se desvíen fuera de tu rango normal.

Dónde encaja OnFinality

OnFinality ejecuta RPC de BNB Smart Chain como parte de un portafolio de red más amplio. Puedes comenzar en un endpoint gestionado y pasar a un nodo dedicado cuando tu carga de trabajo necesite rendimiento predecible o acceso a archive y trace. La superficie JSON-RPC no cambia entre niveles, por lo que migrar es principalmente un cambio de URL y clave en lugar de una reescritura. Explora redes RPC soportadas para ver qué más está disponible, y usa la página de RPC de BNB Smart Chain para detalles actuales de endpoint y red.

Puntos clave

• BNB Smart Chain mainnet usa chain ID 56 y el token BNB; testnet usa chain ID 97 y tBNB.
• Los mismos métodos JSON-RPC de Ethereum funcionan, por lo que las herramientas EVM existentes se aplican con un nuevo endpoint y configuración de cadena.
• eth_getLogs necesita rangos de bloques estrechos y filtros; los rangos amplios son la fuente más común de tiempos de espera.
• Ajusta el nivel del endpoint a tu etapa: público para una prueba, gestionado para aplicaciones, dedicado para cargas pesadas o de archive.
• Producción necesita endpoints redundantes, reintentos con retroceso, monitoreo y un plan para acceso a archive.

Preguntas frecuentes

¿Cuál es el chain ID de BNB Smart Chain? Mainnet es 56 y testnet es 97. Confírmalo con eth_chainId, que devuelve 0x38 en mainnet.

¿Puedo usar herramientas de Ethereum en BNB Smart Chain? Sí. Es compatible con EVM, por lo que ethers, viem, Hardhat y Foundry funcionan con la configuración de cadena y el endpoint correctos.

¿Por qué falla mi llamada eth_getLogs? Generalmente el rango de bloques es demasiado amplio o el conjunto de resultados es demasiado grande. Reduce el rango y filtra por dirección de contrato y topic.

¿Necesito un nodo dedicado? No para empezar. Pasa a un nodo dedicado cuando necesites rendimiento predecible, acceso a archive o consultas pesadas de trace y logs.

¿Cómo pruebo sin gastar BNB real? Usa testnet (chain ID 97) y un faucet para tBNB. Trata el estado de testnet como temporal.

¿Dónde encuentro el endpoint actual? Consulta la página de RPC de BNB Smart Chain para detalles de endpoint y red, y precios de RPC para opciones de nivel.