covalentagentskill skill

---
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](https://goldrush.dev/platform/auth/register/)
2. **Install SDK** (choose one):

**TypeScript/JavaScript:**
```bash
npm install @covalenthq/client-sdk
```

**Python:**
```bash
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:**
```typescript
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("YOUR_API_KEY");
```

**Python:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```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:**
```typescript
const response = await client.BaseService.getLogEventsByAddress(
  "eth-mainnet",
  "0xContractAddress",
  {
    startingBlock: 18000000,
    endingBlock: 18001000
  }
);
```

#### 9. Get Gas Prices

**TypeScript:**
```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:**
```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.

```typescript
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.

```typescript
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.

```typescript
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:
```typescript
const chains = await client.BaseService.getAllChains();
```

---

## Error Handling

**TypeScript:**
```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:**
```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](https://goldrush.dev/docs)
- [API Reference](https://goldrush.dev/docs/api-reference)
- [Supported Chains](https://goldrush.dev/chains)
- [TypeScript SDK](https://www.npmjs.com/package/@covalenthq/client-sdk)
- [Python SDK](https://pypi.org/project/covalent-api-sdk/)
- [Discord Community](https://discord.gg/8ZWgu2pWY4)