Authentication

End-to-end guide for authenticating with the GoldRush Foundational API.

This document provides a comprehensive overview of the authentication process for the Foundational API. All APIs are protected and require a valid GoldRush API key to access. This guide covers how to obtain and use an API key, with examples for both our SDKs and direct REST API calls.

Why is Authentication Required?

Authentication is essential to ensure that only authorized users can access the Foundational API. It allows us to manage access, track usage for billing, and ensure the security and stability of our services.

1. Obtaining a GoldRush API Key

To begin, register for an API key at the GoldRush Platform. This key will be required for all requests to the Foundational API.

2. Supplying the API Key

The Foundational API offers flexible and powerful ways to access blockchain data. You can use one of our GoldRush SDKs for a streamlined experience, or make direct HTTP requests to the various REST APIs.

Using SDKs (Recommended)

For easier integration and to take advantage of built-in features like automatic retries and rate limit handling, we recommend using the TypeScript Client SDK.

TypeScript

Initialize the client with your API key:

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

const ApiServices = async () => {
    const client = new GoldRushClient("YOUR_API_KEY_HERE"); // Replace with your GoldRush API key
    const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
        chainName: "eth-mainnet",
        walletAddress: "vitalik.eth"
    });
    
    if (!resp.error) {
        console.log(resp.data);
    } else {
        console.log(resp.error_message);
    }
};

ApiServices();

Direct API Calls

You can also authenticate by including your API key in direct HTTP requests.

Basic Authentication

Provide your API key as the Basic Auth username. You do not need to provide a password. The trailing colon (:) prevents curl from prompting for a password.

curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
     -u YOUR_API_KEY_HERE: \
     -H 'Content-Type: application/json'

Bearer Token

Provide your API key in an Authorization header with the Bearer scheme.

curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
     -H 'Authorization: Bearer YOUR_API_KEY_HERE'

Query Parameter

Include your API key as the key query parameter in the request URL.

curl -X GET "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/?key=YOUR_API_KEY_HERE"

Error Handling

If an authentication-related error occurs, the API will return a 4XX HTTP status code and a JSON body with details.

Code	Description
401 - Unauthorized	No valid API key was provided, or the key is incorrect.
402 - Payment Required	The account has consumed its allocated API credits.
429 - Too Many Requests	You are being rate-limited.

Frequently Asked Questions (FAQ)

• Which authentication method should I use?

  • We strongly recommend using our SDKs for the best developer experience. If you must make direct API calls, Basic Authentication is preferred over other methods for its security. Placing API keys in URLs (query parameter) is generally discouraged.

• Where can I find my API Key?

  • You can find your API key on the GoldRush Platform after signing up or logging in.

• Are the API keys the same for the different GoldRush products?

  • Yes, the same API key is used to authenticate with all GoldRush products.