FAQ
These FAQs are a self-serve support resource for the Covalent API and organized into the following sections:
General Use
How do you 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 GET /v1/{chain_id}/address/{address}/balances_v2/, then an example of the full request URL is:
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 you 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.
When should you 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 otherwise:
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 don't 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's the chain_id?
The chain_id parameter is the unique integer or name 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.
Note: the Covalent API supports both the chain_id as an integer as well as the chain name. For example, you can use the value of 1 or eth-mainnet in your path parameter.
See the full list of Covalent API supported networks and their corresponding chain_id and name values.
What are the current API rate limits?
See the Covalent API rates card for details on rate limits for the free and premium API tiers.
What if you need a higher API rate limit?
Covalent offers paid Premium APIs for select endpoints which offer higher rate limits.
Why do you 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, 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?
- 402: Payment Required - This error response is given when an account has consumed its allocated credits.
- 404: Page Unavailable - The API server can't 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 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 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're 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 error is intentionally raised to avoid returning erroneous data.
How do you 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 you 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 missing in the response of Get token balances for address?
We fetch token logos from the Trust Wallet repository. If your logo isn't available there, the token balances endpoint won't 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're 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's 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's classified as dust.
How does Covalent determine if an address is involved in a transaction?
What criteria does Covalent use for determining if an address is involved in a transaction? Covalent's transactions endpoints that accept addresses as input will return all transactions where the address appears in:
- the transaction's from field
- the transaction's to field
- a log event's sender field
- a log event's topics
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 using pancakeswap_v2 as the dexname and chain_id of 56 or bsc-mainnet 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 converted 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 aren't 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 too high.
Miscellaneous
What does the message "Support for chain 'klaytn-mainnet' has been sunsetted"?
This message means that the foundation's support contract with Covalent has expired and we've decided to discontinue support for the chain.
How do you contact Developer Support when you're stuck?
We've API support staff available on Discord. Please ask all questions in the #feedback-and-support channel.