Introduction

The Streaming API uses WebSocket protocol for real-time communication. To establish a connection:

  1. Connect to the WebSocket endpoint: wss://gr-staging.streaming.covalenthq.com/graphql
  2. Authenticate using your API key in the connection headers
  3. Subscribe to your desired streams using the subscription message format

Prerequisites

Using any of the GoldRush developer tools requires an API key.

Get Started

Sign up for a free API key to get started with GoldRush.

Authentication

To authenticate with the WebSocket endpoint, you need to include your API key in the connection headers. Here are examples in Python and Node.js:

import { createClient } from "graphql-ws";

// Your GoldRush API key
const API_KEY = 'YOUR_API_KEY';

const client = createClient({
  url: CONNECTION_URL,
  connectionParams: {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  },
  shouldRetry: (retries) => retries < 5,
  on: {
    connecting: () => {
      console.log("⏳ WebSocket connecting...");
    },
    opened: () => {
      console.log("✅ WebSocket connection established");
    },
    closed: () => {
      console.log("❌ WebSocket connection closed");
    },
    error: (err) => {
      console.error("⚠️ WebSocket error:", err);
    },
  },
});

Query Format

The event streams support GraphQL-style querying to filter down specific chains or protocols supported. See GraphQL Endpoints for more information.

Client Messages

Messages sent from the client to the server follow this structure:

subscription {
  newPairs(chain_name: BASE_MAINNET) {
    chain_name
    block_signed_at
    protocol
  }
}

Server Messages

Messages received from the server follow this structure:

{
  "data": {
    "newPairs": [
        {
            "chain_name": "base",
            "protocol": "uniswap",
            "protocol_version": "3",
            "deployer_address": "0x33128a8fc17869897dce68ed026d694621f6fdfd",
            "tx_hash": "0x6771c6ec2a231f85dfa4bd18ce05927cb124a485f1d04e33a475a54be6b48294",
            "block_signed_at": "2025-03-25T15:53:27Z",
            "event_name": "PoolCreated"
        }
    ]
  }
}

Working Example

For working examples, refer to the individual stream pages.

Authentication

To authenticate with the WebSocket endpoint, you need to include your API key in the connection headers. Here are examples in Python and Node.js:

Python Example

import websockets
import json
import asyncio

async def connect_to_stream():
    # Your GoldRush API key
    api_key = "YOUR_API_KEY"
    
    # WebSocket connection URL
    uri = "wss://gr-staging.streaming.covalenthq.com/graphql"
    
    # Headers with bearer token
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    
    async with websockets.connect(uri, extra_headers=headers) as websocket:
        # Subscription query
        subscription = {
            "query": """
            subscription {
                newPairs(chain_name: BASE_MAINNET) {
                    chain_name
                    block_signed_at
                    protocol
                }
            }
            """
        }
        
        # Send subscription
        await websocket.send(json.dumps(subscription))
        
        # Listen for messages
        while True:
            response = await websocket.recv()
            print(json.loads(response))

# Run the async function
asyncio.run(connect_to_stream())

Node.js Example

const WebSocket = require('ws');

// Your GoldRush API key
const API_KEY = 'YOUR_API_KEY';

// Create WebSocket connection with headers
const ws = new WebSocket('wss://gr-staging.streaming.covalenthq.com/graphql', {
    headers: {
        'Authorization': `Bearer ${API_KEY}`
    }
});

// Connection opened
ws.on('open', () => {
    console.log('Connected to WebSocket');
    
    // Subscription query
    const subscription = {
        query: `
        subscription {
            newPairs(chain_name: BASE_MAINNET) {
                chain_name
                block_signed_at
                protocol
            }
        }
        `
    };
    
    // Send subscription
    ws.send(JSON.stringify(subscription));
});

// Listen for messages
ws.on('message', (data) => {
    const response = JSON.parse(data);
    console.log('Received:', response);
});

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

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