Subscribe Events

Subscribe to backrun events using our web-sockets api

WebSocket Subscription Overview

Our API facilitates real-time event tracking through WebSocket connections. By subscribing to specific topics, you can receive immediate notifications as events occur. Maintaining an active connection is crucial; most WebSocket libraries handle this by sending periodic ping messages to the server.

Available Topics and Notifications

You can subscribe to the following topics:

• Opportunity Transactions (opportunityTxs): Notifies you when a new opportunity transaction is available.

• Solver Operations (solverOperations): Alerts you to solver-related operations, such as bids or validations.

Each notification includes detailed event data, enabling you to take appropriate actions.

Response Data Details

Upon subscribing, you'll receive structured data for each event. Fields representing large integers are encoded as hexadecimal strings to ensure precision and compatibility.

Opportunity Transactions (opportunityTxs)

Events in this topic provide:

• Hex-encoded Binary: The transaction's binary data, encoded in hexadecimal format.

• Transaction Hash: A unique identifier for the transaction.

Solver Operations (solverOperations)

Events in this topic include:

• From: Sender's address, represented as a hexadecimal string.

• To: Recipient's address, represented as a hexadecimal string.

• Value: Operation value in Wei, encoded as a hexadecimal string.

• Gas: Allocated gas, encoded as a hexadecimal string.

• MaxFeePerGas: Maximum fee per gas unit, encoded as a hexadecimal string.

• Deadline: Operation deadline timestamp, encoded as a hexadecimal string.

• Solver: Solver's address, represented as a hexadecimal string.

• Control: Controlling address for the transaction, represented as a hexadecimal string.

• UserOpHash: Unique hash of the user's operation, represented as a hexadecimal string.

• BidToken: Address of the token being bid, represented as a hexadecimal string.

• BidAmount: Bid amount in the specified token, encoded as a hexadecimal string.

• Data: Additional arbitrary data, encoded as a hexadecimal string.

• Signature: Signature verifying the operation, encoded as a hexadecimal string.

Example Response

{
  "topic": "solverOperations",
  "data": {
    "From": "0xSenderAddress",
    "To": "0xRecipientAddress",
    "Value": "0xde0b6b3a7640000", // 1 Ether in Wei
    "Gas": "0x7a120", // 500,000 in decimal
    "MaxFeePerGas": "0x77359400", // 2 Gwei in decimal
    "Deadline": "0x64c6f8c0", // Unix timestamp
    "Solver": "0xSolverAddress",
    "Control": "0xControlAddress",
    "UserOpHash": "0xUniqueHash",
    "BidToken": "0xTokenAddress",
    "BidAmount": "0x3782dace9d900000", // 0.25 Ether in Wei
    "Data": "0xEncodedData",
    "Signature": "0xSignatureData"
  }
}

In this example, fields like Value, Gas, MaxFeePerGas, Deadline, and BidAmount are represented as hexadecimal strings, corresponding to their *big.Int values. This encoding ensures that large integer values are accurately transmitted without loss of precision. When processing these fields, ensure your application correctly decodes the hexadecimal strings back into numerical values as needed.

Minimal TypeScript Example

The following TypeScript example demonstrates how to establish a WebSocket connection, subscribe to the opportunityTxs and solverOperations topics, and handle incoming messages:

JavaScript

import WebSocket from 'ws';

// Define your WebSocket endpoint
const wsEndpoint = 'wss://polygon-rpc.fastlane.xyz/ws';

// Topics to subscribe to
enum WebSocketTopic {
  OpportunityTxs = 'opportunityTxs',
  SolveOperations = 'solverOperations'
}

// Subscribe to specified topics
function subscribeToTopics(ws: WebSocket, topics: WebSocketTopic[]) {
  ws.send(JSON.stringify({ action: 'subscribe', params: topics }));
  console.log(`Subscribed to topics: ${topics.join(', ')}`);
}

// Connect and subscribe to topics
(async () => {
  const ws = new WebSocket(wsEndpoint);

  ws.on('open', () => {
    console.log('WebSocket connection established');
    // Subscribe to topics
    subscribeToTopics(ws, [WebSocketTopic.OpportunityTxs, WebSocketTopic.SolveOperations]);
  });

  ws.on('message', (data) => {
    const message = JSON.parse(data.toString());
    console.log('Received message:', message);
  });

  ws.on('close', () => {
    console.log('WebSocket connection closed');
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });
})();


// Define your WebSocket endpoint
const wsEndpoint = 'wss://polygon-rpc.fastlane.xyz/ws';

// Topics to subscribe to
enum WebSocketTopic {
  OpportunityTxs = 'opportunityTxs',
  SolveOperations = 'solverOperations'
}

// Subscribe to specified topics
function subscribeToTopics(ws: WebSocket, topics: WebSocketTopic[]) {
  topics.forEach((topic) => {
    ws.send(JSON.stringify({ action: 'subscribe', topic }));
    console.log(`Subscribed to topic: ${topic}`);
  });
}

// Connect and subscribe to topics
(async () => {
  const ws = new WebSocket(wsEndpoint);

  ws.on('open', () => {
    console.log('WebSocket connection established');
    // Subscribe to topics
    subscribeToTopics(ws, [WebSocketTopic.OpportunityTxs, WebSocketTopic.SolveOperations]);
  });

  ws.on('message', (data) => {
    const message = JSON.parse(data.toString());
    console.log('Received message:', message);
  });

  ws.on('close', () => {
    console.log('WebSocket connection closed');
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });
})();

Python

import asyncio
import websockets
import json
from typing import List

# Define your WebSocket endpoint
ws_endpoint = "wss://polygon-rpc.fastlane.xyz/ws"

# Topics to subscribe to
topics = ["opportunityTxs", "solverOperations"]


async def wait_for_subscription_confirmation(ws, topic: str):
    """Wait for subscription confirmation message for a specific topic"""
    async for message in ws:
        try:
            data = json.loads(message)
            # Check if this is a subscription confirmation
            if (
                data.get("jsonrpc") == "2.0"
                and "result" in data
                and data.get("id") == 1
            ):
                print(f"Subscription confirmed for topic: {topic}")
                return
        except json.JSONDecodeError:
            print(f"Failed to parse message: {message}")


async def subscribe_to_topics(ws, topics: List[str]):
    """Subscribe to multiple topics with proper JSON-RPC format"""
    for topic in topics:
        subscription_message = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "subscribe",
            "params": [topic],
        }

        print(f"Sending subscription request for {topic}:", subscription_message)
        await ws.send(json.dumps(subscription_message))
        await wait_for_subscription_confirmation(ws, topic)


async def handle_messages(ws):
    """Handle incoming WebSocket messages"""
    async for message in ws:
        try:
            data = json.loads(message)
            print("Received message:", data)
        except json.JSONDecodeError:
            print(f"Failed to parse message: {message}")


async def main():
    try:
        async with websockets.connect(ws_endpoint) as ws:
            print("WebSocket connection established")
            await subscribe_to_topics(ws, topics)
            await handle_messages(ws)
    except websockets.exceptions.WebSocketException as e:
        print(f"WebSocket error occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")


if __name__ == "__main__":
    asyncio.run(main())