Skip to content

Getting Started with the Covalent API

Introduction

Covalent is a hosted blockchain data solution providing access to historical and current on-chain data for 100+ supported blockchains, including Moonbeam, Moonriver, and Moonbase Alpha. Covalent maintains a full archival copy of every supported blockchain, meaning every balance, transaction, log event, and NFT asset data is available from the genesis block. This data is available via:

  • Unified API - incorporate blockchain data into your app with a familiar REST API
  • Increment - create and embed custom charts with no-code analytics

This guide will cover all of the details needed to get started with the Covalent API and how to access the API endpoints for Moonbeam using curl commands and JavaScript and Python snippets.

The information presented herein is for informational purposes only and has been provided by third parties. Moonbeam does not endorse any project listed and described on the Moonbeam docs website (https://docs.moonbeam.network/).

Unified API

Covalent's Unified API is a powerful but easy-to-use REST API that offers visibility to assets across all blockchain networks. It features a consistent request and response object format across networks. For example, a user can fetch all the token balances for a wallet address across any supported blockchain by changing the unique blockchain name or id path parameter in the request URL. Covalent's Unified API can offer more data flexibility than JSON-RPC interfaces, which are typically limited to queries on a specific block. It also allows queries on multiple objects and batch exports of data.

Example API response in JSON Click on the above image to try out the request yourself.

Quick Start

If you're already familiar with Covalent and ready to dive in, you simply need the chainID and network name to get started.

Parameter Value
chainName moonbeam-mainnet
chainID 1284
Parameter Value
chainName moonbeam-moonriver
chainID 1285
Parameter Value
chainName moonbeam-moonbase-alpha
chainID 1287

Fundamentals of the Unified API

  • The Covalent API is RESTful and it is designed around the main resources that are available through the web interface
  • The current version of the API is version 1
  • The default return format for all endpoints is JSON
  • All requests require authentication; you will need a free API Key to use the Covalent API
  • The cost of an API call is denominated in credits and varies depending on the particular call. Upon creating an API key, you're given a substantial amount of free credits to get started (100,000 at the time of writing). You can track your usage of these free credits on the Increment Dashboard
  • The root URL of the API is: https://api.covalenthq.com/v1/
  • All requests are done over HTTPS (calls over plain HTTP will fail)
  • The refresh rate of the APIs is real-time: 30s or 2 blocks, and batch 30m or 40 blocks

Types of Endpoints

The Covalent API has three classes of endpoints:

  • Class A — endpoints that return enriched blockchain data applicable to all blockchain networks, eg: balances, transactions, log events, etc
  • Class B — endpoints that are for a specific protocol on a blockchain, e.g. Uniswap is Ethereum-only and is not applicable to other blockchain networks
  • Class C — endpoints that are community built and maintained but powered by Covalent infrastructure

Sample Supported Endpoints

For a full list of supported endpoints, refer to the Covalent API reference. A subset of the supported endpoints include:

  • Balances — get token balances for an address. Returns a list of all ERC-20 and NFT token balances including ERC-721 and ERC-1155 along with their current spot prices (if available)
  • Transactions — retrieves all transactions for an address including decoded log events. Does a deep-crawl of the blockchain to retrieve all transactions that reference this address
  • Transfers — get ERC-20 token transfers for an address along with historical token prices (if available)
  • Token holders — return a paginated list of token holders
  • Log events (smart contract) — return a paginated list of decoded log events emitted by a particular smart contract
  • Log events (topic hash) — return a paginated list of decoded log events with one or more topic hashes separated by a comma
  • Security (Token Approvals) - return a list of approvals across all token contracts categorized by spenders for a wallet’s assets

Request Formatting

Endpoint Format
Balances api.covalenthq.com/v1/1284/address/{ADDRESS}/balances_v2/
Transactions api.covalenthq.com/v1/1284/address/{ADDRESS}/transactions_v2/
Transfers api.covalenthq.com/v1/1284/address/{ADDRESS}/transfers_v2/
Token holders api.covalenthq.com/v1/1284/tokens/{CONTRACT_ADDRESS}/token_holders/
Log events (smart contract) api.covalenthq.com/v1/1284/events/address/{CONTRACT_ADDRESS}/
Log events (topic hash) api.covalenthq.com/v1/1284/events/topics/{TOPIC}/
Security (Token Approvals) api.covalenthq.com/v1/1284/approvals/{ADDRESS}/
Endpoint Format
Balances api.covalenthq.com/v1/1285/address/{ADDRESS}/balances_v2/
Transactions api.covalenthq.com/v1/1285/address/{ADDRESS}/transactions_v2/
Transfers api.covalenthq.com/v1/1285/address/{ADDRESS}/transfers_v2/
Token holders api.covalenthq.com/v1/1285/tokens/{CONTRACT_ADDRESS}/token_holders/
Log events (smart contract) api.covalenthq.com/v1/1285/events/address/{CONTRACT_ADDRESS}/
Log events (topic hash) api.covalenthq.com/v1/1285/events/topics/{TOPIC}/
Security (Token Approvals) api.covalenthq.com/v1/1285/approvals/{ADDRESS}/
Endpoint Format
Balances api.covalenthq.com/v1/1287/address/{ADDRESS}/balances_v2/
Transactions api.covalenthq.com/v1/1287/address/{ADDRESS}/transactions_v2/
Transfers api.covalenthq.com/v1/1287/address/{ADDRESS}/transfers_v2/
Token holders api.covalenthq.com/v1/1287/tokens/{CONTRACT_ADDRESS}/token_holders/
Log events (smart contract) api.covalenthq.com/v1/1287/events/address/{CONTRACT_ADDRESS}/
Log events (topic hash) api.covalenthq.com/v1/1287/events/topics/{TOPIC}/
Security (Token Approvals) api.covalenthq.com/v1/1287/approvals/{ADDRESS}/

API Parameters

Parameter Value
Response Formats JSON, CSV
Real-Time Data Latency 2 blocks
Batch Data Latency 30 minutes
API Free Tier Limit of 4 RPS
API Premium Tier Limit of 50 RPS
Parameter Value
Response Formats JSON, CSV
Real-Time Data Latency 2 blocks
Batch Data Latency 30 minutes
API Free Tier Limit of 4 RPS
API Premium Tier Limit of 50 RPS
Parameter Value
Response Formats JSON, CSV
Real-Time Data Latency 2 blocks
Batch Data Latency 30 minutes
API Free Tier Limit of 4 RPS
API Premium Tier Limit of 50 RPS

API Resources

How to Use the Unified API

First, make sure you have your API Key which begins with ckey_. Once you have your API key you will be able to access any of the supported endpoints. To get information for a specific network, you will need to provide the chain ID.

Checking Prerequisites

To get started with the Covalent API, you will need to have the following:

Using Curl

One of the supported endpoints is the token holders endpoint, which returns a list of all the token holders of a particular token. For this example, you can check the token holders for the ERTH token. The contract address for the ERTH token on Moonbase Alpha is 0x08B40414525687731C23F430CEBb424b332b3d35.

Try running the command below in a terminal window after replacing the placeholder with your API key.

curl https://api.covalenthq.com/v1/1287/tokens/\
0x08B40414525687731C23F430CEBb424b332b3d35/token_holders/ \
-u { INSERT_YOUR_API_KEY }:

Note

The colon : after the API key is important because otherwise you will be prompted for a password (which is not needed).

Unless you already owned some ERTH tokens, your address will be missing from that list. Head over to the Moonbase Alpha ERC-20 Faucet to generate some ERTH tokens for yourself. Now repeat the same Covalent API request as above. The Covalent API updates in real-time, so you should now see your address in the list of token holders for the ERTH token.

Using Javascript

Copy and paste the below code block into your preferred environment, or JSFiddle. After setting the API key, set the address constant. Remember for Moonbase Alpha the chain ID is 1287.

// set your API key
const apiKey = 'INSERT_YOUR_API_KEY';

function getData() {
const address = '0xFEC4f9D5B322Aa834056E85946A32c35A3f5aDD8'; // example
const chainId = '1287'; // Moonbase Alpha TestNet chain ID
const url = new URL(
  `https://api.covalenthq.com/v1/${chainId}/address/${address}/balances_v2/`
);

url.search = new URLSearchParams({
  key: apiKey,
});

// use fetch API to get Covalent data
fetch(url)
  .then((resp) => resp.json())
  .then(function (data) {
  const result = data.data;

  console.log(result);
  return result;
  });
}

getData();
// set your API key
const apiKey = 'INSERT_YOUR_API_KEY';
const address = '0xFEC4f9D5B322Aa834056E85946A32c35A3f5aDD8'; // example
const chainId = '1287'; // Moonbase Alpha TestNet chain ID
const url = new URL(
  `https://api.covalenthq.com/v1/${chainId}/address/${address}/balances_v2/`
);

url.search = new URLSearchParams({
  key: apiKey,
});

async function getData() {
  const response = await fetch(url);
  const result = await response.json();
  console.log(result);
  return result;
}

getData();

The balances endpoint returns a list of all ERC-20 and NFT token balances, including ERC-721 and ERC-1155 balances, along with their current spot prices (if available).

JavaScript Console Output

Using Python

Covalent doesn’t have an official API wrapper. To query the API directly you will have to use the Python requests library. Install requests into your environment from the command line with pip install requests. Then import it and use it in your code. Use the HTTP verbs get methods to return the information from the API. Copy and paste the below code block into your preferred environment and run it. The output should look similar to the screenshot above, however the formatting may vary depending on your environment.

import requests


def fetch_wallet_balance(address):
    api_url = "https://api.covalenthq.com"
    endpoint = f"/v1/1287/address/{address}/balances_v2/"
    url = api_url + endpoint
    response = requests.get(url, auth=("INSERT_YOUR_API_KEY", ""))
    print(response.json())
    return response.json()


# Example address request
fetch_wallet_balance("0xFEC4f9D5B322Aa834056E85946A32c35A3f5aDD8")

Note

The second parameter of auth is empty, because there is no password required - your API key is all that's needed.

Increment

Increment is a no-code charting and reporting tool that enables users to build dynamic, personalized charts with data models. The tool directly encodes business logic—reach, retention, and revenue—into an SQL compiler that outputs valid SQL. Increment can convert any chart made with SQL and bake them into a standardized, open-sourced set of dimensions and measures, known as a model.

Example Increment chart Click on the above image to try out Increment.

Common Use Cases

Increment can be used for:

Example network status increment Click on the above image to get the latest number of Moonbeam network active wallets, transactions and tokens by day, week, month or year.

Increment Resources

The information presented herein has been provided by third parties and is made available solely for general information purposes. Moonbeam does not endorse any project listed and described on the Moonbeam Doc Website (https://docs.moonbeam.network/). Moonbeam Foundation does not warrant the accuracy, completeness or usefulness of this information. Any reliance you place on such information is strictly at your own risk. Moonbeam Foundation disclaims all liability and responsibility arising from any reliance placed on this information by you or by anyone who may be informed of any of its contents. All statements and/or opinions expressed in these materials are solely the responsibility of the person or entity providing those materials and do not necessarily represent the opinion of Moonbeam Foundation. The information should not be construed as professional or financial advice of any kind. Advice from a suitably qualified professional should always be sought in relation to any particular matter or circumstance. The information herein may link to or integrate with other websites operated or content provided by third parties, and such other websites may link to this website. Moonbeam Foundation has no control over any such other websites or their content and will have no liability arising out of or related to such websites or their content. The existence of any such link does not constitute an endorsement of such websites, the content of the websites, or the operators of the websites. These links are being provided to you only as a convenience and you release and hold Moonbeam Foundation harmless from any and all liability arising from your use of this information or the information provided by any third-party website or service.
Last update: January 25, 2024
| Created: June 9, 2021