covalent-goldrush-api-integration

name	Covalent GoldRush API Integration
description	Comprehensive blockchain data API integration using GoldRush Foundational and Streaming APIs with TypeScript and Python SDKs

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

Service	TypeScript	Python	Purpose
Balance	BalanceService	balance_service	Token balances (native, ERC20, NFTs)
Transaction	TransactionService	transaction_service	Transaction history and details
NFT	NftService	nft_service	NFT ownership, metadata, traits
Base	BaseService	base_service	Blocks, logs, chains, gas prices
Security	SecurityService	security_service	Token approvals/allowances
Pricing	PricingService	pricing_service	Historical token prices

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	Purpose	Use Cases
OHLCV Tokens	Token price candles	Trading bots, charts
OHLCV Pairs	Pair price candles	DEX analytics
New DEX Pairs	New pair detection	Sniping bots
Update Pairs	Liquidity updates	Portfolio monitoring
Wallet Activity	Live transactions	Copy trading

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	DEXes
BASE_MAINNET	UNISWAP_V2, UNISWAP_V3, VIRTUALS_V2, CLANKER
SOLANA_MAINNET	RAYDIUM_AMM, RAYDIUM_CPMM, PUMP_FUN, METEORA_DAMM, METEORA_DLMM
ETH_MAINNET	UNISWAP_V2, UNISWAP_V3
BSC_MAINNET	PANCAKESWAP_V2, PANCAKESWAP_V3

---

Chain Names Reference

Common chain names for the Foundational API:

Chain	Name	Chain ID
Ethereum	eth-mainnet	1
Polygon	matic-mainnet	137
Arbitrum	arbitrum-mainnet	42161
Optimism	optimism-mainnet	10
Base	base-mainnet	8453
BSC	bsc-mainnet	56
Avalanche	avalanche-mainnet	43114
Solana	solana-mainnet	(Solana)

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