Introduction
The Streaming API uses WebSocket protocol for real-time communication. To establish a connection:
- Connect to the WebSocket endpoint:
wss://gr-staging.streaming.covalenthq.com/graphql
- Authenticate using your API key in the connection headers
- 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:
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');
});