Skip to content

docs: clarify public WebSocket availability for Flashblocks #1410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dieutx wants to merge 1 commit into from
Closed

docs: clarify public WebSocket availability for Flashblocks #1410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/base-chain/api-reference/ethereum-json-rpc-api/eth_subscribe.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: 'Creates a real-time WebSocket subscription. Flashblocks endpoints
Creates a real-time event subscription over a WebSocket connection. Returns a subscription ID; events are pushed as `eth_subscription` notifications without the client needing to poll.

<Tip>
**Flashblocks:** On `wss://mainnet-preconf.base.org`, `newHeads` emits every ~200ms (once per Flashblock) instead of every ~2 seconds. Three additional subscription types are also available: [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions), [`pendingLogs`](/base-chain/api-reference/flashblocks-api/pendingLogs), and [`newFlashblocks`](/base-chain/api-reference/flashblocks-api/newFlashblocks).
**Flashblocks:** On a Flashblocks-aware provider or self-hosted node, `newHeads` emits every ~200ms (once per Flashblock) instead of every ~2 seconds. Three additional subscription types are also available: [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions), [`pendingLogs`](/base-chain/api-reference/flashblocks-api/pendingLogs), and [`newFlashblocks`](/base-chain/api-reference/flashblocks-api/newFlashblocks). The public `wss://*.base.org` endpoints listed in the RPC overview do not currently accept WebSocket upgrades.
</Tip>

## Parameters
Expand Down
2 changes: 1 addition & 1 deletion docs/base-chain/api-reference/flashblocks-api/newFlashblockTransactions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: 'Subscribe to receive each transaction as it is pre-confirmed into
Subscribe via `eth_subscribe` to receive each transaction as it is pre-confirmed into a Flashblock. Pass `true` as the second parameter to receive full transaction and log data.

<Info>
Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` / `wss://sepolia-preconf.base.org`.
Only available on Flashblocks-aware WebSocket endpoints exposed by a node provider or your own node. The public `wss://*.base.org` endpoints do not currently accept WebSocket upgrades.
</Info>

<Note>
Expand Down
6 changes: 3 additions & 3 deletions docs/base-chain/api-reference/flashblocks-api/newFlashblocks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: 'Subscribe to receive full Flashblock payload stream as each pre-co
Subscribe via `eth_subscribe` to receive full block state updates as each Flashblock is built. Each message contains the accumulated pre-confirmed state for the block in progress.

<Info>
Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` and `wss://sepolia-preconf.base.org`.
Only available on Flashblocks-aware WebSocket endpoints exposed by a node provider or your own node. The public `wss://*.base.org` endpoints do not currently accept WebSocket upgrades.
</Info>

<Note>
Expand Down Expand Up @@ -44,8 +44,8 @@ Each subscription emits **one Flashblock Object per WebSocket message**. Events
```javascript JavaScript
import WebSocket from 'ws';

// Use a Flashblocks-enabled provider WSS endpoint in production
const ws = new WebSocket('wss://mainnet-preconf.base.org');
// Replace with your provider or self-hosted Flashblocks WebSocket endpoint
const ws = new WebSocket(process.env.BASE_FLASHBLOCKS_WSS_URL || 'wss://your-provider.example/ws');

ws.on('open', () => {
ws.send(JSON.stringify({
Expand Down
2 changes: 1 addition & 1 deletion docs/base-chain/api-reference/flashblocks-api/pendingLogs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: 'Subscribe to logs from pre-confirmed transactions matching an opti
Subscribe via `eth_subscribe` to receive logs from pre-confirmed transactions matching an optional filter. Useful for monitoring contract events with sub-block latency.

<Info>
Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` / `wss://sepolia-preconf.base.org`.
Only available on Flashblocks-aware WebSocket endpoints exposed by a node provider or your own node. The public `wss://*.base.org` endpoints do not currently accept WebSocket upgrades.
</Info>

<Note>
Expand Down
10 changes: 7 additions & 3 deletions docs/base-chain/api-reference/rpc-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,12 @@ Base exposes a single, fully EVM-compatible JSON-RPC API across two performance
</Tab>
</Tabs>

<Warning>
Public `base.org` RPC endpoints currently support HTTP only. WebSocket upgrade requests to the `wss://*.base.org` URLs above return `405 Method Not Allowed` as of May 2026. If you need `eth_subscribe`, `newFlashblocks`, `pendingLogs`, or `newFlashblockTransactions`, use a [node provider](/base-chain/node-operators/node-providers) or run your own [Flashblocks-aware node](/base-chain/node-operators/run-a-base-node#enable-flashblocks).
</Warning>

<Info>
The public endpoints above are rate-limited and not suitable for production traffic. For production use, connect through a [node provider](/base-chain/node-operators/node-providers).
The public HTTP endpoints above are rate-limited and not suitable for production traffic. For production use, connect through a [node provider](/base-chain/node-operators/node-providers).
</Info>

## What is the Flashblocks Tier?
Expand Down Expand Up @@ -80,8 +84,8 @@ Methods marked ✓ support the `"pending"` block tag on Flashblocks endpoints.
| [eth_syncing](/base-chain/api-reference/ethereum-json-rpc-api/eth_syncing) | Node sync status | — |
| [net_version](/base-chain/api-reference/ethereum-json-rpc-api/net_version) | Network version ID | — |
| [web3_clientVersion](/base-chain/api-reference/ethereum-json-rpc-api/web3_clientVersion) | Client version string | — |
| [eth_subscribe](/base-chain/api-reference/ethereum-json-rpc-api/eth_subscribe) | Subscribe to events (WSS) | ✓ |
| [eth_unsubscribe](/base-chain/api-reference/ethereum-json-rpc-api/eth_unsubscribe) | Cancel a subscription (WSS) | — |
| [eth_subscribe](/base-chain/api-reference/ethereum-json-rpc-api/eth_subscribe) | Subscribe to events (provider or self-hosted WSS) | ✓ |
| [eth_unsubscribe](/base-chain/api-reference/ethereum-json-rpc-api/eth_unsubscribe) | Cancel a subscription (provider or self-hosted WSS) | — |

### Flashblocks API

Expand Down
6 changes: 4 additions & 2 deletions docs/base-chain/flashblocks/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,11 +105,13 @@ For a comprehensive introduction to how Flashblocks work, see the [Flashblocks O
Transaction data in the [`diff.transactions`](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#diff-object) array is Recursive Length Prefix (RLP) encoded.
</Accordion>

<Accordion title="Why am I getting rate limited on the WebSocket?">
The public WebSocket has a maximum connection limit. For production use, we recommend:
<Accordion title="Why does the public WebSocket return 405 Method Not Allowed?">
The public `wss://*.base.org` endpoints do not currently accept WebSocket upgrade requests. If you need subscription-based Flashblocks data, use:

1. Running your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks)
2. Using a third-party node provider with Flashblocks support

The public HTTP endpoints remain available for standard JSON-RPC requests.
</Accordion>
</AccordionGroup>

Expand Down