covalentagentskill

内容来源：SKILL.md（标准 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)

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:

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

Quick Start

Prerequisites

Get an API Key: Sign up at GoldRush Platform
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

API Key Security: Never hardcode API keys; use environment variables
Error Handling: Always check response.error before accessing data
Pagination: Use next() and prev() methods for paginated responses
Rate Limiting: Implement exponential backoff for rate limit errors
Spam Filtering: Use no_spam=true to filter spam tokens
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