GoldRush API Skill | Agent Skills

GoldRush API

Overview

GoldRush by Covalent provides blockchain data across 100+ chains through a unified REST API, real-time WebSocket streams, a CLI, and an x402 pay-per-request proxy. This skill enables AI agents to query wallet balances, token prices, transaction history, NFT holdings, and DEX pair data without building chain-specific integrations.

When to Use This Skill

Retrieving wallet token balances or total portfolio value across any chain
Fetching transaction history or decoded event logs for an address
Getting current or historical token prices (USD or native)
Monitoring DEX pairs, liquidity events, and real-time OHLCV candles via WebSocket
Building block explorers, portfolio dashboards, tax tools, or DeFi analytics
Accessing on-chain data with no signup via x402 pay-per-request

How It Works

Step 1: Get credentials

Step 2: Set your API key

export GOLDRUSH_API_KEY="your_api_key_here"

Step 3: Query data

REST API (most endpoints):

# Wallet token balances on Ethereum
curl -H "Authorization: Bearer $GOLDRUSH_API_KEY"   "https://api.covalenthq.com/v1/eth-mainnet/address/0xADDRESS/balances_v2/"

CLI (quick terminal queries):

npx @covalenthq/goldrush-cli balances --chain eth-mainnet --address 0xADDRESS

SDK (in code):

import GoldRushClient from "@covalenthq/client-sdk";
const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);
const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet", "0xADDRESS"
);

Examples

Example 1: Token Balances

curl -H "Authorization: Bearer $GOLDRUSH_API_KEY"   "https://api.covalenthq.com/v1/eth-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/"

Example 2: Token Price History

curl -H "Authorization: Bearer $GOLDRUSH_API_KEY"   "https://api.covalenthq.com/v1/pricing/historical_by_addresses_v2/eth-mainnet/USD/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/"

Example 3: Transaction History

curl -H "Authorization: Bearer $GOLDRUSH_API_KEY"   "https://api.covalenthq.com/v1/eth-mainnet/address/0xADDRESS/transactions_v3/"

Example 4: Real-time OHLCV via WebSocket

// Stream live price candles for a token pair
const ws = new WebSocket("wss://streaming.covalenthq.com/v1/eth-mainnet/ohlcv");
ws.on("message", (data) => console.log(JSON.parse(data)));

Best Practices

✅ Use chain slugs: eth-mainnet, matic-mainnet, base-mainnet, bsc-mainnet — full list at https://goldrush.dev/docs/networks ✅ Store API key in GOLDRUSH_API_KEY env var — never hardcode ✅ Use WebSocket streams for real-time data rather than polling REST ✅ Use SDK cursor pagination for large result sets ❌ Don't use x402 for high-volume use cases — get a standard API key instead ❌ Don't use chain IDs (e.g., 1) — use chain slugs (e.g., eth-mainnet)

Security & Safety Notes

API key in GOLDRUSH_API_KEY environment variable only
x402 payments use USDC on Base — set spending limits before autonomous agent use
Read-only data API — no write operations, no transaction signing

Common Pitfalls

Problem: 401 Unauthorized
Solution: Ensure API key is in Authorization: Bearer header, not query string

Problem: chain_name not found
Solution: Use chain slug format — see https://goldrush.dev/docs/networks

Problem: Empty results for new wallet
Solution: Some endpoints require on-chain activity; new wallets with no transactions return empty arrays, not errors

Related Skills

@goldrush-streaming-api — real-time WebSocket DEX pair and OHLCV streams
@goldrush-x402 — pay-per-request blockchain data without API key
@goldrush-cli — terminal-first blockchain data queries

Agent Skills: GoldRush API

Install this agent skill to your local

Skill Files