GoldRush SDK for TypeScript

The GoldRush SDK is the fastest way to integrate the GoldRush API for working with blockchain data. The SDK works with all supported chains including Mainnets and Testnets.

> Use with NodeJS v18 or above for best results.

> The GoldRush API is required. You can register for a free key on GoldRush's website

Using the SDK

> You can also follow the video tutorial

1. Install the dependencies

``bash
npm install @covalenthq/client-sdk
`

2. Create a client using the GoldRushClient

`ts
import { GoldRushClient, Chains } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");

const ApiServices = async () => {
try {
const balanceResp =
await client.BalanceService.getTokenBalancesForWalletAddress(
"eth-mainnet",
"0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
);

if (balanceResp.error) {
throw balanceResp;
}

console.log(balanceResp.data);
} catch (error) {
console.error(error);
}
};
`

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.
3. enableRetry: A boolean that enables retrying the API endpoint in case of a 429 - rate limit error. It is set as true by default.
4. maxRetries: A number that sets the number of retries to be made in case of 429 - rate limit error. To be in effect, it requires enableRetry to be enabled. It is set as 2 by default.
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

$3

The GoldRush SDK natively resolves the underlying wallet address for the following

1. ENS Domains (e.g. demo.eth)
2. Lens Handles (e.g. demo.lens)
3. Unstoppable Domains (e.g. demo.x)
4. RNS Domains (e.g. demo.ron)

$3

All the API call arguments have an option to pass typed objects as Query parameters.

For example, the following sets the quoteCurrency query parameter to CAD and the parameter nft to true for fetching all the token balances, including NFTs, for a wallet address:

`ts
const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
"eth-mainnet",
"0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de",
{
quoteCurrency: "CAD",
nft: true,
}
);
`

$3

All the interfaces used, for arguments, query parameters and responses are also exported from the package which can be used for custom usage.

For example, explicitly typecasting the response

`ts
import {
GoldRushClient,
type BalancesResponse,
type BalanceItem,
} from "@covalenthq/client-sdk";

const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
"eth-mainnet",
"0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de",
{
quoteCurrency: "CAD",
nft: true,
}
);

const data: BalancesResponse = resp.data;
const items: BalanceItem[] = resp.data.items;
`

$3

The SDK supports the following formats for the chain input:

1. Chain Name (e.g. eth-mainnet)
2. Chain ID (e.g. 1)
3. Chain Name Enum (e.g. ChainName.ETH_MAINNET)
4. Chain ID Enum (e.g. ChainID.ETH_MAINNET)

$3

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 0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de on Ethereum:

`ts
import { GoldRushClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
const client = new GoldRushClient("");
try {
for await (const tx of client.TransactionService.getAllTransactionsForAddress(
"eth-mainnet",
"0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
)) {
console.log("tx", tx);
}
} catch (error) {
console.log(error.message);
}
};
`

$3

Paginated methods have been enhanced with the introduction of next() and prev() support functions. These functions facilitate a smoother transition for developers navigating through our links object, which includes prev and next fields. Instead of requiring developers to manually extract values from these fields and create JavaScript API fetch calls for the URL values, the new next() and prev() functions provide a streamlined approach, allowing developers to simulate this behavior more efficiently.

`ts
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.TransactionService.getAllTransactionsForAddressByPage(
"eth-mainnet",
"0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de"
); // assuming resp.data.current_page is 10
if (resp.data !== null) {
const prevPage = await resp.data.prev(); // will retrieve page 9
console.log(prevPage.data);
}
`

$3

1. bigIntParser: Formats input as a bigint value. For example

`ts
bigIntParser("-123"); // -123n
`

You can explore more examples here

2. calculatePrettyBalance: Formats large and raw numbers and bigints to human friendly format. For example

`ts
calculatePrettyBalance(1.5, 3, true, 4); // "0.0015"
`

You can explore more examples here

3. isValidApiKey: Checks for the input as a valid GoldRush API Key. For example

`ts
isValidApiKey(cqt_wF123); // false
`

You can explore more examples here

4. prettifyCurrency: Formats large and raw numbers and bigints to human friendly currency format. For example

`ts
prettifyCurrency(89.0, 2, "CAD"); // "CA$89.00"
`

You can explore more examples here

5. timestampParser: Convert ISO timestamps to various human-readable formats

`ts
timestampParser("2024-10-16T12:39:23.000Z", "descriptive"); // "October 16 2024 at 18:09:23"
`

You can explore more examples here

$3

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(
"",
{},
{
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("");

// 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
quote_rate
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),
}
);
`

$3

All the responses are of the same standardized format

`ts
❴
"data":