API de BNB: Métodos JSON-RPC de BSC y configuración del endpoint

Configuración de la cadena de un vistazo

Antes de escribir cualquier código, asegúrate de que los parámetros de red sean correctos. BSC es equivalente a EVM, por lo que tus herramientas de Ethereum existentes funcionan una vez que el chain ID y el endpoint son correctos.

Si solo necesitas una cosa de esta página, es esa tabla. Agrégala a la configuración de tu billetera, a tu archivo de red de Hardhat/Foundry o a las variables de entorno de tu backend, y la mayoría de los errores de "red incorrecta" desaparecerán.

Recomendación rápida: ¿endpoint compartido o nodo dedicado?

La mayoría de los equipos deberían comenzar con un endpoint de API RPC compartido y pasar a un nodo dedicado cuando aparezca una señal específica. Usa esto para decidir dónde estás hoy.

La decisión rara vez es permanente. Comienza compartido, mide y actualiza las cargas de trabajo que realmente duelen. OnFinality ofrece tanto acceso a la API RPC como nodos dedicados, para que puedas moverte entre ellos sin cambiar la lógica de tu aplicación.

Los métodos de BSC que realmente llamarás

BSC implementa la superficie JSON-RPC estándar de Ethereum. En la práctica, un pequeño subconjunto cubre casi todo el tráfico de producción.

Lectura de estado

• eth_blockNumber — altura actual del bloque, útil para verificaciones de estado y detección de retrasos.
• eth_getBalance — saldo nativo de BNB para una dirección.
• eth_getTransactionCount — nonce, necesario antes de firmar.
• eth_call — ejecuta una llamada de contrato de solo lectura sin una transacción.
• eth_getCode y eth_getStorageAt — bytecode del contrato y slots de almacenamiento sin procesar.
• eth_getBlockByNumber — encabezado del bloque y, opcionalmente, transacciones completas.

Lectura de logs y recibos

• eth_getLogs — el caballo de batalla para indexadores, pero también la fuente más común de timeouts y errores de rango.
• eth_getTransactionReceipt — confirma la inclusión y lee los eventos emitidos.

Escritura

• eth_sendRawTransaction — envía una transacción firmada. Ten en cuenta que BSC no admite eth_sendTransaction en la mayoría de los endpoints alojados, así que firma del lado del cliente.
• eth_gasPrice y eth_estimateGas — estimación de tarifas y gas antes de firmar.

Metadatos de la cadena

• eth_chainId — confirma que estás en 56 o 97.
• net_version — identificador de red heredado, aún utilizado por algunas herramientas.

Comportamiento específico de BSC que vale la pena conocer: los tiempos de bloque son cortos, el gas es barato y el mempool ve un alto volumen de transacciones. Esa combinación significa que la gestión de nonces y el precio del gas importan más que en cadenas más tranquilas.

Configuración del endpoint con curl

Prueba la conectividad antes de integrar cualquier cosa. Una sola llamada a eth_chainId confirma el endpoint, la cadena y tu ruta de red.

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 devuelve 0x38, que es 56 en hexadecimal. Si obtienes un valor diferente, estás apuntando a la red incorrecta. Si obtienes un error de conexión, revisa primero las reglas de salida y el DNS.

Ahora lee un saldo y el último bloque:

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

Para un lote de llamadas, envía un array JSON de objetos de solicitud en una sola solicitud HTTP. El procesamiento por lotes reduce los viajes de ida y vuelta, pero mantén los lotes modestos: los lotes muy grandes son una causa común de timeouts y a menudo están limitados por los endpoints compartidos.

Integración en JavaScript

Con ethers, el proveedor es una sola línea. Mantén el endpoint en la configuración en lugar de codificarlo, para que puedas cambiar de proveedor o agregar failover más adelante.

import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(process.env.BSC_RPC_URL);

const network = await provider.getNetwork();
console.log("chainId", network.chainId.toString()); // expect 56

const block = await provider.getBlockNumber();
const balance = await provider.getBalance("0xYourAddress");
console.log({ block, balance: balance.toString() });

Para viem, el equivalente usa createPublicClient con transporte http() o web3(). Si necesitas actualizaciones push — nuevos bloques, transacciones pendientes o eventos de contrato — usa el transporte WebSocket contra un endpoint wss://. BSC mainnet admite tanto HTTP como WebSocket en OnFinality; testnet es solo HTTP, así que planifica tus herramientas de testnet en consecuencia.

