Covalent Getting Started: API Keys and First Request (2026)

Getting started overview

This guide provides a rapid onboarding path for Covalent, focusing on the essential steps to get your first API call working. Covalent provides a Unified API designed to aggregate data from various blockchain networks, simplifying access for developers building dApps, analytics platforms, and other blockchain-powered solutions. The process involves creating an account, generating an API key, and then using that key to authenticate your requests to the Covalent API. A free tier is available, providing up to 1 million API calls per month, which is suitable for initial development and testing Covalent pricing plans.

The core of Covalent's offering is its ability to index and serve data from numerous blockchains through a consistent API interface. This abstracts away the complexities of interacting with individual blockchain nodes and understanding different chain-specific data structures. Developers can query wallet balances, NFT metadata, transaction histories, and more across supported networks like Ethereum, Polygon, and Avalanche, using a single set of endpoints Covalent official documentation.

Here is a quick reference table outlining the steps:

Create an account and get keys

To begin using Covalent, you must first create an account on their platform. This registration process typically involves providing an email address and setting a password. Once registered, you will gain access to the Covalent dashboard, which serves as your central hub for managing API keys, monitoring usage, and accessing documentation.

Upon logging into your dashboard, locate the section dedicated to API keys. This section is usually clearly labeled, often under headings like "API Keys," "Developers," or "Settings." Within this area, you will find an option to generate a new API key. Covalent API keys are unique identifiers that authenticate your requests, linking them to your account and ensuring you stay within your plan's usage limits. It is crucial to treat your API key as sensitive information, similar to a password, to prevent unauthorized access to your account and API usage.

After generating your API key, copy it immediately and store it securely. Best practices recommend using environment variables or a secrets management system rather than hardcoding the key directly into your application's source code. This approach helps prevent accidental exposure of your key if your code repository becomes public. For development purposes, you might temporarily store it in a .env file. Remember that a compromised API key could lead to unauthorized usage and potential charges if you are on a paid plan. Covalent provides detailed guidance on Covalent API key management within their documentation.

Covalent's API keys are designed to be project-specific. This means you can generate multiple API keys if you are working on different projects or need to revoke access for a specific application without affecting others. Regularly rotating API keys is another security measure that can help mitigate risks associated with long-lived credentials. The dashboard will typically offer options to view, revoke, and generate new keys as needed.

Your first request

Once you have your API key, you can make your first request to the Covalent API. A common starting point is to fetch the historical transactions for a specific wallet address on a given blockchain. For this example, we will use the Ethereum Mainnet (chain ID 1) and a sample wallet address.

Covalent's API endpoints follow a consistent structure. The base URL for the API is generally https://api.covalenthq.com/v1/. All requests require your API key, typically passed as a query parameter named key.

Example: Get historical transactions for a wallet

This example demonstrates how to retrieve the ERC20 token balances for a specific wallet address on the Ethereum blockchain. We will use a public Ethereum address for demonstration purposes.

API Endpoint

GET https://api.covalenthq.com/v1/{chain_id}/address/{wallet_address}/balances_v2/

Parameters

• chain_id: The ID of the blockchain network (e.g., 1 for Ethereum Mainnet, 137 for Polygon Mainnet).
• wallet_address: The public address of the wallet you want to query.
• key: Your Covalent API key.

Sample Request (using curl)

Replace YOUR_API_KEY with your actual Covalent API key and 0x... with a valid Ethereum wallet address (e.g., 0x742d35Cc6634C053292a3b8bc03451f8CcBc532e).

curl -X GET \
  'https://api.covalenthq.com/v1/1/address/0x742d35Cc6634C053292a3b8bc03451f8CcBc532e/balances_v2/?key=YOUR_API_KEY' \
  -H 'Accept: application/json'

Expected Response Structure (abbreviated)

{
  "data": {
    "address": "0x742d35Cc6634C053292a3b8bc03451f8CcBc532e",
    "updated_at": "2026-05-29T10:00:00.000000Z",
    "next_update_at": "2026-05-29T10:01:00.000000Z",
    "quote_currency": "USD",
    "chain_id": 1,
    "items": [
      {
        "contract_decimals": 18,
        "contract_name": "Wrapped Ether",
        "contract_ticker_symbol": "WETH",
        "contract_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "logo_url": "https://logos.covalenthq.com/tokens/1/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.png",
        "balance": "1000000000000000000",
        "quote_rate": 3800.50,
        "quote": 3800.50
      }
      // ... other token balances
    ]
  },
  "error": false,
  "error_message": null,
  "error_code": null
}

This response provides an array of token balances associated with the specified wallet address, including details like contract name, symbol, balance (in its smallest unit), and its current quoted value in USD. The balance field needs to be divided by 10^contract_decimals to get the human-readable amount.

Using SDKs

