GoldRush Streaming API: Скилл для реального времени

--- name: goldrush-streaming-api description: "GoldRush Streaming API — real-time blockchain data via GraphQL subscriptions over WebSocket. Use this skill whenever the user needs live price feeds (OHLCV candles), real-time DEX pair monitoring (new pairs, liquidity updates), wallet activity streaming, decoded swap/transfer events, token search, trader PnL analysis, or any sub-second latency blockchain event push. This is the right skill for trading bots, live dashboards, alerting systems, copy-trading, DEX sniping, and real-time analytics. Also covers one-time GraphQL queries for token discovery and profitability analysis. If the user needs historical data, batch queries, or paginated REST results, use goldrush-foundational-api instead. If the user needs pay-per-request access without an API key, use goldrush-x402 instead." --- # 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](references/sdk-guide.md) for more details. ```typescript 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](references/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://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. | File | When to read | |------|-------------| | [overview.md](references/overview.md) | Need connection setup, supported chains/DEXes list, quickstart code samples, or authentication details | | [endpoints.md](references/endpoints.md) | Building a subscription or query — full parameters, response schemas, decoded event types | | [sdk-guide.md](references/sdk-guide.md) | Need SDK patterns for multiple subscriptions, React integration, raw GraphQL queries, or troubleshooting WebSocket issues |