Configuración de red para billeteras y dApps

Si estás agregando BSC a una billetera o dApp, usa los parámetros de wallet_addEthereumChain. Estos son los valores que los usuarios verán cuando cambien de red.

await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0x38",
    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 a chain ID 0x61 (97), símbolo tBNB y el explorador de testnet. Obtén fondos de testnet de un faucet de BSC antes de intentar enviar transacciones: un saldo cero es la razón más común por la que una escritura en testnet falla silenciosamente.

Modos de fallo y cómo depurarlos

La mayoría de los problemas de RPC de BSC se dividen en unas pocas categorías. Relaciona el síntoma y luego aplica la solución.

Dos hábitos previenen la mayoría de estos problemas. Primero, confirma siempre el chain ID al inicio y falla rápido si es incorrecto. Segundo, trata cada llamada RPC como falible: envuélvela con un timeout, reintenta con backoff y mantén un segundo endpoint en la configuración para failover.

Lista de verificación para producción

Antes de dirigir tráfico real a un endpoint, confirma estos elementos.

• Chain ID verificado al inicio, no asumido.
• Endpoint almacenado en configuración, con al menos una URL de respaldo.
• Timeouts y reintentos configurados para cada ruta de llamada.
• Rangos de eth_getLogs acotados y paginados.
• Manejo de nonce centralizado para que los escritores concurrentes no colisionen.
• Monitoreo de retraso en la altura del bloque, tasa de errores y latencia p95.
• Una ruta documentada hacia un nodo dedicado si el rendimiento compartido se convierte en el cuello de botella.

Si varios de estos ya están causando incidentes, esa es la señal para evaluar infraestructura dedicada. La página de red de BNB Chain de OnFinality enumera el endpoint y los detalles de transporte, y precios de RPC cubre las formas de los planes. Para un marco más amplio, consulta cómo elegir un proveedor de RPC.

Puntos clave

• BSC mainnet es chain ID 56 con BNB como token nativo; testnet es chain ID 97 con tBNB.
• Los endpoints públicos de OnFinality son https://bnb.api.onfinality.io/public para mainnet y https://bnb-testnet.api.onfinality.io/public para testnet.
• Un pequeño conjunto de métodos — eth_chainId, eth_getBalance, eth_call, eth_getLogs, eth_sendRawTransaction — cubre la mayor parte del tráfico de producción.
• Firma las transacciones del lado del cliente; no confíes en eth_sendTransaction en endpoints alojados.
• Los límites de rango de eth_getLogs y el manejo de nonces son las dos fuentes más comunes de incidentes en producción.
• Comienza con un endpoint de API RPC compartido, luego mueve las cargas de trabajo pesadas o sensibles a la latencia a un nodo dedicado.
• Configura siempre un endpoint de respaldo y monitorea el retraso en la altura del bloque.

Preguntas frecuentes

¿Cuál es el chain ID de BSC? BNB Smart Chain mainnet usa chain ID 56 (0x38). La testnet usa chain ID 97 (0x61).

¿BSC admite WebSocket? Sí. BSC mainnet admite transportes HTTP y WebSocket. El acceso a testnet es solo HTTP, así que planifica las suscripciones en consecuencia.

¿Por qué falla mi llamada a eth_getLogs? Generalmente porque el rango de bloques es demasiado amplio para que el endpoint lo sirva en una sola solicitud. Reduce el rango, pagina o usa un endpoint adecuado para cargas de trabajo de indexación.

¿Puedo usar mis herramientas de Ethereum en BSC? Sí. BSC es equivalente a EVM, por lo que ethers, viem, Hardhat y Foundry funcionan una vez que configuras el chain ID y el endpoint correctos.

¿Cómo obtengo BNB de testnet? Usa un faucet de testnet de BSC para fondear tu dirección con tBNB antes de enviar transacciones.

¿Cuándo debería pasar a un nodo dedicado? Cuando el rendimiento compartido, las consultas de logs o la latencia se convierten en problemas recurrentes, por ejemplo, rellenos sostenidos de eth_getLogs o escrituras de trading sensibles a la latencia.

¿Dónde puedo ver qué redes admite OnFinality? La página de redes RPC compatibles enumera la cobertura de red actual y los endpoints.