Overview

The GoldRush API can be used to easily retrieve onchain data including token balances, positions and historical granular transaction data from 100+ blockchains. This data enables hundreds of use cases like wallets, taxation tools, AI model training, onchain data forensics, and many other applications. 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.

Using SDKs (Recommended)

For easier integration and additional functionality, use one of our available SDKs:

• TypeScript SDK
• Python

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

Authentication

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

SDK authentication

Initialize the SDK with your API key:

Query parameter

Use the key=API_KEY query parameter with your API key.

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

Basic Auth

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 do not need to provide a password.

We recommend that you use Basic Auth over authenticating via query parameter when possible.

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 100+ different blockchains. For a full list see here.

Rate limits

The GoldRush Free Trial limits are 4 requests per second and a fixed volume limit of 25,000 API credits.

Upgrading to GoldRush Professional offers 50 requests per second, 300,000 included API credits and the ability to consume 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
400 - Bad Request	The request could not be accepted, usually due to a missing required parameter.
401 - Unauthorized	No valid API key was provided.
402 - Payment Required	An account has consumed its allocated credits.
404 - Not Found	The request path does not exist.
406 - Address Will Predictably Timeout	The API returns this error for addresses where requests will likely timeout due to, for example, too many transactions associated with the address.
429 - Too Many Requests	You are being rate-limited. See the Rate limits section for more information.
500 - Request Timeout	This error response is given when the query will take longer than approximately 90 seconds.
503 - Network Error	The API server can’t handle the request at the time, which might be due to a high number of concurrent requests or if a server is momentarily down. Retry your request in a few minutes or reduce the number of concurrent requests.
507 - Insufficient Storage	The API server is unreachable to new queries as the backlog of existing queries is full. We’re likely aware of the issue and reviewing the queries consuming the resources.
552 - Connection to web3 provider failed	There is an issue with our RPC node impacting specific endpoints like balances_v2 and balances_nft.
562 - Failed to connect to upstream third-party service	The API is unable to reach the external server where the data is hosted at the moment. This error is intentionally raised to avoid returning erroneous data.