​

LLM Integration Guide

​

GoldRush API - LLM Integration Guide (Condensed)

​

Quick Reference

• Free 14 day trial: 25,000 API credits/month, 4 requests/second, no overages
• Vibe Coding tier: $10/month for 10,000 included API credits, 4 requests/second, overages at$0.001/credit
• Professional: $250/month for 300,000 included API credits, 50 requests/second, overages at$0.00077/credit
• x402 (Pay-Per-Request): No subscription required, 100 requests/minute per wallet, pay with stablecoins on Base

​

Chain Names (CRITICAL)

​

Supported Chain Names Table

• Foundational (6 chains) - Full feature parity including historical balances, token holders at any block, and DEX spot prices
• Frontier (28 chains) - Core features with expanding coverage; includes all non-EVM chains
• Community (14 chains) - Growing integration with all core onchain data
• Archived (5 chains) - Limited data availability, no live data

​

Parameter Naming Convention

​

Parameter Mapping (SDK ↔ REST API)

​

Input Validation Rules

​

Ethereum Addresses

• Format: 0x followed by 40 hexadecimal characters
• Regex: ^0x[a-fA-F0-9]{40}$
• Case: Insensitive (both 0xabc... and 0xABC... are valid)
• Special Values: Also accepts ENS names (e.g., vitalik.eth), RNS, Lens Handles, Unstoppable Domains

• ✅ Valid: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
• ✅ Valid: vitalik.eth
• ❌ Invalid: d8dA6BF26964aF9D7eEd9e03E53415D37aA96045 (missing 0x)
• ❌ Invalid: 0xd8dA6BF (too short)

​

Chain Names

• Format: Exact match from supported chains table (case-sensitive)

• ✅ Valid: eth-mainnet
• ❌ Invalid: ethereum (use eth-mainnet)
• ❌ Invalid: Eth-Mainnet (case-sensitive)
• ❌ Invalid: eth_mainnet (use hyphen, not underscore)

​

Block Heights

• Type: Integer ≥ 0
• Special Value: "latest" for current block
• Maximum: Current chain height (varies by chain)

• ✅ Valid: 12345678
• ✅ Valid: latest
• ❌ Invalid: -1

​

Quote Currency

• Type: String (case-insensitive)
• Supported Values: USD, CAD, EUR, SGD, INR, JPY, VND, CNY, KRW, RUB, TRY, NGN, ARS, AUD, CHF, GBP
• Default: USD

​

Pagination

• Page Numbers: 0-indexed (first page is 0)
• Page Size: 100 items per page (default, not configurable for most endpoints)
• End Detection:
  • If returned page has < 100 items, it’s the last page
  • Check has_more field in response (where available)
  • Use links.next for next page URL (where available)

​

Understanding Balance Fields

{
  "contract_decimals": 18,
  "balance": "1500000000000000000",
  "quote_rate": 2500.50,
  "quote": 3750.75,
  "pretty_quote": "$3,750.75"
}

• balance: Raw token amount as string (to handle large numbers/BigInt). This is NOT the human-readable value.
• contract_decimals: Number of decimal places for this token
• quote_rate: Current price of 1 token in quote currency (e.g., USD)
• quote: Total value of this token holding in quote currency
• pretty_quote: Formatted currency string for display

const humanReadable = parseFloat(balance) / Math.pow(10, contract_decimals);
// Example: "1500000000000000000" / 10^18 = 1.5 tokens

​

Understanding Transaction Fields

{
  "successful": true,
  "value": "0",
  "gas_spent": 21000,
  "gas_price": 50000000000,
  "fees_paid": "1050000000000000",
  "gas_quote": 2.75,
  "gas_quote_rate": 2500.00
}

• successful: Boolean indicating if transaction succeeded
• value: Amount of native token transferred (as string, in wei for EVM chains)
• gas_spent: Actual gas units consumed
• gas_price: Gas price in wei (for EVM chains)
• fees_paid: Total fee in wei (gas_spent × gas_price)
• gas_quote: Total fee in quote currency (e.g., USD)
• gas_quote_rate: Native token price used for conversion

​

Error Responses

{
  "data": null,
  "error": true,
  "error_message": "Human-readable error description",
  "error_code": 401
}

​

Common Error Codes

​

Best Practices for LLMs

​

1. Always Validate Chain Names

const VALID_CHAINS = [
  "eth-mainnet", "matic-mainnet", "base-mainnet",
  "arbitrum-mainnet", "optimism-mainnet", "bsc-mainnet"
];

function isValidChain(chainName: string): boolean {
  return VALID_CHAINS.includes(chainName);
}

​

