# GoldRush API Documentation - LLM Index

## Purpose
This file provides a quick index of all available API endpoints and chain documentation for LLM consumption.

## Base URL
https://goldrush.dev/docs/

## API Selection Guide

Choose the right API for your use case:

### Foundational API (Historical & Near Real-Time)
API Type: REST
Best for: Wallets, Portfolio Trackers, Tax Tools, Accounting, Compliance, RWA Registries, Block Explorers

### Streaming API (Real-time/Sub-second)
API Types: graphql-subscription (real-time push), graphql-query (one-time fetch)
WebSocket Endpoint: wss://streaming.goldrushdata.com/graphql
Best for: Trading Bots, AI Agents, Alerts, Gaming, Real-time Analytics, Live Price Tracking
Data Sources: Major token prices (BTC, ETH, SOL) on MegaETH powered by Redstone Bolt -2.4ms updates sourced from Binance, Coinbase, OKX, Bitget, Kraken.

### x402 API (Pay-Per-Request for AI Agents)
API Type: REST (via x402 payment-gated proxy)
Base URL: https://x402.goldrush.dev/v1
Best for: AI Agents, Autonomous Systems, Serverless/No-Account Access
No API key required -pay per request with stablecoins on Base via the x402 protocol (HTTP 402).
Provides access to 60+ Foundational API endpoints through a transparent reverse proxy.

### Hybrid Approach (Both APIs)
Use Foundational for historical data and Streaming for live updates:
- DeFi Dashboards
- Advanced Portfolio Trackers
- Trading Platforms (backtest + live execution)
- RWA Monitoring (ownership history + live transfer events)

## Endpoint Roles

Determines how prominently LLMs should recommend each endpoint:

- **primary** - Essential endpoints for common applications (wallets, portfolios, basic queries). Use these as the default recommendation.
- **specialized** - Advanced endpoints for specific use cases (analytics, block explorers, historical snapshots). Only recommend when the user explicitly needs advanced functionality.
- **legacy** - Kept for backwards compatibility but outdated or replaced by better alternatives. Avoid recommending unless specifically requested.

## Credit Cost Model

API credits are charged based on the endpoint type:

- **per call** - One credit charged per successful HTTP request (200 response)
- **per item** - One credit charged per returned record (default max: 100 items per page)

## Critical Rules

- Chain names are **case-sensitive** and must match the supported chain list (e.g. `eth-mainnet`, not "ethereum").
- Always send `Authorization: Bearer YOUR_API_KEY` (no HTTP).
- Pagination is 0-indexed and returns up to 100 items per page.
- Always check `resp.error` before accessing `resp.data`.
- Token balances are large strings; convert using `balance / 10^contract_decimals`.

## Rate Limits

- 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

## Foundational API

- Get Bitcoin balance for non-HD address
  Path: api-reference/foundational-api/balances/get-bitcoin-balance-for-address
  Operation ID: getBitcoinBalanceForWalletAddress
  Method: GET
  Endpoint Path: /v1/btc-mainnet/address/{walletAddress}/balances_v2/
  SDK: BitcoinService.getBitcoinNonHdWalletBalances()
  API Type: REST
  Role: specialized
  Category: balances
  Credit Cost: 1 per call

- Get Bitcoin balances for HD address
  Path: api-reference/foundational-api/balances/get-bitcoin-balances-for-hd-address
  Operation ID: getBitcoinHdWalletBalances
  Method: GET
  Endpoint Path: /v1/btc-mainnet/address/{walletAddress}/hd_wallets/
  SDK: BitcoinService.getBitcoinHdWalletBalances()
  API Type: REST
  Role: specialized
  Category: balances
  Credit Cost: 0.1 per item
  Use Cases: wallets, accounting-tax-reporting, portfolio-tracking

- Get ERC20 token transfers for address
  Path: api-reference/foundational-api/balances/get-erc20-token-transfers-for-address
  Operation ID: getErc20TransfersForWalletAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/transfers_v2/
  SDK: BalanceService.getErc20TransfersForWalletAddress()
  API Type: REST
  Role: primary
  Category: balances
  Credit Cost: 0.05 per item

- Get historical Bitcoin balance for non-HD address
  Path: api-reference/foundational-api/balances/get-historical-bitcoin-balance-for-address
  Operation ID: getHistoricalBitcoinBalanceForWalletAddress
  Method: GET
  Endpoint Path: /v1/btc-mainnet/address/{walletAddress}/historical_balances/
  SDK: BitcoinService.getBitcoinNonHdWalletBalances()
  API Type: REST
  Role: specialized
  Category: balances
  Credit Cost: 1 per call
  Use Cases: accounting-tax-reporting, audit-compliance-forensics, portfolio-tracking

- Get historical portfolio value over time
  Path: api-reference/foundational-api/balances/get-historical-portfolio-value-over-time
  Operation ID: getHistoricalPortfolioForWalletAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/portfolio_v2/
  SDK: BalanceService.getHistoricalPortfolioForWalletAddress()
  API Type: REST
  Role: primary
  Category: balances
  Credit Cost: 2 per item
  Use Cases: portfolio-tracking, accounting-tax-reporting

- Get historical token balances for address
  Path: api-reference/foundational-api/balances/get-historical-token-balances-for-address
  Operation ID: getHistoricalTokenBalancesForWalletAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/historical_balances/
  SDK: BalanceService.getHistoricalTokenBalancesForWalletAddress()
  API Type: REST
  Role: specialized
  Category: balances
  Credit Cost: 1 per call

