OHLCV Tokens Stream

The OHLCV Tokens stream provides real-time updates on the Open, High, Low, Close prices and Volume of one or many tokens at configurable intervals. This documentation follows our standard streaming API structure.

Credit Cost

TBD

Supported Chains

• Base Mainnet
• BSC Mainnet
• Ethereum Mainnet

Supported DEXes

• Uniswap V2, V3
• PancakeSwap

This stream is currently in Beta. It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. No API credits are currently charged.

We welcome your feedback so please reach out to us directly to report issues or request features.

Authentication

Using any of the GoldRush developer tools requires an API key.

Get Started

Sign up for a free API key to get started with GoldRush.

Parameters

Parameter	Type	Required	Description
chain_name	enum	Yes	Chain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
token_addresses	array<string>	Yes	Array of token addresses on supported DEXes and chains to track
interval	enum	Yes	Frequency of OHLCV data updates, ranging from sub-second to one day
timeframe	enum	Yes	Historical lookback period for OHLCV data, ranging from one minute to one month
limit	int	No	Maximum number of items returned per stream message to control payload size

Connection

If you’re not using the graphql-ws package, you must set the WebSocket protocol header:

"Sec-WebSocket-Protocol" : "graphql-transport-ws"

This header is required for the server to properly recognize and handle your GraphQL subscription requests.

The WebSocket uses the GraphQL query or subscription protocol. Here are examples of how one can connect with different languages:

socket.ts ( graphql-ws )

import { createClient } from "graphql-ws";

const CONNECTION_URL = "wss://gr-staging.streaming.covalenthq.com/graphql";

const client = createClient({
  url: CONNECTION_URL,
  shouldRetry: (retries) => retries < 5,
  on: {
    connecting: () => {
      console.log("⏳ WebSocket connecting...");
    },
    opened: () => {
      console.log("✅ WebSocket connection established");
    },
    closed: () => {
      console.log("❌ WebSocket connection closed");
    },
    error: (err) => {
      console.error("⚠️ WebSocket error:", err);
    },
  },
});

Subscription

Once connected, you can subscribe to the ohlcvCandlesForToken endpoint to receive the pricing data and events.

Basic Subscription Query

subscription {
  ohlcvCandlesForToken(
    chain_name: BASE_MAINNET
    token_addresses: ["0x4B6104755AfB5Da4581B81C552DA3A25608c73B8"]
    interval: ONE_MINUTE
    timeframe: ONE_HOUR
  ) {
    chain_name
    interval
    timeframe
    timestamp
    open
    high
    low
    close
    volume
    volume_usd
    quote_rate
    quote_rate_usd
    base_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
  }
}

Complete Subscription Query

subscription {
  ohlcvCandlesForToken(
    chain_name: BASE_MAINNET
    token_addresses: [
      "0x4B6104755AfB5Da4581B81C552DA3A25608c73B8"
    ]
    interval: ONE_MINUTE
    timeframe: ONE_HOUR
    limit: 1000
  ) {
    chain_name
    pair_address
    interval
    timeframe
    timestamp
    open
    high
    low
    close
    volume
    volume_usd
    quote_rate
    quote_rate_usd
    base_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    quote_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
  }
}

Implementation

client.subscribe({
    query: SUBSCRIPTION_QUERY
}, {
    next: (data) => {
        console.log(JSON.stringify(data));
    },
    error: (err) => console.error("⚠️ Subscription error:", err),
    complete: () => console.log("✅ Subscription completed"),
})

Response Format

Here’s an example of the response data structure:

{
  "data": {
    "ohlcvCandlesForToken": [
      {
        "chain_name": "BASE_MAINNET",
        "pair_address": "0x4b0Aaf3EBb163dd45F663b38b6d93f6093EBC2d3",
        "interval": "ONE_MINUTE",
        "timeframe": "ONE_HOUR",
        "timestamp": "2025-05-29T19:53:00Z",
        "open": 4113151.389790023,
        "high": 4196665.022060752,
        "low": 4113151.389790023,
        "close": 4196665.022060752,
        "volume": 325.7615900713698,
        "volume_usd": 0.2079461510855417,
        "quote_rate": 4196665.022060752,
        "quote_rate_usd": 0.0006319231563715365,
        "quote_token": {
          "contract_name": "Wrapped Ether",
          "contract_symbol": "WETH",
          "contract_address": "0x4200000000000000000000000000000000000006",
          "contract_decimals": 18
        },
        "base_token": {
          "contract_name": "Toshi",
          "contract_symbol": "TOSHI",
          "contract_address": "0xac1bd2486aaf3b5c0fc3fd868558b082a531b2b4",
          "contract_decimals": 18
        }
      }
    ]
  }
}

Response Fields

Field	Type	Description
chain_name	string	The blockchain network where the token exists
pair_address	string	The address of the primary DEX pool with the most liquidity for the token
interval	enum	The candle interval
timeframe	enum	The requested timeframe
timestamp	string	ISO timestamp for the candle
open	float	Opening price for the interval
high	float	Highest price during the interval
low	float	Lowest price during the interval
close	float	Closing price for the interval
volume	float	Trading volume during the interval
volume_usd	float	Trading volume in USD
quote_rate	float	Exchange rate between base and quote tokens
quote_rate_usd	float	USD value of the quote rate
base_token	object	Information about the queried token
quote_token	object	Information about the paired token of the primary DEX pool

GraphQL Playground