WebSocket API

newHeads

Receive one notification for each new canonical head on the hosted EVM route.

TopicnewHeads

Route familyEVM

StageAvailable

Available under EVM WebSocket API. Use the chain-family pages for handle discovery and this page for exact subscription semantics.

Access

Surfaces: raw_rpc_ws
Metering: raw_rpc_ws_target_minute
Scope: EVM head subscription

Handles

Surface	Label	Value
`raw_rpc_ws`	Endpoint	`{RPC_WSS_BASE_URL}/v1/ethereum/{API_KEY}`
`raw_rpc_ws`	Subscribe method	`eth_subscribe`
`raw_rpc_ws`	Notification method	`eth_subscription`

Use `newHeads` when the runtime needs block head updates for confirmation tracking, chain liveness checks, or downstream polling triggers.

Examples use `/v1/ethereum/{api_key}`. The same reviewed topic set applies across the current public EVM websocket routes in the gateway baseline.

Examples

Connect with compatibility URL


wscat -c "{RPC_WSS_BASE_URL}/v1/ethereum/{api_key}"> {>   "jsonrpc": "2.0",>   "id": 1,>   "method": "eth_subscribe",>   "params": [>     "newHeads">   ]> }

Request fields

Subscription request

Field	Type	Required	Notes
`jsonrpc`	`string`	Required	JSON-RPC version. Use `2.0`.
`id`	`string \| number`	Required	Caller request id.
`method`	`string`	Required	Allowlisted subscription method.
`params`	`array`	Required	Subscription topic or filter arguments.

Response fields

Subscribe result

Field	Type	Notes
`jsonrpc`	`string`	JSON-RPC version.
`id`	`string \| number`	Echoed caller request id.
`result`	`string \| number`	Subscription id returned by the hosted route.

Notification shape

Field	Type	Notes
`method`	`string`	Notification method such as `eth_subscription` or `slotNotification`.
`params.subscription`	`string \| number`	Subscription id tied to the current stream.
`params.result`	`object`	Upstream chain payload for the current notification.

EVM overview: Return to the chain-family landing page.
EVM WebSocket API: Open the websocket API tree for this chain family.
Use RPC WebSocket: Return to the task-oriented websocket guide.
Canonical method path: Keep a direct link to this exact subscription page.