- Get native token balance for address
  Path: api-reference/foundational-api/balances/get-native-token-balance
  Operation ID: getNativeTokenBalance
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/balances_native/
  SDK: BalanceService.getNativeTokenBalance()
  API Type: REST
  Role: primary
  Category: balances
  Credit Cost: 0.5 per call
  Use Cases: wallets, accounting-tax-reporting, portfolio-tracking

- Get token balances for address
  Path: api-reference/foundational-api/balances/get-token-balances-for-address
  Operation ID: getTokenBalancesForWalletAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/balances_v2/
  SDK: BalanceService.getTokenBalancesForWalletAddress()
  API Type: REST
  Role: primary
  Category: balances
  Credit Cost: 1 per call
  Use Cases: wallets, portfolio-tracking, accounting-tax-reporting

- Get token holders as of any block height (v2)
  Path: api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2
  Operation ID: getTokenHoldersV2ForTokenAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/
  SDK: BalanceService.getTokenHoldersV2ForTokenAddress()
  API Type: REST
  Role: specialized
  Category: balances
  Credit Cost: 0.02 per item

- Get activity across all chains for address
  Path: api-reference/foundational-api/cross-chain/get-address-activity
  Operation ID: getAddressActivity
  Method: GET
  Endpoint Path: /v1/address/{walletAddress}/activity/
  SDK: AllChainsService.getAddressActivity()
  API Type: REST
  Role: primary
  Category: base
  Credit Cost: 0.5 per call

- Get multichain balances
  Path: api-reference/foundational-api/cross-chain/get-allchains-balances
  Operation ID: getTokenBalances
  Method: GET
  Endpoint Path: /v1/allchains/address/{walletAddress}/balances/
  SDK: AllChainsService.getMultiChainBalances()
  API Type: REST
  Role: specialized
  Category: allchains
  Credit Cost: 2.5 per call
  Use Cases: wallets, accounting-tax-reporting, portfolio-tracking

- Get multichain & multiaddress transactions
  Path: api-reference/foundational-api/cross-chain/get-allchains-transactions
  Operation ID: getTransactions
  Method: GET
  Endpoint Path: /v1/allchains/transactions/
  SDK: AllChainsService.getMultiChainMultiAddressTransactions()
  API Type: REST
  Role: specialized
  Category: allchains
  Credit Cost: 0.25 per item
  Use Cases: wallets, portfolio-tracking, audit-compliance-forensics, accounting-tax-reporting

- Check ownership in NFT collection for specific token
  Path: api-reference/foundational-api/nft/check-ownership-in-nft-collection-token
  Operation ID: checkOwnershipInNftForSpecificTokenId
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/token/{tokenId}/
  API Type: REST
  Role: specialized
  Category: nft
  Credit Cost: 1 per call

- Check ownership in NFT collection
  Path: api-reference/foundational-api/nft/check-ownership-in-nft-collection
  Operation ID: checkOwnershipInNft
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/
  API Type: REST
  Role: specialized
  Category: nft
  Credit Cost: 1 per call

- Get NFTs for address
  Path: api-reference/foundational-api/nft/get-nfts-for-address
  Operation ID: getNftsForAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/balances_nft/
  API Type: REST
  Role: primary
  Category: nft
  Credit Cost: 1 per call

- Get token approvals for address
  Path: api-reference/foundational-api/security/get-token-approvals-for-address
  Operation ID: getApprovals
  Method: GET
  Endpoint Path: /v1/{chainName}/approvals/{walletAddress}/
  SDK: SecurityService.getApprovals()
  API Type: REST
  Role: primary
  Category: security
  Credit Cost: 2 per call

- Get a transaction
  Path: api-reference/foundational-api/transactions/get-a-transaction
  Operation ID: getTransaction
  Method: GET
  Endpoint Path: /v1/{chainName}/transaction_v2/{txHash}/
  SDK: TransactionService.getTransaction()
  API Type: REST
  Role: primary
  Category: transactions
  Credit Cost: 0.1 per call

- Get all transactions in a block by page (v3) 
  Path: api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page
  Operation ID: getTransactionsForBlockByPage
  Method: GET
  Endpoint Path: /v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/
  API Type: REST
  Role: specialized
  Category: transactions
  Credit Cost: 0.1 per item

- Get all transactions in a block (v3)
  Path: api-reference/foundational-api/transactions/get-all-transactions-in-a-block
  Operation ID: getTransactionsForBlockHash
  Method: GET
  Endpoint Path: /v1/{chainName}/block_hash/{blockHash}/transactions_v3/
  API Type: REST
  Role: specialized
  Category: transactions
  Credit Cost: 0.1 per item

- Get earliest transactions for address (v3) 
  Path: api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3
  Operation ID: getEarliestTimeBucketTransactionsForAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/bulk/transactions/{walletAddress}/
  API Type: REST
  Role: specialized
  Category: transactions
  Credit Cost: 0.1 per item

- Get paginated transactions for address (v3)
  Path: api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3
  Operation ID: getTransactionsForAddressV3
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/
  API Type: REST
  Role: primary
  Category: transactions
  Credit Cost: 0.1 per item

- Get recent transactions for address (v3)
  Path: api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3
  Operation ID: getRecentTransactionsForAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/transactions_v3/
  API Type: REST
  Role: primary
  Category: transactions
  Credit Cost: 0.1 per item

- Get bulk time bucket transactions for address (v3)
  Path: api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3
  Operation ID: getTimeBucketTransactionsForAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/
  SDK: TransactionService.getTimeBucketTransactionsForAddress()
  API Type: REST
  Role: specialized
  Category: transactions
  Credit Cost: 0.1 per item

