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. 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.
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.

​
Error Handling

If an authentication-related error occurs, the API will return a 4XX HTTP status code and a JSON body with details.
CodeDescription
401 - UnauthorizedNo valid API key was provided, or the key is incorrect.
402 - Payment RequiredThe account has consumed its allocated API credits.
429 - Too Many RequestsYou 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?
  • Are the API keys the same for the different GoldRush products?
    • Yes, the same API key is used to authenticate with all GoldRush products.