> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Streaming API Quickstart
> Learn how to connect to the GoldRush Streaming API to receive real-time blockchain events over WebSocket.
export const StreamingWsUrl = () => {
const url = "wss://streaming.goldrushdata.com/graphql";
const [copied, setCopied] = React.useState(false);
const handleCopy = () => {
navigator.clipboard.writeText(url);
setCopied(true);
setTimeout(() => setCopied(false), 2000);
};
return
;
};
export const GIQL = ({readOnly, query}) => {
return ;
};
## Prerequisites
Using any of the GoldRush developer tools requires an API key.
\$10/mo - Built for solo builders and AI-native workflows.
\$250/mo - Production-grade with 50 RPS and priority support.
## Connection
The Streaming API supports GraphQL subscriptions over WebSocket, using the [GraphQL over WebSocket](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) protocol.
The recommended approach is to use the official [TypeScript Client SDK](https://www.npmjs.com/package/@covalenthq/client-sdk) which supports the Streaming API and manages all WebSocket connections.
```bash npm theme={null}
npm install @covalenthq/client-sdk
```
```bash yarn theme={null}
yarn add @covalenthq/client-sdk
```
You can also use a GraphQL over WebSocket protocol npm package like [`graphql-ws`](https://www.npmjs.com/package/graphql-ws).
If you're not using the `graphql-ws` package, you must set the WebSocket protocol header:
`"Sec-WebSocket-Protocol" : "graphql-transport-ws"`
This header is required for the server to properly recognize and handle your GraphQL subscription requests.
## OHLCV Token Stream Code Samples
The following examples show how to connect and subscribe to the OHLCV Token stream using your preferred language or tool. Each sample connects to the WebSocket endpoint, authenticates with your API key, and streams real-time OHLCV updates for a token on Base Mainnet.
```typescript GoldRush SDK theme={null}
import {
GoldRushClient,
StreamingChain,
StreamingInterval,
StreamingTimeframe
} from "@covalenthq/client-sdk";
const client = new GoldRushClient(
"",
{},
{
onConnecting: () => console.log("Connecting to streaming service..."),
onOpened: () => console.log("Connected to streaming service!"),
onClosed: () => console.log("Disconnected from streaming service"),
onError: (error) => console.error("Streaming error:", error),
}
);
client.StreamingService.subscribeToOHLCVTokens(
{
chain_name: StreamingChain.BASE_MAINNET,
token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"],
interval: StreamingInterval.ONE_MINUTE,
timeframe: StreamingTimeframe.ONE_HOUR,
},
{
next: (data) => {
console.log("Received OHLCV token data:", data);
},
error: (error) => {
console.error("Streaming error:", error);
},
complete: () => {
console.log("Stream completed");
},
}
);
```
```typescript TypeScript (graphql-ws) theme={null}
import { createClient } from "graphql-ws";
const CONNECTION_URL = "wss://streaming.goldrushdata.com/graphql";
// Define your API key
const API_KEY = "";
const client = createClient({
url: CONNECTION_URL,
connectionParams: {
GOLDRUSH_API_KEY: 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);
},
},
});
const SUBSCRIPTION_QUERY = `
subscription {
ohlcvCandlesForToken(
chain_name: BASE_MAINNET
token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"]
interval: ONE_MINUTE
timeframe: ONE_HOUR
) {
chain_name
interval
timeframe
timestamp
open
high
low
close
volume
volume_usd
quote_rate
quote_rate_usd
base_token {
contract_name
contract_address
contract_decimals
contract_ticker_symbol
}
}
}
`;
client.subscribe(
{
query: SUBSCRIPTION_QUERY,
},
{
next: (data) => {
console.log("Received data:");
console.log(JSON.stringify(data, null, 2));
},
error: (err) => {
console.error("Subscription error:", err);
},
complete: () => {
console.log("Subscription completed");
},
}
);
```
```python Python theme={null}
import asyncio
from gql import gql, Client
from gql.transport.websockets import WebsocketsTransport
# Replace with your actual API key
GOLDRUSH_API_KEY = ""
# GraphQL WebSocket endpoint
WS_URL = "wss://streaming.goldrushdata.com/graphql"
# Define the subscription query
SUBSCRIPTION_QUERY = gql("""
subscription {
ohlcvCandlesForToken(
chain_name: BASE_MAINNET
token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"]
interval: ONE_MINUTE
timeframe: ONE_HOUR
) {
chain_name
interval
timeframe
timestamp
open
high
low
close
volume
volume_usd
quote_rate
quote_rate_usd
base_token {
contract_name
contract_address
contract_decimals
contract_ticker_symbol
}
}
}
""")
async def main():
# Set up WebSocket transport with API key in connection init payload
transport = WebsocketsTransport(
url=WS_URL,
init_payload={"apiKey": API_KEY}
)
# Create GraphQL client
async with Client(
transport=transport,
fetch_schema_from_transport=False,
) as session:
# Subscribe and print data
async for result in session.subscribe(SUBSCRIPTION_QUERY):
print("📡 Received data:")
print(result)
# Run the async main function
asyncio.run(main())
```
```bash Terminal (websocat) theme={null}
( echo '{"type":"connection_init","payload":{"GOLDRUSH_API_KEY":""}}'; \
echo '{"type":"start","id":"1","payload":{"query":"subscription { ohlcvCandlesForToken(chain_name: BASE_MAINNET, token_addresses: [\"0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b\"], interval: ONE_MINUTE, timeframe: ONE_HOUR) { timestamp open high low close volume volume_usd quote_rate quote_rate_usd base_token { contract_name contract_address contract_decimals contract_ticker_symbol } } }"}}' \
) | websocat --header="Sec-WebSocket-Protocol: graphql-ws" wss://streaming.goldrushdata.com/graphql | jq
```
## Response Format
Here is an example of the response you should receive from the above code samples:
```json theme={null}
{
"data": {
"ohlcvCandlesForToken": [
{
"chain_name": "BASE_MAINNET",
"interval": "ONE_MINUTE",
"timeframe": "ONE_HOUR",
"timestamp": "2025-06-27T22:24:00Z",
"open": 0.000604418526534047,
"high": 0.000604638206820701,
"low": 0.000604013151624892,
"close": 0.000604638206820701,
"volume": 1.4980526133065126,
"volume_usd": 6004669.256018968,
"quote_rate": 0.000604638206820701,
"quote_rate_usd": 4007551.6142841205,
"base_token": {
"contract_name": "Virtual Protocol",
"contract_address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
"contract_decimals": 18,
"contract_ticker_symbol": "VIRTUAL"
}
}
]
}
}
```
## GraphQL Playground