- Get transaction summary for address
  Path: api-reference/foundational-api/transactions/get-transaction-summary-for-address
  Operation ID: getTransactionSummary
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/transactions_summary/
  SDK: TransactionService.getTransactionSummary()
  API Type: REST
  Role: primary
  Category: transactions
  Credit Cost: 1 per call

- Get Bitcoin transactions for non-HD address
  Path: api-reference/foundational-api/transactions/get-transactions-for-bitcoin-address
  Operation ID: getTransactionsForBtcAddress
  Method: GET
  Endpoint Path: /v1/cq/covalent/app/bitcoin/transactions/
  SDK: BitcoinService.getTransactionsForBtcAddress()
  API Type: REST
  Role: primary
  Category: transactions
  Credit Cost: 0.1 per item

- Get a block
  Path: api-reference/foundational-api/utility/get-a-block
  Operation ID: getBlock
  Method: GET
  Endpoint Path: /v1/{chainName}/block_v2/{blockHeight}/
  SDK: BaseService.getBlock()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 1 per call

- Get all chain statuses
  Path: api-reference/foundational-api/utility/get-all-chain-statuses
  Operation ID: getAllChainStatus
  Method: GET
  Endpoint Path: /v1/chains/status/
  SDK: BaseService.getAllChainStatus()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 1 per call

- Get all chains
  Path: api-reference/foundational-api/utility/get-all-chains
  Operation ID: getAllChains
  Method: GET
  Endpoint Path: /v1/chains/
  SDK: BaseService.getAllChains()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 0.01 per call

- Get block heights
  Path: api-reference/foundational-api/utility/get-block-heights
  Operation ID: getBlockHeights
  Method: GET
  Endpoint Path: /v1/{chainName}/block_v2/{startDate}/{endDate}/
  SDK: BaseService.getBlockHeights()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 1 per call

- Get gas prices
  Path: api-reference/foundational-api/utility/get-gas-prices
  Operation ID: getGasPrices
  Method: GET
  Endpoint Path: /v1/{chainName}/event/{eventType}/gas_prices/
  SDK: BaseService.getGasPrices()
  API Type: REST
  Role: primary
  Category: base
  Credit Cost: 1 per call

- Get historical token prices
  Path: api-reference/foundational-api/utility/get-historical-token-prices
  Operation ID: getTokenPrices
  Method: GET
  Endpoint Path: /v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/
  SDK: PricingService.getTokenPrices()
  API Type: REST
  Role: primary
  Category: pricing
  Credit Cost: 1 per call

- Get log events by contract address
  Path: api-reference/foundational-api/utility/get-log-events-by-contract-address
  Operation ID: getLogEventsByAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/events/address/{contractAddress}/
  SDK: BaseService.getLogEventsByAddress()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 0.01 per item

- Get log events by topic hash(es)
  Path: api-reference/foundational-api/utility/get-log-events-by-topic-hash
  Operation ID: getLogEventsByTopicHash
  Method: GET
  Endpoint Path: /v1/{chainName}/events/topics/{topicHash}/
  SDK: BaseService.getLogEventsByTopicHash()
  API Type: REST
  Role: specialized
  Category: base
  Credit Cost: 0.01 per item

- Get logs
  Path: api-reference/foundational-api/utility/get-logs
  Operation ID: getLogs
  Method: GET
  Endpoint Path: /v1/{chainName}/events/
  SDK: BaseService.getLogs()
  API Type: REST
  Role: primary
  Category: base
  Credit Cost: 0.01 per item

- Get pool spot prices
  Path: api-reference/foundational-api/utility/get-pool-spot-prices
  Operation ID: getPoolSpotPrices
  Method: GET
  Endpoint Path: /v1/pricing/spot_prices/{chainName}/pools/{contractAddress}/
  SDK: PricingService.getPoolSpotPrices()
  API Type: REST
  Role: specialized
  Category: pricing
  Credit Cost: 1 per call

- Get resolved address for registered address
  Path: api-reference/foundational-api/utility/get-resolved-address-for-registered-address
  Operation ID: getResolvedAddress
  Method: GET
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/resolve_address/
  SDK: BaseService.getResolvedAddress()
  API Type: REST
  Role: primary
  Category: base
  Credit Cost: 1 per call

## x402 API (Pay-Per-Request)

The x402 API is a payment-gated proxy in front of the GoldRush Foundational API. AI agents pay per request using the x402 protocol (HTTP 402) with stablecoins on Base -no API keys, accounts, or subscriptions needed.

Base URL: https://x402.goldrush.dev/v1
Protocol: x402 (HTTP 402 Payment Required)
Network: Base Sepolia testnet (Base mainnet coming soon)
Rate Limit: 100 requests/minute per wallet
Client Libraries: @x402/core, @x402/evm

### How It Works
1. Agent calls an endpoint without payment
2. Server responds with HTTP 402 and payment instructions
3. Agent pays with stablecoins on Base and retries with proof of payment
4. Server validates the request before charging, then returns data

### Pricing Model
- Fixed-Price Endpoints: One price per call (e.g., token balances, NFT holdings)
- Tiered Pricing: For variable-length data - Small (1-50 items), Medium (51-200), Large (201-500), XL (501+)
- Response Caching: Cached responses cost less (TTLs: 30s for balances, 5m for pricing data)

### Discovery Endpoints (Free)

- List all available x402 endpoints
  Endpoint Path: /v1/x402/endpoints
  Method: GET
  Cost: Free
  Role: primary

- Search x402 endpoints
  Endpoint Path: /v1/x402/search?q={query}
  Method: GET
  Cost: Free
  Role: primary

