WebSocket

Standard eth_subscribe for real-time blocks and logs. Supports Monad's monadLogs for proposed-block events. Compatible with ethers, web3, viem.

Endpoint

URL wss://api.monadatlas.com/ws

API key required. Browsers cannot set headers on WebSocket—use query param: wss://api.monadatlas.com/ws?api_key=YOUR_KEY

Subscriptions

Subscription	Description
`newHeads`	New block headers as they are produced
`logs`	Contract events (finalized blocks). Filter by address, topics (e.g. Transfer event)
`monadLogs`	Monad extension: Contract events from proposed blocks. Same filter as `logs` but lower latency (0–1 block). Use for real-time feeds.
`newPendingTransactions`	Pending transactions (if enabled on node)

Example (ethers.js)

import { ethers } from 'ethers';

const provider = new ethers.WebSocketProvider(
  'wss://api.monadatlas.com/ws?api_key=YOUR_KEY'
);

provider.on('block', (blockNumber) => {
  console.log('New block:', blockNumber);
});

Subscribe to Transfer events (logs)

const filter = {
  address: '0xTokenContract...',
  topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
};
provider.on(filter, (log) => {
  console.log('Transfer:', log);
});

monadLogs (proposed blocks, lower latency)

Use monadLogs for real-time events from proposed blocks. Same filter shape as logs:

// Raw WebSocket
ws.send(JSON.stringify({
  id: 1,
  jsonrpc: '2.0',
  method: 'eth_subscribe',
  params: ['monadLogs', { address: '0x6F6B8F1a20703309951a5127c45B49b1CD981A22' }]
}));

Production Notes

Keepalive: Atlas allows long-lived connections (24h nginx timeout). If you see "connection reset without close handshake," the upstream Monad node may have a shorter idle timeout. Send WebSocket pings every 10s to avoid hourly disconnects. Use node MonadAtlas/test-ws-timeout.js to probe timeout behavior.
monadLogs vs logs: monadLogs delivers events from proposed blocks (0–1 block latency). logs delivers finalized blocks. Use monadLogs when speed matters; handle reorgs if needed.
Reconnect: After disconnect, resubscribe and backfill from last block using eth_getLogs or REST API.
Duplicates: Dedupe by txHash + logIndex.
Native MON: Native transfers are not contract events. Use Atlas REST API latest_native_in or poll address_transfers for wallet-level monitoring.
Limits: 5 concurrent connections per API key, 10 subscriptions per connection.