Covalent also provides official SDKs for popular languages like JavaScript, Python, and Go, which simplify API interaction by handling request construction, authentication, and response parsing. For example, using the JavaScript SDK:

import { CovalentClient } from "@covalenthq/client-sdk";

const client = new CovalentClient("YOUR_API_KEY");

async function getWalletBalances(chainId, walletAddress) {
  try {
    const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
      chainId,
      walletAddress
    );
    console.log(resp.data);
  } catch (error) {
    console.error("Error fetching balances:", error);
  }
}

getWalletBalances("1", "0x742d35Cc6634C053292a3b8bc03451f8CcBc532e");

This JavaScript example demonstrates how the SDK abstracts the HTTP request details, allowing developers to focus on the data they need. Information on setting up and using the SDKs can be found in the Covalent SDK documentation.

Common next steps

After successfully making your first API call, consider these next steps to deepen your integration with Covalent:

1. Explore More Endpoints: Covalent offers a wide range of endpoints beyond just wallet balances. Explore the Covalent API reference to discover endpoints for NFT data, transaction details, historical prices, and more. Understanding the available data types will help you build more comprehensive blockchain applications.
2. Integrate SDKs: While direct HTTP calls are useful for testing, integrating one of Covalent's official SDKs (JavaScript, Python, Go) can streamline your development process. SDKs handle authentication, error handling, and data parsing, making it easier to consume API responses in your preferred programming language Covalent SDK guides.
3. Implement Error Handling: As with any external API, implement robust error handling in your application. Covalent's API responses include error, error_message, and error_code fields to help diagnose issues. Refer to the documentation for specific error codes and their meanings.
4. Monitor Usage: Regularly check your API usage through the Covalent dashboard. This helps ensure you stay within your plan's limits and can anticipate when an upgrade might be necessary, especially if your application scales. You can set up alerts for usage thresholds if offered by the platform.
5. Optimize Queries: For applications requiring high performance, learn about Covalent's query parameters for pagination, filtering, and sorting. Efficiently structured queries reduce load times and API call counts, contributing to better user experience and cost management.
6. Explore Webhooks (if available): For real-time updates without constant polling, investigate if Covalent offers webhook functionality. Webhooks can push data to your application when specific events occur on the blockchain, such as new transactions or contract events. While not explicitly detailed in the provided payload, many API providers offer this for event-driven architectures, as discussed in general API design principles Google Cloud webhooks overview.
7. Security Best Practices: Review and implement security best practices for handling API keys, such as using environment variables, managed secrets services, and IP whitelisting if supported. Avoid hardcoding credentials directly into your codebase.

Troubleshooting the first call

Encountering issues with your initial API call is common. Here's a checklist to help diagnose and resolve problems:

• Invalid API Key:
  • Symptom: 401 Unauthorized or 403 Forbidden errors.
  • Solution: Double-check that your API key is correctly copied from your Covalent dashboard and included in the request URL. Ensure there are no leading or trailing spaces. Generate a new key if uncertain about the existing one's validity.
• Incorrect Endpoint or Parameters:
  • Symptom: 404 Not Found or 400 Bad Request errors; unexpected or empty data in the response.
  • Solution: Verify the endpoint URL against the Covalent API reference. Ensure all required path parameters (like chain_id and wallet_address) are correctly formatted and positioned. Check query parameters for correct names and values.
• Missing Headers:
  • Symptom: Requests fail or return malformed responses.
  • Solution: Ensure you are sending the Accept: application/json header. While curl often defaults to this, some HTTP clients or libraries require it explicitly.
• Network Issues:
  • Symptom: Request timeouts, connection errors.
  • Solution: Verify your internet connection. If you are behind a corporate firewall or VPN, ensure that access to api.covalenthq.com is permitted.
• Rate Limits Exceeded:
  • Symptom: 429 Too Many Requests error.
  • Solution: If you are on the free tier, you might hit limits quickly during testing. Wait a short period and retry. For sustained usage, consider upgrading your plan or implementing exponential backoff and retry logic in your application.
• Incorrect Chain ID or Wallet Address:
  • Symptom: Valid API key but no data returned, or an empty items array.
  • Solution: Confirm that the chain_id corresponds to the correct blockchain (e.g., 1 for Ethereum, 137 for Polygon, 43114 for Avalanche C-chain Avalanche Chain IDs). Double-check the wallet address for typos. Use a known active address for initial tests.
• SDK Specific Issues:
  • Symptom: Errors related to SDK methods or instantiation.
  • Solution: Ensure the SDK is correctly installed and imported. Verify that you are calling the methods as documented in the Covalent SDK documentation. Check the SDK's version for compatibility.
• Review Covalent Status Page:
  • Symptom: Widespread API failures across different endpoints.
  • Solution: Check Covalent's official status page (usually linked from their docs or homepage) for any ongoing service disruptions or maintenance.