- Get details for a specific x402 endpoint
  Endpoint Path: /v1/x402/endpoints/{endpoint-name}
  Method: GET
  Cost: Free
  Role: primary

### Data Endpoints (Paid via x402)

All 60+ Foundational API endpoints are available through the x402 proxy. Key examples:

- Get token balances for address (x402)
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/balances_v2/
  Method: GET
  Pricing: Fixed-price per call

- Get recent transactions for address (x402)
  Endpoint Path: /v1/{chainName}/address/{walletAddress}/transactions_v3/
  Method: GET
  Pricing: Tiered (use ?tier=small|medium|large|xl)

## Streaming API

- Token Search Query
  Path: api-reference/streaming-api/queries/token-search-query
  Operation ID: searchToken
  GraphQL Type: graphql-query
  GraphQL Field: searchToken
  Category: streaming
  API Type: graphql-query
  Role: primary
  Status: Beta
  Use Cases: defi-dashboards, trading-intelligence, market-analytics

- Top Trader Wallets for Token Query
  Path: api-reference/streaming-api/queries/upnl-for-token-query
  Operation ID: upnlForToken
  GraphQL Type: graphql-query
  GraphQL Field: upnlForToken
  Category: streaming
  API Type: graphql-query
  Role: specialized
  Status: Beta
  Use Cases: defi-dashboards, trading-intelligence, market-analytics, automation-and-agents

- Wallet PnL by Token Query
  Path: api-reference/streaming-api/queries/upnl-for-wallet-query
  Operation ID: upnlForWallet
  GraphQL Type: graphql-query
  GraphQL Field: upnlForWallet
  Category: streaming
  API Type: graphql-query
  Role: specialized
  Status: Beta
  Use Cases: trading-intelligence, accounting-tax-reporting, portfolio-tracking

- New DEX Pairs Stream
  Path: api-reference/streaming-api/subscriptions/new-dex-pairs-stream
  Operation ID: newPairs
  GraphQL Type: graphql-subscription
  GraphQL Field: newPairs
  SDK: StreamingService.subscribeToNewPairs()
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: trading-intelligence, price-discovery-feeds, defi-dashboards, automation-and-agents

- OHLCV Pairs Stream
  Path: api-reference/streaming-api/subscriptions/ohlcv-pairs-stream
  Operation ID: ohlcvCandlesForPair
  GraphQL Type: graphql-subscription
  GraphQL Field: ohlcvCandlesForPair
  SDK: StreamingService.subscribeToOHLCVPairs()
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: price-discovery-feeds, trading-intelligence, automation-and-agents

- OHLCV Tokens Stream
  Path: api-reference/streaming-api/subscriptions/ohlcv-tokens-stream
  Operation ID: ohlcvCandlesForToken
  GraphQL Type: graphql-subscription
  GraphQL Field: ohlcvCandlesForToken
  SDK: StreamingService.subscribeToOHLCVTokens()
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: price-discovery-feeds, trading-intelligence, automation-and-agents

- Update Pairs Stream
  Path: api-reference/streaming-api/subscriptions/update-pairs-stream
  Operation ID: updatePairs
  GraphQL Type: graphql-subscription
  GraphQL Field: updatePairs
  SDK: StreamingService.subscribeToUpdatePairs()
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: price-discovery-feeds, trading-intelligence, defi-dashboards, automation-and-agents

- Update Tokens Stream
  Path: api-reference/streaming-api/subscriptions/update-tokens-stream
  Operation ID: updateTokens
  GraphQL Type: graphql-subscription
  GraphQL Field: updateTokens
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: price-discovery-feeds, trading-intelligence, defi-dashboards, automation-and-agents

- Wallet Activity Stream
  Path: api-reference/streaming-api/subscriptions/wallet-activity-stream
  Operation ID: walletTxs
  GraphQL Type: graphql-subscription
  GraphQL Field: walletTxs
  SDK: StreamingService.subscribeToWalletActivity()
  Category: streaming
  API Type: graphql-subscription
  Role: primary
  Status: Beta
  Use Cases: trading-intelligence, automation-and-agents, onchain-gaming-infrastructure, defi-dashboards

## Pipeline API

Streaming blockchain data into customer-managed destinations (ClickHouse, Kafka, Postgres, S3, SQS, webhooks). Includes normalizer schemas (column-level field definitions for EVM, HyperCore, and Solana entities), destination guides, ABI decoding reference, and SQL transforms.

- Event Log Decoding
  Path: goldrush-pipeline-api/abi-decoding/event-decoding
  Description: Decode raw EVM event logs into structured evt_ tables using Solidity ABI event definitions.

- Function Decoding
  Path: goldrush-pipeline-api/abi-decoding/function-decoding
  Description: Decode transaction calldata into structured function call tables using Solidity ABI definitions.

- ABI Decoding Overview
  Path: goldrush-pipeline-api/abi-decoding/overview
  Description: Transform raw EVM event logs and transaction calldata into structured, typed rows using Solidity ABI definitions.

- ABI Reference
  Path: goldrush-pipeline-api/abi-decoding/reference
  Description: ABI file format, Solidity type mapping, contract address filtering, and unmatched record handling.

- Architecture
  Path: goldrush-pipeline-api/architecture
  Description: High-level architecture of the GoldRush Pipeline API, covering structured and raw processing paths, pipeline stages, and delivery guarantees.

- Pipeline API Authentication
  Path: goldrush-pipeline-api/authentication
  Description: How authentication works for the GoldRush Pipeline API: platform login, API keys, and ServiceKeys.

- Configuration Reference
  Path: goldrush-pipeline-api/configuration
  Description: Complete reference for the GoldRush Pipeline API YAML configuration file, including source topics, destinations, ABI decoding, SQL transforms, and execution settings.