2. Handle BigInt Balance Values Correctly

// ❌ WRONG
const balance = parseInt(item.balance); // Will overflow for large values

// ✅ CORRECT
const balance = parseFloat(item.balance) / Math.pow(10, item.contract_decimals);

​

3. Implement Pagination Properly

// ✅ CORRECT
let page = 0;
let allItems = [];
let hasMore = true;

while (hasMore) {
  const resp = await fetchPage(page);
  allItems.push(...resp.items);
  hasMore = resp.items.length === 100; // Full page = more data likely exists
  page++;
}

​

4. Use Appropriate Error Handling

const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
  chainName,
  address
);

if (resp.error) {
  // Handle error - don't try to access resp.data
  console.error(resp.error_message);
  return;
}

// Safe to access resp.data here
const balances = resp.data.items;

​

Common Mistakes to Avoid

​

❌ Using Wrong Chain Name Format

// WRONG
const chain = "ethereum";
const chain = "polygon";

// CORRECT
const chain = "eth-mainnet";
const chain = "matic-mainnet";

​

❌ Treating Balance as Number

// WRONG
const balance = parseInt(item.balance); // Overflow!

// CORRECT
const balance = parseFloat(item.balance) / Math.pow(10, item.contract_decimals);

​

❌ Forgetting to Check Error Response

// WRONG
const resp = await client.getSomething();
const data = resp.data.items; // May crash if error

// CORRECT
const resp = await client.getSomething();
if (!resp.error) {
  const data = resp.data.items;
}

​

❌ Not Handling Pagination

// WRONG - only gets first 100 transactions
const resp = await client.getTransactions(chain, address, { page: 0 });

// CORRECT - gets all transactions
let page = 0;
let allTxs = [];
while (true) {
  const resp = await client.getTransactions(chain, address, { page });
  if (resp.error || resp.data.items.length === 0) break;
  allTxs.push(...resp.data.items);
  if (resp.data.items.length < 100) break;
  page++;
}

​

❌ Missing Bearer Prefix in Authorization

# WRONG
curl -H "Authorization: YOUR_API_KEY"

# CORRECT
curl -H "Authorization: Bearer YOUR_API_KEY"

​

❌ Using HTTP Instead of HTTPS

# WRONG
http://api.covalenthq.com/v1/...

# CORRECT
https://api.covalenthq.com/v1/...

​

Frequently Asked Questions (LLM-Specific)

​

Q: How do I convert balance to human-readable format?

const humanReadable = parseFloat(balance) / Math.pow(10, contract_decimals);
// Example:
// balance = "1500000000000000000"
// contract_decimals = 18
// humanReadable = 1.5 tokens

​

Q: What’s the difference between quote and quote_rate?

• quote_rate: Price of 1 token in quote currency (e.g., $2,500.50 per ETH)
• quote: Total value of the balance in quote currency (balance × quote_rate)

​

Q: How do I know which chains support internal transactions?

​

Q: How do I handle ENS names?

const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  "vitalik.eth" // Automatically resolved
);

​

Q: What’s the difference between balances_v2 and balances_native?

• balances_v2: Returns ALL tokens (native + ERC20 + NFTs)
• balances_native: Returns ONLY the native token (ETH, MATIC, etc.)

​

Q: How do I filter out spam tokens?

curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x.../balances_v2/?no-spam=true"

​

Q: When should I use the SDK vs direct REST calls?

• Use SDK: TypeScript/JavaScript projects, automatic pagination, type safety
• Use REST: Python, Go, or any other language; curl testing; maximum flexibility

​

Q: How often does data update?

• Real-time endpoints: 30 seconds or 2 blocks (whichever is faster)
• Historical data: Indexed from genesis block
• NFT metadata: Cached, use with-uncached=true to force refresh

​

Quick Reference: Endpoint URL Patterns

​

Additional Resources

• Full API Documentation: https://goldrush.dev/docs/
• API Reference: https://goldrush.dev/docs/api-reference/
• Guides & Tutorials: https://goldrush.dev/guides/
• Supported Chains: https://goldrush.dev/docs/chains/overview
• Status Page: https://status.goldrush.dev/
• Get API Key: https://goldrush.dev/platform
• Discord Community: https://discord.gg/8ZWgu2pWY4
• GitHub: https://github.com/covalenthq

​

System Prompt Suggestion for AI Agents

You have access to the GoldRush API for blockchain data. Key points:

