FAQs

These FAQs are a self-serve support resource for the Covalent API and organized into the following sections:

  1. General Use
  2. Class A Endpoints
  3. Class B Endpoints
  4. Pricing Endpoints
  5. Miscellaneous

General Use

How do I query an endpoint?

The API host for all requests is https://api.covalenthq.com/v1/.

The endpoint path is appended to the API host (without repeating the /v1/). For example, if the endpoint is:

Query Endpoint

then an example of the full request URL is simply:

https://api.covalenthq.com/v1/1/address/0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B/balances_v2/

 
All Covalent API endpoints are called using GET requests.

Each request must include your API_KEY passed either in the request header (Basic Auth) or as a query parameter (see below).

Your API_KEY starts with ckey_.

 

What can I build using the API?

The Covalent API can be used across a wide variety of Web3 use cases from custom wallets, to NFT marketplaces and dashboards to gaming. Learn how to build popular Web3 dapps using the API by checking out our use case examples here.

 

When should I use Basic Auth over authenticating via query parameter?

We recommend that you should always use Basic Auth over authenticating via query parameter when possible. Authentication via query parameter is offered for all endpoints to make it very simple for developers to use the API:

curl -X GET https://api.covalenthq.com/v1/ENDPOINT/?key=YOUR_API_KEY

 
This works well when embedding the API in applications like Google Sheets or as iFrames that do not support more sophisticated auth methods. However, a key benefit of using Basic Auth is that your request can reliably take advantage of our caching mechanism for better query performance.

curl -X GET https://api.covalenthq.com/v1/ENDPOINT/ \    
    -u API_KEY:   
    -H ‘Content-Type: application/json’
    # The colon prevents curl from asking for a password

 
where API_KEY is passed as the username with no password.

 

What is the chain_id?

The chain_id parameter is the unique integer identifier of an EVM-supported blockchain network. A global list of EVM network Chain IDs can be found at: https://chainlist.org/. For example, Ethereum Mainnet has a chain_id of 1 while Ethereum Kovan Testnet has a chain_id of 42.

See the full list of Covalent API supported networks and their corresponding chain_id values.

 

What are the current API rate limits?

  • 5 requests per second per API key (~13M requests per month)
  • 1,000,000 block range per request for endpoints (such as decoded log events) requiring a block range

 

What if I need a higher API rate limit?

In most of the cases, we have noticed that clients don’t actually need higher rate limits as they can do the following:

  • Random access: distribute/queue their load at a gateway level to smooth unpredicted spikes
  • Per-client polling: distribute their clients’ polls within the polling period using client-ID hashing.

Here are some steps we recommend to optimize the client-side code:

  • Create a queue for your requests.
  • Have a thread that pops requests from the queue at a rate of no more than 5 per second and kicks them off asynchronously (e.g. in a new thread/fiber or in a worker pool).

We are currently exploring tiered plans for our API with a higher service tier. If interested, please complete this short typeform to be amongst the first we contact when any tiered service goes live.

 

Why do I only get back 100 items (or rows) of data?

By default, the API returns 100 items in a single page. To get all the data, simply pass a large value for the page-size parameter in your request.

 

What do the following error messages mean in the context of the Covalent API?

  • 404: Page Unavailable - The API server cannot find the requested API resource. Check your request endpoint.
  • 406: Address Will Predictably Timeout - The API returns this error for addresses where requests will likely timeout due to, as an example, too many transactions associated with the address.
  • 429: Too Many Requests - The client has surpassed its rate limit. This may also be indicated by the server 503: Network Error.
  • 500: Request Timeout - This error response is given when the query will take longer than approximately 90 seconds.
  • 503: Network Error - The API server cannot 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 couple 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 are likely aware of the issue and reviewing the queries consuming the resources.
  • 562: Failed to connect to upstream third-party service - The API server can’t reach the external server where the data is hosted at the moment. This is intentionally done in order to avoid returning erroneous data.

 

How do I get data in CSV format?

Just use the query parameter format=csv in your request. For example:

https://api.covalenthq.com/v1/1/address/0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B/balances_v2/?key=YOUR_API_KEY&format=csv

 
Using our API Reference, you can also switch to Analyst Mode in the global settings and download files directly in CSV format.

 

How do I fix the CORS header ‘Access-Control-Allow-Origin’ missing error?

CORS is an HTTP header-based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources. If you are running your app locally on localhost, you may run into this error when trying to make API calls.

One workaround is to use this extension.


 

Class A Endpoints

Why is the logo_url sometimes missing in the response of Get token balances for address?

We fetch the logos from the Trust Wallet repository. If your logo is not available there, the token balances endpoint will not be able to fetch it.

Use the Trust Wallet Assets web app to add your token and corresponding logo.

 

Why are some NFT collections not found using the Get historical data for NFT collection endpoint, even though they are found using the Get NFT external metadata for contract?

The Get historical data for NFT Collection only supports collections that have had sales activity on a supported NFT marketplaces.

Get NFT external metadata for contract supports all chains and collections.

 

Why does the call to Get token balances for address sometimes timeout when using the nft=true option?

Timouts using the nft=true option are likely due to corresponding timeouts with an external service call made by our API to fetch the NFT metadata. You can confirm this by making the same call and setting no-nft-fetch=true and see if that returns successfully.

 

What is a “dust” token?

When fetching token balances for an externally owned account (EOA), if a token’s quote value is less than 0.10 USD equivalent, it is classified as dust.


 

Class B Endpoints

Why are there data issues with the PancakeSwap endpoints?

The standalone PancakeSwap Class B endpoints are no longer maintained as PancakeSwap is now a supported DEX under the XY=K category of endpoints.

You can try the PancakeSwap XY=K endpoints here using pancakeswap_v2 as the dexname and chain_id=56 for BSC Mainnet.


 

Pricing Endpoints

Why are the token quote rates different than the rates from another provider like CoinGecko?

Token quote rates are currently fetched in BTC and then coverted into USD which likely causes the discrepancies. This will be changed soon with the launch of a new pricing endpoint powered by AMMs across all supported blockchains.

 

Why are quote_rates for some tokens unusually high?

When token prices are not available from our pricing provider, we attempt to calculate the quote_rate ourselves based on its trading parameters from an automated market maker (AMM). Certain tokens that are being traded this way have extremely low trading volume, which when used as an input to an AMM pricing calculation leads to very high token prices. At this time, we recommend users implement a quote_rate threshold to filter out these low-volume tokens where the quote_rate is much too high.


 

Miscellaneous

How do I contact Developer Support when I’m stuck?

We have API support staff available on Discord. Please ask all questions in the #feedback-and-support channel.

Last modified: October 27, 2022: october-changelog-2022 (#243) (b6121bb)