- ClickHouse
  Path: goldrush-pipeline-api/destinations/clickhouse
  Description: Configure a ClickHouse destination for the GoldRush Pipeline API to batch-insert structured blockchain data.

- Kafka
  Path: goldrush-pipeline-api/destinations/kafka
  Description: Configure a Kafka destination for the GoldRush Pipeline API to forward raw blockchain data with exactly-once delivery.

- Object Storage (S3/GCS/R2)
  Path: goldrush-pipeline-api/destinations/object-storage
  Description: Configure an Object Storage destination to write structured blockchain data as JSON or Parquet files to S3, GCS, or R2.

- Destinations Overview
  Path: goldrush-pipeline-api/destinations/overview
  Description: Overview of destination types available in the GoldRush Pipeline API, including delivery guarantees and pipeline modes.

- Postgres
  Path: goldrush-pipeline-api/destinations/postgres
  Description: Configure a Postgres destination for the GoldRush Pipeline API to batch-insert structured blockchain data.

- AWS SQS
  Path: goldrush-pipeline-api/destinations/sqs
  Description: Configure an AWS SQS destination for the GoldRush Pipeline API to deliver structured blockchain data to standard or FIFO queues.

- Webhook
  Path: goldrush-pipeline-api/destinations/webhook
  Description: Configure a Webhook destination for the GoldRush Pipeline API to deliver structured blockchain data via HTTP with retry and idempotency.

- Error Handling
  Path: goldrush-pipeline-api/error-handling
  Description: Error handling behavior for each stage of the GoldRush Pipeline API, including retry policies, failure modes, and monitoring.

- Decode Uniswap V3 Swaps
  Path: goldrush-pipeline-api/guides/decode-uniswap-swaps
  Description: Capture every Uniswap V3 swap event on Base Mainnet as structured rows in your Postgres database using GoldRush Pipeline API.

- Hyperliquid Trades to ClickHouse
  Path: goldrush-pipeline-api/guides/hyperliquid-trades
  Description: Stream Hyperliquid fill and trade data into ClickHouse for real-time trading analytics dashboards.

- Track PumpFun Swaps on Solana
  Path: goldrush-pipeline-api/guides/pumpfun-swaps
  Description: Monitor PumpFun token swaps on Solana to track bonding curve activity, token launches, and graduation events.

- Real-Time DEX Analytics
  Path: goldrush-pipeline-api/guides/real-time-dex-analytics
  Description: Stream decoded Solana DEX trade data into ClickHouse to build real-time analytics dashboards for volume, pricing, and trader activity.

- Filter Stablecoins Transfers
  Path: goldrush-pipeline-api/guides/stablecoin-transfers
  Description: Stream filtered ERC-20 stablecoin token transfers with SQL transforms for compliance monitoring or whale watching.

- Stream to S3 as Parquet
  Path: goldrush-pipeline-api/guides/stream-to-s3-parquet
  Description: Archive blockchain data as partitioned Parquet files in S3 for analytics with tools like Athena, Spark, or DuckDB.

- Webhook Notifications for Transfers
  Path: goldrush-pipeline-api/guides/webhook-notifications
  Description: Get real-time HTTP notifications for ERC-20 token transfers to trigger alerts in your application.

- EVM Normalizers
  Path: goldrush-pipeline-api/normalizers/evm
  Description: Column-level schema reference for EVM normalizers.

- HyperCore Normalizers
  Path: goldrush-pipeline-api/normalizers/hypercore
  Description: Schema reference for HyperCore normalizers including fills, trades, orders, and miscellaneous protocol events.

- Normalizers Overview
  Path: goldrush-pipeline-api/normalizers/overview
  Description: Understand how normalizers convert raw blockchain data into structured, typed rows for downstream consumption.

- Solana Normalizers
  Path: goldrush-pipeline-api/normalizers/solana
  Description: Schema reference for Solana normalizers covering DEX trades, PumpFun events, Raydium, Moonshot, Meteora, SPL transfers, and wallet positions.

- Pipeline API Overview
  Path: goldrush-pipeline-api/overview
  Description: The GoldRush Pipeline API is a managed real-time data pipeline service that streams blockchain data from Covalent's database directly to your own infrastructure - databases, warehouses, queues, object storage, or webhooks. Configure pipelines through the GoldRush Platform with ABI decoding, SQL transforms, and protocol-native schemas built in.

- Pipeline API Quickstart
  Path: goldrush-pipeline-api/quickstart
  Description: Learn how to create your first GoldRush Pipeline to stream blockchain data into your own database.

- Pipeline REST API
  Path: goldrush-pipeline-api/rest-api/overview
  Description: The Pipeline REST API lets you create, update, monitor, and delete pipelines programmatically - everything the Platform UI does, scripted.

- Service Keys
  Path: goldrush-pipeline-api/service-keys
  Description: ServiceKeys are programmatic credentials scoped to the GoldRush Pipeline REST API. They are required to create, update, and delete pipelines outside the Platform UI.

- SQL Transforms
  Path: goldrush-pipeline-api/sql-transforms
  Description: Apply optional per-table row-level filtering, projection, and computed columns using SQL after normalization or ABI decoding and before the destination.

- Supported Chains
  Path: goldrush-pipeline-api/supported-chains
  Description: GoldRush Pipeline API supports multiple blockchains including Base, HyperCore, and Solana with structured, per-block data topics for each chain.

## Hyperliquid API