1. Chain names use format like "eth-mainnet", "matic-mainnet", "base-mainnet" - never use common names like "ethereum" or "polygon"
2. Balance fields are strings representing large numbers. Divide by 10^contract_decimals to get human-readable values
3. All requests require "Authorization: Bearer YOUR_API_KEY" header
4. Pagination returns 100 items per page. If result has 100 items, more pages likely exist
5. Base URL: https://api.covalenthq.com/v1
6. Always check resp.error before accessing resp.data
7. Ethereum addresses: 0x + 40 hex chars, or ENS names
8. For detailed integration guidance, refer to the LLM Integration Guide

​

Error Handling & Troubleshooting

​

Foundational API (REST) Errors

{
  "error": true,
  "error_message": "No valid API key was provided.",
  "error_code": "401"
}

{
  "error": true,
  "error_message": "You are being rate-limited. Please reduce request frequency.",
  "error_code": "429"
}

​

Streaming API (GraphQL/WebSocket) Errors

{
  "errors": [
    {
      "message": "Authentication required. Please provide a valid API key in the connection_init payload under 'GOLDRUSH_API_KEY' or 'Authorization' key.",
      "extensions": {
        "code": "MISSING_TOKEN"
      }
    }
  ]
}

​

Rate Limits

​

Retry Strategies

​

Exponential Backoff with Jitter

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 5
): Promise {
  for (let attempt = 0; attempt  setTimeout(r, baseDelay + jitter));
      continue;
    }

    throw new Error(`Request failed: ${response.status}`);
  }

  throw new Error("Max retries exceeded");
}

import time
import random
import requests

def fetch_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.ok:
            return response

        if response.status_code in (429, 500, 503):
            base_delay = (2 ** attempt)
            jitter = random.uniform(0, 1)
            time.sleep(base_delay + jitter)
            continue

        response.raise_for_status()

    raise Exception("Max retries exceeded")

​

SDK Built-in Retries

​

Streaming Reconnection

import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://gr-staging-v2.streaming.covalenthq.com/graphql",
  connectionParams: {
    GOLDRUSH_API_KEY: "YOUR_API_KEY_HERE",
  },
  shouldRetry: () => true,
  retryAttempts: 5,
});

​

Debugging Tips

​

Verify your API key format

​

Check supported chains

​

Inspect the full error body

​

Test with curl or websocat

# Foundational API
curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
     -u YOUR_API_KEY_HERE: \
     -H 'Content-Type: application/json'

​

Monitor credit usage

​

Contact support for persistent 500/503 errors

​

Quick Reference

​

Foundational API Auth

​

Streaming API Auth

​

FAQ

​

Supported Chains

​

Frequently Asked Questions

​

General Questions

​

What is the GoldRush API?

​

What can I do with the GoldRush API?

​

Do I need API keys to use GoldRush?

​

If a client asks how to verify that GoldRush API is real-time or low-latency, how can we demonstrate or prove that?

• Timestamp validation: Pull /v1/{chain_id}/block_v2/latest/ and compare the block timestamp with the current time (should be sub-second to a few seconds behind depending on chain).
• Latency benchmarks: Use tools like curl or Postman to measure API response time. GoldRush’s streaming endpoints often respond in under 400ms for supported chains.
• Streaming demos: If using the Streaming API, show live updates of token transfers or block finality in dev dashboards.

​

Besides the common 401, 402, and 429 error codes, are there any other error responses we should be aware of?

• 400 Bad Request – Invalid parameters or malformed request.
• 402 Payment Required – Alloted credits exceeded and need to enable Flex Credits or upgrade subscription tier.
• 403 Forbidden – API key is valid but not authorized for the resource.
• 404 Not Found – Endpoint or data not available (e.g. unsupported chain).
• 500 Internal Server Error – Unexpected failure on GoldRush’s side.
• 503 Service Unavailable – Maintenance or backend issue.

​

Foundational API Questions

​

What is the rate limit for API calls?

• 14-day Free Trial: 4 requests per second (RPS), 25,000 API credits.
• Vibe Coding Plan ($10/mo): 4 RPS, 10,000 API credits.
• Professional Plan ($250/mo): 50 RPS, 300,000 API credits.
• Inner Circle: Custom limits, typically up to 100 RPS or higher, based on SLAs.

​

Which plan is right for me?

• Solo founders and indie hackers shipping fast
• Hackathon teams and weekend projects
• AI-native builders using Cursor, Windsurf, or Claude
• Prototyping and validating ideas before scaling

• Teams building production applications
• Apps that need higher rate limits (50 RPS)
• Projects requiring priority support
• Companies with compliance or reliability requirements

​

Can I upgrade from Vibe Coding to Professional?

​

Streaming API Questions

​

How does the Streaming API work?

​

What are Redstone Bolt price feeds?

​

What types of events can I subscribe to?