eth_unsubscribe

The eth_unsubscribe method cancels an existing WebSocket subscription to stop receiving event notifications. This method helps manage resources and network traffic by removing subscriptions that are no longer needed.

Use Cases

• Stopping event notifications when a user navigates away from a page
• Managing resources on both client and server to prevent memory leaks
• Cleaning up inactive subscriptions after data processing is complete
• Handling application state changes requiring different subscription parameters
• Keeping within provider limits on concurrent subscriptions
• Implementing subscription rotation for high-volume event monitoring
• Ensuring graceful shutdown of dApp event monitoring components
• Switching between different blockchain event types
• Freeing up server resources for other users in multi-tenant environments
• Managing sessions for user-specific event tracking

Method Details

This method cancels a subscription using its subscription ID.

Request Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "eth_unsubscribe",
	"params": ["0x9cef478923ff08bf67fde6c64013158d"]
}

Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": true
}

Response Values

• true: The subscription was successfully canceled
• false: No subscription existed with the given ID

Error Scenarios

Error Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"error": {
		"code": -32602,
		"message": "invalid subscription id"
	}
}

Important Notes

• This method must be called over the same WebSocket connection that created the subscription
• Closing the WebSocket connection automatically unsubscribes all associated subscriptions
• The subscription ID comes from the result of a previous eth_subscribe call
• You should unsubscribe from subscriptions that are no longer needed to free up server resources
• The same subscription ID cannot be reused after unsubscribing
• Some providers may limit the number of concurrent subscriptions per connection
• Subscription IDs are unique per connection and not globally unique
• If reconnecting to a different server in a load-balanced environment, old subscription IDs will not be valid
• Some RPC providers may automatically unsubscribe inactive subscriptions after a certain period
• Multiple unsubscribe attempts for the same ID are safe but will return false after the first successful attempt

See also

• eth_subscribe - Create WebSocket event subscriptions
• WebSocket Connection Guide - Working with persistent connections
• eth_getLogs - Alternative for historical event queries
• eth_newFilter - HTTP-based alternative for event filtering
• eth_getFilterChanges - Poll-based alternative to WebSockets
• eth_uninstallFilter - HTTP equivalent for cleaning up filters