Complete data layer for Hyperliquid: a no-rate-limit drop-in `/info` API at `https://hypercore.goldrushdata.com/info`, real-time HyperCore wallet and OHLCV streams, HIP-3 and HIP-4 market coverage, HyperCore warehouse delivery, and HyperEVM Foundational API support.

- Live Analytics App
  Path: goldrush-hyperliquid/analytics-app
  Description: hyperliquid.goldrush.dev - a live Hyperliquid analytics app built on the GoldRush API. HIP-3 Market Screener, Liquidation Cascade Map, Market Health Score, and macro feeds.

- Early Builders Program
  Path: goldrush-hyperliquid/early-builders-program
  Description: Free Hyperliquid API access for pre-revenue teams. Up to 1 million GoldRush credits over 12 months, monthly cohorts, REST and WebSocket from day one.

- Limits, Caching, and Polling
  Path: goldrush-hyperliquid/info-api/limits
  Description: The GoldRush Hyperliquid Info API has no rate limits. Learn how response caching works and recommended polling cadences.

- Info API Migration Guide
  Path: goldrush-hyperliquid/info-api/migration
  Description: Move from the public Hyperliquid /info API to GoldRush by changing one URL and one header. Step-by-step examples in cURL, JavaScript, and Python.

- Info API Overview
  Path: goldrush-hyperliquid/info-api/overview
  Description: A drop-in replacement for the public Hyperliquid `/info` API. Same request body, no rate limits, faster reads, and progressively more types and capabilities.

- SDK Compatibility
  Path: goldrush-hyperliquid/info-api/sdk-compatibility
  Description: Use existing Hyperliquid SDKs (nomeida/hyperliquid for JS, hyperliquid-python-sdk for Python) against GoldRush by overriding the base URL and injecting an Authorization header.

- Hyperliquid API Overview
  Path: goldrush-hyperliquid/overview
  Description: GoldRush is the complete data layer for Hyperliquid that offers a drop-in Hyperliquid `/info` API replacement with no rate limits, real-time streams for HIP-3 and HIP-4 markets and wallet activity, warehouse delivery via Pipeline API, and full HyperEVM coverage.

- Hyperliquid API Quickstart
  Path: goldrush-hyperliquid/quickstart
  Description: Three 5-minute paths to get Hyperliquid data with GoldRush - drop-in Info API, real-time wallet streams, and warehouse delivery.

- Hyperliquid API Roadmap
  Path: goldrush-hyperliquid/roadmap
  Description: What's shipping next on the GoldRush Hyperliquid API - Info API type expansion, batched user state, time-travel queries, and cross-venue unification.

- HIP-3 Markets
  Path: goldrush-hyperliquid/streaming/hip3-markets
  Description: Discover and stream OHLCV for every HIP-3 builder-deployed perp market on Hyperliquid - equities, commodities, niche assets - using GoldRush's deployer-prefix syntax.

- HIP-4 Outcome Markets
  Path: goldrush-hyperliquid/streaming/hip4-markets
  Description: Stream prediction-market outcomes on Hyperliquid - implied-probability charts, fills, and settlement detection for HIP-4 outcome contracts using the same GoldRush WebSocket primitives that power perps and spot.

- Liquidations and Vault Events
  Path: goldrush-hyperliquid/streaming/liquidations-vaults
  Description: Pre-decoded liquidation, vault, staking, delegation, and borrow/lend events from HyperCore - typed and ready to consume, with no parsing required.

- Wallet Firehose
  Path: goldrush-hyperliquid/streaming/wallet-firehose
  Description: Stream real-time activity for thousands of HyperCore wallets in a single WebSocket connection. Powers copy-trade, whale alerts, and live trader dashboards.

- Build with the L2 Order Book
  Path: goldrush-hyperliquid/websocket-api/l2-order-book-recipe
  Description: Use the streaming L2 order book to power top-of-book trackers, depth-weighted mid quotes, slippage estimators, and liquidity heatmaps - no diff replay or snapshot bootstrap required.

- Build with the L4 Order Book
  Path: goldrush-hyperliquid/websocket-api/l4-order-book-diff
  Description: Use the GoldRush-native L4 order-level stream to track individual orders by `oid`, attribute flow by `user`, and reconstruct queue position and microstructure detail that `l2Book` aggregates away.

- Limits and Connections
  Path: goldrush-hyperliquid/websocket-api/limits
  Description: The GoldRush Hyperliquid WebSocket API has no per-IP subscription cap and supports wildcard subscriptions. Learn about connection management and reconnection.

- WebSocket API Migration Guide
  Path: goldrush-hyperliquid/websocket-api/migration
  Description: Move from the public Hyperliquid WebSocket to GoldRush by changing one URL. Step-by-step examples in wscat, JavaScript, and Python.

- WebSocket API Overview
  Path: goldrush-hyperliquid/websocket-api/overview
  Description: A drop-in replacement for the public Hyperliquid WebSocket. Same subscription payloads, no per-IP subscription caps, and pre-decoded HyperCore events on the same `hypercore.goldrushdata.com` host.

- SDK Compatibility
  Path: goldrush-hyperliquid/websocket-api/sdk-compatibility
  Description: Use existing Hyperliquid SDKs (nomeida/hyperliquid for JS, hyperliquid-python-sdk for Python) against the GoldRush WebSocket API by overriding the WebSocket URL.

- batchClearinghouseState
  Path: api-reference/hyperliquid-info/batch-clearinghouse-state
  API: POST https://hypercore.goldrushdata.com/info
  Description: Fetch perpetuals account state for 1 to 50 wallets in a single request. GoldRush-native batch wrapper around clearinghouseState; no upstream Hyperliquid equivalent.

