Una guía completa para usar WebSocket RPC de BNB Smart Chain: endpoints WSS, métodos eth_subscribe, ciclo de vida de la conexión y estrategias de reconexión con ejemplos de código.
Respuesta Directa: Cómo Conectarse a BSC mediante WebSocket RPC
Para conectarte a BNB Smart Chain (BSC) mediante WebSocket RPC, usa un endpoint WSS como wss://bsc-rpc.publicnode.com para la red principal o wss://bsc-testnet.publicnode.com para la red de prueba. Estos endpoints admiten los métodos estándar eth_subscribe compatibles con Ethereum, lo que te permite recibir notificaciones en tiempo real de nuevos bloques, transacciones pendientes y logs. Para aplicaciones de producción, debes usar un proveedor confiable como el servicio API de OnFinality o un proveedor RPC dedicado, ya que los endpoints públicos pueden tener límites de tasa e inestabilidad en la conexión.
Esta guía explica la superficie de WebSocket RPC de BSC, cómo suscribirse y cancelar la suscripción, y cómo construir una conexión resiliente con reconexión automática y resuscripción. Usaremos ethers.js y web3.js para ejemplos prácticos, y proporcionaremos una lista de verificación para solucionar problemas comunes.
- WSS de red principal:
wss://bsc-rpc.publicnode.com(puerta de enlace pública, documentada por PublicNode) - WSS de red de prueba:
wss://bsc-testnet.publicnode.com(puerta de enlace pública) - Endpoints específicos del proveedor: varían según el proveedor (por ejemplo, QuickNode, Alchemy, OnFinality) – consulta la documentación de tu proveedor.
Endpoints WebSocket RPC de BSC y Métodos eth_subscribe
BNB Smart Chain es compatible con EVM, por lo que su WebSocket RPC sigue la especificación JSON-RPC de Ethereum. El método principal para datos en tiempo real es eth_subscribe, que crea una suscripción y devuelve un ID de suscripción. Los tipos de suscripción admitidos son: newHeads, logs, newPendingTransactions y syncing.
La suscripción newHeads envía una notificación cada vez que se añade un nuevo bloque a la cadena. La suscripción logs filtra logs según la dirección y los temas, y es ideal para rastrear eventos de contratos. newPendingTransactions te notifica los hashes de transacciones que entran en el mempool, y syncing proporciona cambios en el estado de sincronización.
La documentación oficial de BNB Chain (docs.bnbchain.org) confirma que BSC admite estas suscripciones estándar de Ethereum. Para métodos JSON-RPC detallados, consulta la documentación JSON-RPC de BNB Chain.
newHeads: Obtén una notificación por cada nuevo encabezado de bloque.logs: Obtén logs que coincidan con un filtro (dirección y temas).newPendingTransactions: Obtén hashes de transacciones pendientes.syncing: Obtén notificaciones cuando cambia el estado de sincronización.
Abrir una Conexión WebSocket y Suscribirse con ethers.js
Para conectarte a BSC mediante WebSocket usando ethers.js, creas una instancia de WebSocketProvider con la URL WSS. Luego puedes usar el método on para escuchar eventos como block o logs. Por ejemplo, para suscribirte a nuevos encabezados de bloque, puedes usar provider.on('block', (blockNumber) => { ... }).
Para logs, puedes usar provider.on('logs', filter, callback) donde el filtro es un objeto con address y topics. El callback recibe un objeto de log con campos como blockNumber, transactionHash y data.
Aquí tienes un ejemplo mínimo que se conecta a la red principal de BSC y registra los números de nuevos bloques:
const { WebSocketProvider } = require('ethers');
const wsUrl = 'wss://bsc-rpc.publicnode.com';
const provider = new WebSocketProvider(wsUrl);
provider.on('block', (blockNumber) => {
console.log('Nuevo bloque:', blockNumber);
});
// Mantener el proceso vivo
setTimeout(() => process.exit(0), 30000);Suscribirse con web3.js
Con web3.js, usas web3.eth.subscribe para crear una suscripción. El método toma el tipo de suscripción y parámetros opcionales. Por ejemplo, para suscribirte a nuevos encabezados de bloque, puedes hacer:
const Web3 = require('web3');
const web3 = new Web3('wss://bsc-rpc.publicnode.com');
const subscription = web3.eth.subscribe('newBlockHeaders', (error, blockHeader) => {
if (error) console.error(error);
console.log('Nuevo encabezado de bloque:', blockHeader.number);
});
Para cancelar la suscripción, llama a subscription.unsubscribe() que devuelve una promesa. Para logs, puedes pasar un objeto de filtro como segundo parámetro: web3.eth.subscribe('logs', { address: '0x...', topics: [...] }, callback).
web3.eth.subscribe('newBlockHeaders')para nuevos bloques.web3.eth.subscribe('logs', filter)para logs.web3.eth.subscribe('newPendingTransactions')para transacciones pendientes.web3.eth.subscribe('syncing')para estado de sincronización.
Entendiendo los Payloads de Notificación
Cuando te suscribes a newHeads, el payload de notificación es un objeto de encabezado de bloque. Incluye campos como number (número de bloque), hash, parentHash, timestamp y transactionsRoot. Para logs, el payload es un objeto de log con address, topics, data, blockNumber, transactionHash y logIndex.
Aquí tienes un ejemplo de un payload de notificación newHeads:
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x1234567890abcdef",
"result": {
"number": "0x1b4",
"hash": "0x...",
"parentHash": "0x...",
"timestamp": "0x...",
"transactionsRoot": "0x..."
}
}
}
Para logs, el payload incluye la address del log, topics, data e información del bloque. Puedes usar estos campos para activar la lógica de tu aplicación.
- Payload de
newHeads: encabezado de bloque connumber,hash,timestamp, etc. - Payload de
logs: objeto de log conaddress,topics,data,blockNumber, etc.
Ciclo de Vida de la Conexión: Por Qué los Endpoints WSS Públicos de BSC Caen
Los endpoints WebSocket públicos en BSC a menudo caen debido a límites de tasa, tiempos de espera por inactividad o balanceo de carga del lado del servidor. Por ejemplo, una puerta de enlace pública podría cerrar conexiones que han estado inactivas durante un cierto período o que exceden una tasa de solicitudes. Este es un comportamiento documentado para muchos proveedores de RPC públicos, pero los límites exactos varían según el proveedor.
Para mantener una conexión estable, necesitas implementar un mecanismo de heartbeat (keepalive). Esto se puede hacer enviando una solicitud JSON-RPC simple (como eth_blockNumber) periódicamente, o usando un marco ping/pong a nivel de protocolo WebSocket. Muchas bibliotecas, como ethers.js, tienen opciones de keepalive integradas.
Cuando una conexión cae, debes reconectarte y volver a suscribirte a tus suscripciones. Esto se debe a que las suscripciones están vinculadas a la conexión. Una estrategia de reconexión robusta implica detectar la desconexión, reconectarse y luego restablecer todas las suscripciones. También debes manejar notificaciones duplicadas que pueden ocurrir si la conexión cae después de que se envía una notificación pero antes de que la recibas.
- Los endpoints públicos pueden tener tiempos de espera por inactividad (por ejemplo, 60 segundos) y límites de tasa.
- Usa un heartbeat para mantener la conexión viva.
- Reconéctate y vuelve a suscribirte al desconectarte.
- Maneja notificaciones duplicadas usando procesamiento idempotente (por ejemplo, verificando números de bloque).
Ejemplo Ejecutable: Reconexión de WebSocketProvider con Resuscripción
A continuación se muestra un script completo de Node.js usando ethers.js que se conecta a BSC, se suscribe a nuevos bloques y logs, y se reconecta automáticamente con resuscripción. Incluye un heartbeat y maneja notificaciones duplicadas rastreando el último número de bloque.
El script usa WebSocketProvider y escucha el evento close para activar la reconexión. También envía una solicitud eth_blockNumber cada 15 segundos como keepalive. Al reconectarse, vuelve a suscribirse a los mismos filtros.
Salida esperada: El script registra números de nuevos bloques y cualquier log que coincida con el filtro. Al desconectarse, registra un mensaje de reconexión y se reanuda.
const { WebSocketProvider } = require('ethers');
const WS_URL = 'wss://bsc-rpc.publicnode.com';
const LOG_FILTER = { address: '0x...' }; // Reemplaza con la dirección de tu contrato
let provider;
let lastBlock = 0;
let reconnectAttempts = 0;
async function connect() {
console.log('Conectando...');
provider = new WebSocketProvider(WS_URL);
provider.on('block', (blockNumber) => {
if (blockNumber > lastBlock) {
console.log('Nuevo bloque:', blockNumber);
lastBlock = blockNumber;
} else {
console.log('Bloque duplicado:', blockNumber);
}
});
provider.on('logs', (log) => {
console.log('Log:', log.transactionHash, log.blockNumber);
});
provider.on('close', () => {
console.log('Conexión cerrada. Reconectando...');
reconnectAttempts++;
setTimeout(connect, 1000 * Math.min(reconnectAttempts, 5));
});
provider.on('error', (error) => {
console.error('Error de WebSocket:', error);
});
// Heartbeat: enviar una solicitud cada 15 segundos
setInterval(async () => {
try {
await provider.send('eth_blockNumber', []);
} catch (e) {
console.error('Heartbeat fallido:', e.message);
}
}, 15000);
}
connect();
// Mantener el proceso vivo
setInterval(() => {}, 1000);Lista de Verificación de Solución de Problemas: 4010, 429 y Límites de Conexión
Al usar WebSocket RPC de BSC, puedes encontrar errores específicos. Aquí hay problemas comunes y cómo resolverlos:
Error 4010 (Límite de suscripciones excedido): Esto ocurre cuando intentas crear demasiadas suscripciones en una sola conexión. El límite suele ser de 10 suscripciones por conexión, pero varía según el proveedor. Para solucionarlo, reduce el número de suscripciones o usa múltiples conexiones.
Error 429 (Demasiadas solicitudes): Este es un error de límite de tasa. Los endpoints públicos a menudo limitan el número de solicitudes por segundo. Para evitarlo, implementa un limitador de tasa en tu cliente o usa un proveedor con límites más altos.
Límite de conexiones por IP: Algunos proveedores limitan el número de conexiones concurrentes desde una sola IP. Si alcanzas este límite, es posible que necesites usar un proveedor que permita más conexiones o distribuir tus conexiones entre múltiples IPs.
Retraso en la altura del bloque: Si tu suscripción no recibe los últimos bloques, puede deberse a que el nodo está atrasado. Verifica el estado de sincronización del nodo usando eth_syncing. Si está sincronizando, espera hasta que esté completamente sincronizado.
- 4010: Reduce las suscripciones o usa múltiples conexiones.
- 429: Implementa limitación de tasa o mejora tu proveedor.
- Límite de conexión: Usa un proveedor con límites más altos o distribuye las conexiones.
- Retraso en la altura del bloque: Verifica
eth_syncingy espera la sincronización.
Compensaciones y Limitaciones de BSC WebSocket RPC
WebSocket RPC es ideal para aplicaciones en tiempo real, pero tiene compensaciones. Requiere una conexión persistente, que puede consumir muchos recursos. Los endpoints públicos pueden ser poco confiables, por lo que para producción, considera usar un proveedor dedicado como el servicio API de OnFinality o un proveedor comercial.
Además, newPendingTransactions puede ser ruidoso y de alto volumen, así que úsalo con prudencia. Para logs, puedes reducir el volumen especificando un filtro estrecho (dirección y temas).
Finalmente, ten en cuenta que el tiempo de bloque de BSC es de alrededor de 3 segundos, por lo que las notificaciones newHeads llegarán con frecuencia. Asegúrate de que tu cliente pueda manejar el rendimiento.
- Las conexiones persistentes requieren más recursos.
- Los endpoints públicos pueden tener límites de tasa y tiempo de inactividad.
- Usa filtros para reducir el volumen de logs.
- El tiempo de bloque de BSC es de ~3 segundos, así que espera notificaciones frecuentes.
Próximos Pasos y Lecturas Adicionales
Ahora que entiendes BSC WebSocket RPC, puedes construir aplicaciones en tiempo real. Para más detalles sobre las especificidades de la red BSC, consulta la página de red de BNB Smart Chain. Si encuentras problemas de desconexión, consulta nuestras soluciones genéricas para desconexiones de WebSocket RPC.
Para la selección de proveedores, consulta la guía de proveedores RPC de BNB Chain y los precios de RPC. También puedes explorar el centro de aprendizaje de OnFinality para más tutoriales.
Recuerda probar tu implementación primero en la red de prueba y siempre monitorear la salud de tu conexión.
Ethereum
Solana
Polygon
Base
Arbitrum
BNB Chain
Polkadot
Optimism
