Covalent GoldRush API Integration Skill

Overview

GoldRush is Covalent’s blockchain data API suite providing access to structured blockchain data across 100+ chains. This skill enables you to integrate with:

1. Foundational API – REST endpoints for historical blockchain data
2. Streaming API – Real-time WebSocket subscriptions for live events

Quick Start

Prerequisites

1. Get an API Key: Sign up at GoldRush Platform
2. Install SDK (choose one):

TypeScript/JavaScript:

npm install @covalenthq/client-sdk

Python:

pip3 install covalent-api-sdk

Authentication

All API calls require a GoldRush API key passed as a Bearer token or when initializing the SDK client.

TypeScript:

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

const client = new GoldRushClient("YOUR_API_KEY");

Python:

from covalent import CovalentClient

client = CovalentClient("YOUR_API_KEY")

Foundational API

The Foundational API provides REST endpoints for structured historical blockchain data.

Available Services

Core Endpoints

1. Get Token Balances

Fetch native and ERC20 token balances with USD prices.

TypeScript:

const response = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  "0xYourAddress"
);

if (!response.error) {
  for (const token of response.data.items) {
    console.log(`${token.contract_ticker_symbol}: ${token.pretty_quote}`);
  }
}

Python:

response = client.balance_service.get_token_balances_for_wallet_address(
    "eth-mainnet",
    "0xYourAddress"
)

if not response.error:
    for token in response.data.items:
        print(f"{token.contract_ticker_symbol}: {token.pretty_quote}")

Parameters:

• chain_name: Chain identifier (e.g., eth-mainnet, matic-mainnet, base-mainnet)
• wallet_address: Wallet address, ENS name, or Lens handle
• quote_currency (optional): USD, EUR, GBP, etc.
• no_spam (optional): Filter spam tokens

2. Get Transactions for Address

Fetch transaction history with decoded logs.

TypeScript:

const response = await client.TransactionService.getTransactionsForAddressV3(
  "eth-mainnet",
  "0xYourAddress"
);

for (const tx of response.data.items) {
  console.log(`TX: ${tx.tx_hash}`);
  console.log(`Value: ${tx.value}`);
  console.log(`Gas: ${tx.gas_spent}`);
}

Python:

response = client.transaction_service.get_transactions_for_address_v3(
    "eth-mainnet",
    "0xYourAddress"
)

for tx in response.data.items:
    print(f"TX: {tx.tx_hash}, Value: {tx.value}")

3. Get Transaction Summary

Get wallet age, transaction count, and gas expenditure.

TypeScript:

const response = await client.TransactionService.getTransactionSummary(
  "eth-mainnet",
  "0xYourAddress"
);

const summary = response.data.items[0];
console.log(`Total Transactions: ${summary.total_count}`);
console.log(`Gas Spent: ${summary.gas_summary.pretty_total_gas_quote}`);

4. Get NFTs for Address

Fetch all NFTs owned by a wallet.

TypeScript:

const response = await client.NftService.getNftsForAddress(
  "eth-mainnet",
  "0xYourAddress"
);

for (const nft of response.data.items) {
  console.log(`Collection: ${nft.contract_name}`);
  console.log(`Token ID: ${nft.nft_data?.token_id}`);
}

Python:

response = client.nft_service.get_nfts_for_address(
    "eth-mainnet",
    "0xYourAddress"
)

for nft in response.data.items:
    print(f"Collection: {nft.contract_name}")

5. Cross-Chain Address Activity

Find all chains where an address has activity.

TypeScript:

const response = await client.BaseService.getAddressActivity(
  "0xYourAddress"
);

for (const chain of response.data.items) {
  console.log(`Active on: ${chain.name} (Chain ID: ${chain.chain_id})`);
  console.log(`Last seen: ${chain.last_seen_at}`);
}

Python:

response = client.base_service.get_address_activity("0xYourAddress")

for chain in response.data.items:
    print(f"Active on: {chain.name}")

6. Get Token Approvals (Security)

Check token approvals and value-at-risk.

TypeScript:

const response = await client.SecurityService.getApprovals(
  "eth-mainnet",
  "0xYourAddress"
);

