​

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: <GOLDRUSH_API_KEY>"

# CORRECT
curl -H "Authorization: Bearer <GOLDRUSH_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 <GOLDRUSH_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

Note: Failed requests are free. No API credits are deducted for any response outside the 2xx range, whatever the cause. A 429, a 501, a 556 and a 500 all cost you nothing, so a retry is never a billing risk.

​

Standard and GoldRush-specific codes

​

The error response body

{
  "data": null,
  "error": true,
  "error_message": "This chain does not currently support flag: with-state.",
  "error_code": 501
}

• error_code is a JSON number, not a string. Compare it with 501, not "501".
• error_code always equals the HTTP status code, so you can branch on either one.
• error_message carries the specific reason. Two requests can share a status code and mean entirely different things, so log the message as well as the code.

Warning: A request with no Authorization header at all is rejected by the edge proxy, not by the API, and returns an HTML body rather than JSON:

401 Authorization Required ...

​

Standard HTTP status codes

​

501 is a capability answer, not an outage

• An unsupported chain. Note that an unrecognized chain name returns 501, not 404:
  { "data": null, "error": true, "error_message": "Chain nosuchchain-mainnet not supported.", "error_code": 501 }
  
• A feature flag the chain does not support. Flags such as with-state and with-input-data are only available on chains with the underlying data. The flag is valid, the chain just cannot serve it:
  { "data": null, "error": true, "error_message": "This chain does not currently support flag: with-state.", "error_code": 501 }
  
  Rather than discovering this by trial, read the capability flags on /v1/chains/, such as is_internal_tx_supported and is_input_data_supported, and skip the call when the flag is false.
• An endpoint restricted to certain chains, for example an EVM-only endpoint called on a non-EVM chain.

Note: The gate runs before the identifier is looked up, so a transaction hash that does not exist returns 404 on a chain that supports the flag and 501 on a chain that does not. That makes a throwaway hash a cheap way to test chain support.

​

GoldRush-specific status codes

Warning: The codes in this section are not registered HTTP status codes. They are specific to the GoldRush API.

Tip: 556 is the one to watch. It means the request was refused on purpose while the backend was under load, not that anything is broken. A burst of 556 is the correct signal to back off; clients that retry it aggressively make the condition worse and last longer.

Note: 565 is short-lived by design. The response is cached for only 10 seconds, because the usual cause is that indexing is a few seconds behind the chain tip. Waiting 10 to 15 seconds and retrying once resolves most occurrences. If a 565 for the same record persists for minutes, raise it on the support page.

​

What to do with every code

​

Retry with exponential backoff

• 557: retry once immediately before backing off. It usually clears on the next attempt.
• 565: wait at least 10 seconds before the first retry.
• 562 and 563: recovery depends on a third party, so allow a ceiling of 30 to 60 seconds rather than a few seconds.
• 429: back off until your request rate is under the limit for your plan. More attempts will not help.

​

Change the request, then retry

​

Fix something, then retry once

​

Do not retry

Note: None of this costs credits. Error responses are not billed, so the cost of a retry is only the rate limit slot it consumes and the latency it adds. Optimize your retry policy for recovery time and for not amplifying an incident, not for spend.

​

Rate Limits

​

Retry Strategies

​

Exponential Backoff with Jitter

// Transient: a later attempt may succeed with the same request.
const RETRYABLE = new Set([
  429, 500, 503, 504,
  551, 552, 554, 556, 557, 558, 561, 562, 563, 565, 567,
]);

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

# Transient: a later attempt may succeed with the same request.
RETRYABLE = {
    429, 500, 503, 504,
    551, 552, 554, 556, 557, 558, 561, 562, 563, 565, 567,
}

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 RETRYABLE:
            # 565 means indexing is a few seconds behind the chain tip,
            # so give it a floor of 10s rather than retrying immediately.
            base_delay = 10 if response.status_code == 565 else (2 ** attempt)
            jitter = random.uniform(0, 1)
            time.sleep(base_delay + jitter)
            continue

        response.raise_for_status()

    raise Exception("Max retries exceeded")

Warning: Never put 403, 410, 416, 501 or 570 in a backoff loop. They are stable answers about the request, the chain or the contract, so every attempt returns the same thing while still consuming a rate limit slot. See What to do with every code for the codes that are worth one retry after you fix something.

​

SDK Built-in Retries

​

Debugging Tips

​

Verify your API key format

​

Check supported chains

​

Inspect the full error body

​

Test with curl

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

​

Monitor credit usage

​

Contact support for persistent server-side errors

​

Quick Reference

​

Foundational 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?

• API key (read-only) - covers the Foundational API, CLI, and x402.

​

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.

​

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?

​

Does GoldRush support Hyperliquid?

​

What are Redstone Bolt price feeds?

​

Not finding answers?

• Error Handling & Troubleshooting — Debug issues and retry strategies
• What is GoldRush — Understand the core platform
• GoldRush SDKs & CLI — Get started with code
• Powered by GoldRush — See real-world examples