Skip to main content

​
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

TaskEndpoint
Live token price candlessubscribeToOHLCVTokens
Live pair price candlessubscribeToOHLCVPairs
Monitor new DEX pairssubscribeToNewPairs
Track pair price/liquidity/volumesubscribeToPairUpdates
Stream wallet activitysubscribeToWalletActivity
Search tokens by name/symbolsearchTokens (query)
Analyze trader PnLgetTradersPnl (query)

​
Key Differences from Foundational API

AspectFoundational APIStreaming API
ProtocolREST (HTTPS)GraphQL over WebSocket
Chain name formateth-mainnet (kebab-case)ETH_MAINNET (SCREAMING_SNAKE_CASE)
AuthenticationAuthorization: Bearer KEYGOLDRUSH_API_KEY in connection_init payload
Data deliveryRequest/responsePush-based (subscriptions)
LatencyBlock-by-blockSub-second
Use caseHistorical data, batch queriesReal-time feeds, live monitoring

​
Critical Rules

  1. Chain names use SCREAMING_SNAKE_CASE — ETH_MAINNET, not eth-mainnet
  2. WebSocket URL — wss://gr-staging-v2.streaming.covalenthq.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.
FileWhen to read
overview.mdNeed connection setup, supported chains/DEXes list, quickstart code samples, or authentication details
endpoints.mdBuilding a subscription or query — full parameters, response schemas, decoded event types
sdk-guide.mdNeed SDK patterns for multiple subscriptions, React integration, raw GraphQL queries, or troubleshooting WebSocket issues