- batchSpotClearinghouseState
  Path: api-reference/hyperliquid-info/batch-spot-clearinghouse-state
  API: POST https://hypercore.goldrushdata.com/info
  Description: Fetch spot balances for 1 to 50 wallets in a single request. GoldRush-native batch wrapper around spotClearinghouseState; no upstream Hyperliquid equivalent.

- clearinghouseState
  Path: api-reference/hyperliquid-info/clearinghouse-state
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's perpetuals account state - open positions, margin summary, account value, and withdrawable balance.

- delegatorHistory
  Path: api-reference/hyperliquid-info/delegator-history
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's HYPE staking event history - delegate, undelegate, deposit, and withdrawal events with timestamps and validator addresses.

- delegatorRewards
  Path: api-reference/hyperliquid-info/delegator-rewards
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's accrued HYPE staking rewards - delegation rewards and validator commission earnings, one entry per accrual.

- delegatorSummary
  Path: api-reference/hyperliquid-info/delegator-summary
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's HYPE staking summary - currently delegated and undelegated amounts plus pending withdrawal totals.

- frontendOpenOrders
  Path: api-reference/hyperliquid-info/frontend-open-orders
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's open orders enriched with frontend-only metadata - TP/SL trigger info, isPositionTpsl, reduceOnly, and orderType.

- metaAndAssetCtxs
  Path: api-reference/hyperliquid-info/meta-and-asset-ctxs
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns the perpetuals universe metadata plus per-asset live mark price, funding, open interest, and day volume.

- outcomeMeta
  Path: api-reference/hyperliquid-info/outcome-meta
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns the active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and side specs for every binary outcome market on HyperCore.

- spotClearinghouseState
  Path: api-reference/hyperliquid-info/spot-clearinghouse-state
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's spot balances per token, including total USD value.

- spotMetaAndAssetCtxs
  Path: api-reference/hyperliquid-info/spot-meta-and-asset-ctxs
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns the spot universe metadata, token configuration, and per-pair live mark price, mid, and 24-hour volume.

- subAccounts
  Path: api-reference/hyperliquid-info/sub-accounts
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a master account's sub-accounts with each sub-account's perp clearinghouse and spot state.

- userFillsByTime
  Path: api-reference/hyperliquid-info/user-fills-by-time
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's fills bounded by a start and end time - the time-windowed variant of userFills.

- userFills
  Path: api-reference/hyperliquid-info/user-fills
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's most recent fills (up to 2,000), with no time window.

- userFunding
  Path: api-reference/hyperliquid-info/user-funding
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's per-coin funding payment history with funding rate, applied size, and USDC amount per event.

- userNonFundingLedgerUpdates
  Path: api-reference/hyperliquid-info/user-non-funding-ledger-updates
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's ledger events except funding payments - deposits, withdrawals, transfers, vault flows, liquidations, and other balance-changing events.

- userTwapSliceFills
  Path: api-reference/hyperliquid-info/user-twap-slice-fills
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's most recent TWAP slice fills, each tagged with the parent TWAP order ID.

- userVaultEquities
  Path: api-reference/hyperliquid-info/user-vault-equities
  API: POST https://hypercore.goldrushdata.com/info
  Description: Returns a user's locked vault equity per vault address, with the unlock timestamp for each entry.

- L2 Order Book
  Path: api-reference/hyperliquid-websocket/l2-order-book
  Description: Subscribe to real-time L2 order book snapshots for any Hyperliquid perp or spot asset over WebSocket.

- L4 Order Book Diff
  Path: api-reference/hyperliquid-websocket/l4-order-book-diff
  Description: Subscribe to GoldRush's order-level Hyperliquid order book — an initial snapshot of every resting order followed by per-block diffs, with full per-order metadata not exposed by the public Hyperliquid WebSocket.

## Chain Documentation

### Support Levels

**Foundational:** These are the top EVM-compatible chains with guaranteed product parity across the entire GoldRush feature suite, including tracing enhancements. Key features that are only supported for these chains include: - **Historical token balances** - **Token holders list for any block height** - **DEX spot prices**

**Frontier:** Cutting-edge blockchain networks where GoldRush continues to expand feature coverage as the ecosystem evolves. This category includes all non-EVM chains and may include special APIs (e.g. Bitcoin).

**Community:** Community-driven blockchain networks with growing GoldRush integration and feature support. All core onchain data such as spot balances, transaction histories for addresses and decoded event logs are provided.

**Archived:** Previously supported blockchain networks that are now in archived status with limited data availability. No live data is available for these chains.

- ADI Chain
  Path: chains/adi-chain
  Chain Name: adi-mainnet
  Chain ID: 36900
  Support Level: frontier

- ApeChain
  Path: chains/apechain
  Chain Name: apechain-mainnet
  Chain ID: 33139
  Support Level: frontier

- Arbitrum Nova
  Path: chains/arbitrum-nova
  Chain Name: arbitrum-nova-mainnet
  Chain ID: 42170
  Support Level: frontier

- Arbitrum
  Path: chains/arbitrum
  Chain Name: arbitrum-mainnet
  Chain ID: 42161
  Support Level: frontier

- Arc Testnet
  Path: chains/arc
  Chain Name: arc-testnet
  Chain ID: 5042002
  Support Level: frontier

- Avalanche C-Chain
  Path: chains/avalanche-c-chain
  Chain Name: avalanche-mainnet
  Chain ID: 43114
  Support Level: frontier

- Axie/Ronin
  Path: chains/axie-ronin
  Chain Name: axie-mainnet
  Chain ID: 2020
  Support Level: frontier

- Base
  Path: chains/base
  Chain Name: base-mainnet
  Chain ID: 8453
  Support Level: foundational

