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.
CODEBLOCK0
Install: INLINECODE1
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 | INLINECODE2 |
| 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
SNAKECASE) |
| 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 SCREAMINGSNAKECASE —
ETH_MAINNET, not INLINECODE15 - WebSocket URL — INLINECODE16
- Protocol header — INLINECODE17
- Auth payload — INLINECODE18
- Auth errors are deferred —
connection_ack always succeeds; auth errors only appear on subscription start - SDK is recommended — handles WebSocket lifecycle, reconnection, and type safety automatically
- Singleton WebSocket — SDK reuses one connection for multiple subscriptions
- 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 |
GoldRush 流式 API
通过 WebSocket 上的 GraphQL 订阅实现实时区块链数据。OHLCV 价格数据流、DEX 交易对事件和钱包活动的亚秒级延迟。
快速开始
重要提示： 始终优先使用最适合您开发环境的官方 GoldRush 客户端 SDK。仅当有特定要求或限制需要避免依赖现有客户端 SDK 时，才使用像 graphql-ws 这样的 GraphQL WebSocket 客户端。
GoldRush 客户端 SDK 为所有流式操作提供自动认证、连接管理、重试逻辑、类型安全和简化 API。详见 SDK 指南。
typescript
import {
GoldRushClient,
StreamingChain,
StreamingInterval,
StreamingTimeframe
} from @covalenthq/client-sdk;
const client = new GoldRushClient(
YOURAPIKEY,
{},
{
onConnecting: () => console.log(正在连接...),
onOpened: () => console.log(已连接！),
onError: (error) => console.error(错误：, error),
}
);
client.StreamingService.subscribeToOHLCVTokens(
{
chainname: StreamingChain.BASEMAINNET,
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(完成),
}
);
安装： npm install @covalenthq/client-sdk
可用数据流
流式 API 提供两种类型的端点：
- - 订阅 — 通过 WebSocket 实时推送。涵盖 OHLCV 价格蜡烛图（按代币或交易对）、新 DEX 交易对创建、交易对更新（价格/流动性/交易量）和实时钱包活动。
- 查询 — 一次性 GraphQL 获取。涵盖代币搜索和交易者盈亏分析。
有关带参数和响应模式的完整端点列表，请参见 endpoints.md。
常见任务 → 数据流
| 任务 | 端点 |
|---|
| 实时代币价格蜡烛图 | subscribeToOHLCVTokens |
| 实时交易对价格蜡烛图 |
subscribeToOHLCVPairs |
| 监控新 DEX 交易对 | subscribeToNewPairs |
| 追踪交易对价格/流动性/交易量 | subscribeToPairUpdates |
| 流式钱包活动 | subscribeToWalletActivity |
| 按名称/符号搜索代币 | searchTokens（查询） |
| 分析交易者盈亏 | getTradersPnl（查询） |
与基础 API 的主要区别
| 方面 | 基础 API | 流式 API |
|---|
| 协议 | REST (HTTPS) | 基于 WebSocket 的 GraphQL |
| 链名称格式 |
eth-mainnet（短横线命名法） | ETH_MAINNET（大写蛇形命名法） |
| 认证 | Authorization: Bearer KEY | connection
init 载荷中的 GOLDRUSHAPI_KEY |
| 数据传递 | 请求/响应 | 基于推送（订阅） |
| 延迟 | 逐区块 | 亚秒级 |
| 使用场景 | 历史数据、批量查询 | 实时数据流、实时监控 |
关键规则
- 1. 链名称使用大写蛇形命名法 — ETHMAINNET，而非 eth-mainnet
- WebSocket URL — wss://streaming.goldrushdata.com/graphql
- 协议头 — Sec-WebSocket-Protocol: graphql-transport-ws
- 认证载荷 — { type: connectioninit, payload: { GOLDRUSHAPIKEY: YOURKEY } }
- 认证错误延迟出现 — connectionack 始终成功；认证错误仅在订阅开始时出现
- 推荐使用 SDK — 自动处理 WebSocket 生命周期、重连和类型安全
- 单例 WebSocket — SDK 为多个订阅复用同一连接
- 清理订阅 — 完成后调用返回的取消订阅函数；调用 disconnect() 关闭所有连接
价格数据源
- - DEX 交换事件 — 价格来源于支持的去中心化交易所上的链上交易
- 链上预言机数据源 — 选定链上的超低延迟中心化交易所聚合价格（例如 MegaETH 上 Redstone Bolt 的 2.4ms 更新频率）
参考文件
当您需要超出本索引提供的详细信息时，请阅读相关参考文件。
构建订阅或查询 — 完整参数、响应模式、解码事件类型 |
|
sdk-guide.md | 需要多个订阅的 SDK 模式、React 集成、原始 GraphQL 查询或 WebSocket 问题排查 |
