Getting Started with the GoldRush SDK

The GoldRush SDK is a one-stop solution for access to blockchain data, including token balances, historical transactions, NFT metadata and more.

Introduction

The GoldRush SDK allows you to easily access the GoldRush Unified API through a programmer-friendly interface, with comprehensive support for all Class A, Class B, and Pricing endpoints grouped under various Services. Here is a list of functionalities and capabilities:

SecurityService: Access to GoldRush's approvals endpoint.
BalanceService: Access to GoldRush's balances endpoints.
BaseServices: Access to GoldRush's log events, chain, and block endpoints.
NftService: Access to GoldRush's NFT endpoints.
PricingService: Access to GoldRush's get historical token prices endpoint.
TransactionService: Access to GoldRush's transactions endpoints (with pagination).
XykService: Access to GoldRush's xy=k endpoints.

Getting Started

First, make sure you have a GoldRush API key. You can sign up for one here and use the key created under the API Keys tab in your user dashboard.

Typescript

Find the SDK here.

Note - use Node v18 and above for best results.

Then, install the app using the command:

npm install @covalenthq/client-sdk

yarn add @covalenthq/client-sdk

After installing the app, you can then import and use the SDK:

import { CovalentClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS"); // Example call
    if (!resp.error) {
        console.log(resp.data);
    } else {
        console.log(resp.error_message);
    }
}

Python

Find the SDK here.

Note - use Python 3.7 and above for best results.

Then, install the app using the command:

pip3 install covalent-api-sdk

After installing the app, you can then import and use the SDK:

from covalent import CovalentClient

def main():
    c = CovalentClient("YOUR_KEY")
    b = c.balance_service.get_token_balances_for_wallet_address("eth-mainnet", "demo.eth")
    if not b.error:
        print(b.data.chain_name)
    else:
        print(b.error_message)

Exploring Use Cases

Retrieving Metadata to Render a User's NFTs

Using the SDK, you can easily access the metadata associated with a user's NFTs by calling the NftService.getNFTsForWalletAddress method. Here's how you can do that:

import { CovalentClient } from "@covalenthq/client-sdk";

const getNFTs = async () => {
    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
    const resp = await client.NftService.getNFTsForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
    if (!resp.error) {
        console.log(resp.data);
    } else {
        console.log(resp.error_message);
    }
}

getNFTs();

Getting a List of Transactions for a Specific Wallet

Similarly, you can retrieve a list of transactions for a specific wallet address by calling the TransactionService.getTransactionsForWalletAddress method. Here's an example:

import { CovalentClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
    try {
        for await (const tx of client.TransactionService.getAllTransactionsForAddress("eth-mainnet", "demo.eth")) {
            console.log("tx", tx);
        }
    } catch (error) {
        console.log(error.message);
    }
}

Getting a List of Token Holders for a Specific Token

You can also retrieve a list of token holders for a specific token contract address by calling the BalanceService.getTokenHoldersV2ForTokenAddress method. Here's an example:

import { CovalentClient } from "@covalenthq/client-sdk";

const getTokenHoldersCount = async () => {
    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
    const tokenAddress = "TOKEN_ADDRESS"; // Replace with the specific token address you're interested in.
    const resp = await client.BalanceService.getTokenHoldersV2ForTokenAddress(tokenAddress, "eth-mainnet");
    
    if (!resp.error) {
        const holderCount = resp.data.items.length; // Assuming the items array contains the holder information.
        console.log(`Number of token holders for token address ${tokenAddress}: ${holderCount}`);
    } else {
        console.log(resp.error_message);
    }
}

getTokenHoldersCount();

Pagination

The following endpoints support pagination:

getErc20TransfersForWalletAddress()
getTokenHoldersV2ForTokenAddress()
getBlockHeights()
getLogEventsByAddress()
getLogEventsByTopicHash()
getChainCollections()
getTokenIdsForContractWithMetadata()
getAllTransactionsForAddress()

Currently, the above-mentioned endpoints are the only ones equipped with pagination capabilities, offering 100 results per page. To advance to the subsequent page, either utilize the link url or the page-number supplied within the endpoint's response.

Pagination with the SDK

With the SDK, developers can specify the desired number of concurrent API calls they wish to make using the threadCount parameter, like so:

import { CovalentClient, CovalentClientSettings } from "@covalenthq/client-sdk";

const settings: CovalentClientSettings = {
    threadCount: 5
}

const ApiServices = async () => {
    const client = new CovalentClient("YOUR_API_KEY", settings); // Replace with your Covalent API key and add set debugger
    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
    if (!resp.error) {
        console.log(resp.data);
    } else {
        console.log(resp.error_message);
    }
}

Pagination with HTTP Request

Without the SDK, developers are required to manually manage page numbers and make successive calls to the API until they've retrieved all the required data.

To get historical transactions as we did above, a developer would call the Get paginated transactions for address (v3) endpoint, specifying a page number (starting at 0).

Here’s what an HTTP request would typically look like:

<https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/transactions_v3/page/0/?key={APIKEY}>

In order to retrieve the next set of transactions (the next page), the developer would increment the page number:

<https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/transactions_v3/page/1/?key={APIKEY}>

This process continues until the returned page has fewer than 100 transactions, indicating it's the last page of data.

Advantages of Pagination with the GoldRush SDK

The HTTP method can pose challenges for developers, such as having to manage page numbers, potential rate limiting, and failed requests. The SDK abstracts these complexities and offers a much more streamlined approach. Additionally the consistent and predictable experience is a plus, with a unified method interface that makes code cleaner and more maintainable.

Conclusion

In conclusion, the GoldRush SDK is an easy-to-use tool that simplifies a plethora of Web3 use cases. To learn more about the GoldRush SDK and the transition from HTTP to simplified blockchain development, check out our blog post here.

A Guide to DeFi Taxes

How To Create a DAO with Smart Contracts