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:

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

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 |

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