for (const approval of response.data.items) {
  console.log(`Token: ${approval.token_address}`);
  console.log(`Spender: ${approval.spender_address}`);
  console.log(`Value at Risk: ${approval.value_at_risk}`);
}

7. Get Historical Token Prices

TypeScript:

const response = await client.PricingService.getTokenPrices(
  "eth-mainnet",
  "USD",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  {
    from: "2024-01-01",
    to: "2024-01-31"
  }
);

8. Get Logs by Contract Address

TypeScript:

const response = await client.BaseService.getLogEventsByAddress(
  "eth-mainnet",
  "0xContractAddress",
  {
    startingBlock: 18000000,
    endingBlock: 18001000
  }
);

9. Get Gas Prices

TypeScript:

const response = await client.BaseService.getGasPrices("eth-mainnet");

console.log(`Safe: ${response.data.items[0].gas_price}`);
console.log(`Fast: ${response.data.items[1].gas_price}`);

Streaming API

The Streaming API provides real-time blockchain data via GraphQL over WebSocket.

Connection Setup

TypeScript:

import { 
  GoldRushClient, 
  StreamingChain, 
  StreamingInterval, 
  StreamingTimeframe 
} from "@covalenthq/client-sdk";

const client = new GoldRushClient(
  "YOUR_API_KEY",
  {},
  {
    onConnecting: () => console.log("Connecting..."),
    onOpened: () => console.log("Connected!"),
    onClosed: () => console.log("Disconnected"),
    onError: (error) => console.error("Error:", error),
  }
);

Available Streams

Stream Examples

1. OHLCV Token Stream

Real-time price candlestick data.

client.StreamingService.subscribeToOHLCVTokens(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => {
      console.log("OHLCV:", data);
      console.log(`Open: ${data.open}, Close: ${data.close}`);
    },
    error: (error) => console.error(error),
    complete: () => console.log("Stream ended"),
  }
);

2. New DEX Pairs Stream

Detect newly created trading pairs.

client.StreamingService.subscribeToNewDEXPairs(
  {
    chain_name: StreamingChain.BASE_MAINNET,
    dex_name: "UNISWAP_V2",
  },
  {
    next: (pair) => {
      console.log("New Pair Detected!");
      console.log(`Token: ${pair.base_token.contract_ticker_symbol}`);
      console.log(`Address: ${pair.base_token.contract_address}`);
    },
    error: (error) => console.error(error),
    complete: () => console.log("Stream ended"),
  }
);

3. Wallet Activity Stream

Track wallet transactions in real-time.

client.StreamingService.subscribeToWalletActivity(
  {
    chain_name: StreamingChain.SOLANA_MAINNET,
    wallet_addresses: ["YourSolanaWalletAddress"],
  },
  {
    next: (activity) => {
      console.log("Wallet Activity:", activity);
    },
    error: (error) => console.error(error),
    complete: () => console.log("Stream ended"),
  }
);

Supported Chains & DEXes

Chain Names Reference

Common chain names for the Foundational API:

For a complete list, use:

const chains = await client.BaseService.getAllChains();

Error Handling

TypeScript:

const response = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  "0xAddress"
);

if (response.error) {
  console.error(`Error: ${response.error_message}`);
  console.error(`Code: ${response.error_code}`);
} else {
  // Process response.data
}

Python:

response = client.balance_service.get_token_balances_for_wallet_address(
    "eth-mainnet",
    "0xAddress"
)

if response.error:
    print(f"Error: {response.error_message}")
else:
    # Process response.data

Best Practices

1. API Key Security: Never hardcode API keys; use environment variables
2. Error Handling: Always check response.error before accessing data
3. Pagination: Use next() and prev() methods for paginated responses
4. Rate Limiting: Implement exponential backoff for rate limit errors
5. Spam Filtering: Use no_spam=true to filter spam tokens
6. Name Resolution: ENS, Lens handles, and Unstoppable Domains resolve automatically

Example Files

See the examples/ directory for complete working examples:

• examples/typescript/foundational/ – REST API examples
• examples/typescript/streaming/ – WebSocket streaming examples
• examples/python/ – Python SDK examples

Resources

• GoldRush Documentation
• API Reference
• Supported Chains
• TypeScript SDK
• Python SDK
• Discord Community