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.

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.

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.

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¶

API Parameters¶

API Resources¶

• API Reference & In-Browser Endpoint Demo
• Covalent Quickstart
• Written Guides

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:

• A free Covalent API Key
• MetaMask installed and connected to Moonbase Alpha
• An account with funds. You can get DEV tokens for testing on Moonbase Alpha once every 24 hours from the Moonbase Alpha Faucet

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 }:

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).

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")

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.

Click on the above image to try out Increment.

Common Use Cases¶

Increment can be used for:

• Analyzing blockchain networks
• Analyzing DEXs
• Analyzing NFT marketplaces
• Tracking monthly active wallets

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¶

• Increment platform
• Increment docs
• Data models overview
• Browse all data models
• Interact with a data model