> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Foundational API 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](https://goldrush.dev/platform/auth/register/). This key will be required for all requests to the Foundational API.

<CardGroup cols={2}>
  <Card icon="wand-magic-sparkles" title="Vibe Coders" href="https://goldrush.dev/platform/auth/register/?plan=vibe">
    \$10/mo - Built for solo builders and AI-native workflows.
  </Card>

  <Card icon="users" title="Teams" href="https://goldrush.dev/platform/auth/register/?plan=professional">
    \$250/mo - Production-grade with 50 RPS and priority support.
  </Card>
</CardGroup>

### API Key Format

A GoldRush API key is prefixed with `cqt_` (or `ckey_` for legacy keys), followed by 26 base58 characters — for example, `cqt_wF…` or `cqt_rQ…`. The same key works across every GoldRush product: Foundational, Streaming, JSON-RPC, Hyperliquid, and x402.

<Note>
  Throughout these docs, the placeholder `<GOLDRUSH_API_KEY>` marks where to substitute your own key. Replace the entire token, including the angle brackets, with your real `cqt_…` key (or read it from a `GOLDRUSH_API_KEY` environment variable, as shown in the code samples). Never commit a real key to source control.
</Note>

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

<Tabs>
  <Tab title="TypeScript">
    Initialize the client with your API key:

    ```typescript theme={null}
    import { GoldRushClient } from "@covalenthq/client-sdk";

    const ApiServices = async () => {
        const client = new GoldRushClient("<GOLDRUSH_API_KEY>"); // 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();
    ```
  </Tab>
</Tabs>

### Direct API Calls

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

<AccordionGroup>
  <Accordion title="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.

    ```bash theme={null}
    curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
         -u <GOLDRUSH_API_KEY>: \
         -H 'Content-Type: application/json'
    ```
  </Accordion>

  <Accordion title="Bearer Token">
    Provide your API key in an `Authorization` header with the `Bearer` scheme.

    ```bash theme={null}
    curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
         -H 'Authorization: Bearer <GOLDRUSH_API_KEY>'
    ```
  </Accordion>

  <Accordion title="Query Parameter">
    Include your API key as the `key` query parameter in the request URL.

    ```bash theme={null}
    curl -X GET "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/?key=<GOLDRUSH_API_KEY>"
    ```
  </Accordion>
</AccordionGroup>

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

For a complete guide to error codes, retry strategies, and debugging tips, see [Error Handling & Troubleshooting](/error-handling).

## Frequently Asked Questions (FAQ)

* **Which authentication method should I use?**
  * We strongly recommend using our [SDKs](#using-sdks-recommended) 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](https://goldrush.dev/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.