Overview

The GoldRush API can be used to easily retrieve onchain data including token balances, positions and historical granular transaction data from dozens of blockchain networks. This data enables hundreds of use-cases like wallets, taxation tools, AI model training, onchain data forensics, and many other use-cases. The GoldRush API is powered by the Covalent Network.

Get Started

Sign up for a free API key to get started with the GoldRush API.

Accessing the GoldRush API

The GoldRush API offers flexible and powerful ways to access blockchain data. You can make direct HTTP requests to various endpoints, or for a more streamlined and integrated experience, use one of our GoldRush SDKs. The SDKs are the preferred method as they provide additional convenience and handle many of the complexities for you.

Using SDKs (Recommended)

For easier integration and additional functionality, use one of our SDKs. The SDKs are available in various languages including TypeScript, Python, and Go. Simply initialize the SDK with your API key:

Direct API calls

You can access the GoldRush API by making HTTP requests to the desired endpoints. Here’s an example using curl:

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

Authentication

Requests to the GoldRush API requires a user account and an API key which can be found on the GoldRush platform. Various authentication mechanisms are available:

Query parameter

bash

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

Basic auth

bash

curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
     -u API_KEY:
     -H 'Content-Type: application/json'
     # The colon prevents curl from asking for a password.

Provide your API key as the basic auth username. You can find your API key in the web interface. You do not need to provide a password.

SDK authentication

The easiest way to authenticate is by using one of our SDKs. Simply initialize the SDK with your API key. Refer to the Using SDKs section for examples in TypeScript, Python, and Go.

Response format

JSON

❴
    "data": {...},
    "error": false,
    "error_message": null,
    "error_code": null
❵

By default, the GoldRush API returns JSON responses with the same shape for all endpoints. The main keys are data, error, error_message and error_code.

Supported networks

The GoldRush API supports over 200+ different blockchains. For a full list see here.

Rate limits

We have a rate limit of 5 requests per second per API key and a volume limit of 100,000 API credits per month for free users, which resets on the first of each month.

If you upgrade to a Premium subscription, you get access to higher rate limits and the ability to consume beyond the 100,000 credit limit using Flex Credits. See the pricing page for more information.

Rate limit error mitigation

Due to the various layers of our infrastructure, you should expect to receive some 429-Too Many Requests responses as you ramp up your API requests per second. If you start to see these errors, implement the following:

1. Limit Concurrency: Implement a client that uses a worker-pool or semaphore to manage the number of concurrent requests.

2. Serialized Requests: Within each worker thread, make requests one after another in a blocking manner. This can be done by processing requests from a work queue in a loop.

3. Retry Strategy: Use an exponential-backoff retry mechanism for handling request failures, ensuring that retries are spaced out with increasing intervals.

The various SDKs automatically implement the above mechanisms.

Refresh rate

The GoldRush API has two types of endpoints:

1. Realtime: These endpoints have a delay of 2 blocks. On blockchains like Ethereum, with block times of 15 seconds, the delay will be 30 seconds. On Polygon, with block times of 3 seconds, the delay will be 6 seconds.
2. Batch: These endpoints have a delay of 30 minutes.

Error codes

The GoldRush API uses standard HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate a server error.

Code	Description
200 - OK	Everything worked as expected.
400 - Bad Request	The request could not be accepted, usually due to a missing required parameter.
401 - Unauthorized	No valid API key was provided.
404 - Not Found	The request path does not exist.
429 - Too Many Requests	You are being rate-limited. Please see the rate limit section for more information.
500, 502, 503 - Server Errors	Something went wrong on a server.