Quickstart

​

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.

​

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');
});