API Reference
Full reference for the GetBlock EVM Data Stream WebSocket API: endpoints, authentication, methods, topics, the event envelope, limits, and errors.
This section documents every method and topic exposed by the EVM Data Stream WebSocket API.
The API has two methods: getblock_subscribe and getblock_unsubscribe. The topic you subscribe to decides what you receive. Each topic has its own page covering its parameters, a live sample response, and every field it returns.
Quickstart
Subscribe to new block headers on Ethereum Mainnet:
# WebSocket-only. Connect first:
wscat -c 'wss://stream.eu-central-1.getblock.io/v1/eth-mainnet/stream' -H 'Authorization: Bearer <API-KEY>'
# Then send:
{
"jsonrpc": "2.0",
"id": 1,
"method": "getblock_subscribe",
"params": [{ "topic": "newHeads" }]
}The service replies with a subscription ID, then pushes one notification per event:
{
"jsonrpc": "2.0",
"method": "getblock_subscribe",
"params": {
"subscription": "0xfd5126364b7ac0fbe8ad9099ce29571c",
"result": {
"eventId": "eth:mainnet:block:0x19dd…0be2:newHeads:0x19dd…0be2",
"removed": false,
"revision": 116876399,
"data": { "number": "0x18d1e1e", "hash": "0x19ddc6864bd5ec1cdbd493e3d3653b529d79293a6773517018153cdff6ac0be2", "…": "…" }
}
}
}Endpoints
Each network has its own WebSocket endpoint. Every topic is available on every network.
Ethereum Mainnet
wss://stream.eu-central-1.getblock.io/v1/eth-mainnet/stream
BNB Smart Chain
wss://stream.eu-central-1.getblock.io/v1/bsc-mainnet/stream
Polygon Mainnet
wss://stream.eu-central-1.getblock.io/v1/polygon-mainnet/stream
Robinhood Mainnet
wss://stream.eu-central-1.getblock.io/v1/robinhood-mainnet/stream
Authentication
Every connection needs a GetBlock API key (gb_…). Create one in Settings → API Keys. Pass it in one of two ways:
Browser WebSocket APIs cannot set an Authorization header, so add the key to the URL instead:
Credentials in a URL can end up in browser history, proxy and gateway logs, or telemetry. Prefer the Authorization header outside the browser, and never log the full query URL.
The server rejects authentication failures during the WebSocket handshake:
401
authorization failed
No API key was sent.
401
invalid api key
The API key is not recognized.
404
—
The network in the URL path is not supported.
429
—
You already have 50 open connections.
Methods
Open a subscription to one topic. Returns a subscription ID, then streams events.
Cancel one subscription without closing the socket.
Topics
erc20Allowence is the current public topic name, including the misspelling. Send it exactly as shown; erc20Allowance is rejected.
Choosing a topic
A signal every time a block is produced
newHeads
Every transaction in each block, in one message
newBlocks
Incoming token payments to a wallet
erc20Transfers with filters.to
Alerts when someone grants a token allowance
erc20Allowence
A contract's events as raw topics and data
logs
A contract's events with named, typed arguments
decodedLogs
NFT mints, burns, and transfers
nftTransfers
Marketplace listing approvals, or setApprovalForAll alerts
nftApprovals
A signal to refresh cached NFT metadata
nftMetadataUpdates
Success or failure of transactions and their gas cost
transactionReceipts
Smart-account (ERC-4337) activity
accountAbstractionOperations
Confirmation that a transaction was included in a block
newMinedTransactions
Transactions before they are mined
newPendingTransactions
Internal calls and contract-to-contract value flow
newMinedTransactionsTraces or newBlockTraces
Concepts that apply to every topic
1. The event envelope
Every notification uses the same envelope. The topic-specific payload sits in params.result.data:
params.subscription
string
The subscription this event belongs to. Use it to route events when one socket carries several subscriptions.
params.result.eventId
string
Stable identifier for this event. A reorg correction for the event carries the same eventId. Treat it as opaque.
params.result.removed
boolean
false for a new event. true when a chain reorganization removed an event you already received.
params.result.revision
number
Monotonic version number. For the same eventId, a higher revision is newer.
params.result.data
object or string
The topic payload. See each topic's page.
2. Reorg corrections
When a block leaves the canonical chain, the stream sends every affected event again on the same subscription with removed: true and a higher revision. There is no separate reorg topic and no option to switch corrections off. Store events by eventId and keep the one with the greatest revision. See Handling chain reorganizations for the full contract and a client reducer.
Reorg corrections are currently enabled on Ethereum and Polygon. BNB Smart Chain and Robinhood will be announced separately.
3. Value encoding
Numeric values such as block numbers, amounts, gas, token IDs, and indexes are returned as EVM hex quantities ("0x18d1e1e"), the same as the Ethereum JSON-RPC API. Addresses in normalized payloads are lowercase; argument values in decodedLogs keep their EIP-55 checksum casing. Ignore unknown fields so that new ones don't break your client.
4. Live-only delivery
The stream carries live events only. Historical ranges (fromBlock, toBlock) and includeRemoved are rejected, and events published while you were disconnected are not replayed. After a reconnect, rebuild state from your own source before relying on the stream again.
5. One socket, many subscriptions
Send several getblock_subscribe requests on one connection and route notifications on params.subscription. Event order across different subscriptions is not guaranteed.
Connection keepalive
The server sends a WebSocket ping about every 30 seconds, and standard clients answer it automatically, so an idle connection with no events stays open.
Python websockets: set ping_interval=None. The server's pong replies do not echo the ping payload. Python websockets checks the payload, treats the pong as missing, and closes the connection with 1011 keepalive ping timeout after about 40 seconds without events. Disabling client pings avoids this; the server's own pings keep the connection alive. Node.js ws and browser clients are not affected.
Limits
These per-user limits apply across all networks and topics:
Open WebSocket connections
50
The WebSocket upgrade is rejected with HTTP 429. No socket is opened.
Active or pending subscriptions
15
Only the new subscribe request fails, with -32001 subscription limit exceeded. The socket and its other subscriptions stay open.
Addresses per transaction filter
50
The subscribe request fails with -32602.
Pricing
Every delivered event costs 10 CU, on every network and topic. You are billed for events after filters are applied, so precise filters directly reduce cost. Each subscription is billed separately: the same event delivered to two subscriptions counts twice.
Errors
Handshake failures use an HTTP status (see Authentication). Requests on an open socket return standard JSON-RPC error objects:
-32700
The message is not valid JSON
parse error
-32600
Invalid JSON-RPC request
—
-32601
Method is not supported
method not found
-32602
Subscription params failed validation
unsupported subscription topic "nope"
-32000
The backing live source could not create the subscription
—
-32001
Per-user active or pending subscription limit reached
subscription limit exceeded
Each topic page lists the -32602 messages specific to its parameters.
Last updated
Was this helpful?