- Berachain
  Path: chains/berachain
  Chain Name: berachain-mainnet
  Chain ID: 80094
  Support Level: frontier

- Bitcoin
  Path: chains/bitcoin
  Chain Name: btc-mainnet
  Chain ID: 20090103
  Support Level: frontier

- Blast
  Path: chains/blast
  Chain Name: blast-mainnet
  Chain ID: 81457
  Support Level: community

- BNB Smart Chain (BSC)
  Path: chains/bnb-smart-chain-bsc
  Chain Name: bsc-mainnet
  Chain ID: 56
  Support Level: foundational

- Canto
  Path: chains/canto
  Chain Name: canto-mainnet
  Chain ID: 7700
  Support Level: community

- Celo
  Path: chains/celo
  Chain Name: celo-mainnet
  Chain ID: 42220
  Support Level: community

- Covalent Onchain Data API
  Path: chains/covalent

- Cronos zkEVM
  Path: chains/cronos-zkevm
  Chain Name: cronos-zkevm-mainnet
  Chain ID: 388
  Support Level: community

- Cronos
  Path: chains/cronos
  Chain Name: cronos-mainnet
  Chain ID: 25
  Support Level: archived

- Ethereum
  Path: chains/ethereum
  Chain Name: eth-mainnet
  Chain ID: 1
  Support Level: foundational

- Fantom
  Path: chains/fantom
  Chain Name: fantom-mainnet
  Chain ID: 250
  Support Level: community

- Gnosis
  Path: chains/gnosis
  Chain Name: gnosis-mainnet
  Chain ID: 100
  Support Level: foundational

- Harmony
  Path: chains/harmony
  Chain Name: harmony-mainnet
  Chain ID: 1666600000
  Support Level: archived

- HyperCore
  Path: chains/hypercore
  Chain Name: hypercore-mainnet
  Chain ID: na
  Support Level: frontier

- HyperEVM
  Path: chains/hyperevm
  Chain Name: hyperevm-mainnet
  Chain ID: 999
  Support Level: frontier

- Ink
  Path: chains/ink
  Chain Name: ink-mainnet
  Chain ID: 57073
  Support Level: frontier

- Linea
  Path: chains/linea
  Chain Name: linea-mainnet
  Chain ID: 59144
  Support Level: frontier

- Lisk Onchain Data API
  Path: chains/lisk

- Manta Pacific Testnet
  Path: chains/manta-pacific
  Chain Name: manta-sepolia-testnet
  Chain ID: 3441006
  Support Level: community

- Mantle
  Path: chains/mantle
  Chain Name: mantle-mainnet
  Chain ID: 5000
  Support Level: frontier

- MegaETH
  Path: chains/megaeth
  Chain Name: megaeth-mainnet
  Chain ID: 4326
  Support Level: frontier

- Monad
  Path: chains/monad
  Chain Name: monad-mainnet
  Chain ID: 143
  Support Level: frontier

- Moonbeam
  Path: chains/moonbeam
  Chain Name: moonbeam-mainnet
  Chain ID: 1284
  Support Level: community

- Moonriver
  Path: chains/moonriver
  Chain Name: moonbeam-moonriver
  Chain ID: 1285
  Support Level: community

- Oasis Sapphire
  Path: chains/oasis-sapphire
  Chain Name: oasis-sapphire-mainnet
  Chain ID: 23294
  Support Level: frontier

- Oasis
  Path: chains/oasis
  Chain Name: emerald-paratime-mainnet
  Chain ID: 42262
  Support Level: community

- opBNB
  Path: chains/opbnb
  Chain Name: bnb-opbnb-mainnet
  Chain ID: 204
  Support Level: community

- Optimism
  Path: chains/optimism
  Chain Name: optimism-mainnet
  Chain ID: 10
  Support Level: foundational

- Plasma
  Path: chains/plasma
  Chain Name: plasma-mainnet
  Chain ID: 9745
  Support Level: frontier

- Polygon
  Path: chains/polygon
  Chain Name: matic-mainnet
  Chain ID: 137
  Support Level: foundational

- Redstone
  Path: chains/redstone
  Chain Name: redstone-mainnet
  Chain ID: 690
  Support Level: community

- Scroll
  Path: chains/scroll
  Chain Name: scroll-mainnet
  Chain ID: 534352
  Support Level: frontier

- Sei
  Path: chains/sei
  Chain Name: sei-mainnet
  Chain ID: 1329
  Support Level: frontier

- Solana
  Path: chains/solana
  Chain Name: solana-mainnet
  Chain ID: 1399811149
  Support Level: frontier

- Sonic
  Path: chains/sonic
  Chain Name: sonic-mainnet
  Chain ID: 146
  Support Level: frontier

- Taiko
  Path: chains/taiko
  Chain Name: taiko-mainnet
  Chain ID: 167000
  Support Level: frontier

- Tempo Onchain Data API
  Path: chains/tempo

- Unichain
  Path: chains/unichain
  Chain Name: unichain-mainnet
  Chain ID: 130
  Support Level: frontier

- Viction
  Path: chains/viction
  Chain Name: viction-mainnet
  Chain ID: 88
  Support Level: frontier

- World Chain
  Path: chains/world-chain
  Chain Name: world-mainnet
  Chain ID: 480
  Support Level: frontier

- ZetaChain
  Path: chains/zetachain
  Chain Name: zetachain-mainnet
  Chain ID: 7000
  Support Level: community

- zkSync Era
  Path: chains/zksync-era
  Chain Name: zksync-mainnet
  Chain ID: 324
  Support Level: frontier