SDK Guide

Additional details on advanced Streaming API features offered by the GoldRush TypeScript Client SDK.

With the official TypeScript Client SDK, developers can access the Streaming API and leverage the following advanced features described in this guide.

npm install @covalenthq/client-sdk

Basic Subscription

The following code sample shows how to set up a subscription to the OHLCV Pairs stream:

GoldRush SDK

import {
  GoldRushClient,
  StreamingChain,
  StreamingInterval,
  StreamingTimeframe,
  StreamingProtocol,
} from "@covalenthq/client-sdk";

const client = new GoldRushClient(
  "<GOLDRUSH_API_KEY>",
  {},
  {
    onConnecting: () => console.log("Connecting to streaming service..."),
    onOpened: () => console.log("Connected to streaming service!"),
    onClosed: () => console.log("Disconnected from streaming service"),
    onError: (error) => console.error("Streaming error:", error),
  }
);

// Subscribe to OHLCV data for trading pairs
const unsubscribeOhlcvPairs = client.StreamingService.subscribeToOHLCVPairs(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    pair_addresses: ["0x9c087Eb773291e50CF6c6a90ef0F4500e349B903"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => {
      console.log("Received OHLCV pair data:", data);
    },
    error: (error) => {
      console.error("Streaming error:", error);
    },
    complete: () => {
      console.log("Stream completed");
    },
  }
);

// Unsubscribe when done
unsubscribeOhlcvPairs();

// Disconnect from streaming service when finished
await client.StreamingService.disconnect();

Multiple Subscriptions

The SDK uses a singleton WebSocket client internally, allowing you to create multiple subscriptions through the same GoldRushClient.

GoldRush SDK

import {
  GoldRushClient,
  StreamingChain,
  StreamingInterval,
  StreamingTimeframe,
  StreamingProtocol,
} from "@covalenthq/client-sdk";

// Create a single client
const client = new GoldRushClient(
  "<GOLDRUSH_API_KEY>",
  {},
  {
    onConnecting: () => console.log("Connecting to streaming service..."),
    onOpened: () => console.log("Connected to streaming service!"),
    onClosed: () => console.log("Disconnected from streaming service"),
    onError: (error) => console.error("Streaming error:", error),
  }
);

// Create multiple subscriptions through the same connection
const unsubscribePairs = client.StreamingService.subscribeToOHLCVPairs(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    pair_addresses: ["0x9c087Eb773291e50CF6c6a90ef0F4500e349B903"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => console.log("OHLCV Pairs:", data),
  }
);

const unsubscribeTokens = client.StreamingService.subscribeToOHLCVTokens(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    token_addresses: ["0x4B6104755AfB5Da4581B81C552DA3A25608c73B8"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => console.log("OHLCV Tokens:", data),
  }
);

const unsubscribeWallet = client.StreamingService.subscribeToWalletActivity(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    wallet_addresses: ["0xbaed383ede0e5d9d72430661f3285daa77e9439f"],
  },
  {
    next: (data) => console.log("Wallet Activity:", data),
  }
);

// Unsubscribe from individual streams when needed
unsubscribePairs();
unsubscribeTokens();
unsubscribeWallet();

// Or disconnect from all streams at once
await client.StreamingService.disconnect();

React Integration

For React applications, use the useEffect hook to properly manage subscription lifecycle:

GoldRush SDK

useEffect(() => {
  const unsubscribe = client.StreamingService.rawQuery(
    `subscription {
        ohlcvCandlesForPair(
          chain_name: BASE_MAINNET
          pair_addresses: ["0x9c087Eb773291e50CF6c6a90ef0F4500e349B903"],
          interval: StreamingInterval.ONE_MINUTE,
          timeframe: StreamingTimeframe.ONE_HOUR,
        ) {
          open
          high
          low
          close
          volume
          price_usd
          volume_usd
          chain_name
          pair_address
          interval
          timeframe
          timestamp
        }
      }`,
    {},
    {
      next: (data) => console.log("Received streaming data:", data),
      error: (err) => console.error("Subscription error:", err),
      complete: () => console.info("Subscription completed"),
    }
  );

  // Cleanup function - unsubscribe when component unmounts
  return () => {
    unsubscribe();
  };
}, []);

GraphQL Queries

You can also use raw GraphQL queries for more streamlined and selective data scenarios:

GoldRush SDK

const unsubscribeNewPairs = client.StreamingService.rawQuery(
  `subscription {
       newPairs(
         chain_name: BASE_MAINNET,
         protocols: [UNISWAP_V2, UNISWAP_V3]
       ) {
         chain_name
         protocol
         pair_address
         tx_hash
         liquidity
         base_token_metadata {
           contract_name
           contract_ticker_symbol
         }
         quote_token_metadata {
           contract_name
           contract_ticker_symbol
         }
       }
     }`,
  {},
  {
    next: (data) => console.log("Raw new pairs data:", data),
    error: (error) => console.error("Error:", error),
  }
);

// Raw query for token OHLCV data
const unsubscribeTokenOHLCV = client.StreamingService.rawQuery(
  `subscription {
      ohlcvCandlesForToken(
        chain_name: BASE_MAINNET
        token_addresses: ["0x4B6104755AfB5Da4581B81C552DA3A25608c73B8"]
        interval: ONE_MINUTE
        timeframe: ONE_HOUR
      ) {
        open
        high
        low
        close
        volume
        volume_usd
        quote_rate
        quote_rate_usd
        timestamp
        base_token {
          contract_name
          contract_ticker_symbol
        }
      }
    }`,
  {},
  {
    next: (data) => console.log("Raw token OHLCV data:", data),
    error: (error) => console.error("Error:", error),
  }
);