goldrush-streaming-api

GoldRush Streaming API

Real-time blockchain data via GraphQL subscriptions over WebSocket. Sub-second latency for OHLCV price feeds, DEX pair events, and wallet activity.

Quick Start

IMPORTANT: Always prioritize using the official available GoldRush Client SDKs best suited for your development ecosystem. Only use a GraphQL WebSocket Client like graphql-ws if there are specific requirements or contraints to avoid dependencies on available Client SDKs. The GoldRush Client SDKs provides automatic authentication, connection management, retry logic, type safety, and a simplified API for all streaming operations. see SDK Guide for more details.

import {
  GoldRushClient,
  StreamingChain,
  StreamingInterval,
  StreamingTimeframe
} from "@covalenthq/client-sdk";

const client = new GoldRushClient(
  "YOUR_API_KEY",
  {},
  {
    onConnecting: () => console.log("Connecting..."),
    onOpened: () => console.log("Connected!"),
    onError: (error) => console.error("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("OHLCV:", data),
    error: (error) => console.error(error),
    complete: () => console.log("Done"),
  }
);

Install: npm install @covalenthq/client-sdk

Available Streams

The Streaming API offers two types of endpoints:

• Subscriptions — real-time push via WebSocket. Covers OHLCV price candles (by token or pair), new DEX pair creation, pair updates (price/liquidity/volume), and live wallet activity.
• Queries — one-time GraphQL fetch. Covers token search and trader PnL analysis.

For the full list of endpoints with parameters and response schemas, see endpoints.md.

Common Tasks → Stream

Task	Endpoint
Live token price candles	subscribeToOHLCVTokens
Live pair price candles	subscribeToOHLCVPairs
Monitor new DEX pairs	subscribeToNewPairs
Track pair price/liquidity/volume	subscribeToPairUpdates
Stream wallet activity	subscribeToWalletActivity
Search tokens by name/symbol	searchTokens (query)
Analyze trader PnL	getTradersPnl (query)

Key Differences from Foundational API

Aspect	Foundational API	Streaming API
Protocol	REST (HTTPS)	GraphQL over WebSocket
Chain name format	eth-mainnet (kebab-case)	ETH_MAINNET (SCREAMING_SNAKE_CASE)
Authentication	Authorization: Bearer KEY	GOLDRUSH_API_KEY in connection_init payload
Data delivery	Request/response	Push-based (subscriptions)
Latency	Block-by-block	Sub-second
Use case	Historical data, batch queries	Real-time feeds, live monitoring

Critical Rules

1. Chain names use SCREAMING_SNAKE_CASE — ETH_MAINNET, not eth-mainnet
2. WebSocket URL — wss://streaming.goldrushdata.com/graphql
3. Protocol header — Sec-WebSocket-Protocol: graphql-transport-ws
4. Auth payload — { "type": "connection_init", "payload": { "GOLDRUSH_API_KEY": "YOUR_KEY" } }
5. Auth errors are deferred — connection_ack always succeeds; auth errors only appear on subscription start
6. SDK is recommended — handles WebSocket lifecycle, reconnection, and type safety automatically
7. Singleton WebSocket — SDK reuses one connection for multiple subscriptions
8. Cleanup subscriptions — call the returned unsubscribe function when done; call disconnect() to close all

Price Feed Sources

• DEX swap events — prices derived from onchain trades across supported DEXes
• Onchain oracle feeds — ultra-low-latency CEX-aggregated prices on select chains (e.g., Redstone Bolt on MegaETH at 2.4ms update frequency)

Reference Files

Read the relevant reference file when you need details beyond what this index provides.

File	When to read
overview.md	Need connection setup, supported chains/DEXes list, quickstart code samples, or authentication details
endpoints.md	Building a subscription or query — full parameters, response schemas, decoded event types
sdk-guide.md	Need SDK patterns for multiple subscriptions, React integration, raw GraphQL queries, or troubleshooting WebSocket issues