@covalenthq/client-sdk 2.2.6 → 2.3.0

package/README.md

@@ -46,7 +46,7 @@ The GoldRush SDK is the fastest way to integrate the GoldRush API for working wi
        const balanceResp =
          await client.BalanceService.getTokenBalancesForWalletAddress(
            "eth-mainnet",
-           "demo.eth"
+           "0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
          );
 
        if (balanceResp.error) {
@@ -60,7 +60,7 @@ The GoldRush SDK is the fastest way to integrate the GoldRush API for working wi
    };
    ```
 
-   The `GoldRushClient` can be configured with a second object argument, `settings`. The settings offered are
+   The `GoldRushClient` can be configured with a second object argument, `settings`, and a third argument for `streamingConfig`. The settings offered are
 
    1. **debug**: A boolean that enables server logs of the API calls, enhanced with the request URL, response time and code, and other settings. It is set as `false` by default.
    2. **threadCount**: A number that sets the number of concurrent requests allowed. It is set as `2` by default.
@@ -69,6 +69,15 @@ The GoldRush SDK is the fastest way to integrate the GoldRush API for working wi
    5. **retryDelay**: A number that sets the delay in `ms` for retrying the API endpoint in case of `429 - rate limit` error. To be in effect, it requires `enableRetry` to be enabled. It is set as `2` by default.
    6. **source**: A string that defines the `source` of the request of better analytics.
 
+   The `streamingConfig` is optional and configures the real-time streaming service. The available options are:
+
+   1. **shouldRetry**: A function that determines whether to retry connection based on retry count. Defaults to retry up to 5 times.
+   2. **maxReconnectAttempts**: Maximum number of reconnection attempts. Defaults to `5`.
+   3. **onConnecting**: Callback function triggered when connecting to the streaming service.
+   4. **onOpened**: Callback function triggered when connection is successfully established.
+   5. **onClosed**: Callback function triggered when connection is closed.
+   6. **onError**: Callback function triggered when an error occurs.
+
 ## Features
 
 ### 1. Name Resolution
@@ -89,7 +98,7 @@ For example, the following sets the `quoteCurrency` query parameter to `CAD` and
 ```ts
 const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
   "eth-mainnet",
-  "demo.eth",
+  "0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de",
   {
     quoteCurrency: "CAD",
     nft: true,
@@ -112,7 +121,7 @@ import {
 
 const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
   "eth-mainnet",
-  "demo.eth",
+  "0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de",
   {
     quoteCurrency: "CAD",
     nft: true,
@@ -136,7 +145,7 @@ The SDK supports the following formats for the chain input:
 
 For paginated responses, the GoldRush API can at max support 100 items per page. However, the Covalent SDK leverages generators to _seamlessly fetch all items without the user having to deal with pagination_.
 
-For example, the following fetches ALL transactions for `demo.eth` on Ethereum:
+For example, the following fetches ALL transactions for `0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de` on Ethereum:
 
 ```ts
 import { GoldRushClient } from "@covalenthq/client-sdk";
@@ -146,7 +155,7 @@ const ApiServices = async () => {
   try {
     for await (const tx of client.TransactionService.getAllTransactionsForAddress(
       "eth-mainnet",
-      "demo.eth"
+      "0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
     )) {
       console.log("tx", tx);
     }
@@ -166,7 +175,7 @@ import { GoldRushClient } from "@covalenthq/client-sdk";
 const client = new GoldRushClient("<YOUR_API_KEY>");
 const resp = await client.TransactionService.getAllTransactionsForAddressByPage(
   "eth-mainnet",
-  "demo.eth"
+  "0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
 ); // assuming resp.data.current_page is 10
 if (resp.data !== null) {
   const prevPage = await resp.data.prev(); // will retrieve page 9
@@ -216,7 +225,219 @@ if (resp.data !== null) {
 
    You can explore more examples [here](./test/unit/timestamp-parser.test.ts)
 
-### 8. Standardized (Error) Responses
+### 8. Real-time Streaming
+
+The GoldRush SDK now supports real-time streaming of blockchain data via WebSocket connections. This allows you to subscribe to live data feeds for OHLCV (Open, High, Low, Close, Volume) data for trading pairs and tokens, new DEX pair creations, wallet activity, and more.
+
+```ts
+import {
+  GoldRushClient,
+  StreamingChain,
+  StreamingInterval,
+  StreamingTimeframe,
+  StreamingProtocol,
+} from "@covalenthq/client-sdk";
+
+const client = new GoldRushClient(
+  "<YOUR_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 unsubscribePairs = 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
+// unsubscribePairs();
+
+// 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`.
+
+```ts
+// Create a single client
+const client = new GoldRushClient("<YOUR_API_KEY>");
+
+// 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:
+
+```tsx
+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();
+  };
+}, []);
+```
+
+#### Raw Queries
+
+You can also use raw GraphQL queries for more streamlined and selective data scenarios:
+
+```ts
+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),
+  }
+);
+```
+
+### 9. Standardized (Error) Responses
 
 All the responses are of the same standardized format
 
@@ -343,6 +564,23 @@ The Covalent SDK provides comprehensive support for all Class A, Class B, and Pr
 - `getEarliestTransactionsForAddress()`: Fetch and render the earliest transactions involving an address. Frequently seen in wallet applications.
 </details>
 
+<details>
+  <summary>
+   9. <strong>Streaming Service</strong>: Real-time blockchain data streaming via WebSocket connections
+  </summary>
+
+- `getClient()`: Get the underlying GraphQL WebSocket client for direct access.
+- `isConnected`: Check the connection status of the streaming service.
+- `subscribeToOHLCVPairs()`: Subscribe to real-time OHLCV (Open, High, Low, Close, Volume) data for specific trading pairs. Supports multiple chains and configurable intervals and timeframes.
+- `subscribeToOHLCVTokens()`: Subscribe to real-time OHLCV (Open, High, Low, Close, Volume) data for specific tokens. Tracks token prices across their primary DEX pools with configurable intervals and timeframes.
+- `subscribeToTokenBalances()`: Subscribe to real-time token balance updates for a specific wallet address. Tracks balance changes across native and ERC-20 tokens with USD valuations.
+- `subscribeToWalletActivity()`: Subscribe to real-time wallet activity including transactions, token transfers, and smart contract interactions. Provides decoded transaction details for swaps, transfers, bridges, deposits, withdrawals, and approvals.
+- `subscribeToNewPairs()`: Subscribe to real-time notifications when new liquidity pairs are created on supported decentralized exchanges (DEXes). Supports Uniswap V2/V3 across Base, Ethereum, and BSC networks.
+- `rawQuery()`: Execute custom GraphQL subscription queries for advanced streaming scenarios and future extensibility.
+- `disconnect()`: Properly disconnect from the streaming service.
+
+</details>
+
 ## Contributing
 
 Contributions, issues and feature requests are welcome!

package/dist/cjs/index.d.ts

@@ -12,4 +12,5 @@ export * from "./src/utils/types/Generic.types";
 export * from "./src/utils/types/NftService.types";
 export * from "./src/utils/types/PricingService.types";
 export * from "./src/utils/types/SecurityService.types";
+export * from "./src/utils/types/StreamingService.types";
 export * from "./src/utils/types/TransactionService.types";