themystic07/Covalent GoldRush API Integration

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