Covalent API integration

Covalent API Integration

Covalent is a unified API for getting on-chain data from 200+ networks without needing to maintain your own archive node. Instead of writing separate integrations for Ethereum, Polygon, Arbitrum, and Base, you make one request to Covalent and get a normalized response with decoded transactions, token balances, and transfer history.

What Covalent Really Solves

Typical scenario: you need to show a user token portfolio across 5 networks, transaction history, and NFTs. Without Covalent this is 5 different RPC nodes, manual ABI parsing, CoinGecko requests for prices — and a couple weeks of work. With Covalent:

# Balances of all ERC-20 tokens at address
GET /v1/{chainId}/address/{walletAddress}/balances_v2/

# Transaction history
GET /v1/{chainId}/address/{walletAddress}/transactions_v3/

# NFTs at address
GET /v1/{chainId}/address/{walletAddress}/balances_nft/

Each response already contains: USD value, decimals-adjusted balances, token metadata, human-readable decoded data for popular protocols.

Authentication and Rate Limits

API key is passed via Basic Auth header. Free tier: 4 requests per second, 100k requests per month. For production — paid tiers from $50/month.

const client = new CovalentClient(process.env.COVALENT_API_KEY);

const response = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  walletAddress,
  { nft: false, noNftFetch: true }
);

GoldRush SDK (official TypeScript client) is typed, handles pagination automatically, has retry logic. Better to use it than raw fetch.

Main Endpoint Groups

Balances API — current and historical balances of ERC-20, ERC-721, ERC-1155. Includes USD value at current or historical price. Parameter historic_balance_interval allows getting time series of balance without traversing thousands of blocks yourself.

Transactions API — full transaction history with decoded event logs. Parameter decode includes human-readable decoding for Uniswap, Aave, OpenSea and 50+ more protocols. Pagination is cursor-based, not offset-based — important when working with wallets with thousands of transactions.

NFT API — metadata, ownership history, floor price from Opensea/Blur. Endpoint getNftsForAddress returns adjusted IPFS URLs with fallback to HTTP gateway.

Cross-Chain Activity API — activity summary for address across all networks in one request. Useful for "multi-chain wallet scanner" scenarios.

Practical Integration Nuances

Caching is mandatory: balance data changes no more than once per block (~12 sec for Ethereum). Cache responses in Redis with TTL 15–30 seconds. Without caching at 100 concurrent users you'll quickly hit rate limit.

Pagination: transaction history of long-lived wallets can contain thousands of pages. Implement lazy loading, don't load everything at once:

async function* getAllTransactions(chain: string, address: string) {
  let pageNumber = 0;
  while (true) {
    const resp = await client.TransactionService
      .getTransactionsForAddressV3(chain, address, pageNumber);
    yield resp.data.items;
    if (!resp.data.links?.next) break;
    pageNumber++;
  }
}

Error handling: Covalent returns HTTP 200 even on errors — check the error field in response body. Field error_message is sometimes informative, sometimes not; log full response on unexpected results.

Chain IDs: Covalent uses both numeric chain IDs (1 for Ethereum) and string identifiers ("eth-mainnet"). In SDK use string format — less confusion when working with testnets.

Known Limitations

Covalent indexes historical data with delay for new networks — don't rely on data with less than one block delay. For real-time data (pending transaction monitoring, current DEX price) you need direct RPC.

Decoded data works only for whitelisted protocols. Custom or obscure contracts return raw logs — ABI decoding you'll have to do yourself via ethers.Interface.