# GoldRush API Documentation - Complete LLM Reference > This file is optimized for Large Language Models (LLMs) and AI agents. > It contains structured frontmatter metadata and full content for all API endpoints and chain documentation. --- ## Table of Contents ### Quick Reference - [API Selection Guide](#api-selection-guide) - Choose between Foundational, Streaming, or Hybrid approach - [Endpoint Roles](#endpoint-roles) - Understanding primary vs specialized endpoints - [Credit Cost Model](#credit-cost-model) - How API credits are charged - [Quick Decision Tree](#quick-decision-tree) - Fast endpoint selection for common scenarios - [Chain Names & Validation](#chain-names-critical) - Supported chains and parameter rules - [Common Query Patterns](#common-multi-endpoint-workflows) - Real-world endpoint combinations ### API Documentation - [Foundational API](#foundational-api-documentation) - 36 REST endpoints - [Streaming API](#streaming-api-documentation) - 9 GraphQL endpoints - [Pipeline API](#pipeline-api-documentation) - 32 pages (normalizers, destinations, guides) - [Hyperliquid API](#hyperliquid-api-documentation) - 39 pages (Info API, streaming recipes, and API reference) - [x402 API](#x402-api-documentation) - Pay-per-request access for AI agents (60+ endpoints) - [Chain Documentation](#chain-documentation) - 50 supported chains --- # API Selection Guide ## Choosing Between Foundational and Streaming APIs ### Foundational API - Historical & Near Real-Time **API Type:** REST **When to use:** Your application needs historical blockchain data, batch queries, or near real-time updates (block-by-block). **Primary use cases:** - Wallets (balance checks, transaction history) - Portfolio Trackers (historical performance, P&L) - Tax Tools & Accounting (transaction history, cost basis) - Compliance & Auditing (historical records, audit trails) - RWA Registries (ownership records, asset provenance, transfer history) - Block Explorers (historical blockchain data) ### Streaming API - Real-time/Sub-second **API Types:** graphql-subscription (real-time push via WebSocket), graphql-query (one-time GraphQL fetch) **WebSocket Endpoint:** `wss://streaming.goldrushdata.com/graphql` **When to use:** Your application needs sub-second latency updates and real-time event notifications. **Primary use cases:** - Trading Bots (real-time OHLCV, DEX activity) - AI Agents (real-time event reactions) - Alerts & Notifications (real-time monitoring) - Gaming (live game state, real-time events) - Real-time Analytics (live metrics, dashboards) - Price Tracking (live price feeds) **Data Sources:** - Major token prices (BTC, ETH, SOL) on MegaETH are powered by Redstone Bolt -ultra-low-latency CEX price feeds updated every 2.4ms (~400 updates/sec), sourced from Binance, Coinbase, OKX, Bitget, and Kraken via co-located Bolt nodes. ### x402 API - Pay-Per-Request for AI Agents **API Type:** REST (via x402 payment-gated proxy) **Base URL:** `https://x402.goldrush.dev/v1` **When to use:** Your AI agent needs blockchain data without API keys, accounts, or subscriptions. Agents pay per request using the x402 protocol with stablecoins on Base. **Primary use cases:** - AI Agents (autonomous blockchain data access with wallet-based payments) - Serverless Applications (no account setup, pay-as-you-go) - Prototyping & Experimentation (instant access, no onboarding) **How it works:** 1. Agent calls an endpoint without payment 2. Server responds with HTTP 402 (Payment Required) and payment instructions 3. Agent pays with stablecoins on Base, retries with proof of payment 4. Server validates the request *before* charging, then returns data **Key details:** - Transparent reverse proxy in front of `api.covalenthq.com` -same data, same endpoints - 60+ Foundational API endpoints available - Request validation before payment (no charge for malformed requests) - Network: Base Sepolia testnet (Base mainnet coming soon) - Rate limit: 100 requests/minute per wallet ### Hybrid Approach - Best of Both **When to use:** Your application needs both historical context and real-time updates. **Common patterns:** - **DeFi Dashboards:** Foundational for historical charts/TVL + Streaming for live prices/transactions - **Advanced Portfolio Trackers:** Foundational for historical performance + Streaming for live balance updates - **Trading Platforms:** Foundational for backtesting + Streaming for live trade execution - **RWA Monitoring & Compliance:** Foundational for ownership history/audit trails + Streaming for live transfer events/alerts ## Endpoint Roles Each endpoint is classified with a role that determines how prominently LLMs should recommend it: - **primary** - Essential endpoints for common applications (wallets, portfolios, basic queries). These are the default recommendations for typical use cases. - **specialized** - Advanced endpoints for specific use cases (analytics, block explorers, historical snapshots at specific block heights). 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 pricing model: - **per call** - One credit charged per successful HTTP request (200 response). The total cost is fixed regardless of response size. - **per item** - One credit charged per returned record in the response. Default pagination limit is 100 items per page. Example: An endpoint with "0.1 per item" returning 50 records costs 5 credits (0.1 × 50 = 5). --- ## Chain Capabilities Matrix This matrix helps you quickly identify which chains support specific features. ### Legend - ✓ = Supported - F = Foundational API, S = Streaming API - HB = Historical Balances, NFT = NFT Assets & Metadata #### Foundational Chains | Chain Name | APIs | Advanced Features | Block Time | Network | |------------|------|-------------------|------------|---------| | Base (`base-mainnet`) | F, S | - | 2s | Mainnet | | BNB Smart Chain (BSC) (`bsc-mainnet`) | F, S | HB | 5s | Mainnet | | Ethereum (`eth-mainnet`) | F, S | HB | 12s | Mainnet | | Gnosis (`gnosis-mainnet`) | F | - | 5s | Mainnet | | Optimism (`optimism-mainnet`) | F | - | 2s | Mainnet | | Polygon (`matic-mainnet`) | F, S | HB | 3s | Mainnet | #### Frontier Chains | Chain Name | APIs | Advanced Features | Block Time | Network | |------------|------|-------------------|------------|---------| | ADI Chain (`adi-mainnet`) | F | - | 1s | Mainnet | | ApeChain (`apechain-mainnet`) | F | - | 1s | Mainnet | | Arbitrum (`arbitrum-mainnet`) | F | - | 1s | Mainnet | | Arbitrum Nova (`arbitrum-nova-mainnet`) | F | - | 5s | Mainnet | | Arc Testnet (`arc-testnet`) | F | - | 1s | Testnet | | Avalanche C-Chain (`avalanche-mainnet`) | F | - | 3s | Mainnet | | Axie/Ronin (`axie-mainnet`) | F | - | 3s | Mainnet | | Berachain (`berachain-mainnet`) | F | - | 2s | Mainnet | | Bitcoin (`btc-mainnet`) | F | HB | 600s | Mainnet | | HyperCore (`hypercore-mainnet`) | S | - | 1s | Mainnet | | HyperEVM (`hyperevm-mainnet`) | F, S | - | 1s | Mainnet | | Ink (`ink-mainnet`) | F | - | 1s | Mainnet | | Linea (`linea-mainnet`) | F | - | 10s | Mainnet | | Mantle (`mantle-mainnet`) | F | - | 15s | Mainnet | | MegaETH (`megaeth-mainnet`) | F, S | - | 1s | Mainnet | | Monad (`monad-mainnet`) | F, S | - | 1s | Mainnet | | Oasis Sapphire (`oasis-sapphire-mainnet`) | F | - | 24s | Mainnet | | Plasma (`plasma-mainnet`) | F | - | 1s | Mainnet | | Scroll (`scroll-mainnet`) | F | - | 3s | Mainnet | | Sei (`sei-mainnet`) | F | - | 1s | Mainnet | | Solana (`solana-mainnet`) | F, S | - | 1s | Mainnet | | Sonic (`sonic-mainnet`) | F | - | 1s | Mainnet | | Taiko (`taiko-mainnet`) | F | - | 22s | Mainnet | | Unichain (`unichain-mainnet`) | F | - | 1s | Mainnet | | Viction (`viction-mainnet`) | F | - | 2s | Mainnet | | World Chain (`world-mainnet`) | F | - | 2s | Mainnet | | zkSync Era (`zksync-mainnet`) | F | - | 10s | Mainnet | #### Community Chains | Chain Name | APIs | Advanced Features | Block Time | Network | |------------|------|-------------------|------------|---------| | Blast (`blast-mainnet`) | F | - | 2s | Mainnet | | Canto (`canto-mainnet`) | F | - | 7s | Mainnet | | Celo (`celo-mainnet`) | F | - | 5s | Mainnet | | Cronos zkEVM (`cronos-zkevm-mainnet`) | F | - | 5s | Mainnet | | Fantom (`fantom-mainnet`) | F | - | 2s | Mainnet | | Manta Pacific Testnet (`manta-sepolia-testnet`) | F | - | 10s | Testnet | | Moonbeam (`moonbeam-mainnet`) | F | - | 6s | Mainnet | | Moonriver (`moonbeam-moonriver`) | F | - | 12s | Mainnet | | Oasis (`emerald-paratime-mainnet`) | F | - | 20s | Mainnet | | opBNB (`bnb-opbnb-mainnet`) | F | - | 1s | Mainnet | | Redstone (`redstone-mainnet`) | F | - | 2s | Mainnet | | ZetaChain (`zetachain-mainnet`) | F | - | 5s | Mainnet | #### Archived Chains | Chain Name | APIs | Advanced Features | Block Time | Network | |------------|------|-------------------|------------|---------| | Cronos (`cronos-mainnet`) | - | - | 6s | Mainnet | | Harmony (`harmony-mainnet`) | - | - | 2s | Mainnet | **Quick Filters:** - **Historical Balances**: Only chains with "HB" support historical balance queries - **Real-time Streaming**: Chains with "S" support WebSocket subscriptions - **Fast Chains**: Chains with block time <2s are ideal for real-time apps --- ## Quick Decision Tree **Select the right endpoint based on what the user wants to do:** ### Balance & Portfolio Queries - Check wallet balance → `getTokenBalancesForWalletAddress` (primary, REST, 1 per call) - Get historical balance at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, REST, 1 per call) - Get portfolio value over time → `getHistoricalPortfolioForWalletAddress` (primary, REST, 2 per item) - Get native token only → `getNativeTokenBalance` (primary, REST, 0.5 per call) ### Transaction Queries - Get recent transactions → `getRecentTransactionsForAddress` (primary, REST, 0.1 per item) - Get paginated history → `getTransactionsForAddressV3` (primary, REST, 0.1 per item) - Get single transaction details → `getTransaction` (primary, REST, 0.1 per call) - Get ERC20 transfers → `getErc20TransfersForWalletAddress` (primary, REST, 0.05 per item) - Get transaction summary → `getTransactionSummary` (primary, REST, 1 per call) ### Security & Approvals - Check token approvals → `getApprovals` (primary, REST, 2 per call) - Check NFT approvals → `getNftApprovals` (primary, REST, 1 per call) ### Real-time Monitoring (Streaming) - Track real-time prices → `subscribeToOHLCVTokens` (primary, subscription) - Monitor wallet activity → `subscribeToWalletActivity` (primary, subscription) - Detect new DEX pairs → `subscribeToNewPairs` (primary, subscription) - Track specific pair prices → `subscribeToOHLCVPairs` (primary, subscription) ### NFT & Token Queries - Get NFT holdings → `getNftsForAddress` (primary, REST, 1 per call) - Search for tokens → `searchToken` (primary, query) - Get token holders → `getTokenHoldersV2ForTokenAddress` (specialized, REST, 0.02 per item) ### Multi-chain Queries - Check which chains address is active on → `getAddressActivity` (primary, REST, 0.5 per call) - Get balances across chains → `getMultiChainBalances` (specialized, REST, 2.5 per call) - Get transactions across chains → `getMultiChainMultiAddressTransactions` (specialized, REST, 0.25 per item) ### Token & Price Queries - Search for token by name/symbol → `searchToken` (primary, query) - Get token price history → `getTokenPrices` (primary, REST, 1 per call) - Get DEX pool prices → `getPoolSpotPrices` (specialized, REST, Foundational only) - Track real-time token prices → `subscribeToOHLCVTokens` (primary, subscription) ### Block & Event Queries - Get block details → `getBlock` (specialized, REST, 1 per call) - Get block heights by date → `getBlockHeights` (specialized, REST, 1 per call) - Get contract event logs → `getLogEventsByAddress` (specialized, REST, 0.01 per item) - Get logs by topic hash → `getLogEventsByTopicHash` (specialized, REST, 0.01 per item) ### DeFi & Trading - Track DEX pair creation → `subscribeToNewPairs` (primary, subscription) - Monitor DEX pair updates → `subscribeToUpdatePairs` (primary, subscription) - Get OHLCV candles for pairs → `subscribeToOHLCVPairs` (primary, subscription) ### Compliance & Auditing - Get token holder snapshots → `getTokenHoldersV2ForTokenAddress` (specialized, REST, Foundational only) - Get historical balances at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, REST, Foundational only) - Audit transaction history → `getTransactionsForAddressV3` (primary, REST, 0.1 per item) ### AI Agent Access (x402 - No API Key) - Discover available endpoints → `GET /v1/x402/endpoints` (free, no payment) - Search endpoints by keyword → `GET /v1/x402/search?q={query}` (free, no payment) - Get token balances (pay-per-request) → `GET /v1/{chain}/address/{wallet}/balances_v2/` (x402, fixed-price) - Get transactions (pay-per-request) → `GET /v1/{chain}/address/{wallet}/transactions_v3/?tier=small` (x402, tiered) --- # LLM Integration Guide # GoldRush API - LLM Integration Guide (Condensed) **Purpose:** Quick reference for LLMs and AI agents to correctly use the GoldRush API, focusing on error prevention and critical validation rules. --- ## Quick Reference | Item | Value | |------|-------| | **Base URL** | `https://api.covalenthq.com/v1` | | **Authentication** | Bearer token in `Authorization` header | | **API Key** | Sign up at goldrush.dev/platform (starts with `cqt_` or `ckey_`) | | **TypeScript SDK** | `@covalenthq/client-sdk` | | **Response Format** | JSON | | **Protocol** | HTTPS only (HTTP will fail) | **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 --- ## Chain Names (CRITICAL) Chain names use the format: `{network}-{environment}`. These are **case-sensitive** and must match exactly. ### Supported Chain Names Table | Common Name | Chain Name (API Parameter) | Chain ID | Support Level | |-------------|---------------------------|----------|---------------| | Base | `base-mainnet` | 8453 | foundational | | BNB Smart Chain (BSC) | `bsc-mainnet` | 56 | foundational | | Ethereum | `eth-mainnet` | 1 | foundational | | Gnosis | `gnosis-mainnet` | 100 | foundational | | Optimism | `optimism-mainnet` | 10 | foundational | | Polygon | `matic-mainnet` | 137 | foundational | | ADI Chain | `adi-mainnet` | 36900 | frontier | | ApeChain | `apechain-mainnet` | 33139 | frontier | | Arbitrum | `arbitrum-mainnet` | 42161 | frontier | | Arbitrum Nova | `arbitrum-nova-mainnet` | 42170 | frontier | | Arc Testnet | `arc-testnet` | 5042002 | frontier | | Avalanche C-Chain | `avalanche-mainnet` | 43114 | frontier | | Axie/Ronin | `axie-mainnet` | 2020 | frontier | | Berachain | `berachain-mainnet` | 80094 | frontier | | Bitcoin | `btc-mainnet` | 20090103 | frontier | | HyperCore | `hypercore-mainnet` | na | frontier | | HyperEVM | `hyperevm-mainnet` | 999 | frontier | | Ink | `ink-mainnet` | 57073 | frontier | | Linea | `linea-mainnet` | 59144 | frontier | | Mantle | `mantle-mainnet` | 5000 | frontier | | MegaETH | `megaeth-mainnet` | 4326 | frontier | | Monad | `monad-mainnet` | 143 | frontier | | Oasis Sapphire | `oasis-sapphire-mainnet` | 23294 | frontier | | Plasma | `plasma-mainnet` | 9745 | frontier | | Scroll | `scroll-mainnet` | 534352 | frontier | | Sei | `sei-mainnet` | 1329 | frontier | | Solana | `solana-mainnet` | 1399811149 | frontier | | Sonic | `sonic-mainnet` | 146 | frontier | | Taiko | `taiko-mainnet` | 167000 | frontier | | Unichain | `unichain-mainnet` | 130 | frontier | | Viction | `viction-mainnet` | 88 | frontier | | World Chain | `world-mainnet` | 480 | frontier | | zkSync Era | `zksync-mainnet` | 324 | frontier | | Blast | `blast-mainnet` | 81457 | community | | Canto | `canto-mainnet` | 7700 | community | | Celo | `celo-mainnet` | 42220 | community | | Cronos zkEVM | `cronos-zkevm-mainnet` | 388 | community | | Fantom | `fantom-mainnet` | 250 | community | | Manta Pacific Testnet | `manta-sepolia-testnet` | 3441006 | community | | Moonbeam | `moonbeam-mainnet` | 1284 | community | | Moonriver | `moonbeam-moonriver` | 1285 | community | | Oasis | `emerald-paratime-mainnet` | 42262 | community | | opBNB | `bnb-opbnb-mainnet` | 204 | community | | Redstone | `redstone-mainnet` | 690 | community | | ZetaChain | `zetachain-mainnet` | 7000 | community | | Cronos | `cronos-mainnet` | 25 | archived | | Harmony | `harmony-mainnet` | 1666600000 | archived | **Note:** Always use the "Chain Name (API Parameter)" value in API calls. Using common names will result in errors. **Chain Support Levels:** Chains are categorized into four support levels. See [Chain Documentation](#chain-documentation) for complete definitions. - **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 GoldRush uses different naming conventions depending on the context: | Context | Convention | Example | |---------|-----------|----------| | TypeScript SDK | camelCase | `chainName`, `walletAddress` | | REST API Path Parameters | camelCase | `{chainName}`, `{walletAddress}` | | REST API Query Parameters | kebab-case | `quote-currency`, `block-height` | | JSON Response Fields | snake_case | `chain_id`, `updated_at` | ### Parameter Mapping (SDK ↔ REST API) | SDK Parameter | REST Query Parameter | |--------------|---------------------| | chainName | N/A (path parameter) | | walletAddress | N/A (path parameter) | | quoteCurrency | quote-currency | | blockHeight | block-height | | noLogs | no-logs | | withInternal | with-internal | | withState | with-state | | withInputData | with-input-data | --- ## 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 **Examples:** - ✅ Valid: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` - ✅ Valid: `vitalik.eth` - ❌ Invalid: `d8dA6BF26964aF9D7eEd9e03E53415D37aA96045` (missing 0x) - ❌ Invalid: `0xd8dA6BF` (too short) ### Chain Names - **Format:** Exact match from supported chains table (case-sensitive) **Examples:** - ✅ 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) **Examples:** - ✅ 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 ```json { "contract_decimals": 18, "balance": "1500000000000000000", "quote_rate": 2500.50, "quote": 3750.75, "pretty_quote": "$3,750.75" } ``` **Field Explanations:** - `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 **To get human-readable balance:** ```javascript const humanReadable = parseFloat(balance) / Math.pow(10, contract_decimals); // Example: "1500000000000000000" / 10^18 = 1.5 tokens ``` --- ## Understanding Transaction Fields ```json { "successful": true, "value": "0", "gas_spent": 21000, "gas_price": 50000000000, "fees_paid": "1050000000000000", "gas_quote": 2.75, "gas_quote_rate": 2500.00 } ``` **Field Explanations:** - `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 All error responses follow this schema: ```json { "data": null, "error": true, "error_message": "Human-readable error description", "error_code": 401 } ``` ### Common Error Codes | HTTP Status | error_code | Meaning | Solution | |------------|-----------|---------|----------| | 401 | 401 | Invalid or missing API key | Check Authorization header format: `Bearer YOUR_API_KEY` | | 400 | 400 | Invalid request parameters | Verify chain name, address format, or other parameters | | 404 | 404 | Resource not found | Check if chain name is valid or address has activity | | 429 | 429 | Rate limit exceeded | Reduce request frequency or upgrade plan | | 500 | 500 | Internal server error | Retry request, contact support if persists | --- ## Best Practices for LLMs ### 1. Always Validate Chain Names ```typescript 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 ```typescript // ❌ 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 ```typescript // ✅ 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 ```typescript 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 ```typescript // WRONG const chain = "ethereum"; const chain = "polygon"; // CORRECT const chain = "eth-mainnet"; const chain = "matic-mainnet"; ``` ### ❌ Treating Balance as Number ```typescript // WRONG const balance = parseInt(item.balance); // Overflow! // CORRECT const balance = parseFloat(item.balance) / Math.pow(10, item.contract_decimals); ``` ### ❌ Forgetting to Check Error Response ```typescript // 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 ```typescript // 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 ```bash # WRONG curl -H "Authorization: YOUR_API_KEY" # CORRECT curl -H "Authorization: Bearer YOUR_API_KEY" ``` ### ❌ Using HTTP Instead of HTTPS ```bash # 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? **A:** Divide the balance string by 10^contract_decimals: ```typescript 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`? **A:** - `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? **A:** Only Foundational chains support tracing features (`with-internal`, `with-state`, `with-input-data`). Currently, only `eth-mainnet` fully supports all tracing features. Check the endpoint documentation for "Foundational Chains" support. ### Q: How do I handle ENS names? **A:** Just pass the ENS name directly as the wallet address. GoldRush automatically resolves it: ```typescript const resp = await client.BalanceService.getTokenBalancesForWalletAddress( "eth-mainnet", "vitalik.eth" // Automatically resolved ); ``` ### Q: What's the difference between `balances_v2` and `balances_native`? **A:** - `balances_v2`: Returns ALL tokens (native + ERC20 + NFTs) - `balances_native`: Returns ONLY the native token (ETH, MATIC, etc.) Use `balances_native` for lightweight queries when you only need the native token balance. ### Q: How do I filter out spam tokens? **A:** Use the `no-spam` query parameter: ```bash 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? **A:** - **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? **A:** - 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 | Data Type | URL Pattern | |-----------|------------| | Token Balances | `/v1/{chain}/address/{address}/balances_v2/` | | Native Balance Only | `/v1/{chain}/address/{address}/balances_native/` | | Transaction History | `/v1/{chain}/address/{address}/transactions_v3/page/{page}/` | | Single Transaction | `/v1/{chain}/transaction_v2/{txHash}/` | | NFT Metadata | `/v1/{chain}/tokens/{contract}/nft_metadata/{tokenId}/` | | Token Holders | `/v1/{chain}/tokens/{contract}/token_holders_v2/` | | Cross-Chain Activity | `/v1/address/{address}/activity/` | | Security Approvals | `/v1/{chain}/approvals/{address}/` | | ERC20 Transfers | `/v1/{chain}/address/{address}/transfers_v2/` | | Historical Prices | `/v1/pricing/historical_by_address/{chain}/{contract}/` | --- ## 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 When building AI agents that use GoldRush API, include this in your system prompt: ``` 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 ``` --- **Last Updated:** January 2025 **API Version:** v1 **Documentation Version:** 2.0 (LLM-Optimized Condensed) --- ## LLM Operational Guide (Deeper Dive) This section is optimized for real-world task routing and error prevention. Use it after `llms.txt`. ### Task-to-Endpoint Map - Current wallet balances → `getTokenBalancesForWalletAddress` - Native token only → `getNativeTokenBalance` - ERC20 transfers → `getErc20TransfersForWalletAddress` - Recent transactions → `getRecentTransactionsForAddress` - Full history (paged) → `getTransactionsForAddressV3` (page 0 = earliest) - Transaction summary → `getTransactionSummary` - Single transaction → `getTransaction` - Token holders snapshot → `getTokenHoldersV2ForTokenAddress` (Foundational chains only) - Historical balances at block → `getHistoricalTokenBalancesForWalletAddress` (Foundational chains only) - Historical token prices → `getTokenPrices` - Pool spot prices → `getPoolSpotPrices` (Foundational chains only) - Approvals (ERC20/NFT) → `getApprovals`, `getNftApprovals` - Multi-chain activity → `getAddressActivity` - Multi-chain balances → `getMultiChainBalances` (no ENS/domain names) - Multi-chain txs → `getMultiChainMultiAddressTransactions` (no ENS/domain names) - Streaming wallet activity → `subscribeToWalletActivity` - Streaming OHLCV tokens/pairs → `subscribeToOHLCVTokens`, `subscribeToOHLCVPairs` - Streaming new pairs/updates → `subscribeToNewPairs`, `subscribeToUpdatePairs` - Streaming token search → `searchToken` (GraphQL query) ### Parameter & Naming Rules - Chain names are case-sensitive; use the exact `chain_name` values from the chain table. - REST path params are camelCase; REST query params are kebab-case. - Pagination is 0-indexed; 100 items per page is the default. - Always check `resp.error` before accessing `resp.data`. - Token balances are strings; convert with decimals to avoid overflow. ### Chain Support Boundaries - Foundational-only features: historical token balances, token holders at any block, pool spot prices, tracing flags. - Non-EVM chains have partial coverage (e.g. Bitcoin has dedicated endpoints; Solana supports balances only). - Streaming uses enum chain names like `ETH_MAINNET` in GraphQL. ### Common Mistakes to Avoid - Using common chain names (e.g. "ethereum") instead of `eth-mainnet`. - Treating `balance` fields as numbers without decimals conversion. - Forgetting pagination or assuming a single page is complete. - Mixing Streaming subscriptions when historical data is required (or vice versa). --- ## Common Errors & Troubleshooting This section covers common errors for frequently used endpoints. ### Get token balances for address **1. 400 Bad Request - Invalid address** - Solution: Ensure address starts with 0x and is 40 hex characters - Example: Valid: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` **2. 404 Not Found - Chain not found** - Solution: Use exact chain name (case-sensitive): `eth-mainnet` not "ethereum" - Example: Correct: `eth-mainnet` | Wrong: `ethereum` **3. Response contains spam tokens** - Solution: Filter by `is_spam: false` or use minimum quote threshold - Example: Filter: `items.filter(t => !t.is_spam && parseFloat(t.quote) > 0.01)` ### Get paginated transactions for address (v3) **1. 400 Bad Request - Invalid pagination** - Solution: Page numbers are 0-indexed. First page is 0, not 1. - Example: First: `page-number=0` | Second: `page-number=1` **2. Incomplete transaction history** - Solution: Check `pagination.has_more` field. Continue until `has_more: false`. - Example: Loop: `while (response.data.pagination.has_more)` ### Get a transaction **1. 404 Not Found - Transaction not found** - Solution: Verify tx hash format (0x + 64 hex chars) and wait for confirmation - Example: Valid: `0x1234...` (66 chars total) **2. Tracing costs extra credits** - Solution: Each trace flag adds 0.05 credits. Only on Foundational chains. - Example: Base: 0.1 | With traces: 0.25 credits ### Wallet Activity Stream **1. WebSocket connection failed** - Solution: Verify URL (wss://streaming.goldrushdata.com/graphql) and auth header - Example: Header: `Authorization: Bearer YOUR_API_KEY` **2. Subscription not receiving data** - Solution: Use enum format: `ETH_MAINNET` not `eth-mainnet`. Check chain supports Streaming. - Example: GraphQL: `ETH_MAINNET` | REST: `eth-mainnet` ### General Tips - Always check `response.error` field before accessing `response.data` - Chain names are case-sensitive: use exact values from Chain Capabilities Matrix - Token balances are strings: use BigInt or decimal libraries for math - Pagination is 0-indexed: first page is 0, not 1 - Check Chain Capabilities Matrix for feature availability --- ## Common Multi-Endpoint Workflows Real-world scenarios often require combining multiple endpoints. Here are proven patterns: ### Portfolio Valuation & Analysis ``` 1. getTokenBalancesForWalletAddress → Get current token holdings with spot prices 2. getHistoricalPortfolioForWalletAddress → Get historical portfolio value over time 3. getTransactionsForAddressV3 → Get full transaction history for cost basis ``` **Use case:** Building portfolio trackers, tax calculators, wealth management dashboards ### Transaction Deep Dive ``` 1. getRecentTransactionsForAddress → Get latest transactions 2. getTransaction(txHash) → Get detailed decoded data for specific transaction 3. getLogEventsByAddress → Get contract event logs for context ``` **Use case:** Transaction explorers, audit trails, forensic analysis ### Security Audit ``` 1. getApprovals → Check ERC20 token approvals 2. getNftApprovals → Check NFT approvals 3. getRecentTransactionsForAddress → Review recent approval transactions ``` **Use case:** Security dashboards, wallet protection tools, approval management ### Trading Bot Setup (Hybrid: Foundational + Streaming) ``` Historical Data (Foundational API): 1. getTokenPrices → Get historical price data for backtesting 2. getHistoricalPortfolioForWalletAddress → Analyze historical performance Live Monitoring (Streaming API): 3. subscribeToNewPairs → Detect newly created DEX pairs 4. subscribeToOHLCVPairs → Track real-time price movements 5. subscribeToWalletActivity → Monitor whale wallet transactions ``` **Use case:** Automated trading systems, arbitrage bots, market monitoring ### Multi-Chain Portfolio ``` 1. getAddressActivity → Discover which chains the address is active on 2. getMultiChainBalances → Get balances across all active chains 3. getMultiChainMultiAddressTransactions → Get transaction history across chains ``` **Use case:** Cross-chain wallets, multi-chain portfolio trackers, aggregated analytics ### RWA Monitoring & Compliance (Hybrid) ``` Historical Records (Foundational API): 1. getHistoricalTokenBalancesForWalletAddress → Ownership history at specific blocks 2. getTransactionsForAddressV3 → Complete transfer history 3. getTokenHoldersV2ForTokenAddress → Token holder snapshots Live Monitoring (Streaming API): 4. subscribeToWalletActivity → Real-time transfer notifications 5. subscribeToUpdatePairs → Live asset valuation updates ``` **Use case:** RWA registries, compliance platforms, real-time asset tracking ### NFT Collection Analysis ``` 1. getNftsForAddress → Get NFT holdings for an address 2. checkOwnershipInNft → Verify NFT ownership for token gating 3. getRecentTransactionsForAddress → Get recent NFT transaction history ``` **Use case:** NFT galleries, token-gated access, collection tracking --- # Foundational API Documentation ## 1. Get Bitcoin balance for non-HD address **Path:** api-reference/foundational-api/balances/get-bitcoin-balance-for-address **Operation Identity:** - Operation ID: `getBitcoinBalanceForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/btc-mainnet/address/{walletAddress}/balances_v2/` - TypeScript SDK: `BitcoinService.getBitcoinNonHdWalletBalances()` **Metadata:** ```yaml title: Get Bitcoin balance for non-HD address openapi: GET /v1/btc-mainnet/address/{walletAddress}/balances_v2/ category: balances api_type: REST operation_identity: {"operation_id":"getBitcoinBalanceForWalletAddress","method":"GET","path":"/v1/btc-mainnet/address/{walletAddress}/balances_v2/","sdk_service":"BitcoinService","sdk_method":"getBitcoinNonHdWalletBalances"} endpoint_role: specialized credit_cost: 1 per call chains: ["btc-mainnet"] use_cases: [] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `walletAddress` | string | Yes | The requested bitcoin non-HD address. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `contract_display_name` | `string` | A display-friendly name for the contract. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_urls` | `object` | The contract logo URLs. | | `last_transferred_at` | `string` | The timestamp when the token was transferred. | | `block_height` | `integer` | The height of the block. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: ETH on Ethereum. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `balance_24h` | `string` | b;The 24h asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote_rate_24h` | `number` | The 24h exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `quote_24h` | `number` | The 24h balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | | `pretty_quote_24h` | `string` | A prettier version of the 24h quote for rendering purposes. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 2. Get Bitcoin balances for HD address **Path:** api-reference/foundational-api/balances/get-bitcoin-balances-for-hd-address **Operation Identity:** - Operation ID: `getBitcoinHdWalletBalances` - Method: `GET` - Endpoint Path: `/v1/btc-mainnet/address/{walletAddress}/hd_wallets/` - TypeScript SDK: `BitcoinService.getBitcoinHdWalletBalances()` **Metadata:** ```yaml title: Get Bitcoin balances for HD address openapi: GET /v1/btc-mainnet/address/{walletAddress}/hd_wallets/ category: balances api_type: REST operation_identity: {"operation_id":"getBitcoinHdWalletBalances","method":"GET","path":"/v1/btc-mainnet/address/{walletAddress}/hd_wallets/","sdk_service":"BitcoinService","sdk_method":"getBitcoinHdWalletBalances"} endpoint_role: specialized credit_cost: 0.1 per item chains: ["btc-mainnet"] use_cases: ["wallets","accounting-tax-reporting","portfolio-tracking"] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `walletAddress` | string | Yes | The extended public key (xPub/yPub/zPub) of the HD wallet. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert the balance to. Supports `USD`, `CAD`, `EUR`, etc. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The extended public key (xPub/yPub/zPub) or HD wallet address. | | `chain_id` | `integer` | The requested chain ID eg: `20090103`. | | `chain_name` | `string` | The requested chain name eg: `btc-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of HD wallet balance items, each containing derived addresses and balances. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `child_address` | `string` | The specific Bitcoin address derived from the HD wallet. | | `address_path` | `string` | Derivation path used to derive the specific Bitcoin address, e.g., `M/0H/0/0`. | | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The name of the token, e.g., `Bitcoin`. | | `contract_ticker_symbol` | `string` | The ticker symbol for the token, e.g., `BTC`. | | `contract_address` | `string` | Address placeholder for native tokens like BTC. | | `contract_display_name` | `string` | A display-friendly name for the token, e.g., `Bitcoin`. | | `supports_erc` | `array` | Typically null for Bitcoin, but left for compatibility. | | `logo_urls` | `object` | The contract logo URLs. | | `last_transferred_at` | `string` | The timestamp when the token was last transferred. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: BTC on Bitcoin. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `balance_24h` | `string` | b;The 24h asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote_rate_24h` | `number` | The 24h exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `quote_24h` | `number` | The 24h balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | | `pretty_quote_24h` | `string` | A prettier version of the 24h quote for rendering purposes. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** Requests that return status 200 and no data cost 0.1 credits. --- ## 3. Get ERC20 token transfers for address **Path:** api-reference/foundational-api/balances/get-erc20-token-transfers-for-address **Operation Identity:** - Operation ID: `getErc20TransfersForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/transfers_v2/` - TypeScript SDK: `BalanceService.getErc20TransfersForWalletAddress()` **Metadata:** ```yaml title: Get ERC20 token transfers for address openapi: GET /v1/{chainName}/address/{walletAddress}/transfers_v2/ category: balances api_type: REST operation_identity: {"operation_id":"getErc20TransfersForWalletAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/transfers_v2/","sdk_service":"BalanceService","sdk_method":"getErc20TransfersForWalletAddress"} endpoint_role: primary credit_cost: 0.05 per item chains: all use_cases: [] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `contract-address` | string | Yes | - | The requested contract address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `starting-block` | integer | No | 0 | The block height to start from, defaults to `0`. | | `ending-block` | integer | No | current | The block height to end at, defaults to current block height. | | `page-size` | integer | No | 100 | Number of items per page. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Whether or not transaction is successful. | | `miner_address` | `string` | The address of the miner. | | `from_address` | `string` | The sender's wallet address. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The transaction's gas_price * gas_spent, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `transfers` | `array` | | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 0.05 per item **Processing:** Realtime --- ## 4. Get historical Bitcoin balance for non-HD address **Path:** api-reference/foundational-api/balances/get-historical-bitcoin-balance-for-address **Operation Identity:** - Operation ID: `getHistoricalBitcoinBalanceForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/btc-mainnet/address/{walletAddress}/historical_balances/` - TypeScript SDK: `BitcoinService.getBitcoinNonHdWalletBalances()` **Metadata:** ```yaml title: Get historical Bitcoin balance for non-HD address openapi: GET /v1/btc-mainnet/address/{walletAddress}/historical_balances/ category: balances api_type: REST operation_identity: {"operation_id":"getHistoricalBitcoinBalanceForWalletAddress","method":"GET","path":"/v1/btc-mainnet/address/{walletAddress}/historical_balances/","sdk_service":"BitcoinService","sdk_method":"getBitcoinNonHdWalletBalances"} endpoint_role: specialized credit_cost: 1 per call chains: ["btc-mainnet"] use_cases: ["accounting-tax-reporting","audit-compliance-forensics","portfolio-tracking"] beta: false related: ["get-token-balances-for-address","get-native-token-balance","get-bitcoin-balance-for-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `walletAddress` | string | Yes | Only Bitcoin non-HD addresses are supported. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `block-height` | integer | No | the | Ending block to define a block range. Omitting this parameter defaults to the latest block height. | | `date` | string | No | the | Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_url` | `string` | The contract logo URL. | | `block_height` | `integer` | The height of the block. | | `last_transferred_block_height` | `integer` | The block height when the token was last transferred. | | `contract_display_name` | `string` | | | `last_transferred_at` | `string` | The timestamp when the token was transferred. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: ETH on Ethereum. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 5. Get historical portfolio value over time **Path:** api-reference/foundational-api/balances/get-historical-portfolio-value-over-time **Operation Identity:** - Operation ID: `getHistoricalPortfolioForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/portfolio_v2/` - TypeScript SDK: `BalanceService.getHistoricalPortfolioForWalletAddress()` **Metadata:** ```yaml title: Get historical portfolio value over time openapi: GET /v1/{chainName}/address/{walletAddress}/portfolio_v2/ category: balances api_type: REST operation_identity: {"operation_id":"getHistoricalPortfolioForWalletAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/portfolio_v2/","sdk_service":"BalanceService","sdk_method":"getHistoricalPortfolioForWalletAddress"} endpoint_role: primary credit_cost: 2 per item chains: all use_cases: ["portfolio-tracking","accounting-tax-reporting"] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `days` | integer | No | 30 | The number of days to return data for. Defaults to 30 days. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `logo_url` | `string` | The contract logo URL. | | `holdings` | `array` | | **Content:** **Credit Cost:** 2 per 30 days **Processing:** Realtime > **Note:** Rebasing tokens (e.g. stETH, aTokens, cTokens) are supported on [Foundational Chains](https://goldrush.dev/docs/chains/overview#foundational-chains). --- ## 6. Get historical token balances for address **Path:** api-reference/foundational-api/balances/get-historical-token-balances-for-address **Operation Identity:** - Operation ID: `getHistoricalTokenBalancesForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/historical_balances/` - TypeScript SDK: `BalanceService.getHistoricalTokenBalancesForWalletAddress()` **Metadata:** ```yaml title: Get historical token balances for address openapi: GET /v1/{chainName}/address/{walletAddress}/historical_balances/ category: balances api_type: REST operation_identity: {"operation_id":"getHistoricalTokenBalancesForWalletAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/historical_balances/","sdk_service":"BalanceService","sdk_method":"getHistoricalTokenBalancesForWalletAddress"} endpoint_role: specialized credit_cost: 1 per call chains: ["eth-mainnet","matic-mainnet","bsc-mainnet","base-mainnet","optimism-mainnet","gnosis-mainnet"] use_cases: [] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-spam` | boolean | No | - | If `true`, the suspected spam tokens are removed. Supported on all Foundational Chains. | | `block-height` | integer | No | the | Ending block to define a block range. Omitting this parameter defaults to the latest block height. | | `date` | string | No | the | Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_url` | `string` | The contract logo URL. | | `block_height` | `integer` | The height of the block. | | `last_transferred_block_height` | `integer` | The block height when the token was last transferred. | | `contract_display_name` | `string` | | | `last_transferred_at` | `string` | The timestamp when the token was transferred. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: ETH on Ethereum. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** Endpoint only supported on all [Foundational Chains](https://goldrush.dev/chains/). Rebasing tokens (e.g. stETH, aTokens, cTokens) also supported on [Foundational Chains](https://goldrush.dev/docs/chains/overview#foundational-chains). --- ## 7. Get native token balance for address **Path:** api-reference/foundational-api/balances/get-native-token-balance **Operation Identity:** - Operation ID: `getNativeTokenBalance` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/balances_native/` - TypeScript SDK: `BalanceService.getNativeTokenBalance()` **Metadata:** ```yaml title: Get native token balance for address openapi: GET /v1/{chainName}/address/{walletAddress}/balances_native/ category: balances api_type: REST operation_identity: {"operation_id":"getNativeTokenBalance","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/balances_native/","sdk_service":"BalanceService","sdk_method":"getNativeTokenBalance"} endpoint_role: primary credit_cost: 0.5 per call chains: all use_cases: ["wallets","accounting-tax-reporting","portfolio-tracking"] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-bitcoin-balance-for-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `block-height` | integer | No | the | Ending block to define a block range. Omitting this parameter defaults to the latest block height. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_url` | `string` | The contract logo URL. | | `block_height` | `integer` | The height of the block. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | **Content:** **Credit Cost:** 0.5 per call **Processing:** Realtime > **Note:** Not supported on non-EVM chains such as Bitcoin and Solana. --- ## 8. Get token balances for address **Path:** api-reference/foundational-api/balances/get-token-balances-for-address **Operation Identity:** - Operation ID: `getTokenBalancesForWalletAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/balances_v2/` - TypeScript SDK: `BalanceService.getTokenBalancesForWalletAddress()` **Metadata:** ```yaml title: Get token balances for address openapi: GET /v1/{chainName}/address/{walletAddress}/balances_v2/ category: balances api_type: REST operation_identity: {"operation_id":"getTokenBalancesForWalletAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/balances_v2/","sdk_service":"BalanceService","sdk_method":"getTokenBalancesForWalletAddress"} endpoint_role: primary credit_cost: 1 per call chains: all use_cases: ["wallets","portfolio-tracking","accounting-tax-reporting"] beta: false related: ["get-historical-bitcoin-balance-for-address","get-native-token-balance","get-bitcoin-balance-for-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-spam` | boolean | No | - | If `true`, the suspected spam tokens are removed. Supported on all Foundational Chains. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `contract_display_name` | `string` | A display-friendly name for the contract. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_urls` | `object` | The contract logo URLs. | | `last_transferred_at` | `string` | The timestamp when the token was transferred. | | `block_height` | `integer` | The height of the block. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: ETH on Ethereum. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `balance_24h` | `string` | b;The 24h asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote_rate_24h` | `number` | The 24h exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `quote_24h` | `number` | The 24h balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | | `pretty_quote_24h` | `string` | A prettier version of the 24h quote for rendering purposes. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** Rebasing tokens (e.g. stETH, aTokens, cTokens) are supported on [Foundational Chains](https://goldrush.dev/docs/chains/overview#foundational-chains). ### Related guides Understanding Web3 Wallets with GoldRush How to Get Bitcoin Balances and Transactions Comparing GoldRush’s Token Balances API to RPC Providers --- ## 9. 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 Identity:** - Operation ID: `getTokenHoldersV2ForTokenAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/` - TypeScript SDK: `BalanceService.getTokenHoldersV2ForTokenAddress()` **Metadata:** ```yaml title: Get token holders as of any block height (v2) openapi: GET /v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/ category: balances api_type: REST operation_identity: {"operation_id":"getTokenHoldersV2ForTokenAddress","method":"GET","path":"/v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/","sdk_service":"BalanceService","sdk_method":"getTokenHoldersV2ForTokenAddress"} endpoint_role: specialized credit_cost: 0.02 per item chains: ["eth-mainnet","matic-mainnet","bsc-mainnet","base-mainnet","optimism-mainnet","gnosis-mainnet"] use_cases: [] beta: false related: ["get-token-balances-for-address","get-historical-bitcoin-balance-for-address","get-native-token-balance"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `tokenAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `no-snapshot` | boolean | No | false | Defaults to `false`. Set to `true` to bypass last snapshot and get the latest token holders list. | | `block-height` | integer | No | the | Ending block to define a block range. Omitting this parameter defaults to the latest block height. | | `date` | string | No | the | Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date. | | `page-size` | integer | No | 100 | Number of items per page. Note: Currently, only values of `100` and `1000` are supported. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_url` | `string` | The contract logo URL. | | `address` | `string` | The requested address. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `total_supply` | `string` | b;Total supply of this token. | | `block_height` | `integer` | The height of the block. | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 0.02 per item **Processing:** Realtime > **Note:** When no `block-height` is specified, the default is to use the latest token holder snapshot which updates every 30 mins. To fetch the current token holders list without using the snapshot, set `no-snapshot=true`. Page size is either `100` (default) or `1000`. Supported only on [Foundational Chains](https://goldrush.dev/chains/). --- ## 10. Get activity across all chains for address **Path:** api-reference/foundational-api/cross-chain/get-address-activity **Operation Identity:** - Operation ID: `getAddressActivity` - Method: `GET` - Endpoint Path: `/v1/address/{walletAddress}/activity/` - TypeScript SDK: `AllChainsService.getAddressActivity()` **Metadata:** ```yaml title: Get activity across all chains for address openapi: GET /v1/address/{walletAddress}/activity/ category: base api_type: REST operation_identity: {"operation_id":"getAddressActivity","method":"GET","path":"/v1/address/{walletAddress}/activity/","sdk_service":"AllChainsService","sdk_method":"getAddressActivity"} endpoint_role: primary credit_cost: 0.5 per call chains: [] use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `walletAddress` | string | Yes | The requested wallet address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `testnets` | boolean | No | - | Set to true to include testnets with activity in the response. By default, it's set to `false` and only returns mainnet activity. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `address` | `string` | The requested address. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `extends` | `object` | | | `first_seen_at` | `string` | The timestamp when the address was first seen on the chain. | | `last_seen_at` | `string` | The timestamp when the address was last seen on the chain. | **Content:** **Credit Cost:** 0.5 per call **Processing:** Realtime --- ## 11. Get multichain balances **Path:** api-reference/foundational-api/cross-chain/get-allchains-balances **Operation Identity:** - Operation ID: `getTokenBalances` - Method: `GET` - Endpoint Path: `/v1/allchains/address/{walletAddress}/balances/` - TypeScript SDK: `AllChainsService.getMultiChainBalances()` **Metadata:** ```yaml title: Get multichain balances openapi: GET /v1/allchains/address/{walletAddress}/balances/ category: allchains api_type: REST operation_identity: {"operation_id":"getTokenBalances","method":"GET","path":"/v1/allchains/address/{walletAddress}/balances/","sdk_service":"AllChainsService","sdk_method":"getMultiChainBalances"} endpoint_role: specialized credit_cost: 2.5 per call chains: all use_cases: ["wallets","accounting-tax-reporting","portfolio-tracking"] beta: false related: ["get-allchains-transactions","all-chains"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `walletAddress` | string | Yes | The requested address. Domain names (e.g. `demo.eth`) NOT supported. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `chains` | string | No | all | Comma separated list of chain names or IDs to retrieve token balances from. Defaults to all foundational chains. | | `limit` | integer | No | max | Number of token balances to return per page, up to the default max of 100 items. | | `before` | string | No | - | Pagination cursor pointing to fetch token balances before a certain point. | | `cutoff-timestamp` | integer | No | - | UNIX timestamp to retrieve the balance snapshot from the nearest block before the specified cutoff time. | | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, `GBP`, `BTC` and `ETH`. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | Timestamp for when the data was last updated. | | `cursor_before` | `string` | Pagination cursor pointing to the previous page. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `items` | `array` | List of token balances returned by the API. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `contract_display_name` | `string` | A display-friendly name for the contract. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `logo_urls` | `object` | The contract logo URLs. | | `last_transferred_at` | `string` | The timestamp when the token was transferred. | | `is_native_token` | `boolean` | Indicates if a token is the chain's native gas token, eg: ETH on Ethereum. | | `type` | `string` | One of `cryptocurrency`, `stablecoin`, `nft` or `dust`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `balance_24h` | `string` | b;The 24h asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `quote_rate_24h` | `number` | The 24h exchange rate for the requested quote currency. | | `quote` | `number` | The current balance converted to fiat in `quote-currency`. | | `quote_24h` | `number` | The 24h balance converted to fiat in `quote-currency`. | | `pretty_quote` | `string` | A prettier version of the quote for rendering purposes. | | `pretty_quote_24h` | `string` | A prettier version of the 24h quote for rendering purposes. | | `chain_id` | `integer` | The chain ID that this balance is on. eg: `1`. | | `chain_name` | `string` | The chain name that this balance is on. eg: `eth-mainnet`. | | `chain_display_name` | `string` | A display-friendly name for the chain. | **Content:** **Credit Cost:** 2.5 per call **Processing:** Realtime > **Note:** Base cost is `2.5` credits (including requests that return with status `200` but no items) for the first page. Subsequent pages cost `1` credit. All EVM chains are supported. When no chains are specified, the [Foundational Chains](https://goldrush.dev/chains) are passed as default. Domain names (e.g. `demo.eth`) are not supported. The UNIX `cutoff-timestamp` retrieves the token balance snapshot from the nearest block before the specified timestamp. Balances presented in descending order of the fiat quote value for most major tokens. Minor tokens may be presented in descending order of their `last_transferred_at` timestamp. Rebasing tokens (e.g. stETH, aTokens, cTokens) are supported on [Foundational Chains](https://goldrush.dev/docs/chains/overview#foundational-chains). --- ## 12. Get multichain & multiaddress transactions **Path:** api-reference/foundational-api/cross-chain/get-allchains-transactions **Operation Identity:** - Operation ID: `getTransactions` - Method: `GET` - Endpoint Path: `/v1/allchains/transactions/` - TypeScript SDK: `AllChainsService.getMultiChainMultiAddressTransactions()` **Metadata:** ```yaml title: Get multichain & multiaddress transactions openapi: GET /v1/allchains/transactions/ category: allchains api_type: REST operation_identity: {"operation_id":"getTransactions","method":"GET","path":"/v1/allchains/transactions/","sdk_service":"AllChainsService","sdk_method":"getMultiChainMultiAddressTransactions"} endpoint_role: specialized credit_cost: 0.25 per item chains: all use_cases: ["wallets","portfolio-tracking","audit-compliance-forensics","accounting-tax-reporting"] beta: false related: ["all-chains","get-allchains-balances"] ``` ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `chains` | string | No | all | Comma separated list of chain names or IDs to retrieve transactions from. Defaults to all foundational chains. | | `addresses` | string | No | - | Comma separated list of addresses for which transactions are fetched. | | `limit` | integer | No | max | Number of transactions to return per page, up to the default max of 100 items. | | `before` | string | No | - | Pagination cursor pointing to fetch transactions before a certain point. | | `after` | string | No | - | Pagination cursor pointing to fetch transactions after a certain point. | | `with-logs` | boolean | No | - | Whether to include raw logs in the response. | | `with-decoded-logs` | boolean | No | - | Whether to include decoded logs in the response. | | `with-internal` | boolean | No | - | Whether to include internal transfers/transactions. | | `with-state` | boolean | No | - | Whether to include all transaction state changes with before and after values. | | `with-input-data` | boolean | No | - | Whether to include the transaction's input data such as the Method ID. | | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, `GBP`, `BTC` and `ETH`. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | Timestamp for when the data was last updated. | | `cursor_before` | `string` | Pagination cursor pointing to the previous page. | | `cursor_after` | `string` | Pagination cursor pointing to the next page. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `items` | `array` | List of transactions returned by the API. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_height` | `integer` | The height of the block. | | `block_signed_at` | `string` | The signed block timestamp in UTC. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from blocks that are reorged. | | `tx_hash` | `string` | The transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `miner_address` | `string` | The address of the miner who mined the block. | | `from_address` | `string` | | | `to_address` | `string` | The recipient's wallet address. | | `value` | `string` | b;The value of the transaction in wei. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_offered` | `integer` | The gas offered for the transaction. | | `gas_spent` | `integer` | The gas actually spent by the transaction. | | `gas_price` | `integer` | The gas price at the time of this tx in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `successful` | `boolean` | Indicated whether the transaction was successful or failed. | | `chain_id` | `string` | The chain ID of the blockchain where the transaction occurred. | | `chain_name` | `string` | The chain name of the blockchain where the transaction occurred. | | `explorers` | `array` | The block explorer links for this transaction. | | `log_events` | `array` | Event logs generated by the transaction. | | `internal_transfers` | `array` | List of internal transfers/transactions associated with the wallet address. | | `state_changes` | `array` | List of state changes with before and after values and balances for involved contract and wallet addresses. | | `input_data` | `object` | Object with a transaction's input data such as the Method ID. | **Content:** **Credit Cost:** 0.25 per item **Processing:** Realtime > **Note:** Base cost is `0.1` credits (e.g. requests that return with status `200` but no items). Calls without logs cost `0.1` credits/item. Calls `with-logs` costs `0.2` credits/item. Calls `with-decoded-logs` costs `0.25` credits/item. The following tracing features each cost `0.05` per transaction that they are available for: - `with-internal` - includes internal transfers/transactions. - `with-state` - includes all transaction state changes with before and after values. - `with-input-data` - includes the transaction's input data such as the Method ID. Currently, tracing features are supported on the following chains: - `eth-mainnet` This Multichain & Multiaddress Transactions API is supported across all EVM chains. When no chains are specified, the [Foundational Chains](https://goldrush.dev/chains) are passed as default. Domain names (e.g. `demo.eth`) are not supported. --- ## 13. Check ownership in NFT collection for specific token **Path:** api-reference/foundational-api/nft/check-ownership-in-nft-collection-token **Operation Identity:** - Operation ID: `checkOwnershipInNftForSpecificTokenId` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/token/{tokenId}/` **Metadata:** ```yaml title: Check ownership in NFT collection for specific token openapi: GET /v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/token/{tokenId}/ category: nft api_type: REST operation_identity: {"operation_id":"checkOwnershipInNftForSpecificTokenId","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/token/{tokenId}/"} endpoint_role: specialized credit_cost: 1 per call chains: ["eth-mainnet","matic-mainnet","base-mainnet","bsc-mainnet","gnosis-mainnet","optimism-mainnet"] use_cases: [] beta: false related: ["get-nfts-for-address","check-ownership-in-nft-collection"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `collectionContract` | string | Yes | The requested collection address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `tokenId` | string | Yes | The requested token ID. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `address` | `string` | The requested address. | | `collection` | `string` | The requested collection. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. Supported on all Foundational Chains. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `token_id` | `string` | b;The token's id. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `last_transfered_at` | `string` | | | `balance` | `string` | b;Nft balance. | | `balance_24h` | `string` | | | `type` | `string` | | | `nft_data` | `object` | | **Content:** **Credit Cost:** 1 per call **Processing:** Batch ### Related guides How to Create an NFT Allowlist (AKA Whitelist) --- ## 14. Check ownership in NFT collection **Path:** api-reference/foundational-api/nft/check-ownership-in-nft-collection **Operation Identity:** - Operation ID: `checkOwnershipInNft` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/` **Metadata:** ```yaml title: Check ownership in NFT collection openapi: GET /v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/ category: nft api_type: REST operation_identity: {"operation_id":"checkOwnershipInNft","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/"} endpoint_role: specialized credit_cost: 1 per call chains: ["eth-mainnet","matic-mainnet","base-mainnet","optimism-mainnet","bsc-mainnet","gnosis-mainnet"] use_cases: [] beta: false related: ["get-nfts-for-address","check-ownership-in-nft-collection-token"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `collectionContract` | string | Yes | The requested collection address. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `traits-filter` | string | No | - | Filters NFTs based on a specific trait. If this filter is used, the API will return all NFTs with the specified trait. Must be used with "values-filter", is case-sensitive, and requires proper URL encoding. | | `values-filter` | string | No | - | Filters NFTs based on a specific trait value. If this filter is used, the API will return all NFTs with the specified trait value. Must be used with "traits-filter", is case-sensitive, and requires proper URL encoding. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `address` | `string` | The requested address. | | `collection` | `string` | The requested collection. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. Supported on all Foundational Chains. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `token_id` | `string` | b;The token's id. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `last_transfered_at` | `string` | | | `balance` | `string` | b;Nft balance. | | `balance_24h` | `string` | | | `type` | `string` | | | `nft_data` | `object` | | **Content:** **Credit Cost:** 1 per call **Processing:** Batch ### Related guides How to Create an NFT Allowlist (AKA Whitelist) --- ## 15. Get NFTs for address **Path:** api-reference/foundational-api/nft/get-nfts-for-address **Operation Identity:** - Operation ID: `getNftsForAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/balances_nft/` **Metadata:** ```yaml title: Get NFTs for address openapi: GET /v1/{chainName}/address/{walletAddress}/balances_nft/ category: nft api_type: REST operation_identity: {"operation_id":"getNftsForAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/balances_nft/"} endpoint_role: primary credit_cost: 1 per call chains: ["eth-mainnet","matic-mainnet","bsc-mainnet","arbitrum-mainnet","optimism-mainnet","base-mainnet","mantle-mainnet","linea-mainnet","zksync-mainnet","gnosis-mainnet","scroll-mainnet","apechain-mainnet"] use_cases: [] beta: false related: ["check-ownership-in-nft-collection","check-ownership-in-nft-collection-token"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `no-spam` | boolean | No | - | If `true`, the suspected spam tokens are removed. Supported on all Foundational Chains. | | `no-nft-asset-metadata` | boolean | No | - | If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `is_spam` | `boolean` | Denotes whether the token is suspected spam. Supported on all Foundational Chains. | | `last_transfered_at` | `string` | The timestamp when the token was transferred. | | `block_height` | `integer` | The height of the block. | | `balance` | `string` | b;The asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `balance_24h` | `string` | b;The 24h asset balance. Use `contract_decimals` to scale this balance for display purposes. | | `type` | `string` | | | `floor_price_quote` | `number` | The current floor price converted to fiat in `quote-currency`. The floor price is determined by the last minimum sale price within the last 30 days across all the supported markets where the collection is sold on. | | `pretty_floor_price_quote` | `string` | A prettier version of the floor price quote for rendering purposes. | | `floor_price_native_quote` | `number` | The current floor price in native currency. The floor price is determined by the last minimum sale price within the last 30 days across all the supported markets where the collection is sold on. | | `nft_data` | `array` | | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 16. Get token approvals for address **Path:** api-reference/foundational-api/security/get-token-approvals-for-address **Operation Identity:** - Operation ID: `getApprovals` - Method: `GET` - Endpoint Path: `/v1/{chainName}/approvals/{walletAddress}/` - TypeScript SDK: `SecurityService.getApprovals()` **Metadata:** ```yaml title: Get token approvals for address openapi: GET /v1/{chainName}/approvals/{walletAddress}/ category: security api_type: REST operation_identity: {"operation_id":"getApprovals","method":"GET","path":"/v1/{chainName}/approvals/{walletAddress}/","sdk_service":"SecurityService","sdk_method":"getApprovals"} endpoint_role: primary credit_cost: 2 per call chains: all use_cases: [] beta: false related: [] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `token_address` | `string` | The address for the token that has approvals. | | `token_address_label` | `string` | The name for the token that has approvals. | | `ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `logo_url` | `string` | The contract logo URL. | | `quote_rate` | `number` | The exchange rate for the requested quote currency. | | `balance` | `string` | b;Wallet balance of the token. | | `balance_quote` | `number` | Value of the wallet balance of the token. | | `pretty_balance_quote` | `string` | A prettier version of the quote for rendering purposes. | | `value_at_risk` | `string` | Total amount at risk across all spenders. | | `value_at_risk_quote` | `number` | Value of total amount at risk across all spenders. | | `pretty_value_at_risk_quote` | `string` | A prettier version of the quote for rendering purposes. | | `spenders` | `array` | Contracts with non-zero approvals for this token. | **Content:** **Credit Cost:** 2 per call **Processing:** Realtime --- ## 17. Get a transaction **Path:** api-reference/foundational-api/transactions/get-a-transaction **Operation Identity:** - Operation ID: `getTransaction` - Method: `GET` - Endpoint Path: `/v1/{chainName}/transaction_v2/{txHash}/` - TypeScript SDK: `TransactionService.getTransaction()` **Metadata:** ```yaml title: Get a transaction openapi: GET /v1/{chainName}/transaction_v2/{txHash}/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransaction","method":"GET","path":"/v1/{chainName}/transaction_v2/{txHash}/","sdk_service":"TransactionService","sdk_method":"getTransaction"} endpoint_role: primary credit_cost: 0.1 per call chains: all use_cases: [] beta: false related: ["get-transaction-summary-for-address","get-earliest-transactions-for-address-v3","get-recent-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `txHash` | string | Yes | The transaction hash. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | | `with-internal` | boolean | No | - | Whether to include internal transfers/transactions. | | `with-state` | boolean | No | - | Whether to include all transaction state changes with before and after values. | | `with-input-data` | boolean | No | - | Whether to include the transaction's input data such as the Method ID. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | | `internal_transfers` | `array` | List of internal transfers/transactions associated with the wallet address. | | `state_changes` | `array` | List of state changes with before and after values and balances for involved contract and wallet addresses. | | `input_data` | `object` | Object with a transaction's input data such as the Method ID. | **Content:** **Credit Cost:** 0.1 per call **Processing:** Realtime > **Note:** Base cost is `0.1` credits (e.g. requests that return with status `200` but no items). Calls with `no-logs` cost `0.05` credits/item. The following tracing features each cost `0.05` credits where available on [Foundational Chains](https://goldrush.dev/chains): - `with-internal` - includes internal transfers/transactions. - `with-state` - includes all transaction state changes with before and after values. - `with-input-data` - includes the transaction’s input data such as the Method ID. Currently, tracing features are supported on the following chains: - `eth-mainnet` ### Related guides Comparing GoldRush's Transactions API to RPC Providers How to Get Transaction History for an Address on Ethereum --- ## 18. Get all transactions in a block by page (v3) **Path:** api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page **Operation Identity:** - Operation ID: `getTransactionsForBlockByPage` - Method: `GET` - Endpoint Path: `/v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/` **Metadata:** ```yaml title: Get all transactions in a block by page (v3) openapi: GET /v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransactionsForBlockByPage","method":"GET","path":"/v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/"} endpoint_role: specialized credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `blockHeight` | integer | Yes | The requested block height. Also accepts `latest` to get latest block. | | `page` | integer | Yes | The requested 0-indexed page number. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `links` | `object` | | | `items` | `array` | List of response items. | ### Link Fields | Field | Type | Description | |-------|------|-------------| | `prev` | `string` | URL link to the next page. | | `next` | `string` | URL link to the previous page. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime --- ## 19. Get all transactions in a block (v3) **Path:** api-reference/foundational-api/transactions/get-all-transactions-in-a-block **Operation Identity:** - Operation ID: `getTransactionsForBlockHash` - Method: `GET` - Endpoint Path: `/v1/{chainName}/block_hash/{blockHash}/transactions_v3/` **Metadata:** ```yaml title: Get all transactions in a block (v3) openapi: GET /v1/{chainName}/block_hash/{blockHash}/transactions_v3/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransactionsForBlockHash","method":"GET","path":"/v1/{chainName}/block_hash/{blockHash}/transactions_v3/"} endpoint_role: specialized credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `blockHash` | string | Yes | The requested block hash. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime ### Related guides Introducing Transactions V3 APIs Comparing GoldRush's Transactions API to RPC Providers How to Track Wallets or Transactions with the GoldRush API How to Get the Number of Transactions in a Block How to Get All Historical Transactions in a Block --- ## 20. Get earliest transactions for address (v3) **Path:** api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3 **Operation Identity:** - Operation ID: `getEarliestTimeBucketTransactionsForAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/bulk/transactions/{walletAddress}/` **Metadata:** ```yaml title: Get earliest transactions for address (v3) openapi: GET /v1/{chainName}/bulk/transactions/{walletAddress}/ category: transactions api_type: REST operation_identity: {"operation_id":"getEarliestTimeBucketTransactionsForAddress","method":"GET","path":"/v1/{chainName}/bulk/transactions/{walletAddress}/"} endpoint_role: specialized credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-recent-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `complete` | `boolean` | | | `current_bucket` | `integer` | The current bucket of the response. | | `links` | `object` | | | `items` | `array` | List of response items. | ### Link Fields | Field | Type | Description | |-------|------|-------------| | `prev` | `string` | URL link to the next page. | | `next` | `string` | URL link to the previous page. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** Returns the same results as the first timebucket for an address in the [Get recent transactions](/docs/api/transactions/get-recent-transactions-for-address-v3/) endpoint. Requests that return status 200 and no data cost 0.1 credits. Enabling `no-logs` reduces request cost to 0.05 per item. ### Related guides Introducing Transactions V3 APIs Comparing GoldRush's Transactions API to RPC Providers How to Get Transaction History for an Address on Ethereum --- ## 21. Get paginated transactions for address (v3) **Path:** api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3 **Operation Identity:** - Operation ID: `getTransactionsForAddressV3` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/` **Metadata:** ```yaml title: Get paginated transactions for address (v3) openapi: GET /v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransactionsForAddressV3","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/"} endpoint_role: primary credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `page` | integer | Yes | The requested page, 0-indexed. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | | `block-signed-at-asc` | boolean | No | - | Sort the transactions in ascending chronological order. By default, it's set to `false` and returns transactions in descending chronological order. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `current_page` | `integer` | The current page of the response. | | `links` | `object` | | | `items` | `array` | List of response items. | ### Link Fields | Field | Type | Description | |-------|------|-------------| | `prev` | `string` | URL link to the next page. | | `next` | `string` | URL link to the previous page. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** This endpoint returns paginated transactions, starting with the earliest transactions on page 0. For the most recent transactions, refer to the [Get recent transactions for address (v3)](https://www.covalenthq.com/docs/api/transactions/get-recent-transactions-for-address-v3/) endpoint. Requests that return status 200 and no data cost 0.1 credits. Enabling `no-logs` reduces request cost to 0.05 per item. ### Related guides Introducing Transactions V3 APIs Comparing GoldRush's Transactions API to RPC Providers How to Get Transaction History for an Address on Ethereum --- ## 22. Get recent transactions for address (v3) **Path:** api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3 **Operation Identity:** - Operation ID: `getRecentTransactionsForAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/transactions_v3/` **Metadata:** ```yaml title: Get recent transactions for address (v3) openapi: GET /v1/{chainName}/address/{walletAddress}/transactions_v3/ category: transactions api_type: REST operation_identity: {"operation_id":"getRecentTransactionsForAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/transactions_v3/"} endpoint_role: primary credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | | `block-signed-at-asc` | boolean | No | - | Sort the transactions in ascending chronological order. By default, it's set to `false` and returns transactions in descending chronological order. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `current_page` | `integer` | The current page of the response. | | `links` | `object` | | | `items` | `array` | List of response items. | ### Link Fields | Field | Type | Description | |-------|------|-------------| | `prev` | `string` | URL link to the next page. | | `next` | `string` | URL link to the previous page. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** Requests that return status 200 and no data cost 0.1 credits. Enabling `no-logs` reduces request cost to 0.05 per item. ### Related guides Introducing Transactions V3 APIs Comparing GoldRush's Transactions API to RPC Providers --- ## 23. Get bulk time bucket transactions for address (v3) **Path:** api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3 **Operation Identity:** - Operation ID: `getTimeBucketTransactionsForAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/` - TypeScript SDK: `TransactionService.getTimeBucketTransactionsForAddress()` **Metadata:** ```yaml title: Get bulk time bucket transactions for address (v3) openapi: GET /v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/ category: transactions api_type: REST operation_identity: {"operation_id":"getTimeBucketTransactionsForAddress","method":"GET","path":"/v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/","sdk_service":"TransactionService","sdk_method":"getTimeBucketTransactionsForAddress"} endpoint_role: specialized credit_cost: 0.1 per item chains: all use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | | `timeBucket` | integer | Yes | The 0-indexed 15-minute time bucket. E.g. 27 Feb 2023 05:23 GMT = 1677475383 (Unix time). 1677475383/900=1863861 timeBucket. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `no-logs` | boolean | No | - | Omit log events. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `complete` | `boolean` | | | `current_bucket` | `integer` | The current bucket of the response. | | `links` | `object` | | | `items` | `array` | List of response items. | ### Link Fields | Field | Type | Description | |-------|------|-------------| | `prev` | `string` | URL link to the next page. | | `next` | `string` | URL link to the previous page. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. Use it to remove transactions from re-org-ed blocks. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `successful` | `boolean` | Indicates whether a transaction failed or succeeded. | | `from_address` | `string` | The sender's wallet address. | | `miner_address` | `string` | The address of the miner. | | `to_address` | `string` | The receiver's wallet address. | | `value` | `string` | b;The value attached to this tx. | | `value_quote` | `number` | The value attached in `quote-currency` to this tx. | | `pretty_value_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_metadata` | `object` | The requested chain native gas token metadata. | | `gas_offered` | `integer` | | | `gas_spent` | `integer` | The gas spent for this tx. | | `gas_price` | `integer` | The gas price at the time of this tx. | | `fees_paid` | `string` | b;The total transaction fees (`gas_price` * `gas_spent`) paid for this tx, denoted in wei. | | `gas_quote` | `number` | The gas spent in `quote-currency` denomination. | | `pretty_gas_quote` | `string` | A prettier version of the quote for rendering purposes. | | `gas_quote_rate` | `number` | The native gas exchange rate for the requested `quote-currency`. | | `explorers` | `array` | The explorer links for this transaction. | | `log_events` | `array` | The log events. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** Requests that return status 200 and no data cost 0.1 credits. Enabling `no-logs` reduces request cost to 0.05 per item. ### Related guides Scaling Transactions API with Time Buckets Introducing Transactions V3 APIs Comparing GoldRush's Transactions API to RPC Providers --- ## 24. Get transaction summary for address **Path:** api-reference/foundational-api/transactions/get-transaction-summary-for-address **Operation Identity:** - Operation ID: `getTransactionSummary` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/transactions_summary/` - TypeScript SDK: `TransactionService.getTransactionSummary()` **Metadata:** ```yaml title: Get transaction summary for address openapi: GET /v1/{chainName}/address/{walletAddress}/transactions_summary/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransactionSummary","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/transactions_summary/","sdk_service":"TransactionService","sdk_method":"getTransactionSummary"} endpoint_role: primary credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-a-transaction","get-earliest-transactions-for-address-v3","get-recent-transactions-for-address-v3"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `with-gas` | boolean | No | - | Include gas summary details. Response times may be impacted for wallets with large number of transactions. | | `with-transfer-count` | boolean | No | - | Represents the total count of ERC-20 token movement events, including `Transfer`, `Deposit` and `Withdraw`. Response times may be impacted for wallets with large number of transactions. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `address` | `string` | The requested address. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `total_count` | `integer` | The total number of transactions. | | `transfer_count` | `integer` | Represents the total count of ERC-20 token movement events, including `Transfer`, `Deposit` and `Withdraw`. | | `earliest_transaction` | `object` | The earliest transaction detected. | | `latest_transaction` | `object` | The latest transaction detected. | | `gas_summary` | `object` | The gas summary for the transactions. | **Content:** **Credit Cost:** 1 per call **Processing:** Batch > **Note:** - Base cost is `1` credit. - Using `with-gas` is an additional `1` credit. - Using `with-transfer-count` is an additional `3` credits. ### Related guides Building Web3 Wallets (Part 7) - Multi-Chain Wallet Activity Summary Comparing GoldRush's Transactions API to RPC Providers How to Get Transaction History for an Address on Ethereum --- ## 25. Get Bitcoin transactions for non-HD address **Path:** api-reference/foundational-api/transactions/get-transactions-for-bitcoin-address **Operation Identity:** - Operation ID: `getTransactionsForBtcAddress` - Method: `GET` - Endpoint Path: `/v1/cq/covalent/app/bitcoin/transactions/` - TypeScript SDK: `BitcoinService.getTransactionsForBtcAddress()` **Metadata:** ```yaml title: Get Bitcoin transactions for non-HD address openapi: GET /v1/cq/covalent/app/bitcoin/transactions/ category: transactions api_type: REST operation_identity: {"operation_id":"getTransactionsForBtcAddress","method":"GET","path":"/v1/cq/covalent/app/bitcoin/transactions/","sdk_service":"BitcoinService","sdk_method":"getTransactionsForBtcAddress"} endpoint_role: primary credit_cost: 0.1 per item chains: ["btc-mainnet"] use_cases: [] beta: false related: ["get-a-transaction","get-transaction-summary-for-address","get-earliest-transactions-for-address-v3"] ``` ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `address` | string | No | - | The bitcoin address to query. | | `page-size` | integer | No | 100 | Number of items per page. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `chain_id` | `integer` | The requested chain ID eg: `20090103`. | | `chain_name` | `string` | The requested chain name eg: `btc-mainnet`. | | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. | | `tx_hash` | `string` | The requested transaction hash. | | `tx_idx` | `integer` | The position index of the tx in the block. | | `type` | `string` | Either 'input' as the sender or 'output' as the receiver of btc. | | `address` | `string` | The wallet address. | | `value` | `string` | b;The value attached to this tx in satoshi. | | `quote` | `number` | The value attached to this tx in USD. | | `quote_rate` | `number` | The value token exchange rate in USD. | | `fees_paid` | `string` | b;The total transaction fees denoted in satoshi. | | `gas_quote` | `number` | The gas spent in USD. | | `gas_quote_rate` | `number` | The native gas token exchange rate in USD. | | `coinbase` | `boolean` | Indicates if this is a coinbase tx where btc is rewarded to a miner for validating the block. | | `locktime` | `integer` | The earliest Unix timestamp or block height at which the tx is valid and can be included. Is `0` if no restriction. | | `weight` | `integer` | A measure that reflects impact on the block size limit. Used to determine fees. | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 0.1 per item **Processing:** Realtime > **Note:** Only supports non-HD bitcoin addresses. --- ## 26. Get a block **Path:** api-reference/foundational-api/utility/get-a-block **Operation Identity:** - Operation ID: `getBlock` - Method: `GET` - Endpoint Path: `/v1/{chainName}/block_v2/{blockHeight}/` - TypeScript SDK: `BaseService.getBlock()` **Metadata:** ```yaml title: Get a block openapi: GET /v1/{chainName}/block_v2/{blockHeight}/ category: base api_type: REST operation_identity: {"operation_id":"getBlock","method":"GET","path":"/v1/{chainName}/block_v2/{blockHeight}/","sdk_service":"BaseService","sdk_method":"getBlock"} endpoint_role: specialized credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-block-heights","get-logs","get-log-events-by-contract-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `blockHeight` | string | Yes | The block height or `latest` for the latest block available. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_hash` | `string` | The hash of the block. | | `signed_at` | `string` | The block signed timestamp in UTC. | | `height` | `integer` | The block height. | | `block_parent_hash` | `string` | The parent block hash. | | `extra_data` | `string` | Extra data written to the block. | | `miner_address` | `string` | The address of the miner. | | `mining_cost` | `integer` | The associated mining cost. | | `gas_used` | `integer` | The associated gas used. | | `gas_limit` | `integer` | The associated gas limit. | | `transactions_link` | `string` | The link to the related tx by block endpoint. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 27. Get all chain statuses **Path:** api-reference/foundational-api/utility/get-all-chain-statuses **Operation Identity:** - Operation ID: `getAllChainStatus` - Method: `GET` - Endpoint Path: `/v1/chains/status/` - TypeScript SDK: `BaseService.getAllChainStatus()` **Metadata:** ```yaml title: Get all chain statuses openapi: GET /v1/chains/status/ category: base api_type: REST operation_identity: {"operation_id":"getAllChainStatus","method":"GET","path":"/v1/chains/status/","sdk_service":"BaseService","sdk_method":"getAllChainStatus"} endpoint_role: specialized credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `name` | `string` | The chain name eg: `eth-mainnet`. | | `chain_id` | `string` | The requested chain ID eg: `1`. | | `is_testnet` | `boolean` | True if the chain is a testnet. | | `logo_url` | `string` | A png logo url for the chain. | | `black_logo_url` | `string` | A black png logo url for the chain. | | `white_logo_url` | `string` | A white png logo url for the chain. | | `is_appchain` | `boolean` | True if the chain is an AppChain. | | `chain_tip_height` | `integer` | The height of the lastest block available. | | `chain_tip_signed_at` | `string` | The signed timestamp of lastest block available. | | `has_data` | `boolean` | True if the chain has data and ready for querying. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 28. Get all chains **Path:** api-reference/foundational-api/utility/get-all-chains **Operation Identity:** - Operation ID: `getAllChains` - Method: `GET` - Endpoint Path: `/v1/chains/` - TypeScript SDK: `BaseService.getAllChains()` **Metadata:** ```yaml title: Get all chains openapi: GET /v1/chains/ category: base api_type: REST operation_identity: {"operation_id":"getAllChains","method":"GET","path":"/v1/chains/","sdk_service":"BaseService","sdk_method":"getAllChains"} endpoint_role: specialized credit_cost: 0.01 per call chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `name` | `string` | The chain name eg: `eth-mainnet`. | | `chain_id` | `string` | The requested chain ID eg: `1`. | | `is_testnet` | `boolean` | True if the chain is a testnet. | | `db_schema_name` | `string` | Schema name to use for direct SQL. | | `label` | `string` | The chains label eg: `Ethereum Mainnet`. | | `category_label` | `string` | The category label eg: `Ethereum`. | | `logo_url` | `string` | A png logo url for the chain. | | `black_logo_url` | `string` | A black png logo url for the chain. | | `white_logo_url` | `string` | A white png logo url for the chain. | | `color_theme` | `object` | The color theme for the chain. | | `is_appchain` | `boolean` | True if the chain is an AppChain. | | `appchain_of` | `object` | The ChainItem the appchain is a part of. | **Content:** **Credit Cost:** 0.01 per call **Processing:** Realtime --- ## 29. Get block heights **Path:** api-reference/foundational-api/utility/get-block-heights **Operation Identity:** - Operation ID: `getBlockHeights` - Method: `GET` - Endpoint Path: `/v1/{chainName}/block_v2/{startDate}/{endDate}/` - TypeScript SDK: `BaseService.getBlockHeights()` **Metadata:** ```yaml title: Get block heights openapi: GET /v1/{chainName}/block_v2/{startDate}/{endDate}/ category: base api_type: REST operation_identity: {"operation_id":"getBlockHeights","method":"GET","path":"/v1/{chainName}/block_v2/{startDate}/{endDate}/","sdk_service":"BaseService","sdk_method":"getBlockHeights"} endpoint_role: specialized credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-a-block","get-logs","get-log-events-by-contract-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `startDate` | string | Yes | The start date in YYYY-MM-DD format. | | `endDate` | string | Yes | The end date in YYYY-MM-DD format or `latest` for the latest block available. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `page-size` | integer | No | 100 | Number of items per page. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_hash` | `string` | The hash of the block. | | `signed_at` | `string` | The block signed timestamp in UTC. | | `height` | `integer` | The block height. | | `block_parent_hash` | `string` | The parent block hash. | | `extra_data` | `string` | Extra data written to the block. | | `miner_address` | `string` | The address of the miner. | | `mining_cost` | `integer` | The associated mining cost. | | `gas_used` | `integer` | The associated gas used. | | `gas_limit` | `integer` | The associated gas limit. | | `transactions_link` | `string` | The link to the related tx by block endpoint. | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime --- ## 30. Get gas prices **Path:** api-reference/foundational-api/utility/get-gas-prices **Operation Identity:** - Operation ID: `getGasPrices` - Method: `GET` - Endpoint Path: `/v1/{chainName}/event/{eventType}/gas_prices/` - TypeScript SDK: `BaseService.getGasPrices()` **Metadata:** ```yaml title: Get gas prices openapi: GET /v1/{chainName}/event/{eventType}/gas_prices/ category: base api_type: REST operation_identity: {"operation_id":"getGasPrices","method":"GET","path":"/v1/{chainName}/event/{eventType}/gas_prices/","sdk_service":"BaseService","sdk_method":"getGasPrices"} endpoint_role: primary credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `eventType` | string | Yes | The desired event type to retrieve gas prices for. Supports `erc20` transfer events, `uniswapv3` swap events and `nativetokens` transfers. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `event_type` | `string` | The requested event type. | | `gas_quote_rate` | `number` | The exchange rate for the requested quote currency. | | `base_fee` | `string` | b;The lowest gas fee for the latest block height. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `gas_price` | `string` | The average gas price, in WEI, for the time interval. | | `gas_spent` | `string` | The average gas spent for the time interval. | | `gas_quote` | `number` | The average gas spent in `quote-currency` denomination for the time interval. | | `other_fees` | `object` | Other fees, when applicable. For example: OP chain L1 fees. | | `total_gas_quote` | `number` | The sum of the L1 and L2 gas spent, in quote-currency, for the specified time interval. | | `pretty_total_gas_quote` | `string` | A prettier version of the total average gas spent, in quote-currency, for the specified time interval, for rendering purposes. | | `interval` | `string` | The specified time interval. | **Content:** **Credit Cost:** 1 per call **Processing:** Batch > **Note:** Currently support these event types: `erc20` token transfers, `nativetokens` transfer, and `uniswapv3` swap events. ### Related guides How to Fetch Onchain Gas Prices and Estimate Gas Costs --- ## 31. Get historical token prices **Path:** api-reference/foundational-api/utility/get-historical-token-prices **Operation Identity:** - Operation ID: `getTokenPrices` - Method: `GET` - Endpoint Path: `/v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/` - TypeScript SDK: `PricingService.getTokenPrices()` **Metadata:** ```yaml title: Get historical token prices openapi: GET /v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/ category: pricing api_type: REST operation_identity: {"operation_id":"getTokenPrices","method":"GET","path":"/v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/","sdk_service":"PricingService","sdk_method":"getTokenPrices"} endpoint_role: primary credit_cost: 1 per call chains: all use_cases: [] beta: false related: ["get-pool-spot-prices"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `quoteCurrency` | string | Yes | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | | `contractAddress` | string | Yes | Contract address for the token. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. Supports multiple contract addresses separated by commas. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `from` | string | No | - | The start day of the historical price range (YYYY-MM-DD). | | `to` | string | No | - | The end day of the historical price range (YYYY-MM-DD). | | `prices-at-asc` | boolean | No | - | Sort the prices in chronological ascending order. By default, it's set to `false` and returns prices in chronological descending order. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `contract_name` | `string` | The string returned by the `name()` method. | | `contract_ticker_symbol` | `string` | The ticker symbol for this contract. This field is set by a developer and non-unique across a network. | | `contract_address` | `string` | Use the relevant `contract_address` to lookup prices, logos, token transfers, etc. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `update_at` | `string` | | | `quote_currency` | `string` | The requested quote currency eg: `USD`. | | `logo_urls` | `object` | The contract logo URLs. | | `items` | `array` | List of response items. | ### Logo Url Fields | Field | Type | Description | |-------|------|-------------| | `token_logo_url` | `string` | The token logo URL. | | `protocol_logo_url` | `string` | The protocol logo URL. | | `chain_logo_url` | `string` | The chain logo URL. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `date` | `string` | The date of the price capture. | | `price` | `number` | The price in the requested `quote-currency`. | | `pretty_price` | `string` | A prettier version of the price for rendering purposes. | **Content:** **Credit Cost:** 1 per call **Processing:** Batch > **Note:** Supports a comma separated list of token contract addresses. If no date range is provided, the spot price (with a 5 minute refresh) is provided. --- ## 32. Get log events by contract address **Path:** api-reference/foundational-api/utility/get-log-events-by-contract-address **Operation Identity:** - Operation ID: `getLogEventsByAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/events/address/{contractAddress}/` - TypeScript SDK: `BaseService.getLogEventsByAddress()` **Metadata:** ```yaml title: Get log events by contract address openapi: GET /v1/{chainName}/events/address/{contractAddress}/ category: base api_type: REST operation_identity: {"operation_id":"getLogEventsByAddress","method":"GET","path":"/v1/{chainName}/events/address/{contractAddress}/","sdk_service":"BaseService","sdk_method":"getLogEventsByAddress"} endpoint_role: specialized credit_cost: 0.01 per item chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `contractAddress` | string | Yes | The requested contract address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `starting-block` | integer | No | - | The first block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `ending-block` | string | No | - | The last block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `page-size` | integer | No | 100 | Number of items per page. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `log_offset` | `integer` | The offset is the position of the log entry within an event log. | | `tx_hash` | `string` | The requested transaction hash. | | `raw_log_topics` | `array` | The log topics in raw data. | | `sender_contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `sender_name` | `string` | The name of the sender. | | `sender_contract_ticker_symbol` | `string` | | | `sender_address` | `string` | The address of the sender. | | `sender_logo_url` | `string` | The contract logo URL. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `sender_factory_address` | `string` | The address of the deployed UniswapV2 like factory contract for this DEX. | | `raw_log_data` | `string` | The log events in raw. | | `decoded` | `object` | The decoded item. | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 0.01 per item **Processing:** Realtime --- ## 33. Get log events by topic hash(es) **Path:** api-reference/foundational-api/utility/get-log-events-by-topic-hash **Operation Identity:** - Operation ID: `getLogEventsByTopicHash` - Method: `GET` - Endpoint Path: `/v1/{chainName}/events/topics/{topicHash}/` - TypeScript SDK: `BaseService.getLogEventsByTopicHash()` **Metadata:** ```yaml title: Get log events by topic hash(es) openapi: GET /v1/{chainName}/events/topics/{topicHash}/ category: base api_type: REST operation_identity: {"operation_id":"getLogEventsByTopicHash","method":"GET","path":"/v1/{chainName}/events/topics/{topicHash}/","sdk_service":"BaseService","sdk_method":"getLogEventsByTopicHash"} endpoint_role: specialized credit_cost: 0.01 per item chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `topicHash` | string | Yes | The endpoint will return event logs that contain this topic hash. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `starting-block` | integer | No | - | The first block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `ending-block` | string | No | - | The last block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `secondary-topics` | string | No | - | Additional topic hash(es) to filter on - padded & unpadded address fields are supported. Separate multiple topics with a comma. | | `page-size` | integer | No | 100 | Number of items per page. Omitting this parameter defaults to 100. | | `page-number` | integer | No | - | 0-indexed page number to begin pagination. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | | `pagination` | `object` | Pagination metadata. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `log_offset` | `integer` | The offset is the position of the log entry within an event log. | | `tx_hash` | `string` | The requested transaction hash. | | `raw_log_topics` | `array` | The log topics in raw data. | | `sender_contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `sender_name` | `string` | The name of the sender. | | `sender_contract_ticker_symbol` | `string` | | | `sender_address` | `string` | The address of the sender. | | `sender_logo_url` | `string` | The contract logo URL. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `sender_factory_address` | `string` | The address of the deployed UniswapV2 like factory contract for this DEX. | | `raw_log_data` | `string` | The log events in raw. | | `decoded` | `object` | The decoded item. | ### Pagination Fields | Field | Type | Description | |-------|------|-------------| | `has_more` | `boolean` | True if there is another page. | | `page_number` | `integer` | The requested page number. | | `page_size` | `integer` | The requested number of items on the current page. | | `total_count` | `integer` | The total number of items across all pages for this request. | **Content:** **Credit Cost:** 0.01 per item **Processing:** Realtime --- ## 34. Get logs **Path:** api-reference/foundational-api/utility/get-logs **Operation Identity:** - Operation ID: `getLogs` - Method: `GET` - Endpoint Path: `/v1/{chainName}/events/` - TypeScript SDK: `BaseService.getLogs()` **Metadata:** ```yaml title: Get logs openapi: GET /v1/{chainName}/events/ category: base api_type: REST operation_identity: {"operation_id":"getLogs","method":"GET","path":"/v1/{chainName}/events/","sdk_service":"BaseService","sdk_method":"getLogs"} endpoint_role: primary credit_cost: 0.01 per item chains: all use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-log-events-by-contract-address"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `starting-block` | integer | No | - | The first block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `ending-block` | string | No | - | The last block to retrieve log events with. Accepts decimals, hexadecimals, or the strings `earliest` and `latest`. | | `address` | string | No | - | The address of the log events sender contract. | | `topics` | string | No | - | The topic hash(es) to retrieve logs with. | | `block-hash` | string | No | - | The block hash to retrieve logs for. | | `skip-decode` | boolean | No | - | Omit decoded log events. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `chain_tip_height` | `integer` | The latest block height of the blockchain at the time this response was provided. | | `chain_tip_signed_at` | `string` | The timestamp of the latest signed block at the time this response was provided. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `block_signed_at` | `string` | The block signed timestamp in UTC. | | `block_height` | `integer` | The height of the block. | | `block_hash` | `string` | The hash of the block. | | `tx_offset` | `integer` | The offset is the position of the tx in the block. | | `log_offset` | `integer` | The offset is the position of the log entry within an event log. | | `tx_hash` | `string` | The requested transaction hash. | | `raw_log_topics` | `array` | The log topics in raw data. | | `sender_contract_decimals` | `integer` | Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. | | `sender_name` | `string` | The name of the sender. | | `sender_contract_ticker_symbol` | `string` | The ticker symbol for the sender. This field is set by a developer and non-unique across a network. | | `sender_address` | `string` | The address of the sender. | | `supports_erc` | `array` | A list of supported standard ERC interfaces, eg: `ERC20` and `ERC721`. | | `sender_logo_url` | `string` | The contract logo URL. | | `sender_factory_address` | `string` | The address of the deployed UniswapV2 like factory contract for this DEX. | | `raw_log_data` | `string` | The log events in raw. | | `decoded` | `object` | The decoded item. | **Content:** **Credit Cost:** 0.01 per item **Processing:** Realtime > **Note:** Limits: - For a block range of 2,000 blocks or less, the response will include all logs within the range. - For a block range greater than 2,000 blocks:- The response will include up to 10,000 logs. - If the number of logs exceeds 10,000, no logs will be included in the response. Instead, the response will contain a suggested range within the `info` object, including a link and message. --- ## 35. Get pool spot prices **Path:** api-reference/foundational-api/utility/get-pool-spot-prices **Operation Identity:** - Operation ID: `getPoolSpotPrices` - Method: `GET` - Endpoint Path: `/v1/pricing/spot_prices/{chainName}/pools/{contractAddress}/` - TypeScript SDK: `PricingService.getPoolSpotPrices()` **Metadata:** ```yaml title: Get pool spot prices openapi: GET /v1/pricing/spot_prices/{chainName}/pools/{contractAddress}/ category: pricing api_type: REST operation_identity: {"operation_id":"getPoolSpotPrices","method":"GET","path":"/v1/pricing/spot_prices/{chainName}/pools/{contractAddress}/","sdk_service":"PricingService","sdk_method":"getPoolSpotPrices"} endpoint_role: specialized credit_cost: 1 per call chains: ["eth-mainnet","matic-mainnet","base-mainnet","optimism-mainnet","bsc-mainnet","gnosis-mainnet"] use_cases: [] beta: false related: ["get-historical-token-prices"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `contractAddress` | string | Yes | The pool contract address. | ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `quote-currency` | string | No | - | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. | | `pool_address` | `string` | The deployed pool contract address. | | `token_0_address` | `string` | The deployed contract address of `token_0` in the token pair making up the pool. | | `token_0_name` | `string` | The deployed contract name of `token_0` in the token pair making up the pool. | | `token_0_ticker` | `string` | The deployed contract symbol of `token_0` in the token pair making up the pool. | | `token_0_price` | `string` | Price of `token_0` in units of `token_1`. | | `token_0_price_24h` | `string` | Price of `token_0` in units of `token_1` as of 24 hours ago. | | `token_0_price_quote` | `string` | Price of `token_0` in the selected quote currency (defaults to USD). | | `token_0_price_24h_quote` | `string` | Price of `token_0` in the selected quote currency (defaults to USD) as of 24 hours ago. | | `token_1_address` | `string` | The deployed contract address of `token_1` in the token pair making up the pool. | | `token_1_name` | `string` | The deployed contract name of `token_1` in the token pair making up the pool. | | `token_1_ticker` | `string` | The deployed contract symbol of `token_1` in the token pair making up the pool. | | `token_1_price` | `string` | Price of `token_1` in units of `token_0`. | | `token_1_price_24h` | `string` | Price of `token_1` in units of `token_0` as of 24 hours ago. | | `token_1_price_quote` | `string` | Price of `token_1` in the selected quote currency (defaults to USD). | | `token_1_price_24h_quote` | `string` | Price of `token_1` in the selected quote currency (defaults to USD) as of 24 hours ago. | | `quote_currency` | `string` | The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, `GBP`, `BTC` and `ETH`. | **Content:** **Credit Cost:** 1 per call **Processing:** Batch > **Note:** Supports pools on Uniswap V2, V3 and their forks on all [Foundational Chains](https://goldrush.dev/chains/). --- ## 36. Get resolved address for registered address **Path:** api-reference/foundational-api/utility/get-resolved-address-for-registered-address **Operation Identity:** - Operation ID: `getResolvedAddress` - Method: `GET` - Endpoint Path: `/v1/{chainName}/address/{walletAddress}/resolve_address/` - TypeScript SDK: `BaseService.getResolvedAddress()` **Metadata:** ```yaml title: Get resolved address for registered address openapi: GET /v1/{chainName}/address/{walletAddress}/resolve_address/ category: base api_type: REST operation_identity: {"operation_id":"getResolvedAddress","method":"GET","path":"/v1/{chainName}/address/{walletAddress}/resolve_address/","sdk_service":"BaseService","sdk_method":"getResolvedAddress"} endpoint_role: primary credit_cost: 1 per call chains: ["eth-mainnet","axie-mainnet","base-mainnet","matic-mainnet"] use_cases: [] beta: false related: ["get-a-block","get-block-heights","get-logs"] ``` ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainName` | string | Yes | The chain name eg: `eth-mainnet`. | | `walletAddress` | string | Yes | The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. | ### Response Fields | Field | Type | Description | |-------|------|-------------| | `updated_at` | `string` | The timestamp when the response was generated. Useful to show data staleness to users. | | `chain_id` | `integer` | The requested chain ID eg: `1`. | | `chain_name` | `string` | The requested chain name eg: `eth-mainnet`. | | `items` | `array` | List of response items. | ### Item Fields | Field | Type | Description | |-------|------|-------------| | `address` | `string` | The requested address. | | `name` | `string` | | **Content:** **Credit Cost:** 1 per call **Processing:** Realtime ### Related guides How to Resolve a Wallet Address Given an ENS Domain --- # Streaming API Documentation ## Connection Details - **WebSocket Endpoint:** `wss://streaming.goldrushdata.com/graphql` - **Protocol:** `graphql-transport-ws` (GraphQL over WebSocket) - **Authentication:** Pass your GoldRush API key as `GOLDRUSH_API_KEY` in the `connection_init` payload - **Recommended Client:** [@covalenthq/client-sdk](https://www.npmjs.com/package/@covalenthq/client-sdk) ## 1. Token Search Query **Path:** api-reference/streaming-api/queries/token-search-query **Operation Identity:** - Operation ID: `searchToken` - GraphQL Type: `graphql-query` - GraphQL Field: `searchToken` **Metadata:** ```yaml title: Token Search Query tag: Beta category: streaming api_type: graphql-query operation_identity: {"operation_id":"searchToken","type":"graphql-query","field":"searchToken"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["defi-dashboards","trading-intelligence","market-analytics"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** This GraphQL query lets you discover actively traded tokens that match a keyword or ticker symbol. Each result includes pricing, volume marketcap, and base/quote metadata. Use it to build comprehensive token search features. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This query is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `query` | `string` | Yes | Search query string - can be token name, symbol, or address. Empty string returns all tokens. | | `chain_name` | `enum` | No | Optional chain filter. When provided, only tokens on this chain are returned. Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | ## Query You can query the `searchToken` endpoint with: - Free text (e.g. `"skitten"`) - Token contract address (e.g. `0x4B6104755AfB5Da4581B81C552DA3A25608c73B8`) - Token pair address (e.g. `0xa46d5090499eFB9c5dD7d95F7ca69F996b9Fb761`) The response is sorted in descending order by volume (in USD). ```graphql query { searchToken( query: "skitten" chain_name: BASE_MAINNET ) { volume chain_name base_token { contract_name contract_address contract_decimals contract_ticker_symbol } swap_count market_cap quote_rate volume_usd quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } quote_rate_usd pair_address } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "searchToken": [ { "pair_address": "0xa46d5090499efb9c5dd7d95f7ca69f996b9fb761", "chain_name": "BASE_MAINNET", "quote_rate": 2.3637041719e-7, "quote_rate_usd": 0.0007961152019156508, "volume": 19888966.385959223, "volume_usd": 15833.908490251517, "market_cap": 786165.7030043972, "base_token": { "contract_name": "Ski Mask Kitten", "contract_ticker_symbol": "SKITTEN", "contract_address": "0x4b6104755afb5da4581b81c552da3a25608c73b8", "contract_decimals": 18 }, "quote_token": { "contract_name": "Wrapped Ether", "contract_ticker_symbol": "WETH", "contract_address": "0x4200000000000000000000000000000000000006", "contract_decimals": 18 } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `volume` | `float` | 24h trading volume for the pair in quote token units | | `chain_name` | `enum` | The blockchain network where the token was created Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `base_token` | `object` | Metadata for the searched token, including address, decimals, name, and ticker symbol Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `swap_count` | `string` | Number of swaps in the tracking period | | `market_cap` | `float` | Estimated market capitalization in USD for the base token | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `volume_usd` | `float` | 24h trading volume in USD | | `quote_token` | `object` | Metadata for the paired quote asset Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `quote_rate_usd` | `float` | USD value of the quote rate | | `pair_address` | `string` | Liquidity pool contract that backs the result token/quote pair | --- ## 2. Top Trader Wallets for Token Query **Path:** api-reference/streaming-api/queries/upnl-for-token-query **Operation Identity:** - Operation ID: `upnlForToken` - GraphQL Type: `graphql-query` - GraphQL Field: `upnlForToken` **Metadata:** ```yaml title: Top Trader Wallets for Token Query tag: Beta category: streaming api_type: graphql-query operation_identity: {"operation_id":"upnlForToken","type":"graphql-query","field":"upnlForToken"} endpoint_role: specialized credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","matic-mainnet","gnosis-mainnet","optimism-mainnet","megaeth-mainnet"] use_cases: ["defi-dashboards","trading-intelligence","market-analytics","automation-and-agents"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** This GraphQL query provides a list of wallets with the highest trading volume for a specific token over the last 30 days, along with detailed information about their holdings, transaction activity, realized and unrealized profit/loss metrics. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `GNOSIS_MAINNET` - `MEGAETH_MAINNET` - `OPTIMISM_MAINNET` - `POLYGON_MAINNET` > **Note:** **This query is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainNameUpnl`](/api-reference/streaming-api/types/chain-name-upnl) | | `token_address` | `string` | Yes | Token contract address on a supported DEX and chain | ## Query You can query the `upnlForToken` endpoint to retrieve top wallet trading data. ```graphql query { upnlForToken( chain_name: ETH_MAINNET token_address: "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D" ) { volume wallet_address transactions_count balance contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } token_address pnl_realized_usd pnl_unrealized_usd marketcap_usd balance_pretty } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "upnlForToken": [ { "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d", "wallet_address": "0x91d40e4818f4d4c57b4578d9eca6afc92ac8debe", "volume": "56708716", "transactions_count": 554, "pnl_realized_usd": -43239.81, "balance": "32944375440228563000000000", "balance_pretty": "32944375.4402", "pnl_unrealized_usd": 535182, "contract_metadata": { "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D", "contract_name": "Covalent X Token", "contract_ticker_symbol": "CXT", "contract_decimals": 18 } }, { "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d", "wallet_address": "0xfe97b0c517a84f98fc6ede3cd26b43012d31992a", "volume": "39102028", "transactions_count": 241, "pnl_realized_usd": 8799.58, "balance": "323138960338677960000000000", "balance_pretty": "323138960.3387", "pnl_unrealized_usd": 6417132, "contract_metadata": { "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D", "contract_name": "Covalent X Token", "contract_ticker_symbol": "CXT", "contract_decimals": 18 } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `volume` | `string` | Total volume of tokens transferred (string to avoid JS precision loss) | | `wallet_address` | `string` | Wallet address of the token holder (lowercase with 0x prefix) | | `transactions_count` | `int` | Total number of transactions | | `balance` | `string` | Current token balance (string to avoid JS precision loss) | | `contract_metadata` | `object` | Token contract metadata Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `token_address` | `string` | Token contract address (lowercase with 0x prefix) | | `pnl_realized_usd` | `float` | Realized profit and loss in USD | | `pnl_unrealized_usd` | `float` | Unrealized profit and loss in USD | | `marketcap_usd` | `string` | Market capitalization in USD | | `balance_pretty` | `string` | Human-readable token balance with proper decimal places | --- ## 3. Wallet PnL by Token Query **Path:** api-reference/streaming-api/queries/upnl-for-wallet-query **Operation Identity:** - Operation ID: `upnlForWallet` - GraphQL Type: `graphql-query` - GraphQL Field: `upnlForWallet` **Metadata:** ```yaml title: Wallet PnL by Token Query tag: Beta category: streaming api_type: graphql-query operation_identity: {"operation_id":"upnlForWallet","type":"graphql-query","field":"upnlForWallet"} endpoint_role: specialized credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","matic-mainnet","gnosis-mainnet","optimism-mainnet","megaeth-mainnet"] use_cases: ["trading-intelligence","accounting-tax-reporting","portfolio-tracking"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** This GraphQL query provides detailed financial metrics, including unrealized and realized profit and loss (PnL), current balance, and transaction insights for each token held by a specific wallet address. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `GNOSIS_MAINNET` - `MEGAETH_MAINNET` - `OPTIMISM_MAINNET` - `POLYGON_MAINNET` > **Note:** **This query is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainNameUpnl`](/api-reference/streaming-api/types/chain-name-upnl) | | `wallet_address` | `string` | Yes | The wallet address to query | ## Query You can query the `upnlForWallet` endpoint to retrieve detailed PnL metrics for a wallet. ```graphql query { upnlForWallet( chain_name: ETH_MAINNET wallet_address: "0xfe97b0C517a84F98fc6eDe3CD26B43012d31992a" ) { cost_basis contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } net_balance_change token_address current_price pnl_realized_usd pnl_unrealized_usd marketcap_usd } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "upnlForWallet": [ { "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d", "cost_basis": 0.03219392, "current_price": 0.032418, "pnl_realized_usd": null, "pnl_unrealized_usd": 318.22842, "net_balance_change": "1420158", "marketcap_usd": "32418001.4431", "contract_metadata": { "contract_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d", "contract_name": "Covalent X Token", "contract_ticker_symbol": "CXT", "contract_decimals": 18 } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `cost_basis` | `float` | Cost basis per token | | `contract_metadata` | `object` | Token contract metadata Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `net_balance_change` | `string` | Net token movement (inflow - outflow) in the last 7 days, not the actual on-chain balance | | `token_address` | `string` | Token contract address (lowercase with 0x prefix) | | `current_price` | `float` | Current price per token | | `pnl_realized_usd` | `float` | Realized profit and loss in USD | | `pnl_unrealized_usd` | `float` | Unrealized profit and loss in USD | | `marketcap_usd` | `string` | Market capitalization in USD | --- ## 4. New DEX Pairs Stream **Path:** api-reference/streaming-api/subscriptions/new-dex-pairs-stream **Operation Identity:** - Operation ID: `newPairs` - GraphQL Type: `graphql-subscription` - GraphQL Field: `newPairs` - TypeScript SDK: `StreamingService.subscribeToNewPairs()` **Metadata:** ```yaml title: New DEX Pairs Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"newPairs","type":"graphql-subscription","field":"newPairs","sdk_service":"StreamingService","sdk_method":"subscribeToNewPairs"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["trading-intelligence","price-discovery-feeds","defi-dashboards","automation-and-agents"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","update-pairs-stream"] ``` **Content:** The New DEX Pairs stream provides real-time updates when **new liquidity pairs** are created on decentralized exchanges (DEXes). This documentation follows our standard streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `protocols` | `enum[]` | Yes | DEX protocols to filter results by Type: [`UnifiedProtocol`](/api-reference/streaming-api/types/unified-protocol) | ## Subscription You can subscribe to the `newPairs` endpoint to receive events. ```graphql subscription { newPairs( chain_name: BASE_MAINNET protocols: [ UNISWAP_V2 UNISWAP_V3 ] ) { pair { contract_name contract_address contract_decimals contract_ticker_symbol } liquidity tx_hash supply pair_address dev_holdings base_token { contract_name contract_address contract_decimals contract_ticker_symbol } protocol protocol_version market_cap quote_rate quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } quote_rate_usd event_name block_signed_at deployer_address chain_name } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "newPairs": [ { "chain_name": "base", "protocol": "uniswap", "protocol_version": "3", "pair_address": "0xa7dfb58a6e0d675c19f76dfd3b8b80a3a4814728", "deployer_address": "0x33128a8fc17869897dce68ed026d694621f6fdfd", "tx_hash": "0x5374c0182580ff2b3e868f58bdce697f3e4256baebc6f6e8db008fadb32d6253", "block_signed_at": "2025-05-28T22:01:41Z", "liquidity": 177.50267302070574, "supply": 1000000000, "market_cap": 6153.261270529, "event_name": "PoolCreated", "quote_rate": 0.000006153261270529, "quote_rate_usd": 0.000006153261270529, "base_token": { "contract_address": "0x8ac05571b525dd555320df58a40a0c0ab6d807c7", "contract_decimals": 18, "contract_name": "GOAT", "contract_ticker_symbol": "GOAT" }, "quote_token": { "contract_address": "0x1111111111166b7fe7bd91427724b487980afc69", "contract_decimals": 18, "contract_name": "Zora", "contract_ticker_symbol": "ZORA" }, "pair": { "contract_address": "0xa7dfb58a6e0d675c19f76dfd3b8b80a3a4814728", "contract_decimals": 18, "contract_name": "GOAT-ZORA Pool", "contract_ticker_symbol": "GOAT-ZORA" } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `pair` | `object` | Metadata for the pair including contract address, decimals, name, and symbol Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `pair.contract_name` | `string` | Name of the token contract | | `pair.contract_address` | `string` | Address of the token contract | | `pair.contract_decimals` | `int` | Number of decimal places for the token | | `pair.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `liquidity` | `float` | Initial liquidity amount in USD | | `tx_hash` | `string` | Transaction hash of the pair creation | | `supply` | `float` | Total supply of the pair token | | `pair_address` | `string` | Address of the new pair contract | | `dev_holdings` | `float` | Developer token holdings | | `base_token` | `object` | Metadata for the base token including contract address, decimals, name, and symbol Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `protocol` | `string` | DEX protocol name (e.g., uniswap, pancakeswap) | | `protocol_version` | `string` | Version of the DEX protocol | | `market_cap` | `float` | Market capitalization in USD | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `quote_token` | `object` | Metadata for the quote token including contract address, decimals, name, and symbol Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `quote_rate_usd` | `float` | USD value of the quote rate | | `event_name` | `string` | Name of the contract event (e.g., PoolCreated) | | `block_signed_at` | `string` | Timestamp when the block was signed (ISO-8601) | | `deployer_address` | `string` | Address that deployed the pair contract | | `chain_name` | `string` | The blockchain network where the pair was created | --- ## 5. OHLCV Pairs Stream **Path:** api-reference/streaming-api/subscriptions/ohlcv-pairs-stream **Operation Identity:** - Operation ID: `ohlcvCandlesForPair` - GraphQL Type: `graphql-subscription` - GraphQL Field: `ohlcvCandlesForPair` - TypeScript SDK: `StreamingService.subscribeToOHLCVPairs()` **Metadata:** ```yaml title: OHLCV Pairs Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"ohlcvCandlesForPair","type":"graphql-subscription","field":"ohlcvCandlesForPair","sdk_service":"StreamingService","sdk_method":"subscribeToOHLCVPairs"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","hypercore-mainnet"] use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"] beta: true related: ["ohlcv-tokens-stream","new-dex-pairs-stream","update-pairs-stream"] ``` **Content:** import { OhlcvChartSnippet } from "/snippets/ohlcv-chart.mdx"; The OHLCV Pairs stream provides real-time updates on the Open, High, Low, Close prices and Volume of ** one or many token pairs** at configurable intervals. This documentation follows our standard streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPERCORE_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `pair_addresses` | `array` | Yes | Array of pair addresses on supported DEXes and chains to track | | `interval` | `enum` | Yes | Time interval between each OHLCV candle Type: [`OhlcvTimeInterval`](/api-reference/streaming-api/types/ohlcv-time-interval) | | `timeframe` | `enum` | Yes | How far back to fetch historical OHLCV data Type: [`OhlcvTimeFrame`](/api-reference/streaming-api/types/ohlcv-time-frame) | | `limit` | `int` | No | Maximum number of items returned per stream message to control payload size | ## Subscription You can subscribe to the `ohlcvCandlesForPair` endpoint to receive the pricing events. ```graphql subscription { ohlcvCandlesForPair( chain_name: BASE_MAINNET pair_addresses: [ "0x9c087Eb773291e50CF6c6a90ef0F4500e349B903" "0x4b0Aaf3EBb163dd45F663b38b6d93f6093EBC2d3" ] interval: ONE_MINUTE timeframe: ONE_HOUR limit: 1000 ) { pair_address base_token { contract_name contract_address contract_decimals contract_ticker_symbol } volume timeframe high quote_rate low quote_rate_usd quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } interval id volume_usd close chain_name open timestamp } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "ohlcvCandlesForPair": [ { "chain_name": "BASE_MAINNET", "pair_address": "0x4b0Aaf3EBb163dd45F663b38b6d93f6093EBC2d3", "interval": "ONE_MINUTE", "timeframe": "ONE_HOUR", "timestamp": "2025-05-29T19:53:00Z", "open": 4113151.389790023, "high": 4196665.022060752, "low": 4113151.389790023, "close": 4196665.022060752, "volume": 325.7615900713698, "volume_usd": 0.2079461510855417, "quote_rate": 4196665.022060752, "quote_rate_usd": 0.0006319231563715365, "quote_token": { "contract_name": "Wrapped Ether", "contract_symbol": "WETH", "contract_address": "0x4200000000000000000000000000000000000006", "contract_decimals": 18 }, "base_token": { "contract_name": "Toshi", "contract_symbol": "TOSHI", "contract_address": "0xac1bd2486aaf3b5c0fc3fd868558b082a531b2b4", "contract_decimals": 18 } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `pair_address` | `string` | The address of the primary DEX pool with the most liquidity for the token | | `base_token` | `object` | Information about the queried token Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `volume` | `float` | Trading volume during the interval | | `timeframe` | `enum` | The requested timeframe Type: [`OhlcvTimeFrame`](/api-reference/streaming-api/types/ohlcv-time-frame) | | `high` | `float` | Highest price during the interval | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `low` | `float` | Lowest price during the interval | | `quote_rate_usd` | `float` | USD value of the quote rate | | `quote_token` | `object` | Information about the paired token of the primary DEX pool Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `interval` | `enum` | The candle interval Type: [`OhlcvTimeInterval`](/api-reference/streaming-api/types/ohlcv-time-interval) | | `id` | `string` | Unique identifier for this candle | | `volume_usd` | `float` | Trading volume in USD | | `close` | `float` | Closing price for the interval | | `chain_name` | `enum` | The blockchain network where the token exists Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `open` | `float` | Opening price for the interval | | `timestamp` | `string` | Candle timestamp (ISO-8601) | --- ## 6. OHLCV Tokens Stream **Path:** api-reference/streaming-api/subscriptions/ohlcv-tokens-stream **Operation Identity:** - Operation ID: `ohlcvCandlesForToken` - GraphQL Type: `graphql-subscription` - GraphQL Field: `ohlcvCandlesForToken` - TypeScript SDK: `StreamingService.subscribeToOHLCVTokens()` **Metadata:** ```yaml title: OHLCV Tokens Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"ohlcvCandlesForToken","type":"graphql-subscription","field":"ohlcvCandlesForToken","sdk_service":"StreamingService","sdk_method":"subscribeToOHLCVTokens"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hypercore-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"] beta: true related: ["ohlcv-pairs-stream","new-dex-pairs-stream","update-pairs-stream"] ``` **Content:** import { OhlcvChartSnippet } from "/snippets/ohlcv-chart.mdx"; The OHLCV Tokens stream provides real-time updates on the Open, High, Low, Close prices and Volume of **one or many tokens** at configurable intervals. This documentation follows our standard streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPERCORE_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Supported Token Price Feeds In addition to DEX-sourced prices, this stream supports institutional-grade price feeds from the following providers: | Provider | Description | |---|---| | [Redstone Bolt](https://redstone.finance/) | Ultra-low-latency CEX price feeds updated every **2.4 ms** (~400 updates/sec). Bolt nodes are co-located with chain sequencer infrastructure and aggregate prices from **Binance, Coinbase, OKX, Bitget, and Kraken**. | Pass the feed name in the `token_addresses` array with `chain_name` set to the feed's chain name. | Feed Name | Asset | Chain Name | |---|---|---| | `REDSTONE-BTC` | Bitcoin | `MEGAETH_MAINNET` | | `REDSTONE-ETH` | Ethereum | `MEGAETH_MAINNET` | | `REDSTONE-SOL` | Solana | `MEGAETH_MAINNET` | | `REDSTONE-BNB` | BNB | `MEGAETH_MAINNET` | | `REDSTONE-XRP` | XRP | `MEGAETH_MAINNET` | | `REDSTONE-ADA` | Cardano | `MEGAETH_MAINNET` | | `REDSTONE-DOGE` | Dogecoin | `MEGAETH_MAINNET` | | `REDSTONE-USDT` | Tether | `MEGAETH_MAINNET` | | `REDSTONE-USDC` | USD Coin | `MEGAETH_MAINNET` | ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `token_addresses` | `array` | Yes | Array of token addresses on supported DEXes and chains to track | | `interval` | `enum` | Yes | Time interval between each OHLCV candle Type: [`OhlcvTimeInterval`](/api-reference/streaming-api/types/ohlcv-time-interval) | | `timeframe` | `enum` | Yes | How far back to fetch historical OHLCV data Type: [`OhlcvTimeFrame`](/api-reference/streaming-api/types/ohlcv-time-frame) | | `limit` | `int` | No | Maximum number of items returned per stream message to control payload size | ## Subscription You can subscribe to the `ohlcvCandlesForToken` endpoint to receive the pricing events. ```graphql subscription { ohlcvCandlesForToken( chain_name: BASE_MAINNET token_addresses: ["0x4B6104755AfB5Da4581B81C552DA3A25608c73B8"] interval: ONE_MINUTE timeframe: ONE_HOUR limit: 1000 ) { pair_address base_token { contract_name contract_address contract_decimals contract_ticker_symbol } volume timeframe high quote_rate low quote_rate_usd quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } interval id volume_usd close chain_name open timestamp } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "ohlcvCandlesForToken": [ { "chain_name": "BASE_MAINNET", "interval": "ONE_MINUTE", "timeframe": "ONE_HOUR", "timestamp": "2025-06-27T22:24:00Z", "open": 0.000604418526534047, "high": 0.000604638206820701, "low": 0.000604013151624892, "close": 0.000604638206820701, "volume": 1.4980526133065126, "volume_usd": 6004669.256018968, "quote_rate": 0.000604638206820701, "quote_rate_usd": 4007551.6142841205, "base_token": { "contract_name": "Virtual Protocol", "contract_address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b", "contract_decimals": 18, "contract_ticker_symbol": "VIRTUAL" } } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `pair_address` | `string` | The address of the primary DEX pool with the most liquidity for the token | | `base_token` | `object` | Information about the queried token Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `volume` | `float` | Trading volume during the interval | | `timeframe` | `enum` | The requested timeframe Type: [`OhlcvTimeFrame`](/api-reference/streaming-api/types/ohlcv-time-frame) | | `high` | `float` | Highest price during the interval | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `low` | `float` | Lowest price during the interval | | `quote_rate_usd` | `float` | USD value of the quote rate | | `quote_token` | `object` | Information about the paired token of the primary DEX pool Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `interval` | `enum` | The candle interval Type: [`OhlcvTimeInterval`](/api-reference/streaming-api/types/ohlcv-time-interval) | | `id` | `string` | Unique identifier for this candle | | `volume_usd` | `float` | Trading volume in USD | | `close` | `float` | Closing price for the interval | | `chain_name` | `enum` | The blockchain network where the token exists Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `open` | `float` | Opening price for the interval | | `timestamp` | `string` | Candle timestamp (ISO-8601) | --- ## 7. Update Pairs Stream **Path:** api-reference/streaming-api/subscriptions/update-pairs-stream **Operation Identity:** - Operation ID: `updatePairs` - GraphQL Type: `graphql-subscription` - GraphQL Field: `updatePairs` - TypeScript SDK: `StreamingService.subscribeToUpdatePairs()` **Metadata:** ```yaml title: Update Pairs Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"updatePairs","type":"graphql-subscription","field":"updatePairs","sdk_service":"StreamingService","sdk_method":"subscribeToUpdatePairs"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["price-discovery-feeds","trading-intelligence","defi-dashboards","automation-and-agents"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** The Update Pairs stream provides real-time updates on the prices, volumes, market cap and liquidity of ** one or many token pairs**. This documentation follows our standard streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `pair_addresses` | `array` | Yes | Array of pair addresses on supported DEXes and chains to track | ## Subscription You can subscribe to the `updatePairs` endpoint to receive the events. ```graphql subscription { updatePairs( chain_name: BASE_MAINNET pair_addresses: [ "0x9c087Eb773291e50CF6c6a90ef0F4500e349B903" "0x4b0Aaf3EBb163dd45F663b38b6d93f6093EBC2d3" ] ) { trader liquidity pair_address base_token { contract_name contract_address contract_decimals contract_ticker_symbol } last_5m { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } last_6hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } market_cap quote_rate last_24hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } last_1hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } quote_rate_usd sender quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } id chain_name direction timestamp } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "updatePairs": { "chain_name": "BASE_MAINNET", "pair_address": "0x9c087Eb773291e50CF6c6a90ef0F4500e349B903", "timestamp": "2025-08-13T12:34:56Z", "quote_rate": 0.0002962, "quote_rate_usd": 1.39, "market_cap": 1250000.50, "liquidity": 850000.25, "base_token": { "contract_name": "Virtual", "contract_ticker_symbol": "VIRTUAL", "contract_address": "0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b", "contract_decimals": 18 }, "quote_token": { "contract_name": "Wrapped Ether", "contract_ticker_symbol": "WETH", "contract_address": "0x4200000000000000000000000000000000000006", "contract_decimals": 18 }, "last_5m": { "price": { "current_value": 1.39, "previous_value": 1.37, "pct_change": 1.46 }, "swap_count": { "current_value": 10, "previous_value": 8, "pct_change": 25.0 }, "volume_usd": { "current_value": 975.52, "previous_value": 820.10, "pct_change": 18.95 } }, "last_1hr": { "price": { "current_value": 1.39, "previous_value": 1.36, "pct_change": 2.21 }, "swap_count": { "current_value": 100, "previous_value": 85, "pct_change": 17.65 }, "volume_usd": { "current_value": 12500.00, "previous_value": 10200.00, "pct_change": 22.55 } } } } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `trader` | `string` | Address of the trader who initiated the swap | | `liquidity` | `float` | Total liquidity in the pool | | `pair_address` | `string` | The address of the DEX pair | | `base_token` | `object` | Information about the base token in the pair Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `last_5m` | `object` | Aggregated trading metrics for the last 5 minutes Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_5m.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_5m.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_5m.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `last_6hr` | `object` | Aggregated trading metrics for the last 6 hours Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_6hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_6hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_6hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `market_cap` | `float` | Market capitalization of the token pair | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `last_24hr` | `object` | Aggregated trading metrics for the last 24 hours Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_24hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_24hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_24hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `last_1hr` | `object` | Aggregated trading metrics for the last 1 hour Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_1hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_1hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_1hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `quote_rate_usd` | `float` | Exchange rate between base and quote tokens in USD | | `sender` | `string` | Address that sent the transaction | | `quote_token` | `object` | Information about the quote token in the pair Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `id` | `string` | Unique identifier for this swap event | | `chain_name` | `enum` | The blockchain network where the pair exists Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `direction` | `string` | Swap direction: buy or sell | | `timestamp` | `string` | Timestamp of the latest swap (ISO-8601) | --- ## 8. Update Tokens Stream **Path:** api-reference/streaming-api/subscriptions/update-tokens-stream **Operation Identity:** - Operation ID: `updateTokens` - GraphQL Type: `graphql-subscription` - GraphQL Field: `updateTokens` **Metadata:** ```yaml title: Update Tokens Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"updateTokens","type":"graphql-subscription","field":"updateTokens"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["price-discovery-feeds","trading-intelligence","defi-dashboards","automation-and-agents"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** The Update Tokens stream provides real-time updates on the prices, volumes, market cap and liquidity of **one or many tokens** by tracking the highest-volume pool for each token. This documentation follows our standard streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` - `SOLANA_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `token_addresses` | `array` | Yes | Array of token addresses on supported DEXes and chains to track | ## Subscription You can subscribe to the `updateTokens` endpoint to receive real-time swap updates for the highest-volume pool of each token. ```graphql subscription { updateTokens( chain_name: BASE_MAINNET token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"] ) { trader liquidity pair_address base_token { contract_name contract_address contract_decimals contract_ticker_symbol } last_5m { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } last_6hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } market_cap quote_rate last_24hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } last_1hr { volume { previous_value pct_change current_value } unique_sellers { previous_value pct_change current_value } sell_count { previous_value pct_change current_value } price { previous_value pct_change current_value } buy_count { previous_value pct_change current_value } sell_volume { previous_value pct_change current_value } volume_usd { previous_value pct_change current_value } buy_volume { previous_value pct_change current_value } swap_count { previous_value pct_change current_value } unique_buyers { previous_value pct_change current_value } } quote_rate_usd sender quote_token { contract_name contract_address contract_decimals contract_ticker_symbol } id chain_name direction timestamp } } ``` ## Response Format Here's an example of the response data structure: ```json { "data": { "updateTokens": { "chain_name": "BASE_MAINNET", "pair_address": "0x9c087Eb773291e50CF6c6a90ef0F4500e349B903", "timestamp": "2025-06-28T14:30:00Z", "direction": "buy", "trader": "0xd2216ed62a5c84f285a051839e808902fe8fc90b", "sender": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "quote_rate": 0.0002962, "quote_rate_usd": 1.39, "volume": 0.2079461510855417, "volume_usd": 975.515187, "market_cap": 1390000, "liquidity": 450000, "base_token": { "contract_name": "Virtual Protocol", "contract_address": "0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b", "contract_decimals": 18, "contract_ticker_symbol": "VIRTUAL" }, "quote_token": { "contract_name": "Wrapped Ether", "contract_address": "0x4200000000000000000000000000000000000006", "contract_decimals": 18, "contract_ticker_symbol": "WETH" }, "last_5m": { "price_delta": { "current_value": 1.39, "previous_value": 1.38, "pct_change": 0.72 }, "swap_count": { "current_value": 12, "previous_value": 8, "pct_change": 50 }, "buy_volume": { "current_value": 500.25, "previous_value": 320.10, "pct_change": 56.3 }, "sell_volume": { "current_value": 475.26, "previous_value": 290.50, "pct_change": 63.6 }, "unique_traders": { "current_value": 5, "previous_value": 3, "pct_change": 66.7 }, "total_buy_txns": { "current_value": 7, "previous_value": 5, "pct_change": 40 }, "total_sell_txns": { "current_value": 5, "previous_value": 3, "pct_change": 66.7 } } } } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `trader` | `string` | Address of the trader who initiated the swap | | `liquidity` | `float` | Total liquidity in the pool | | `pair_address` | `string` | The address of the DEX pair | | `base_token` | `object` | Information about the base token in the pair Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `base_token.contract_name` | `string` | Name of the token contract | | `base_token.contract_address` | `string` | Address of the token contract | | `base_token.contract_decimals` | `int` | Number of decimal places for the token | | `base_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `last_5m` | `object` | Aggregated trading metrics for the last 5 minutes Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_5m.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_5m.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_5m.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `last_6hr` | `object` | Aggregated trading metrics for the last 6 hours Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_6hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_6hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_6hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `market_cap` | `float` | Market capitalization of the token pair | | `quote_rate` | `float` | Exchange rate between base and quote tokens | | `last_24hr` | `object` | Aggregated trading metrics for the last 24 hours Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_24hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_24hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_24hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `last_1hr` | `object` | Aggregated trading metrics for the last 1 hour Type: [`TimeframeMetrics`](/api-reference/streaming-api/types/timeframe-metrics) | | `last_1hr.volume` | `object` | Total volume in native/quote token (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__previous_value float Total value for the previous duration __RESPONSE_ROW__last_1hr.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__last_1hr.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_sellers object Number of unique seller addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_sellers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_sellers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_sellers.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_count object Number of sell transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_count.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_count.current_value float Total value for the most recent duration __RESPONSE_ROW__price object Price: current_value = current price, previous_value = price at window start Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__price.previous_value float Total value for the previous duration __RESPONSE_ROW__price.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__price.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_count object Number of buy transactions Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_count.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_count.current_value float Total value for the most recent duration __RESPONSE_ROW__sell_volume object Total sell volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__sell_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__sell_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__sell_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__volume_usd object Total volume in USD (buy + sell) Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__volume_usd.previous_value float Total value for the previous duration __RESPONSE_ROW__volume_usd.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__volume_usd.current_value float Total value for the most recent duration __RESPONSE_ROW__buy_volume object Total buy volume in USD Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__buy_volume.previous_value float Total value for the previous duration __RESPONSE_ROW__buy_volume.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__buy_volume.current_value float Total value for the most recent duration __RESPONSE_ROW__swap_count object Total number of swaps Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__swap_count.previous_value float Total value for the previous duration __RESPONSE_ROW__swap_count.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__swap_count.current_value float Total value for the most recent duration __RESPONSE_ROW__unique_buyers object Number of unique buyer addresses Type: [`MetricValue`](/api-reference/streaming-api/types/metric-value) __RESPONSE_ROW__unique_buyers.previous_value float Total value for the previous duration __RESPONSE_ROW__unique_buyers.pct_change float Percent change between current_value and previous_value __RESPONSE_ROW__unique_buyers.current_value float Total value for the most recent duration | | `quote_rate_usd` | `float` | Exchange rate between base and quote tokens in USD | | `sender` | `string` | Address that sent the transaction | | `quote_token` | `object` | Information about the quote token in the pair Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `quote_token.contract_name` | `string` | Name of the token contract | | `quote_token.contract_address` | `string` | Address of the token contract | | `quote_token.contract_decimals` | `int` | Number of decimal places for the token | | `quote_token.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `id` | `string` | Unique identifier for this swap event | | `chain_name` | `enum` | The blockchain network where the pair exists Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | | `direction` | `string` | Swap direction: buy or sell | | `timestamp` | `string` | Timestamp of the latest swap (ISO-8601) | --- ## 9. Wallet Activity Stream **Path:** api-reference/streaming-api/subscriptions/wallet-activity-stream **Operation Identity:** - Operation ID: `walletTxs` - GraphQL Type: `graphql-subscription` - GraphQL Field: `walletTxs` - TypeScript SDK: `StreamingService.subscribeToWalletActivity()` **Metadata:** ```yaml title: Wallet Activity Stream tag: Beta category: streaming api_type: graphql-subscription operation_identity: {"operation_id":"walletTxs","type":"graphql-subscription","field":"walletTxs","sdk_service":"StreamingService","sdk_method":"subscribeToWalletActivity"} endpoint_role: primary credit_cost: null chains: ["base-mainnet","eth-mainnet","bsc-mainnet","monad-mainnet","hypercore-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet"] use_cases: ["trading-intelligence","automation-and-agents","onchain-gaming-infrastructure","defi-dashboards"] beta: true related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"] ``` **Content:** The Wallet Activity stream provides real-time updates on wallet **transactions, token transfers, and interactions with smart contracts **. This documentation follows our standard Streaming API structure. **Credit Cost:** TBD **Supported Chains:** - `BASE_MAINNET` - `BSC_MAINNET` - `ETH_MAINNET` - `HYPERCORE_MAINNET` - `HYPEREVM_MAINNET` - `MEGAETH_MAINNET` - `MONAD_MAINNET` - `POLYGON_MAINNET` > **Note:** **This stream is currently in Beta.** It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. **No API credits are currently charged.** We welcome your feedback so please [reach out](mailto:support@covalenthq.com) to us directly to report issues or request features. ## Supported Actions All transactions are returned as raw data, but the following transaction types are decoded: ### EVM Chains & Solana - [`ApproveTransaction`](/api-reference/streaming-api/types/approve-transaction) — Decoded details for a token spending approval - [`BridgeTransaction`](/api-reference/streaming-api/types/bridge-transaction) — Decoded details for a cross-chain bridge transfer - [`DepositTransaction`](/api-reference/streaming-api/types/deposit-transaction) — Decoded details for a token deposit or liquidity addition - [`SwapTransaction`](/api-reference/streaming-api/types/swap-transaction) — Decoded details for a token swap on a decentralized exchange - [`TransferTransaction`](/api-reference/streaming-api/types/transfer-transaction) — Decoded details for a token transfer between addresses - [`WithdrawTransaction`](/api-reference/streaming-api/types/withdraw-transaction) — Decoded details for a token withdrawal or liquidity removal ### Hypercore #### Hypercore Fill Transaction - [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) — Decoded details for a Hypercore perpetuals trade fill #### Hypercore Misc Events - [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event) — Decoded details for a Hypercore staking delegation or undelegation event - [`HypercoreDepositEvent`](/api-reference/streaming-api/types/hypercore-deposit-event) — Decoded details for a Hypercore cross-chain deposit from an external chain - [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event) — Decoded details for a Hypercore funding rate payment between long and short holders - [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) — Decoded details for a Hypercore ledger update (withdraw, deposit, transfer, liquidation, etc.) - [`HypercoreWithdrawalEvent`](/api-reference/streaming-api/types/hypercore-withdrawal-event) — Decoded details for a finalized Hypercore cross-chain withdrawal ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `wallet_addresses` | `array` | Yes | Addresses to track | | `chain_name` | `enum` | Yes | Blockchain network to filter events Type: [`ChainName`](/api-reference/streaming-api/types/chain-name) | ## Subscription You can subscribe to the `walletTxs` endpoint to receive events. ```graphql Hypercore subscription { walletTxs( wallet_addresses: ["0x8e80c4b533dd977cf716b5c24fd9223129272804"] chain_name: HYPERCORE_MAINNET ) { decoded_details { ... on ErrorDetails { message typeString } ... on HypercoreDelegationEvent { type typeString hash time is_undelegate amount validator } ... on HypercoreDepositEvent { type typeString hash time amount } ... on HypercoreFillTransaction { type typeString liquidation { market_price method liquidated_user } twap_id builder_fee side cloid closed_pnl fee fee_token oid dir start_position tid size price builder time crossed hash coin } ... on HypercoreFundingEvent { type typeString hash time szi funding_amount coin funding_rate } ... on HypercoreLedgerEvent { type typeString delta { ... on LedgerSubAccountTransfer { destination usdc user } ... on LedgerWithdraw { fee usdc nonce } ... on LedgerLiquidation { liquidated_ntl_pos account_value liquidated_positions { szi coin } leverage_type } ... on LedgerSpotTransfer { amount usdc_value native_token_fee fee destination fee_token nonce user token } ... on LedgerVaultLeaderCommission { usdc vault } ... on LedgerSend { amount usdc_value destination_dex native_token_fee fee destination fee_token nonce user source_dex token } ... on LedgerVaultDeposit { usdc user vault } ... on LedgerInternalTransfer { fee destination usdc user } ... on LedgerAccountClassTransfer { amount token } ... on LedgerAccountActivationGas { amount token } ... on LedgerVaultCreate { fee usdc vault } ... on LedgerBorrowLend { amount interest_amount operation token } ... on LedgerDeposit { usdc } ... on LedgerRewardsClaim { amount } ... on LedgerPerpDexClassTransfer { amount dex to_perp token } ... on LedgerCStakingTransfer { amount is_deposit token } ... on LedgerSpotGenesis { amount token } ... on LedgerDeployGasAuction { amount token } ... on LedgerVaultDistribution { usdc vault } ... on LedgerVaultWithdraw { requested_usd commission basis closing_cost user vault } } hash ledger_type time } ... on HypercoreWithdrawalEvent { type typeString hash time amount } } gas_used block_hash to_address tx_hash block_height decoded_type miner_address tx_offset block_signed_at from_address logs { data emitter_address log_offset topics } value chain_name successful } } ``` ```graphql EVM Chains & Solana subscription { walletTxs( wallet_addresses: [ "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc" "0x4200000000000000000000000000000000000006" ] chain_name: BASE_MAINNET ) { decoded_details { ... on ApproveTransaction { type typeString amount quote_usd quote_rate_usd spender contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } } ... on BridgeTransaction { type typeString amount quote_usd quote_rate_usd contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } from to } ... on DepositTransaction { type typeString amount quote_usd quote_rate_usd contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } from to } ... on ErrorDetails { message typeString } ... on SwapTransaction { type typeString amount_out amount_in token_out { contract_name contract_address contract_decimals contract_ticker_symbol } token_in { contract_name contract_address contract_decimals contract_ticker_symbol } } ... on TransferTransaction { type typeString amount quote_usd quote_rate_usd contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } from to } ... on WithdrawTransaction { type typeString amount quote_usd quote_rate_usd contract_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } from to } } gas_used block_hash to_address tx_hash block_height decoded_type miner_address tx_offset block_signed_at from_address logs { data emitter_address log_offset topics } value chain_name successful } } ``` ## Response Format Here's an example of the response data structure: ```json Hypercore { "data": { "walletTxs": [ { "decoded_details": { "type": "FILL", "typeString": "FILL", "liquidation": null, "twap_id": null, "builder_fee": null, "side": "BUY", "cloid": "0x00000000000000000000019d8d47e098", "closed_pnl": "0.0", "fee": "0.152339", "fee_token": "USDC", "oid": "381460857711", "dir": "Open Long", "start_position": "254.82", "tid": "851999089020363", "size": "17.66", "price": "84.571", "builder": null, "time": "2026-04-14T18:37:25.662Z", "crossed": true, "hash": "0x32813029e2aee9d633fa043925538b02029b000f7da208a8d649db7ca1a2c3c0", "coin": "SOL" }, "gas_used": 0, "block_hash": "hypercore_block", "to_address": "0x8e80c4b533dd977cf716b5c24fd9223129272804", "tx_hash": "0x32813029e2aee9d633fa043925538b02029b000f7da208a8d649db7ca1a2c3c0", "block_height": 0, "decoded_type": "FILL", "miner_address": "hypercore_miner", "tx_offset": 0, "block_signed_at": "2026-04-14T18:37:25.662Z", "from_address": "0x8e80c4b533dd977cf716b5c24fd9223129272804", "logs": [], "value": 1493, "chain_name": "hypercore-mainnet", "successful": true }, { "decoded_details": { "type": "FILL", "typeString": "FILL", "liquidation": null, "twap_id": null, "builder_fee": null, "side": "BUY", "cloid": "0x00000000000000020000019d8d480dd9", "closed_pnl": "0.0", "fee": "0.083655", "fee_token": "USDC", "oid": "381461134036", "dir": "Open Long", "start_position": "272.48", "tid": "299654811699485", "size": "9.7", "price": "84.552", "builder": null, "time": "2026-04-14T18:37:25.662Z", "crossed": true, "hash": "0x32813029e2aee9d633fa043925538b02029b000f7da208a8d649db7ca1a2c3c0", "coin": "SOL" }, "gas_used": 0, "block_hash": "hypercore_block", "to_address": "0x8e80c4b533dd977cf716b5c24fd9223129272804", "tx_hash": "0x32813029e2aee9d633fa043925538b02029b000f7da208a8d649db7ca1a2c3c0", "block_height": 0, "decoded_type": "FILL", "miner_address": "hypercore_miner", "tx_offset": 0, "block_signed_at": "2026-04-14T18:37:25.662Z", "from_address": "0x8e80c4b533dd977cf716b5c24fd9223129272804", "logs": [], "value": 820, "chain_name": "hypercore-mainnet", "successful": true } ] } } ``` ```json EVM Chains & Solana { "data": { "walletTxs": [ { "tx_hash": "0x23a4f9710c23678a8c6ae25d7e3aa75a82866231e9bd541114046c5a710a8355", "from_address": "0xd2216ed62a5c84f285a051839e808902fe8fc90b", "to_address": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "value": 0, "chain_name": "base-mainnet", "block_signed_at": "2025-05-29T19:27:25Z", "block_height": 30878749, "block_hash": "0x2435aec7c20678ee82ae251ab1066e15ed3dac7ff0ea086c44ee8476a721abde", "miner_address": "0x4200000000000000000000000000000000000011", "gas_used": 195861, "tx_offset": 118, "successful": true, "decoded_type": "SWAP", "decoded_details": { "token_in": { "contract_address": "0x4200000000000000000000000000000000000006", "contract_decimals": 18, "contract_ticker_symbol": "WETH" }, "token_out": { "contract_address": "0x14b2f229097df3c92b43ea871860e3fae08d7f06", "contract_decimals": 18, "contract_ticker_symbol": "EXAMPLE" }, "amount_in": "258844786659364206700114", "amount_out": "66094025142553271" }, "logs": [ { "emitter": "0x4200000000000000000000000000000000000006", "topics": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x000000000000000000000000286f3add5dd41ba6e208f9f9a68533107fd0d0fa", "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] }, { "emitter": "0x14b2f229097df3c92b43ea871860e3fae08d7f06", "topics": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x000000000000000000000000d2216ed62a5c84f285a051839e808902fe8fc90b", "0x000000000000000000000000286f3add5dd41ba6e208f9f9a68533107fd0d0fa" ] }, { "emitter": "0x286f3add5dd41ba6e208f9f9a68533107fd0d0fa", "topics": [ "0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67", "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] }, { "emitter": "0x4200000000000000000000000000000000000006", "topics": [ "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65", "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] } ] } ] } } ``` ### Field Descriptions | Field | Type | Description | | --- | --- | --- | | `decoded_details` | `interface` | The decoded event data (varies by event type) Type: [`DecodedDetails`](/api-reference/streaming-api/types/decoded-details) | | `decoded_details.type` | `enum` | Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) | | `decoded_details.amount` | `string` | Amount of tokens approved for spending | | `decoded_details.quote_usd` | `float` | Total USD value of the approved amount | | `decoded_details.quote_rate_usd` | `float` | USD price per token at time of approval | | `decoded_details.spender` | `string` | Address of the approved spender | | `decoded_details.contract_metadata` | `object` | Metadata for the approved token contract Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) __RESPONSE_ROW__contract_name string Name of the token contract __RESPONSE_ROW__decoded_details.contract_address string Address of the token contract __RESPONSE_ROW__decoded_details.contract_decimals int Number of decimal places for the token __RESPONSE_ROW__decoded_details.contract_ticker_symbol string Ticker symbol of the token Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) | | `amount` | `string` | Amount of tokens bridged | | `quote_usd` | `float` | Total USD value of the bridged amount | | `quote_rate_usd` | `float` | USD price per token at time of bridge | | `contract_metadata` | `object` | Metadata for the bridged token contract Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `from` | `string` | Sender wallet address | | `to` | `string` | Recipient wallet address | __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__amount string Amount of tokens deposited __RESPONSE_ROW__quote_usd float Total USD value of the deposited amount __RESPONSE_ROW__quote_rate_usd float USD price per token at time of deposit __RESPONSE_ROW__contract_metadata object Metadata for the deposited token contract Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | Field | Type | Description | | --- | --- | --- | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `from` | `string` | Sender wallet address | | `to` | `string` | Recipient or pool address | __RESPONSE_ROW__message string Error or status message describing the issue __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__hash string Transaction/event hash from the Hypercore L1 __RESPONSE_ROW__time string ISO-8601 timestamp of the delegation event __RESPONSE_ROW__is_undelegate boolean Whether this is an undelegation (true) or delegation (false) __RESPONSE_ROW__amount string Delegation amount __RESPONSE_ROW__validator string Validator address that received or lost the delegation __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__hash string Transaction/event hash from the Hypercore L1 __RESPONSE_ROW__time string ISO-8601 timestamp of the deposit event __RESPONSE_ROW__amount string Deposit amount in USDC __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__liquidation object Liquidation details, present only when this fill resulted from a liquidation Type: [`HypercoreLiquidation`](/api-reference/streaming-api/types/hypercore-liquidation) | Field | Type | Description | | --- | --- | --- | | `liquidation.market_price` | `string` | Mark price at the time of liquidation | | `liquidation.method` | `string` | Liquidation method: Market or Backstop | | `liquidation.liquidated_user` | `string` | Address of the user whose position was liquidated | | `twap_id` | `string` | TWAP order ID when this fill was part of a TWAP execution | | `builder_fee` | `string` | Fee paid to the builder, if a builder was involved | | `side` | `string` | Fill side: BUY, SELL, or UNSPECIFIED | | `cloid` | `string` | Client-supplied order ID for programmatic order tracking | | `closed_pnl` | `string` | Realized PnL from the closed portion of the position | | `fee` | `string` | Fee charged for this fill | | `fee_token` | `string` | Token in which the fee was denominated | | `oid` | `string` | Order ID that originated this fill | | `dir` | `string` | Direction indicator for the position change | | `start_position` | `string` | Position size before this fill executed | | `tid` | `string` | Unique trade ID assigned by the exchange | | `size` | `string` | Filled quantity | | `price` | `string` | Execution price per unit | | `builder` | `string` | Address of the builder that constructed this order | | `time` | `string` | ISO-8601 timestamp of the fill | | `crossed` | `boolean` | Whether the order crossed the spread (true = taker, false = maker) | | `hash` | `string` | On-chain transaction hash | | `coin` | `string` | Market/coin symbol (e.g. ETH, BTC) | __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__hash string Transaction/event hash from the Hypercore L1 __RESPONSE_ROW__time string ISO-8601 timestamp of the funding event __RESPONSE_ROW__szi string Position size indicator at the time of funding __RESPONSE_ROW__funding_amount string Funding payment amount in USDC __RESPONSE_ROW__coin string Market/coin symbol (e.g. ETH, BTC) __RESPONSE_ROW__funding_rate string Funding rate applied for this settlement __RESPONSE_ROW__type string Ledger subtype discriminator (e.g. withdraw, deposit, spot_transfer, send) __RESPONSE_ROW__delta union Subtype-specific ledger delta payload Type: [`LedgerDelta`](/api-reference/streaming-api/types/ledger-delta) | Field | Type | Description | | --- | --- | --- | | `delta.destination` | `string` | Destination sub-account address | | `delta.usdc` | `string` | Transfer amount in USDC | | `delta.user` | `string` | Source user address | | `delta.fee` | `string` | Withdrawal fee | | `delta.usdc` | `string` | Withdrawal amount in USDC | | `delta.nonce` | `string` | Withdrawal nonce | | `delta.liquidated_ntl_pos` | `string` | Liquidated notional position value | | `delta.account_value` | `string` | Account value at time of liquidation | | `delta.liquidated_positions` | `object[]` | List of positions that were liquidated Type: [`LedgerLiquidatedPosition`](/api-reference/streaming-api/types/ledger-liquidated-position) | | `delta.leverage_type` | `string` | Leverage type (e.g. cross, isolated) | | `delta.amount` | `string` | Transfer amount | | `delta.usdc_value` | `string` | USDC equivalent value | | `delta.native_token_fee` | `string` | Fee in native token | | `delta.fee` | `string` | Transfer fee | | `delta.destination` | `string` | Destination user address | | `delta.fee_token` | `string` | Token used for fee payment | | `delta.nonce` | `string` | Transfer nonce | | `delta.user` | `string` | Source user address | | `delta.token` | `string` | Token identifier | | `delta.usdc` | `string` | Commission amount in USDC | | `delta.vault` | `string` | Vault address | | `delta.amount` | `string` | Send amount | | `delta.usdc_value` | `string` | USDC equivalent value | | `delta.destination_dex` | `string` | Destination DEX identifier | | `delta.native_token_fee` | `string` | Fee in native token | | `delta.fee` | `string` | Send fee | | `delta.destination` | `string` | Recipient address | | `delta.fee_token` | `string` | Token used for fee payment | | `delta.nonce` | `string` | Send nonce | | `delta.user` | `string` | Sender address | | `delta.source_dex` | `string` | Source DEX identifier | | `delta.token` | `string` | Token identifier | | `delta.usdc` | `string` | Deposit amount in USDC | | `delta.user` | `string` | Depositor address | | `delta.vault` | `string` | Vault address | | `delta.fee` | `string` | Transfer fee | | `delta.destination` | `string` | Destination user address | | `delta.usdc` | `string` | Transfer amount in USDC | | `delta.user` | `string` | Source user address | | `delta.amount` | `string` | Transfer amount | | `delta.token` | `string` | Token identifier | | `delta.amount` | `string` | Gas fee amount | | `delta.token` | `string` | Token used for gas payment | | `delta.fee` | `string` | Vault creation fee | | `delta.usdc` | `string` | Initial deposit amount in USDC | | `delta.vault` | `string` | Vault address | | `delta.amount` | `string` | Borrow or lend amount | | `delta.interest_amount` | `string` | Accrued interest amount | | `delta.operation` | `string` | Operation type: borrow or lend | | `delta.token` | `string` | Token identifier | | `delta.usdc` | `string` | Deposit amount in USDC | | `delta.amount` | `string` | Claimed rewards amount | | `delta.amount` | `string` | Transfer amount | | `delta.dex` | `string` | DEX identifier | | `delta.to_perp` | `boolean` | Whether transferring to perp (true) or to spot (false) | | `delta.token` | `string` | Token identifier | | `delta.amount` | `string` | Transfer amount | | `delta.is_deposit` | `boolean` | Whether this is a deposit (true) or withdrawal (false) | | `delta.token` | `string` | Token identifier | | `delta.amount` | `string` | Genesis distribution amount | | `delta.token` | `string` | Token identifier | | `delta.amount` | `string` | Auction amount | | `delta.token` | `string` | Token identifier | | `delta.usdc` | `string` | Distribution amount in USDC | | `delta.vault` | `string` | Vault address | | `delta.requested_usd` | `string` | Requested withdrawal amount in USD | | `delta.commission` | `string` | Commission charged | | `delta.basis` | `string` | Cost basis of the withdrawn share | | `delta.closing_cost` | `string` | Cost to close positions for withdrawal | | `delta.user` | `string` | Withdrawer address | | `delta.vault` | `string` | Vault address | | `hash` | `string` | Transaction/event hash from the Hypercore L1 | | `ledger_type` | `string` | Ledger subtype discriminator (e.g. withdraw, deposit, spot_transfer, send) | | `time` | `string` | ISO-8601 timestamp of the ledger event | __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__hash string Transaction/event hash from the Hypercore L1 __RESPONSE_ROW__time string ISO-8601 timestamp of the withdrawal event __RESPONSE_ROW__amount string Withdrawal amount in USDC __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__amount_out string Amount of tokens received __RESPONSE_ROW__amount_in string Amount of tokens sold __RESPONSE_ROW__token_out object Metadata for the token bought Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | Field | Type | Description | | --- | --- | --- | | `token_out.contract_name` | `string` | Name of the token contract | | `token_out.contract_address` | `string` | Address of the token contract | | `token_out.contract_decimals` | `int` | Number of decimal places for the token | | `token_out.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `token_in` | `object` | Metadata for the token sold Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | | `token_in.contract_name` | `string` | Name of the token contract | | `token_in.contract_address` | `string` | Address of the token contract | | `token_in.contract_decimals` | `int` | Number of decimal places for the token | | `token_in.contract_ticker_symbol` | `string` | Ticker symbol of the token | __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__amount string Amount of tokens transferred __RESPONSE_ROW__quote_usd float Total USD value of the transferred amount __RESPONSE_ROW__quote_rate_usd float USD price per token at time of transfer __RESPONSE_ROW__contract_metadata object Metadata for the transferred token contract Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | Field | Type | Description | | --- | --- | --- | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `from` | `string` | Sender wallet address | | `to` | `string` | Recipient wallet address | __RESPONSE_ROW__type enum Enum value identifying the transaction type Type: [`TransactionType`](/api-reference/streaming-api/types/transaction-type) __RESPONSE_ROW__amount string Amount of tokens withdrawn __RESPONSE_ROW__quote_usd float Total USD value of the withdrawn amount __RESPONSE_ROW__quote_rate_usd float USD price per token at time of withdrawal __RESPONSE_ROW__contract_metadata object Metadata for the withdrawn token contract Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata) | Field | Type | Description | | --- | --- | --- | | `contract_metadata.contract_name` | `string` | Name of the token contract | | `contract_metadata.contract_address` | `string` | Address of the token contract | | `contract_metadata.contract_decimals` | `int` | Number of decimal places for the token | | `contract_metadata.contract_ticker_symbol` | `string` | Ticker symbol of the token | | `from` | `string` | Source pool or contract address | | `to` | `string` | Recipient wallet address | | Field | Type | Description | | --- | --- | --- | | `gas_used` | `string` | The amount of gas used by the transaction | | `block_hash` | `string` | The hash of the block containing the transaction | | `to_address` | `string` | The recipient's address | | `tx_hash` | `string` | The transaction hash | | `block_height` | `int` | The block number where the transaction was included | | `decoded_type` | `string` | The type of decoded event (e.g., SWAP) | | `miner_address` | `string` | The address of the block miner | | `tx_offset` | `int` | The position of the transaction in the block | | `block_signed_at` | `string` | Timestamp when the block containing this transaction was signed (ISO-8601) | | `from_address` | `string` | The sender's address | | `logs` | `object[]` | Array of event logs emitted during the transaction Type: [`TransactionLog`](/api-reference/streaming-api/types/transaction-log) | | `logs.data` | `string` | ABI-encoded log data | | `logs.emitter_address` | `string` | Address of the contract that emitted the log | | `logs.log_offset` | `int` | Position of the log within the transaction | | `logs.topics` | `array` | Indexed event parameters (topic[0] is the event signature hash) | | `value` | `string` | The transaction value in native currency | | `chain_name` | `string` | The blockchain network where the transaction occurred | | `successful` | `boolean` | Whether the transaction was successful | ## Decoded Events Note from the [Subscription](#subscription) query above, this stream decodes events which you can fetch with fragment spreads. See the full schema of available [decoded events](/goldrush-streaming-api/decoded-events). --- # Pipeline API Documentation The Pipeline API streams blockchain data into customer-managed destinations (ClickHouse, Kafka, Postgres, S3, SQS, webhooks). Pages include normalizer schemas (per-entity column definitions for EVM, HyperCore, and Solana), destination integration guides, ABI decoding reference, SQL transforms, and end-to-end recipes. ## 1. Event Log Decoding **Path:** goldrush-pipeline-api/abi-decoding/event-decoding **Metadata:** ```yaml title: Event Log Decoding sidebarTitle: Event Decoding description: Decode raw EVM event logs into structured evt_ tables using Solidity ABI event definitions. ``` **Content:** The EventDecoder transforms raw event log rows into structured, typed output tables. Each matched event produces a table named `{chain_name}_evt_{event_name_snake_case}` with columns derived from the event's ABI parameters. ## How It Works **Normalization** The LogsNormalizer upstream produces rows containing `raw_log_topics` (a JSON array of 32-byte hex topics) and `raw_log_data` (a hex-encoded byte string). **Signature Matching** The EventDecoder reads `topics[0]`, which is the keccak256 hash of the event signature (e.g., `Transfer(address,address,uint256)`), and matches it against event entries in the provided ABI file. **Indexed Parameter Decoding** Indexed parameters are decoded from `topics[1..N]`. Each indexed parameter occupies exactly one topic slot. Note that dynamic types (`string`, `bytes`, arrays) produce a keccak256 hash rather than the original value when indexed. **Non-Indexed Parameter Decoding** Non-indexed parameters are ABI-decoded from `raw_log_data` according to standard Solidity ABI encoding rules. **Table Emission** The decoded row is emitted to a table named `{chain_name}_evt_{event_name_snake_case}`. For example, a `Swap` event on the Base chain produces rows in the `base_evt_swap` table. ## Output Schema Every `{chain_name}_evt_` table includes a set of envelope columns inherited from the raw log, followed by the decoded ABI parameters. ### Envelope Columns | Column | Type | Source | |---|---|---| | `block_height` | UINT64 | From logs envelope | | `block_signed_at` | TIMESTAMP | From logs envelope | | `tx_hash` | STRING | From logs envelope | | `log_offset` | UINT32 | From logs envelope | | `contract_address` | STRING | From logs envelope | ### ABI Parameter Columns Each parameter defined in the event ABI becomes an additional column. The column name is the parameter name converted to `snake_case`, and the column type is determined by the [Solidity type mapping](/goldrush-pipeline-api/abi-decoding/reference#solidity-type-mapping). ## Worked Example: Uniswap V3 Swap Consider the Uniswap V3 `Swap` event: ```solidity event Swap( address indexed sender, address indexed recipient, int256 amount0, int256 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick ); ``` - `sender` and `recipient` are **indexed** - decoded from `topics[1]` and `topics[2]`. - `amount0`, `amount1`, `sqrtPriceX96`, `liquidity`, and `tick` are **non-indexed** - decoded from `raw_log_data`. ### Resulting `base_evt_swap` Table | Column | Type | |---|---| | `block_height` | UINT64 | | `block_signed_at` | TIMESTAMP | | `tx_hash` | STRING | | `log_offset` | UINT32 | | `contract_address` | STRING | | `sender` | STRING | | `recipient` | STRING | | `amount0` | STRING | | `amount1` | STRING | | `sqrt_price_x96` | STRING | | `liquidity` | STRING | | `tick` | STRING | > **Note:** Integer types (`int256`, `uint160`, `uint128`, `int24`) are represented as STRING columns to preserve full precision. See the [type mapping reference](/goldrush-pipeline-api/abi-decoding/reference#solidity-type-mapping) for details. ## Indexed Dynamic Types When a dynamic type (`string`, `bytes`, or an array type) is marked as `indexed`, the EVM stores a keccak256 hash of the value in the topic slot rather than the value itself. The EventDecoder writes this hash as a hex string. There is no way to recover the original value from the hash alone. --- ## 2. Function Decoding **Path:** goldrush-pipeline-api/abi-decoding/function-decoding **Metadata:** ```yaml title: Function Decoding sidebarTitle: Function Decoding description: Decode transaction calldata into structured function call tables using Solidity ABI definitions. ``` **Content:** Function decoding transforms raw transaction calldata into structured, typed rows. When configured, the pipeline matches each transaction's input data against ABI function signatures and produces decoded rows in `{chain_name}_fn_{function_name}` tables. ## How It Works 1. The normalizer produces rows for the `transactions` table, each containing an `input_data` field (hex-encoded calldata) 2. The decoder matches the first 4 bytes of `input_data` (the function selector) against ABI function entries 3. Parameters are decoded from `input_data[4:]` using ABI type definitions 4. Each decoded call is emitted to a `{chain_name}_fn_{function_name_snake_case}` table > **Note:** Only `function` ABI entries with `stateMutability` of `nonpayable` or `payable` are used. View and pure functions are excluded since they do not appear in transaction calldata. ## Output Schema Each decoded function table includes envelope columns from the source transaction plus the ABI-defined parameters: | Column | Type | Source | | --- | --- | --- | | `block_height` | UINT64 | From transactions envelope | | `block_signed_at` | TIMESTAMP | From transactions envelope | | `tx_hash` | STRING | From transactions envelope | | `tx_offset` | UINT32 | From transactions envelope | | `from_address` | STRING | From transactions envelope | | `to_address` | STRING | From transactions envelope | | `value` | STRING | From transactions envelope | | `gas_limit` | UINT64 | From transactions envelope | | `receipt_status` | STRING | From transactions envelope | | *(ABI parameters)* | *(mapped type)* | Decoded from calldata | ## Example For an ERC-20 `transfer` function call on Base: ```solidity function transfer(address to, uint256 amount) external returns (bool); ``` The output table `base_fn_transfer` would contain: | Column | Type | | --- | --- | | `block_height` | UINT64 | | `block_signed_at` | TIMESTAMP | | `tx_hash` | STRING | | `tx_offset` | UINT32 | | `from_address` | STRING | | `to_address` | STRING | | `value` | STRING | | `gas_limit` | UINT64 | | `receipt_status` | STRING | | `to` | STRING | | `amount` | STRING | ## Configuration Function decoding is activated by setting the `abi` section in your pipeline config and using a `transactions` topic entity: ```yaml topic: "base.mainnet.ref.block.transactions" abi: path: "/etc/pipeline-api/erc20.json" contract_addresses: - "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" unmatched: "skip" ``` Contract address filtering matches against the `to_address` field (the contract being called). ## When to Use Function Decoding vs Event Decoding | | Event Decoding | Function Decoding | | --- | --- | --- | | **Source** | `logs` topic entity | `transactions` topic entity | | **Decodes** | Emitted event logs | Transaction calldata | | **Output tables** | `{chain_name}_evt_{name}` | `{chain_name}_fn_{name}` | | **Best for** | Tracking state changes, transfers, approvals | Analyzing what functions were called and with what parameters | | **Includes failed txs** | No (failed txs don't emit events) | Yes (calldata exists even if tx reverted) | > **Tip:** Most use cases are better served by event decoding. Use function decoding when you specifically need to analyze calldata - for example, tracking MEV bot calls, analyzing governance proposals, or monitoring specific function invocations regardless of success. --- ## 3. ABI Decoding Overview **Path:** goldrush-pipeline-api/abi-decoding/overview **Metadata:** ```yaml title: ABI Decoding Overview sidebarTitle: Overview description: Transform raw EVM event logs and transaction calldata into structured, typed rows using Solidity ABI definitions. ``` **Content:** ABI decoding is an optional pipeline stage that transforms raw EVM event logs or transaction calldata into structured, typed rows using Solidity ABI definitions. It is activated when an `abi` section is present in your pipeline configuration. ## Applicability ABI decoding only applies to the following topic entities: - **`logs`** - raw event logs emitted by smart contracts. - **`transactions`** - raw transaction calldata submitted to the network. > **Warning:** ABI decoding is incompatible with the Kafka (raw) destination. Pipelines that combine ABI decoding with a Kafka destination are rejected at startup. ## Decoders The pipeline provides two decoders, each responsible for a different entity type: | Decoder | Input Entity | Output Tables | |---|---|---| | **EventDecoder** | `logs` | `{chain_name}_evt_{event_name}` tables | | **FunctionDecoder** | `transactions` | `{chain_name}_fn_{function_name}` tables | ### Data Flow ``` logs stream ──────► EventDecoder ──────► base_evt_swap, base_evt_transfer, ... transactions stream ──► FunctionDecoder ──► base_fn_exact_input_single, base_fn_transfer, ... ``` Raw log or transaction rows flow through the appropriate decoder, which matches each record against the provided ABI. Matched records are emitted into named output tables derived from the event or function name. Unmatched records are either dropped or routed to a raw fallback table, depending on your configuration. ## Configuration Add the `abi` section to your pipeline configuration to enable decoding: ```yaml abi: path: "/etc/pipeline-api/abi.json" contract_addresses: - "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45" unmatched: "skip" ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `path` | string | Yes | -- | Path to the ABI JSON file. Must conform to the standard Solidity ABI JSON format. | | `contract_addresses` | list | No | -- | Optional list of contract addresses to filter on. When omitted, all contracts are decoded. | | `unmatched` | string | No | `skip` | Strategy for records that do not match any ABI entry. `skip` drops the record; `raw_table` writes it to `raw_logs` or `raw_transactions`. | ## Next Steps ### Event Decoding Decode event logs into structured evt_ tables. [Read more](/goldrush-pipeline-api/abi-decoding/event-decoding) ### Function Decoding Decode transaction calldata into structured fn_ tables. [Read more](/goldrush-pipeline-api/abi-decoding/function-decoding) ### Reference ABI file format, type mappings, and filtering behavior. [Read more](/goldrush-pipeline-api/abi-decoding/reference) --- ## 4. ABI Reference **Path:** goldrush-pipeline-api/abi-decoding/reference **Metadata:** ```yaml title: ABI Reference sidebarTitle: Reference description: ABI file format, Solidity type mapping, contract address filtering, and unmatched record handling. ``` **Content:** ## ABI File Format The pipeline accepts standard Solidity ABI JSON files. Only `event` and `function` entries are used - all other entry types (constructor, fallback, receive) are ignored. ```json [ { "type": "event", "name": "Transfer", "inputs": [ { "name": "from", "type": "address", "indexed": true }, { "name": "to", "type": "address", "indexed": true }, { "name": "value", "type": "uint256", "indexed": false } ] }, { "type": "function", "name": "transfer", "stateMutability": "nonpayable", "inputs": [ { "name": "to", "type": "address" }, { "name": "amount", "type": "uint256" } ] } ] ``` You can obtain ABI files from: - Block explorers (Etherscan, Basescan) under the "Contract" tab - Solidity compiler output (`artifacts/` directory) - The `cast interface` command from Foundry > **Tip:** You can combine multiple contract ABIs into a single file. The decoder uses event signature hashes and function selectors for matching, so entries from different contracts do not conflict as long as names are unique. ## Solidity Type Mapping | Solidity Type | Column Type | Notes | | --- | --- | --- | | `address` | STRING | Hex-encoded, checksummed | | `uint8` through `uint256` | STRING | Full precision as decimal strings | | `int8` through `int256` | STRING | Full precision as decimal strings | | `bool` | BOOLEAN | | | `bytes` | STRING | Hex-encoded with `0x` prefix | | `bytes1` through `bytes32` | STRING | Hex-encoded with `0x` prefix | | `string` | STRING | | | `tuple` | JSON | JSON-serialized object | | Arrays (e.g., `uint256[]`) | JSON | JSON-serialized array | > **Note:** All integer types are stored as decimal strings to preserve full precision. Solidity `uint256` values can exceed the range of 64-bit integers, so string representation avoids truncation. ## Contract Address Filtering When `contract_addresses` is specified in the ABI config, only matching records are decoded: | Decoding Mode | Filter Field | Description | | --- | --- | --- | | Event decoding | `contract_address` | The contract that emitted the event | | Function decoding | `to_address` | The contract that was called | When the list is empty or omitted, all records are decoded regardless of contract address. Records from contracts not in the filter list are subject to the `unmatched` strategy. ## Unmatched Records When a log or transaction does not match any ABI signature (either because it's from a non-matching contract or because the signature is not in the ABI file): | `unmatched` Setting | Behavior | | --- | --- | | `skip` (default) | Drop the record silently | | `raw_table` | Write to `raw_logs` or `raw_transactions` table with original columns intact | Use `raw_table` when you want to capture all records and handle unmatched ones separately in your downstream processing. ## Configuration Reference ```yaml abi: path: "/etc/pipeline-api/abi.json" contract_addresses: - "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45" - "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" unmatched: "skip" ``` | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `path` | string | yes | - | Path to ABI JSON file | | `contract_addresses` | list | no | all | Contract address whitelist. Decodes all contracts when empty. | | `unmatched` | string | no | `skip` | How to handle records that don't match any ABI signature | ## Validation The pipeline validates ABI configuration at startup: - ABI file must exist and be valid JSON - ABI file must contain at least one `event` or `function` entry relevant to the topic entity - ABI decoding is only compatible with `logs` and `transactions` topic entities - ABI decoding is incompatible with the Kafka (raw) destination type - Output table names from ABI entries must not collide with each other or with normalizer output tables > **Warning:** If validation fails, the pipeline will not start. Check the error message in the GoldRush Platform dashboard for details on which validation check failed. --- ## 5. Architecture **Path:** goldrush-pipeline-api/architecture **Metadata:** ```yaml title: Architecture sidebarTitle: Architecture description: High-level architecture of the GoldRush Pipeline API, covering structured and raw processing paths, pipeline stages, and delivery guarantees. ``` **Content:** The GoldRush Pipeline API processes blockchain data from the Covalent Database and routes it to your infrastructure. There are two distinct processing paths depending on your use case. ## Processing Paths ``` Covalent Database | +--------------+--------------+ | | Structured Pipeline Raw Pipeline | | Normalization Byte-level | passthrough ABI Decoding (optional) | | Kafka SQL Transforms (optional) | +--+--+--+--+ | | | | | CH PG OS SQS WH CH = ClickHouse PG = Postgres OS = Object Storage SQS = Amazon SQS WH = Webhook ``` ### Structured pipeline Data flows from the Covalent Database through a series of processing stages before landing in your chosen destination: ClickHouse, Postgres, Object Storage, SQS, or Webhook. Each stage is optional except normalization and the final destination. Structured destinations provide **at-least-once** delivery guarantees. ### Raw pipeline Byte-level passthrough directly to a Kafka topic. No normalization, no decoding, no transforms. Use this when you need the lowest latency path to raw block data. The raw pipeline provides **exactly-once** delivery guarantees. ## Processing Stages ### Normalization Converts source data into a consistent tabular schema. Each entity type (logs, transactions, traces, etc.) is mapped to a well-defined set of columns with predictable types. This stage runs on every record in the structured pipeline and cannot be skipped. ### ABI decoding Optionally decodes raw event logs and transaction input data against a provided ABI. Matched entries are expanded into named, typed columns (one table per event or function signature). Unmatched entries can be skipped or routed to a `raw_*` fallback table depending on your configuration. ### SQL transforms Optional SQL statements applied per table after decoding. Use these to filter, project, or reshape data before it reaches the destination. Transforms run as standard SQL against the in-flight table, so you can use `WHERE`, `SELECT`, joins across tables in the same pipeline, and aggregate functions. ### Destination The terminal stage that writes processed data to your destination. Each destination type has its own configuration, batching behavior, and retry semantics. See the individual destination reference pages for details. ## Execution Modes ### Unbounded (continuous streaming) The default mode. The pipeline runs continuously, consuming new data as it arrives. There is no defined stop point. Use this for real-time indexing, monitoring, and any workload that should stay current with the chain. ### Bounded (batch) The pipeline processes data between a start point and a defined stop point, then terminates. Use this for backfills, one-off analyses, or any workload with a known data range. Configure `stop_from` and optionally `stop_offsets` to define the end boundary. > **Note:** Checkpointing is enabled in both modes. If a pipeline restarts, it resumes from the last successful checkpoint rather than reprocessing from the beginning. --- ## 6. Pipeline API Authentication **Path:** goldrush-pipeline-api/authentication **Metadata:** ```yaml title: Pipeline API Authentication sidebarTitle: Authentication description: How authentication works for the GoldRush Pipeline API: platform login, API keys, and ServiceKeys. ``` **Content:** The Pipeline API has three distinct credential types. Picking the right one matters - a regular GoldRush API key cannot create or manage pipelines, and a ServiceKey cannot call the Foundational, Streaming, CLI, or x402 APIs. ## Credential types at a glance | Credential | What it authenticates | Scope | Where used | | --- | --- | --- | --- | | **Platform login** | A human user signing in to the GoldRush Platform UI. | Full account access for that user. | [GoldRush Platform](https://goldrush.dev/platform/) - sign in, billing, creating API keys and ServiceKeys. | | **API key** | A read-only programmatic credential. | Read-only across Foundational, Streaming, CLI, x402. **Cannot manage pipelines.** | `Authorization: Bearer ` on Foundational, Streaming, CLI, x402. | | **ServiceKey** | A programmatic credential scoped to pipeline management. | Full CRUD on pipelines belonging to your group. **Cannot call Foundational, Streaming, CLI, or x402.** | `Authorization: Bearer ` on the [Pipeline REST API](/api-reference/pipeline-api/list-pipelines). | > **Warning:** API keys and ServiceKeys are not interchangeable. Sending a regular API key to a Pipeline REST endpoint returns `403 Forbidden`. Sending a ServiceKey to a Foundational or Streaming endpoint also returns `403`. ## 1. Platform login You authenticate as a user with email/password (or SSO) to access the [GoldRush Platform](https://goldrush.dev/platform/). The Platform is where you: - Configure pipelines through the UI. - Manage billing and your subscription. - Create and rotate API keys. - Create and rotate ServiceKeys. ### Vibe Coders $10/mo - Built for solo builders and AI-native workflows. [Read more](https://goldrush.dev/platform/auth/register/?plan=vibe) ### Teams $250/mo - Production-grade with 50 RPS and priority support. [Read more](https://goldrush.dev/platform/auth/register/?plan=professional) ## 2. API keys (read-only) A regular GoldRush API key is a **read-only** programmatic credential. It works against: - **Foundational API** - REST queries for balances, transactions, NFTs, etc. - **Streaming API** - GraphQL/WebSocket subscriptions and queries. - **CLI** - all `goldrush` commands. - **x402** - pay-per-request proxy. It does **not** work for the Pipeline REST API, and it does not authenticate platform login. ## 3. ServiceKeys (Pipeline CRUD) A ServiceKey is a programmatic credential scoped specifically to pipeline management. Use it to: - List, create, update, pause, resume, and delete pipelines via the REST API. - Poll status, logs, metrics, and destination health. - Drive pipeline configuration from CI/CD, infrastructure-as-code, or scripts. ServiceKeys are issued from the GoldRush Platform and can be rotated or revoked at any time. See [Service Keys](/goldrush-pipeline-api/service-keys) for details. ## Destination credentials Destination credentials (database passwords, webhook tokens, S3 access keys) are part of your **pipeline configuration**, not an authentication mechanism for GoldRush itself. You provide them when creating or updating a pipeline: ```yaml destination: type: "postgres" url: "postgresql://your-host:5432/your-database" user: "${PG_USER}" password: "${PG_PASSWORD}" ``` Destination credentials are stored encrypted, injected at deploy time via environment variable interpolation, and masked as `******` when read back through the REST API. They are never exposed in logs or the UI after being set. > **Note:** Because secrets read back as `******`, never echo them back in a write. Use [`PATCH`](/api-reference/pipeline-api/update-pipeline) to rotate a secret by sending the new value in `destination_config`. ## Error handling | Status | Cause | Resolution | | --- | --- | --- | | `401 Unauthorized` | Missing or malformed `Authorization` header. | Send `Authorization: Bearer `. | | `403 Forbidden` (Pipeline REST) | The credential is a regular API key, not a ServiceKey. | Create a ServiceKey on the Platform and retry. | | `403 Forbidden` (Foundational/Streaming) | The credential is a ServiceKey, not an API key. | Use your regular API key for read endpoints. | | `403 Forbidden` (Pipeline REST, valid ServiceKey) | The ServiceKey does not have access to the requested pipeline. | Confirm the pipeline belongs to the same group as the key. | | Destination credential failure | The pipeline cannot connect to your destination. | Check [destination-health](/api-reference/pipeline-api/get-pipeline-destination-health) and [logs](/api-reference/pipeline-api/get-pipeline-logs). | For a complete guide to error codes, retry strategies, and debugging tips, see [Error Handling & Troubleshooting](/error-handling). ## FAQ - **Can I use the same key for all GoldRush products?** - No. API keys cover the read-only products (Foundational, Streaming, CLI, x402). ServiceKeys cover the Pipeline REST API. Platform login is separate. - **Where do I create a ServiceKey?** - On the [GoldRush Platform](https://goldrush.dev/platform/), under your account settings. See [Service Keys](/goldrush-pipeline-api/service-keys). - **How are destination credentials stored?** - Encrypted at rest, injected at deploy time, masked as `******` on read. They are never exposed in logs or the UI after being set. - **Do I need to allowlist GoldRush IP addresses?** - If your destination is behind a firewall, yes. Contact [support](mailto:support@covalenthq.com) for the current egress IP list. --- ## 7. Configuration Reference **Path:** goldrush-pipeline-api/configuration **Metadata:** ```yaml title: Configuration Reference sidebarTitle: Configuration description: Complete reference for the GoldRush Pipeline API YAML configuration file, including source topics, destinations, ABI decoding, SQL transforms, and execution settings. ``` **Content:** The pipeline reads its configuration from a single YAML file. Secrets can be injected using `${ENV_VAR}` interpolation in destination credential fields. The source is managed by GoldRush -- you only configure the topic, processing options, and destination. ## Minimal Example ```yaml project: "analytics-prod" topic: "base.mainnet.ref.block.logs" destination: type: "postgres" url: "postgresql://db.example.com:5432/analytics" user: "${PG_USER}" password: "${PG_PASSWORD}" ``` ## Top-Level Fields | Field | Type | Required | Description | |---|---|---|---| | `project` | string | yes | Project identifier. Used to derive database schema, consumer group, and checkpoint path. | | `topic` | string | yes | Source topic. Must follow the `{chain}.{network}.{qualifier}.block.{entity}` pattern. | | `destination` | object | yes | Destination configuration. See [Destination Types](#destination-types) below. | | `abi` | object | no | ABI decoding configuration. | | `transforms` | map | no | SQL transforms per table. | | `execution` | object | no | Execution mode and settings. | ## Topic Format Topics follow a strict naming convention: ``` {chain}.{network}.{qualifier}.block.{entity} ``` For example: `base.mainnet.ref.block.logs`, `base.mainnet.ref.block.transactions`. ## Destination Types Each destination type has its own set of required and optional fields. The `type` field within the `destination` object determines which destination is used. | Destination Type | `type` Value | Description | |---|---|---| | ClickHouse | `clickhouse` | Column-oriented analytics database | | Postgres | `postgres` | Relational database | | Object Storage | `object_storage` | S3-compatible blob storage | | Amazon SQS | `sqs` | Message queue | | Webhook | `webhook` | HTTP POST to your endpoint | | Kafka | `kafka` | Raw byte-level passthrough (raw pipeline only) | > **Note:** Each destination type has its own reference page with full configuration details, batching options, and examples. ## ABI Decoding The `abi` object configures optional ABI decoding for event logs and transaction input data. | Field | Type | Required | Description | |---|---|---|---| | `abi.path` | string | yes | Path to the ABI JSON file. | | `abi.contract_addresses` | list | no | Restrict decoding to specific contract addresses. If omitted, all matching signatures are decoded. | | `abi.unmatched` | string | no | Behavior for entries that do not match the ABI. `skip` (default) drops them; `raw` writes them to a `raw_*` fallback table. | ## SQL Transforms The `transforms` map applies SQL statements per output table. Keys are table names (e.g., `evt_swap`, `raw_logs`); values are SQL strings. ```yaml transforms: evt_swap: > SELECT block_number, tx_hash, contract_address, sender, recipient, amount0, amount1 FROM evt_swap WHERE contract_address = '0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45' ``` Transforms run after ABI decoding (if configured) and before the destination stage. Standard SQL is supported, including `WHERE`, `SELECT`, joins across tables within the same pipeline, and aggregate functions. > **Warning:** A SQL syntax error or runtime error in a transform will fail the pipeline. Validate your SQL before deploying. ## Execution The `execution` object controls how the pipeline runs. | Field | Type | Required | Default | Description | |---|---|---|---|---| | `execution.mode` | string | no | `unbounded` | `unbounded` (continuous) or `bounded` (batch). | | `execution.start_from` | string | no | `earliest` | `earliest`, `latest`, or block height. | | `execution.stop_from` | string | no | `never` | `never`, `latest`, or block height. Only meaningful in `bounded` mode. | ## Complete Example ```yaml project: "analytics-prod" topic: "base.mainnet.ref.block.logs" destination: type: "postgres" url: "postgresql://db.example.com:5432/analytics" user: "${PG_USER}" password: "${PG_PASSWORD}" batch_size: 1000 abi: path: "/etc/pipeline-api/uniswap-v3.json" contract_addresses: - "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45" unmatched: "skip" transforms: evt_swap: > SELECT block_number, tx_hash, contract_address, sender, recipient, amount0, amount1 FROM evt_swap WHERE contract_address = '0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45' execution: mode: "unbounded" start_from: "earliest" ``` > **Tip:** Use `${ENV_VAR}` interpolation for all destination credentials. Never commit secrets directly in the YAML file. --- ## 8. ClickHouse **Path:** goldrush-pipeline-api/destinations/clickhouse **Metadata:** ```yaml title: ClickHouse sidebarTitle: ClickHouse description: Configure a ClickHouse destination for the GoldRush Pipeline API to batch-insert structured blockchain data. ``` **Content:** The ClickHouse destination writes structured pipeline output to a ClickHouse database using batch inserts. It supports configurable buffer sizes and flush intervals for throughput tuning. ## Configuration ```yaml destination: type: "clickhouse" url: "clickhouse://host:8123/db" user: "${CH_USER}" password: "${CH_PASSWORD}" batch_size: 10000 flush_interval_ms: 5000 ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `url` | string | yes | -- | JDBC connection URL | | `user` | string | yes | -- | Database user | | `password` | string | yes | -- | Database password | | `batch_size` | int | no | 10,000 | Rows per batch insert | | `flush_interval_ms` | long | no | 5,000 | Max time (ms) between flushes | ## How It Works 1. Rows are buffered in memory as they arrive from the pipeline. 2. When the buffer reaches `batch_size` **or** `flush_interval_ms` elapses since the last flush, a batch `INSERT` executes against the target table. 3. The `INSERT` SQL is dynamically generated from the field names present in each row. 4. All column names are automatically quoted in the generated SQL to handle reserved words. ## Type Coercion The destination maps pipeline data types to ClickHouse column types as follows: | Data Type | Database Handling | |---|---| | String | String column | | Long | Int64 / UInt64 | | Integer | Int32 / UInt32 | | Double | Float64 | | Boolean | Bool / UInt8 | | byte[] | Bytes | | null | Null | --- ## 9. Kafka **Path:** goldrush-pipeline-api/destinations/kafka **Metadata:** ```yaml title: Kafka sidebarTitle: Kafka description: Configure a Kafka destination for the GoldRush Pipeline API to forward raw blockchain data with exactly-once delivery. ``` **Content:** The Kafka destination forwards raw bytes from the pipeline source directly to a target Kafka topic. Unlike other destinations, Kafka operates in **Raw** pipeline mode - no normalization, ABI decoding, or transforms are applied. ## Configuration ```yaml destination: type: "kafka" bootstrap_servers: "broker1:9092,broker2:9092" sasl: mechanism: "SCRAM-SHA-512" username: "${KAFKA_USER}" password: "${KAFKA_PASSWORD}" output_topic: "my-output-topic" ``` ### Fields | Field | Type | Required | Description | |---|---|---|---| | `bootstrap_servers` | string | yes | Target Kafka broker addresses | | `sasl.mechanism` | string | yes | SASL mechanism (e.g., `SCRAM-SHA-512`) | | `sasl.username` | string | yes | SASL username | | `sasl.password` | string | yes | SASL password | | `output_topic` | string | yes | Target topic name | ## Key Behavior - **Raw passthrough** - bytes from the source are forwarded without any processing. No normalization, ABI decoding, or transform stages run. - **Exactly-once delivery** - the destination uses transactional producing to guarantee exactly-once semantics end to end. - **Validation at startup** - if your pipeline configuration includes `abi` or `transforms` sections alongside a Kafka destination, the pipeline will reject the configuration and fail to start. > **Warning:** ABI decoding and transform configurations are not compatible with the Kafka destination. Remove those sections from your pipeline definition before deploying. --- ## 10. Object Storage (S3/GCS/R2) **Path:** goldrush-pipeline-api/destinations/object-storage **Metadata:** ```yaml title: Object Storage (S3/GCS/R2) sidebarTitle: Object Storage description: Configure an Object Storage destination to write structured blockchain data as JSON or Parquet files to S3, GCS, or R2. ``` **Content:** The Object Storage destination writes structured pipeline output as files to S3, Google Cloud Storage, or Cloudflare R2. It supports JSON (NDJSON) and Parquet formats with optional compression and time-based partitioning. ## Configuration ```yaml destination: type: "object_storage" provider: "s3" bucket: "my-bucket" base_path: "pipeline-data" format: "json" compression: "gzip" partition_by: - "hour" batch_size: 10000 batch_interval_ms: 60000 region: "auto" access_key_id: "${AWS_ACCESS_KEY_ID}" secret_access_key: "${AWS_SECRET_ACCESS_KEY}" ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `provider` | string | yes | -- | `s3`, `gcs`, or `r2` | | `bucket` | string | yes | -- | Bucket name | | `base_path` | string | no | -- | Prefix path within bucket | | `format` | string | no | `json` | `json` (NDJSON) or `parquet` | | `compression` | string | no | `none` | `none`, `gzip`, `snappy`, or `zstd` | | `partition_by` | list | no | `["hour"]` | Time partitioning granularity: `hour` or `day` | | `batch_size` | int | no | 10,000 | Records per file | | `batch_interval_ms` | long | no | 60,000 | Max time (ms) between file writes | | `region` | string | yes (S3/R2) | -- | AWS region | | `endpoint` | string | yes (R2) | -- | S3-compatible endpoint URL | | `access_key_id` | string | yes | -- | Access key | | `secret_access_key` | string | yes | -- | Secret key | ## File Layout Files are written using the following path structure: ``` s3://{bucket}/{base_path}/{project}/{stream_name}/year=YYYY/month=MM/day=DD/hour=HH/{file_id}.{ext} ``` The **file ID** uses the format `{partition}-{minOffset}_{maxOffset}-{uuid}`, which enables deduplication on retry. If a write is retried, the same file ID is produced, overwriting the previous attempt rather than creating a duplicate. ## File Extensions | Format | Compression | Extension | |---|---|---| | json | none | `.json` | | json | gzip | `.json.gz` | | json | snappy | `.json.snappy` | | json | zstd | `.json.zst` | | parquet | any | `.parquet` | > **Note:** For Parquet files, compression (snappy or zstd) is applied natively by the Parquet writer and does not change the file extension. For JSON files, compression is applied as a stream wrapper around the output. --- ## 11. Destinations Overview **Path:** goldrush-pipeline-api/destinations/overview **Metadata:** ```yaml title: Destinations Overview sidebarTitle: Overview description: Overview of destination types available in the GoldRush Pipeline API, including delivery guarantees and pipeline modes. ``` **Content:** The GoldRush Pipeline API supports six destination types for delivering processed blockchain data to your infrastructure. Each destination operates in one of two pipeline modes: - **Structured** - Data passes through normalization, optional ABI decoding, and optional transforms before delivery. - **Raw** - Bytes are forwarded directly from the source with no processing. ## Destination Routing Table | Destination Type | Pipeline Mode | Delivery Guarantee | |---|---|---| | [ClickHouse](/goldrush-pipeline-api/destinations/clickhouse) | Structured | At-least-once | | [Postgres](/goldrush-pipeline-api/destinations/postgres) | Structured | At-least-once | | [Kafka](/goldrush-pipeline-api/destinations/kafka) | Raw | Exactly-once | | [Object Storage (S3/GCS/R2)](/goldrush-pipeline-api/destinations/object-storage) | Structured | At-least-once | | [AWS SQS](/goldrush-pipeline-api/destinations/sqs) | Structured | At-least-once | | [Webhook](/goldrush-pipeline-api/destinations/webhook) | Structured | At-least-once | ## Table Naming Convention For database destinations (ClickHouse and Postgres), tables are written to `{schema}.{table}` where: - **schema** is derived from the project name. Hyphens in the project name are converted to underscores (e.g., project `analytics-prod` writes to schema `analytics_prod`). - **table** is the normalizer output table name. > **Warning:** Tables don't need to pre-exist in the target database. The pipeline auto-creates tables. ## Available Destinations ### ClickHouse Batch inserts into ClickHouse with configurable buffer size and flush intervals. [Read more](/goldrush-pipeline-api/destinations/clickhouse) ### Postgres Batch inserts into PostgreSQL with automatic column quoting for reserved words. [Read more](/goldrush-pipeline-api/destinations/postgres) ### Kafka Raw byte passthrough to a Kafka topic with exactly-once transactional delivery. [Read more](/goldrush-pipeline-api/destinations/kafka) ### Object Storage Write JSON or Parquet files to S3, GCS, or R2 with time-based partitioning. [Read more](/goldrush-pipeline-api/destinations/object-storage) ### AWS SQS Deliver records to standard or FIFO SQS queues with built-in deduplication. [Read more](/goldrush-pipeline-api/destinations/sqs) ### Webhook HTTP POST delivery with retry logic, backoff, and idempotency keys. [Read more](/goldrush-pipeline-api/destinations/webhook) --- ## 12. Postgres **Path:** goldrush-pipeline-api/destinations/postgres **Metadata:** ```yaml title: Postgres sidebarTitle: Postgres description: Configure a Postgres destination for the GoldRush Pipeline API to batch-insert structured blockchain data. ``` **Content:** The Postgres destination writes structured pipeline output to a PostgreSQL database using batch inserts. It follows the same batching model as the ClickHouse destination with defaults tuned for PostgreSQL workloads. ## Configuration ```yaml destination: type: "postgres" url: "postgresql://host:5432/db" user: "${PG_USER}" password: "${PG_PASSWORD}" batch_size: 1000 flush_interval_ms: 5000 ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `url` | string | yes | -- | JDBC connection URL | | `user` | string | yes | -- | Database user | | `password` | string | yes | -- | Database password | | `batch_size` | int | no | 1,000 | Rows per batch insert | | `flush_interval_ms` | long | no | 5,000 | Max time (ms) between flushes | ## How It Works 1. Rows are buffered in memory as they arrive from the pipeline. 2. When the buffer reaches `batch_size` **or** `flush_interval_ms` elapses since the last flush, a batch `INSERT` executes against the target table. 3. The `INSERT` SQL is dynamically generated from the field names present in each row. 4. All column names are automatically quoted in the generated SQL to handle PostgreSQL reserved words such as `user`, `from`, and `order`. --- ## 13. AWS SQS **Path:** goldrush-pipeline-api/destinations/sqs **Metadata:** ```yaml title: AWS SQS sidebarTitle: SQS description: Configure an AWS SQS destination for the GoldRush Pipeline API to deliver structured blockchain data to standard or FIFO queues. ``` **Content:** The AWS SQS destination delivers structured pipeline output as messages to an Amazon SQS queue. It supports both standard and FIFO queues with built-in deduplication. ## Configuration ```yaml destination: type: "sqs" queue_url: "https://sqs.us-east-1.amazonaws.com/123456789/my-queue.fifo" region: "auto" access_key_id: "${AWS_ACCESS_KEY_ID}" secret_access_key: "${AWS_SECRET_ACCESS_KEY}" batch_size: 10 message_group_id: "" ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `queue_url` | string | yes | -- | SQS queue URL | | `region` | string | yes | -- | AWS region | | `access_key_id` | string | yes | -- | AWS access key | | `secret_access_key` | string | yes | -- | AWS secret key | | `batch_size` | int | no | 10 | Messages per batch (max 10) | | `message_group_id` | string | no | auto-derived | FIFO message group ID | ## FIFO Queue Detection FIFO mode is automatically activated when either condition is met: - The `queue_url` ends with `.fifo` - A `message_group_id` value is explicitly set When FIFO mode is active, the destination sets the `MessageGroupId` and `MessageDeduplicationId` on every message. ## Message Format Each message is a JSON object containing the project, stream name, and the record payload: ```json { "project": "analytics-prod", "stream": "hl_fills", "record": { "block_number": 12345, "...": "..." } } ``` ### Message Attributes Each SQS message includes the following message attributes: | Attribute | Type | Description | |---|---|---| | `project` | String | Project name | | `stream` | String | Stream name | | `block_number` | String | Block number, if present in the record | ## Deduplication For FIFO queues, the deduplication ID is deterministically derived from source metadata using the format: ``` {topic}-{partition}-{offset} ``` This ensures that retried deliveries do not produce duplicate messages in the queue. --- ## 14. Webhook **Path:** goldrush-pipeline-api/destinations/webhook **Metadata:** ```yaml title: Webhook sidebarTitle: Webhook description: Configure a Webhook destination for the GoldRush Pipeline API to deliver structured blockchain data via HTTP with retry and idempotency. ``` **Content:** The Webhook destination delivers structured pipeline output to an HTTP endpoint. It supports configurable batching, retry with exponential backoff, and idempotency keys for safe retries. ## Configuration ```yaml destination: type: "webhook" url: "https://api.example.com/events" method: "POST" headers: Authorization: "Bearer ${WEBHOOK_TOKEN}" Content-Type: "application/json" batch_size: 1 timeout_ms: 10000 retry: max_attempts: 3 backoff_ms: 1000 ``` ### Fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | `url` | string | yes | -- | Webhook endpoint URL | | `method` | string | no | `POST` | HTTP method | | `headers` | map | no | -- | Custom HTTP headers | | `batch_size` | int | no | 1 | Records per request | | `timeout_ms` | long | no | 10,000 | Request timeout (ms) | | `retry.max_attempts` | int | no | 3 | Max retry attempts | | `retry.backoff_ms` | long | no | 1,000 | Initial backoff delay (ms) | ## Payload Format The request body format depends on the `batch_size` setting. ### Single-record payload (`batch_size` = 1) ```json { "project": "analytics-prod", "stream": "hl_fills", "record": { "..." } } ``` ### Batched payload (`batch_size` > 1) ```json { "project": "analytics-prod", "stream": "hl_fills", "records": [ { "..." }, { "..." } ], "count": 2 } ``` ## Idempotency Every request includes an `X-Idempotency-Key` header derived from source metadata, allowing your endpoint to safely deduplicate retried deliveries. | Mode | Key Format | |---|---| | Single record | `{topic}-{partition}-{offset}` | | Batch | `{topic}-{partition}-{minOffset}_{maxOffset}` | ## Retry Behavior The destination retries failed requests using exponential backoff. The initial delay is set by `retry.backoff_ms` and doubles on each subsequent attempt, up to `retry.max_attempts`. | Response | Action | |---|---| | 2xx | Success - record acknowledged | | 429 | Retry, honoring `Retry-After` header if present; otherwise use backoff | | 5xx | Retry with exponential backoff | | 4xx (not 429) | Permanent failure - batch is skipped | --- ## 15. Error Handling **Path:** goldrush-pipeline-api/error-handling **Metadata:** ```yaml title: Error Handling sidebarTitle: Error Handling description: Error handling behavior for each stage of the GoldRush Pipeline API, including retry policies, failure modes, and monitoring. ``` **Content:** Each stage of the pipeline has defined behavior for error conditions. Transient errors are retried automatically; permanent errors either skip the offending record or fail the pipeline depending on severity. ## Normalization | Scenario | Behavior | |---|---| | Corrupt or unknown protobuf | Skip record, increment error counter, log warning. | | Unknown event variant | Skip event, increment error counter, continue processing. | Normalization errors are non-fatal. Individual records that cannot be parsed are dropped, and the pipeline continues. Error counters track the volume of skipped records for monitoring. ## ABI Decoding | Scenario | Behavior | |---|---| | Matched signature, bad data | Skip entry, increment error counter, log warning. | | Unmatched ABI entry | Skip or write to `raw_*` table, depending on the `abi.unmatched` config value. | > **Note:** If `abi.unmatched` is set to `raw`, unmatched entries are written to a fallback table (e.g., `raw_logs`) rather than being dropped. This is useful for auditing or debugging incomplete ABIs. ## Transforms | Scenario | Behavior | |---|---| | SQL runtime error | Fail pipeline. | Transform errors are treated as configuration errors and are always fatal. A malformed or invalid SQL statement will halt the pipeline immediately. Validate your transforms before deploying to production. > **Warning:** Transform failures are not retried. Fix the SQL in your configuration file and redeploy the pipeline. ## Destination Destination error handling varies by destination type. Transient failures are retried with exponential backoff. Permanent failures either skip the batch or fail the pipeline. ### Database destinations (ClickHouse, Postgres) | Scenario | Behavior | |---|---| | Transient write failure (timeout, connection reset) | Retry with exponential backoff. | | Permanent write failure (schema mismatch, constraint violation) | Fail pipeline. | ### Object Storage | Scenario | Behavior | |---|---| | Upload failure | Retry with exponential backoff. | ### Amazon SQS | Scenario | Behavior | |---|---| | Transient failure (throttling, temporary unavailability) | Retry with exponential backoff. | | Permanent failure (invalid queue, authorization error) | Fail pipeline. | ### Webhook | Scenario | Behavior | |---|---| | 2xx response | Success. | | 429 (Too Many Requests) | Retry with exponential backoff. Respects `Retry-After` header if present. | | 5xx (Server Error) | Retry with exponential backoff. | | 4xx (Client Error, not 429) | Permanent failure. Skip batch. | > **Tip:** Return a `Retry-After` header with 429 responses to control the backoff interval. Without it, the pipeline uses its default exponential backoff schedule. ## Monitoring Pipeline error counters and status are available through the GoldRush Platform dashboard and the [Pipeline REST API](/goldrush-pipeline-api/rest-api/overview). Use either to: - Track skipped record counts per stage - see [`metrics`](/api-reference/pipeline-api/get-pipeline-metrics) (`normalization_errors`). - Monitor throughput and lag - see [`metrics`](/api-reference/pipeline-api/get-pipeline-metrics) (`records_per_second`, `processing_delay_ms`, `pending_records`). - Detect destination outages - see [`destination-health`](/api-reference/pipeline-api/get-pipeline-destination-health). - Read worker logs for fatal errors - see [`logs`](/api-reference/pipeline-api/get-pipeline-logs). - Confirm runtime deployment phase (`DEPLOYING` / `RUNNING` / `FAILED`) - see [`status`](/api-reference/pipeline-api/get-pipeline-status). > **Note:** When a pipeline fails due to a permanent error, it stops consuming new data and preserves its last checkpoint. After you fix the underlying issue, the pipeline resumes from the last successful checkpoint on restart. --- ## 16. Decode Uniswap V3 Swaps **Path:** goldrush-pipeline-api/guides/decode-uniswap-swaps **Metadata:** ```yaml title: Decode Uniswap V3 Swaps sidebarTitle: Uniswap V3 Swaps description: Capture every Uniswap V3 swap event on Base Mainnet as structured rows in your Postgres database using GoldRush Pipeline API. ``` **Content:** ## Use Case Uniswap V3 is one of the highest-volume DEX protocols on Base. If you are building trading analytics, monitoring liquidity, or tracking volume trends, you need a reliable stream of decoded swap events landing in a queryable database. This guide walks you through configuring a pipeline that: - Subscribes to decoded log events on Base Mainnet - Filters for the Uniswap V3 `Swap` event using ABI decoding - Writes structured swap rows into a Postgres table ## Prerequisites - A GoldRush API key with Pipeline API access - A Postgres database reachable from the internet (or via VPN peering) - The Uniswap V3 Pool ABI (the `Swap` event signature) ## Pipeline Configuration The following YAML is generated by the GoldRush Platform when you complete the setup steps below. ```yaml project: "uniswap-analytics" topic: "base.mainnet.ref.block.logs" destination: type: "postgres" url: "postgresql://your-host:5432/analytics" user: "${PG_USER}" password: "${PG_PASSWORD}" batch_size: 1000 abi: path: "uniswap-v3-pool.json" contract_addresses: - "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45" unmatched: "skip" transforms: base_evt_swap: > SELECT block_height, block_signed_at, tx_hash, contract_address, sender, recipient, amount0, amount1, sqrt_price_x96, liquidity, tick FROM base_evt_swap ``` ### Key Configuration Details | Field | Purpose | |-------|---------| | `topic` | `base.mainnet.ref.block.logs` delivers all decoded log events on Base Mainnet. | | `abi.path` | Points to the Uniswap V3 Pool ABI. The platform provides common ABIs; you can also upload your own. | | `abi.contract_addresses` | Restricts decoding to the specified contract. Add more addresses to cover additional pools. | | `abi.unmatched` | Set to `skip` so that log events not matching the ABI are silently dropped. | | `transforms.base_evt_swap` | A SQL transform that selects specific columns from the decoded `evt_swap` table. | | `destination.batch_size` | Rows are flushed to Postgres in batches of 1,000 for throughput. | ### ABI Snippet The pipeline uses the `Swap` event from the Uniswap V3 Pool contract: ```json { "anonymous": false, "inputs": [ { "indexed": true, "name": "sender", "type": "address" }, { "indexed": true, "name": "recipient", "type": "address" }, { "indexed": false, "name": "amount0", "type": "int256" }, { "indexed": false, "name": "amount1", "type": "int256" }, { "indexed": false, "name": "sqrtPriceX96", "type": "uint160" }, { "indexed": false, "name": "liquidity", "type": "uint128" }, { "indexed": false, "name": "tick", "type": "int24" } ], "name": "Swap", "type": "event" } ``` ## Deploy via the GoldRush Platform **Create a new pipeline** Log in to the [GoldRush Platform](https://goldrush.dev/platform/) and navigate to **Manage Pipeline API** in the left sidebar. Click **Create Pipeline**. **Configure the Postgres destination** Select **Postgres** as the destination type. Enter your JDBC connection URL, and use environment variable references (`${PG_USER}`, `${PG_PASSWORD}`) for credentials. Set **Batch size** to `1000`. **Select source topic** Choose **Base Mainnet** as the network and **Block Logs** (`base.mainnet.ref.block.logs`) as the data topic. **Configure ABI decoding** In the **ABI Decoding** section, select the built-in **Uniswap V3 Pool** ABI or upload your own JSON ABI file. Enter the contract address `0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45`. Set **Unmatched events** to **Skip**. **Add a SQL transform** In the **Transforms** section, add a transform for the `base_evt_swap` output table. Paste the SQL SELECT statement from the configuration above to project only the columns you need. **Deploy** Review the generated YAML configuration, then click **Create**. The pipeline will begin consuming events within a few seconds. ## Verify the Pipeline Once the pipeline is running, connect to your Postgres database and confirm that data is arriving: ```sql -- Check row count SELECT COUNT(*) FROM evt_swap; -- View the most recent swaps SELECT block_height, tx_hash, sender, recipient, amount0, amount1, tick FROM evt_swap ORDER BY block_height DESC LIMIT 10; -- Aggregate swap volume over the last hour SELECT DATE_TRUNC('minute', block_signed_at) AS minute, COUNT(*) AS swap_count, SUM(ABS(amount0)) AS total_amount0 FROM evt_swap WHERE block_signed_at > NOW() - INTERVAL '1 hour' GROUP BY 1 ORDER BY 1 DESC; ``` ## Tips ### Scaling for production Increase `batch_size` to 5,000 or higher if your Postgres instance can handle larger write batches. This reduces the number of round trips and improves throughput during high-volume periods. ### Monitoring multiple pools Add additional contract addresses to the `abi.contract_addresses` list to capture swaps across multiple Uniswap V3 pools in a single pipeline. ### Indexing for query performance Create indexes on `block_height`, `tx_hash`, and `contract_address` in your Postgres table to speed up common analytical queries. ### Handling schema changes If the ABI changes (for example, a new version of the pool contract), create a new pipeline with the updated ABI. The platform does not modify existing table schemas automatically. --- ## 17. Hyperliquid Trades to ClickHouse **Path:** goldrush-pipeline-api/guides/hyperliquid-trades **Metadata:** ```yaml title: Hyperliquid Trades to ClickHouse sidebarTitle: Hyperliquid Trades description: Stream Hyperliquid fill and trade data into ClickHouse for real-time trading analytics dashboards. ``` **Content:** ## Use Case You want to build a real-time trading analytics dashboard by streaming Hyperliquid fill events into ClickHouse. This gives you sub-second query performance over high-volume trading data for PnL tracking, volume analysis, and market monitoring. ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `hl-analytics`. **Select your source** Choose **Hyperliquid** as the chain and **Fills** as the data type. This streams every order fill event from Hyperliquid. **Configure the ClickHouse destination** Select **ClickHouse** as the destination type and enter your connection details: ```yaml destination: type: "clickhouse" url: "clickhouse://your-host:8123/analytics" user: "${CH_USER}" password: "${CH_PASSWORD}" batch_size: 10000 ``` **Add a SQL transform (optional)** Add a transform to filter for specific trading pairs and map side codes to human-readable labels: ```yaml transforms: hl_fills: > SELECT block_number, block_time, user_address, coin, px, sz, fee, CASE WHEN side = 'B' THEN 'buy' ELSE 'sell' END AS trade_side, closed_pnl, tid FROM hl_fills WHERE coin IN ('ETH', 'BTC', 'SOL') ``` **Deploy** Review and deploy. Fill events begin flowing to ClickHouse within seconds. ## Verify Data ```sql SELECT coin, trade_side, count(*) AS fills, sum(toFloat64OrZero(sz)) AS total_size FROM hl_analytics.hl_fills WHERE block_time >= now() - INTERVAL 1 HOUR GROUP BY coin, trade_side ORDER BY total_size DESC; ``` ## Sample Analytical Queries **Volume by coin over the last 24 hours:** ```sql SELECT coin, count(*) AS trade_count, sum(toFloat64OrZero(sz) * toFloat64OrZero(px)) AS volume_usd FROM hl_analytics.hl_fills WHERE block_time >= toString(now() - INTERVAL 24 HOUR) GROUP BY coin ORDER BY volume_usd DESC; ``` **Top traders by realized PnL:** ```sql SELECT user_address, sum(toFloat64OrZero(closed_pnl)) AS total_pnl, count(*) AS fill_count FROM hl_analytics.hl_fills WHERE closed_pnl != '0' AND closed_pnl != '' GROUP BY user_address ORDER BY total_pnl DESC LIMIT 20; ``` ## Production Tips - **Batch size**: ClickHouse performs best with large inserts. The default of 10,000 rows per batch is a good starting point. Increase to 50,000+ for high-throughput streams. - **ORDER BY key**: Choose columns that match your most common query patterns. `(coin, block_number)` works well for time-series analytics by trading pair. - **Trades vs Fills**: Use the `fills` entity for per-user fill data (includes PnL, fees). Use the `trades` entity for aggregate market trades (includes buyer/seller details). --- ## 18. Track PumpFun Swaps on Solana **Path:** goldrush-pipeline-api/guides/pumpfun-swaps **Metadata:** ```yaml title: Track PumpFun Swaps on Solana sidebarTitle: PumpFun Swaps description: Monitor PumpFun token swaps on Solana to track bonding curve activity, token launches, and graduation events. ``` **Content:** ## Use Case You want to track PumpFun activity on Solana - token launches, swaps on bonding curves, and graduation events. This data powers trading dashboards, token launch trackers, and bonding curve analytics. ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `pumpfun-tracker`. **Configure the Postgres destination** Select **Postgres** as the destination type and enter your connection details: ```yaml destination: type: "postgres" url: "postgresql://your-host:5432/solana_data" user: "${PG_USER}" password: "${PG_PASSWORD}" batch_size: 1000 ``` **Select your source** Choose **Solana** as the chain and **Pump.fun Events** as the data type. This streams all PumpFun lifecycle events: token creates, swaps, completions, and withdrawals. **Add a SQL transform (optional)** Filter swaps to only include specific columns: ```yaml transforms: sol_pf_swap: > SELECT user, mint, bonding_curve, sol_amount, token_amount, direction, virtual_sol_reserves, virtual_token_reserves FROM sol_pf_swap ``` **Deploy** Review and deploy. PumpFun events begin flowing to your Postgres database. ## Output Tables The PumpFun normalizer routes events to 4 tables based on event type: | Event | Table | Description | | --- | --- | --- | | Token Create | `sol_pf_create` | New token launches with bonding curve parameters | | Swap | `sol_pf_swap` | Buy/sell swaps on the bonding curve | | Complete | `sol_pf_complete` | Bonding curve graduation (migration to DEX) | | Withdraw | `sol_pf_withdraw` | Liquidity withdrawals | ## Verify Data ```sql -- Recent swaps SELECT mint, direction, sol_amount, token_amount, virtual_sol_reserves FROM pumpfun_tracker.sol_pf_swap ORDER BY sol_amount DESC LIMIT 20; ``` ## Sample Analytical Queries **Most traded tokens by swap count:** ```sql SELECT mint, count(*) AS swap_count, sum(CASE WHEN direction = 'buy' THEN 1 ELSE 0 END) AS buys, sum(CASE WHEN direction = 'sell' THEN 1 ELSE 0 END) AS sells FROM pumpfun_tracker.sol_pf_swap GROUP BY mint ORDER BY swap_count DESC LIMIT 20; ``` **Tokens that graduated (completed bonding curve):** ```sql SELECT c.mint, c.bonding_curve, cr.name, cr.symbol FROM pumpfun_tracker.sol_pf_complete c JOIN pumpfun_tracker.sol_pf_create cr ON c.mint = cr.mint ORDER BY cr.name; ``` **Bonding curve progression for a specific token:** ```sql SELECT direction, sol_amount, token_amount, virtual_sol_reserves, virtual_token_reserves FROM pumpfun_tracker.sol_pf_swap WHERE mint = 'your-token-mint-address' ORDER BY virtual_sol_reserves; ``` ## Production Tips - **All 4 tables** receive data from a single pipeline. You do not need separate pipelines for creates, swaps, and completions. - **Bonding curve math**: The `virtual_sol_reserves` and `virtual_token_reserves` fields track the bonding curve state after each swap. Use these to reconstruct price curves. - **High volume**: PumpFun generates significant swap volume. Consider using ClickHouse instead of Postgres if you need to run analytical queries over millions of swaps. --- ## 19. Real-Time DEX Analytics **Path:** goldrush-pipeline-api/guides/real-time-dex-analytics **Metadata:** ```yaml title: Real-Time DEX Analytics sidebarTitle: DEX Analytics description: Stream decoded Solana DEX trade data into ClickHouse to build real-time analytics dashboards for volume, pricing, and trader activity. ``` **Content:** ## Use Case You want to build a real-time DEX analytics dashboard by streaming trade data across multiple Solana DEX protocols (Raydium, Orca, Meteora, PumpFun, and others) into ClickHouse. The `dex_trades` entity aggregates trades from all supported protocols into a single, unified schema. ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `dex-analytics`. **Configure the ClickHouse destination** Select **ClickHouse** as the destination type: ```yaml destination: type: "clickhouse" url: "clickhouse://your-host:8123/dex_data" user: "${CH_USER}" password: "${CH_PASSWORD}" batch_size: 10000 flush_interval_ms: 3000 ``` **Select your source** Choose **Solana** as the chain and **Swaps** as the data type. This streams every decoded DEX trade across all supported Solana protocols. **Add a SQL transform (optional)** Filter out dust trades and select the most useful columns: ```yaml transforms: swaps: > SELECT block_slot, block_date, tx_id, pool_address, base_mint, quote_mint, base_amount, quote_amount, price_usd, volume_usd, protocol_name, trader, txn_fee_lamports FROM swaps WHERE volume_usd > 10 ``` **Deploy** Review and deploy. DEX trades begin streaming to ClickHouse. ## Verify Data ```sql SELECT protocol_name, count(*) AS trades, sum(volume_usd) AS total_volume FROM dex_analytics.sol_dex_trades WHERE block_date = today() GROUP BY protocol_name ORDER BY total_volume DESC; ``` ## Sample Dashboard Queries **Volume by protocol over the last 24 hours:** ```sql SELECT protocol_name, count(*) AS trade_count, sum(volume_usd) AS volume_usd, avg(volume_usd) AS avg_trade_size FROM dex_analytics.sol_dex_trades WHERE block_date >= toString(today() - 1) GROUP BY protocol_name ORDER BY volume_usd DESC; ``` **Top pools by volume:** ```sql SELECT pool_address, base_mint, quote_mint, protocol_name, count(*) AS trades, sum(volume_usd) AS volume_usd FROM dex_analytics.sol_dex_trades WHERE block_date = today() GROUP BY pool_address, base_mint, quote_mint, protocol_name ORDER BY volume_usd DESC LIMIT 20; ``` **OHLCV aggregation for a token (5-minute candles):** ```sql SELECT toStartOfFiveMinutes(parseDateTimeBestEffort(block_date)) AS candle_time, min(price_usd) AS low, max(price_usd) AS high, argMin(price_usd, block_slot) AS open, argMax(price_usd, block_slot) AS close, sum(volume_usd) AS volume FROM dex_analytics.sol_dex_trades WHERE base_mint = 'your-token-mint' AND block_date >= toString(today()) GROUP BY candle_time ORDER BY candle_time; ``` **Most active traders:** ```sql SELECT trader, count(*) AS trade_count, sum(volume_usd) AS total_volume, countDistinct(base_mint) AS unique_tokens FROM dex_analytics.sol_dex_trades WHERE block_date = today() GROUP BY trader ORDER BY total_volume DESC LIMIT 20; ``` ## Production Tips - **Flush interval**: A 3-second flush interval keeps dashboard data fresh. Increase to 5-10 seconds if write throughput becomes a bottleneck. - **volume_usd > 10 filter**: Removes dust trades that add noise to analytics. Adjust the threshold based on your use case. - **Protocol coverage**: The `sol_dex_trades` entity aggregates trades from all supported Solana protocols. The `protocol_name` column identifies the source (Raydium, Orca, Meteora, etc.). - **Materialized views**: For high-frequency dashboard queries, consider ClickHouse materialized views to pre-aggregate data by time bucket and protocol. --- ## 20. Filter Stablecoins Transfers **Path:** goldrush-pipeline-api/guides/stablecoin-transfers **Metadata:** ```yaml title: Filter Stablecoins Transfers sidebarTitle: Stablecoin Transfers description: Stream filtered ERC-20 stablecoin token transfers with SQL transforms for compliance monitoring or whale watching. ``` **Content:** ## Use Case You want to stream only USDC transfers on Base Mainnet into Postgres, with amounts converted from raw units to human-readable values. This is useful for compliance monitoring, whale watching, or building token-specific analytics. ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `usdc-whale-watch`. **Configure the Postgres destination** Select **Postgres** as the destination type: ```yaml destination: type: "postgres" url: "postgresql://your-host:5432/compliance" user: "${PG_USER}" password: "${PG_PASSWORD}" batch_size: 500 ``` **Select your source** Choose **Base Mainnet** as the chain and **Transfers** as the data type. This streams every token and native transfer on Base. **Add a SQL transform** Filter to USDC transfers only and convert the raw amount to a human-readable decimal value. USDC on Base has 6 decimals: ```yaml transforms: transfers: > SELECT block_height, block_signed_at, tx_hash, from_address, to_address, CAST(amount AS DOUBLE) / 1000000 AS amount_usdc FROM transfers WHERE contract_address = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' ``` **Deploy** Review and deploy. Only USDC transfers flow to your database - all other tokens are filtered out before reaching the destination. ## How the Transform Works The SQL transform runs inside the pipeline, before data reaches your database: 1. **WHERE clause** filters to only transfers where the `contract_address` matches USDC on Base 2. **CAST and arithmetic** converts the raw `amount` (stored as a string of the integer value in smallest units) to a `DOUBLE` divided by 10^6 3. **SELECT** projects only the columns you need, reducing storage This means your Postgres database only stores the data you care about - no wasted writes for irrelevant tokens. ## Verify Data ```sql SELECT block_height, tx_hash, from_address, to_address, amount_usdc FROM usdc_whale_watch.transfers ORDER BY amount_usdc DESC LIMIT 20; ``` ## Extending to Multiple Tokens To track multiple tokens, expand the WHERE clause with an IN filter: ```yaml transforms: transfers: > SELECT block_height, block_signed_at, tx_hash, contract_address, from_address, to_address, amount FROM transfers WHERE contract_address IN ( '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', '0x4200000000000000000000000000000000000006', '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb' ) ``` > **Tip:** When tracking multiple tokens with different decimal places, keep the raw `amount` as a string and handle decimal conversion in your application layer instead. ## Production Tips - **Batch size**: A smaller batch size (500) is appropriate here because the SQL transform filters out most records, resulting in lower write throughput to the destination. - **Indexing**: Add indexes on `from_address`, `to_address`, and `amount_usdc` for common query patterns. - **Alerting**: Combine this pipeline with a simple cron job or application query to trigger alerts when `amount_usdc` exceeds a threshold. --- ## 21. Stream to S3 as Parquet **Path:** goldrush-pipeline-api/guides/stream-to-s3-parquet **Metadata:** ```yaml title: Stream to S3 as Parquet sidebarTitle: S3 Parquet Export description: Archive blockchain data as partitioned Parquet files in S3 for analytics with tools like Athena, Spark, or DuckDB. ``` **Content:** ## Use Case You want to archive Base Mainnet block data as partitioned Parquet files in Amazon S3. Once stored, you can query the data with tools like AWS Athena, Apache Spark, or DuckDB without running any database infrastructure. ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `block-archive`. **Configure the Object Storage Destination** Select **Object Storage** as the destination type. Enter your S3 credentials and configure the file format: **Select Your Source** Choose **Base Mainnet** as the chain and **Blocks** as the data type. This streams block headers and metadata from every Base block. **Review your configuration** ```yaml destination: type: "object_storage" provider: "s3" bucket: "my-blockchain-data" base_path: "base-mainnet" format: "parquet" compression: "snappy" partition_by: - "day" batch_size: 50000 batch_interval_ms: 300000 region: "auto" access_key_id: "${AWS_ACCESS_KEY_ID}" secret_access_key: "${AWS_SECRET_ACCESS_KEY}" ``` **Deploy** Review and deploy the pipeline. Data begins writing to S3 as partitioned Parquet files. ## File Layout Once running, files appear in S3 with this structure: ``` s3://my-blockchain-data/base-mainnet/block-archive/blocks/ year=2025/ month=03/ day=18/ 0-1000_50000-abc123.parquet 0-50001_100000-def456.parquet day=19/ ... ``` Each file contains up to 50,000 records. The file ID encodes the partition, offset range, and a UUID for deduplication on retry. ## Query with DuckDB You can query the Parquet files directly without loading them into a database: ```sql -- Install and load the httpfs extension for S3 access INSTALL httpfs; LOAD httpfs; SET s3_region = 'auto'; SET s3_access_key_id = 'your-key'; SET s3_secret_access_key = 'your-secret'; -- Query block data SELECT height, miner_address, gas_used, gas_limit, transaction_count, signed_at FROM read_parquet('s3://my-blockchain-data/base-mainnet/block-archive/blocks/year=2025/month=03/day=18/*.parquet') ORDER BY height DESC LIMIT 20; ``` ## Compression Options | Format | Compression | Best For | | --- | --- | --- | | Parquet + Snappy | Fast reads, moderate compression | Interactive queries (Athena, DuckDB) | | Parquet + Zstd | Higher compression ratio | Long-term archival, storage cost optimization | | JSON + Gzip | Human-readable, widely compatible | Debugging, simple consumers | > **Tip:** Parquet with Snappy is the best default for most analytics workloads. It balances compression ratio, read speed, and broad tool compatibility. ## Production Tips - **Batch size**: Larger batches (50,000+) produce fewer, larger files - better for query performance. Smaller batches (1,000-5,000) reduce latency to S3. - **Partition by day** for archival workloads. Use **hour** if you need finer-grained partitions for time-range queries. - **GCS and R2**: Change `provider` to `gcs` or `r2` and update credentials accordingly. R2 requires an `endpoint` field. --- ## 22. Webhook Notifications for Transfers **Path:** goldrush-pipeline-api/guides/webhook-notifications **Metadata:** ```yaml title: Webhook Notifications for Transfers sidebarTitle: Webhook Notifications description: Get real-time HTTP notifications for ERC-20 token transfers to trigger alerts in your application. ``` **Content:** ## Use Case You want to receive HTTP notifications whenever a specific ERC-20 token is transferred on Base Mainnet. This enables real-time alerting, event-driven workflows, or feeding data into systems that consume webhooks (Slack, PagerDuty, custom backends). ## Pipeline Configuration **Create a new pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `transfer-alerts`. **Configure the webhook destination** Select **Webhook** as the destination type and configure your endpoint: ```yaml destination: type: "webhook" url: "https://api.yourapp.com/webhooks/transfers" headers: Authorization: "Bearer ${WEBHOOK_TOKEN}" Content-Type: "application/json" batch_size: 1 timeout_ms: 5000 retry: max_attempts: 5 backoff_ms: 2000 ``` **Select your source** Choose **Base Mainnet** as the chain and **Transfers** as the data type. This streams every token transfer event. **Add a SQL transform to filter** Filter to only USDC transfers on Base (contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`): ```yaml transforms: transfers: > SELECT block_height, block_signed_at, tx_hash, contract_address, from_address, to_address, amount FROM transfers WHERE contract_address = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' ``` **Deploy** Review and deploy. Your webhook endpoint begins receiving POST requests for each matching transfer. ## Webhook Payload Each transfer arrives as a JSON POST request: ```json { "project": "transfer-alerts", "stream": "transfers", "record": { "block_height": 28451023, "block_signed_at": "2025-03-18T14:22:05Z", "tx_hash": "0xabc123...", "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "from_address": "0x1234...", "to_address": "0x5678...", "amount": "1000000000" } } ``` The request includes an `X-Idempotency-Key` header for deduplication on your end. ## Handling Idempotency Every webhook request includes an `X-Idempotency-Key` header with a deterministic value based on the source record's position. Store this key and check for duplicates before processing: ```javascript app.post('/webhooks/transfers', (req, res) => { const idempotencyKey = req.headers['x-idempotency-key']; // Check if already processed if (await cache.has(idempotencyKey)) { return res.status(200).json({ status: 'duplicate' }); } // Process the transfer const { record } = req.body; await processTransfer(record); // Mark as processed await cache.set(idempotencyKey, true, { ttl: 86400 }); res.status(200).json({ status: 'ok' }); }); ``` > **Warning:** Always return a 2xx status code promptly. The pipeline retries on 5xx and 429 responses with exponential backoff. A 4xx response (other than 429) causes the batch to be permanently skipped. ## Retry Behavior | Response | Pipeline Action | | --- | --- | | 2xx | Success, move to next record | | 429 | Retry with `Retry-After` header if present, else exponential backoff | | 5xx | Retry with exponential backoff | | 4xx (not 429) | Permanent failure, skip and log | ## Production Tips - **batch_size: 1** sends one transfer per HTTP request - simplest to handle. Increase to 5-10 for higher throughput if your endpoint supports batch payloads. - **timeout_ms**: Set this lower than your endpoint's actual timeout to allow for retry overhead. 5,000 ms is a good default. - **Filtering**: The SQL transform runs before the webhook, so you only pay for HTTP requests on records that match your filter. Add multiple WHERE conditions to narrow further. --- ## 23. EVM Normalizers **Path:** goldrush-pipeline-api/normalizers/evm **Metadata:** ```yaml title: EVM Normalizers sidebarTitle: EVM description: Column-level schema reference for EVM normalizers. ``` **Content:** EVM normalizers process block data into structured, typed rows for EVM chains. Each normalizer maps a single entity type to a single output table with a fixed column schema. ## BlocksNormalizer **Entity:** `blocks` | **Output table:** `blocks` | Column | Type | Description | | --- | --- | --- | | `chain_name` | STRING | Blockchain name | | `height` | UINT64 | Block number | | `block_hash` | STRING | Block hash (hex) | | `block_parent_hash` | STRING | Parent block hash (hex) | | `nonce` | UINT64 | Block nonce | | `transactions_root` | STRING | Transactions trie root (hex) | | `state_root` | STRING | State trie root (hex) | | `miner_address` | STRING | Miner/validator address (hex) | | `difficulty` | STRING | Block difficulty (big integer) | | `total_difficulty` | STRING | Cumulative difficulty (big integer) | | `size` | UINT64 | Block size in bytes | | `extra_data` | STRING | Extra data field (hex) | | `gas_limit` | UINT64 | Gas limit | | `gas_used` | UINT64 | Gas used | | `signed_at` | TIMESTAMP | Block timestamp (ISO 8601) | | `transaction_count` | UINT32 | Number of transactions | | `base_fee_per_gas` | STRING | EIP-1559 base fee (big integer) | | `withdrawals_root` | STRING | Withdrawals trie root (hex) | | `logs_bloom` | STRING | Bloom filter (hex) | | `blob_gas_used` | UINT64 | EIP-4844 blob gas used | | `excess_blob_gas` | UINT64 | EIP-4844 excess blob gas | | `parent_beacon_block_root` | STRING | Beacon chain parent root (hex) | ## TracesNormalizer **Entity:** `traces` | **Output table:** `traces` | Column | Type | Description | | --- | --- | --- | | `block_height` | UINT64 | Block number | | `block_hash` | STRING | Block hash (hex) | | `block_signed_at` | TIMESTAMP | Block timestamp | | `chain_name` | STRING | Blockchain name | | `tx_hash` | STRING | Transaction hash (hex) | | `tx_offset` | UINT32 | Transaction index in block | | `from_address` | STRING | Caller address (hex) | | `to_address` | STRING | Callee address (hex) | | `value` | STRING | ETH value transferred (big integer) | | `method_id` | STRING | 4-byte function selector (hex) | | `input_data` | STRING | Call input data (hex) | | `output_data` | STRING | Call output data (hex) | | `trace_type` | STRING | Trace type (call, create, suicide) | | `call_type` | STRING | Call type (call, delegatecall, staticcall) | | `gas_limit` | UINT64 | Gas limit for this call | | `gas_used` | UINT64 | Gas used by this call | | `subtraces` | UINT32 | Number of child traces | | `trace_address` | JSON | Position in trace tree (e.g., [0,1,2]) | | `error` | STRING | Error message if failed | | `status` | STRING | Execution status | | `trace_id` | STRING | Unique trace identifier | ## TransactionsNormalizer **Entity:** `transactions` | **Output table:** `transactions` | Column | Type | Description | | --- | --- | --- | | `block_height` | UINT64 | Block number | | `block_hash` | STRING | Block hash (hex) | | `block_signed_at` | TIMESTAMP | Block timestamp | | `chain_name` | STRING | Blockchain name | | `tx_hash` | STRING | Transaction hash (hex) | | `nonce` | UINT64 | Sender's nonce | | `tx_offset` | UINT32 | Transaction index in block | | `from_address` | STRING | Sender address (hex) | | `to_address` | STRING | Recipient address (hex) | | `value` | STRING | ETH value (big integer) | | `gas_limit` | UINT64 | Gas limit | | `gas_price` | STRING | Gas price (big integer) | | `input_data` | STRING | Transaction input data (hex) | | `max_fee_per_gas` | STRING | EIP-1559 max fee (big integer) | | `max_priority_fee_per_gas` | STRING | EIP-1559 max priority fee (big integer) | | `receipt_status` | STRING | Transaction receipt status | | `type` | STRING | Transaction type | | `blob_versioned_hashes` | JSON | EIP-4844 blob hashes (JSON array) | | `access_list` | JSON | EIP-2930 access list (JSON array) | ## LogsNormalizer **Entity:** `logs (alias: `log`)` | **Output table:** `logs` | Column | Type | Description | | --- | --- | --- | | `block_height` | UINT64 | Block number | | `block_signed_at` | TIMESTAMP | Block timestamp | | `block_hash` | STRING | Block hash (hex) | | `block_parent_hash` | STRING | Parent block hash (hex) | | `chain_name` | STRING | Blockchain name | | `miner_address` | STRING | Miner address (hex) | | `gas_used` | UINT64 | Block gas used | | `gas_limit` | UINT64 | Block gas limit | | `tx_hash` | STRING | Transaction hash (hex) | | `tx_offset` | UINT32 | Transaction index | | `log_offset` | UINT32 | Log index within transaction | | `contract_address` | STRING | Emitting contract (hex) | | `raw_log_data` | STRING | Log data field (hex) | | `raw_log_topics` | JSON | Log topics array (JSON of hex strings) | ## ReceiptsNormalizer **Entity:** `receipts` | **Output table:** `receipts` | Column | Type | Description | | --- | --- | --- | | `block_height` | UINT64 | Block number | | `block_hash` | STRING | Block hash (hex) | | `block_signed_at` | TIMESTAMP | Block timestamp | | `chain_name` | STRING | Blockchain name | | `receipt_root_hash` | STRING | Receipts trie root (hex) | | `tx_hash` | STRING | Transaction hash (hex) | | `tx_offset` | UINT32 | Transaction index | | `receipt_status` | UINT32 | Receipt status (0=fail, 1=success) | | `output_data` | STRING | Return data (hex) | | `receipt_gas_used` | UINT64 | Gas used by transaction | | `receipt_cumulative_gas_used` | UINT64 | Cumulative gas used in block | | `receipt_effective_gas_price` | STRING | Effective gas price (big integer) | | `receipt_blob_gas_used` | UINT64 | EIP-4844 blob gas used | | `receipt_blob_gas_price` | STRING | EIP-4844 blob gas price | | `receipt_state_root` | STRING | Post-tx state root (hex) | | `receipt_contract_address` | STRING | Created contract address (hex) | ## TransfersNormalizer **Entity:** `transfers (alias: `transfer`)` | **Output table:** `transfers` | Column | Type | Description | | --- | --- | --- | | `block_height` | UINT64 | Block number | | `block_signed_at` | TIMESTAMP | Block timestamp | | `chain_name` | STRING | Blockchain name | | `tx_hash` | STRING | Transaction hash (hex) | | `tx_offset` | UINT32 | Transaction index | | `log_offset` | UINT32 | Log index | | `contract_address` | STRING | Token contract address (hex) | | `from_address` | STRING | Sender address (hex) | | `to_address` | STRING | Recipient address (hex) | | `token_id` | STRING | NFT token ID (big integer) | | `amount` | STRING | Transfer amount (big integer) | ## SwapsNormalizer **Entity:** `swaps` | **Output table:** `swaps` | Column | Type | Description | | --- | --- | --- | | `chain_name` | STRING | Blockchain name | | `block_signed_at` | TIMESTAMP | Block timestamp (ISO 8601) | | `block_height` | UINT64 | Block number | | `block_hash` | STRING | Block hash (hex) | | `tx_hash` | STRING | Transaction hash (hex) | | `log_offset` | UINT32 | Log index within transaction | | `tx_offset` | UINT32 | Transaction index within block | | `pair_address` | STRING | DEX pair contract address (hex) | | `topic0` | STRING | Event signature hash (hex) | | `topic1` | STRING | Indexed parameter 1 (hex) | | `topic2` | STRING | Indexed parameter 2 (hex) | | `topic3` | STRING | Indexed parameter 3 (hex) | | `data_raw` | STRING | Complete raw log data (hex) | | `protocol` | STRING | Protocol name (e.g., "uniswap_v2") | | `removed` | BOOLEAN | Removed flag (chain reorganization) | | `token0` | STRING | Token0 address (hex) | | `token1` | STRING | Token1 address (hex) | | `reserve0` | STRING | Reserve0 from Sync event (Uniswap V2) | | `reserve1` | STRING | Reserve1 from Sync event (Uniswap V2) | --- ## 24. HyperCore Normalizers **Path:** goldrush-pipeline-api/normalizers/hypercore **Metadata:** ```yaml title: HyperCore Normalizers sidebarTitle: HyperCore description: Schema reference for HyperCore normalizers including fills, trades, orders, and miscellaneous protocol events. ``` **Content:** HyperCore normalizers process trading and protocol event data from the HyperCore chain into structured tables. The `miscevents` normalizer routes events to one of 6 tables based on the event type. ## FillsNormalizer **Entity:** `fills` | **Table:** `hl_fills` Each fill represents one side of a matched order. | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `stream` | STRING | Stream identifier | | `user_address` | STRING | User address | | `coin` | STRING | Trading pair | | `px` | STRING | Price | | `sz` | STRING | Size | | `side` | STRING | Buy/Sell | | `time` | STRING | Fill time | | `start_position` | STRING | Starting position | | `dir` | STRING | Direction | | `closed_pnl` | STRING | Closed PnL | | `hash` | STRING | Fill hash | | `oid` | UINT64 | Order ID | | `crossed` | BOOLEAN | Whether fill crossed spread | | `fee` | STRING | Trading fee | | `tid` | UINT64 | Trade ID | | `fee_token` | STRING | Fee token | | `builder_fee` | STRING | Builder fee (optional) | | `cloid` | STRING | Client order ID (optional) | | `twap_id` | UINT64 | TWAP ID (optional) | | `builder` | STRING | Builder address (optional) | | `liquidation_user` | STRING | Liquidated user | | `liquidation_mark_px` | STRING | Mark price at liquidation | | `liquidation_method` | STRING | Liquidation method | Liquidation fields are null when no liquidation occurred. ## TradesNormalizer **Entity:** `trades` | **Tables:** 2 tables The TradesNormalizer produces two fan-out tables from each matched trade: a raw passthrough (`hl_trades`) and an enriched table (`hl_enriched_trades`) with derived market metadata. Users can disable either table via the transforms block. ### hl_trades | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `stream` | STRING | Stream identifier | | `coin` | STRING | Trading pair or coin code (e.g. `BTC`, `PURR/USDC`, `@107`, `nanofunds:USDAI`, `#350`) | | `px` | STRING | Trade price | | `sz` | STRING | Trade size | | `side` | STRING | Aggressor side | | `time` | STRING | Trade time | | `tid` | UINT64 | Trade ID | | `hash` | STRING | Trade hash | | `users` | JSON | Array of user addresses | | `buyer_json` | JSON | Buyer fill details (JSON) | | `seller_json` | JSON | Seller fill details (JSON) | ### hl_enriched_trades | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `stream` | STRING | Stream identifier | | `coin` | STRING | Raw trading pair or coin code | | `px` | STRING | Trade price | | `sz` | STRING | Trade size | | `side` | STRING | Aggressor side | | `time` | STRING | Trade time | | `tid` | UINT64 | Trade ID | | `hash` | STRING | Trade hash | | `users` | JSON | Array of user addresses | | `buyer_json` | JSON | Buyer fill details (JSON) | | `seller_json` | JSON | Seller fill details (JSON) | | `base_symbol` | STRING | Resolved base asset symbol (e.g. `ETH`, `PURR`, `#350`). Null for unresolvable spot-index codes. | | `market_name` | STRING | Human-readable market name (e.g. `ETH-USD`, `PURR/USDC`, `#350`) | | `market_type` | STRING | Market classification: `perp`, `spot`, or `prediction` | | `usd_amount` | STRING | Notional trade value (`px × sz`) | | `buyer_address` | STRING | Buyer wallet address (first element of `users`) | | `seller_address` | STRING | Seller wallet address (second element of `users`) | | `is_hip3` | BOOLEAN | True if the coin is a HIP-3 deployable perp DEX market (e.g. `nanofunds:USDAI`) | | `is_hip4` | BOOLEAN | True if the coin is a HIP-4 prediction market (e.g. `#350`) | ## OrdersNormalizer **Entity:** `orders` | **Table:** `hl_orders` Order lifecycle events including placements, cancellations, and fills. | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `stream` | STRING | Stream identifier | | `builder` | STRING | Builder address (optional) | | `hash` | STRING | Order event hash (optional) | | `time` | STRING | Order time | | `user` | STRING | User address | | `status` | STRING | Order status | | `coin` | STRING | Trading pair | | `side` | STRING | Buy/Sell | | `oid` | UINT64 | Order ID | | `limit_px` | STRING | Limit price | | `sz` | STRING | Order size | | `orig_sz` | STRING | Original order size | | `timestamp` | INT64 | Order timestamp | | `order_type` | STRING | Order type | | `tif` | STRING | Time in force | | `reduce_only` | BOOLEAN | Reduce-only flag | | `is_trigger` | BOOLEAN | Trigger order flag | | `is_position_tpsl` | BOOLEAN | Position TP/SL flag | | `trigger_condition` | STRING | Trigger condition | | `trigger_px` | STRING | Trigger price | | `cloid` | STRING | Client order ID (optional) | | `children_json` | JSON | Child orders (JSON array) | ## MiscEventsNormalizer **Entity:** `miscevents` | **Tables:** 6 tables The MiscEvents normalizer routes each event to the appropriate table based on its type: | Event Type | Output Table | | --- | --- | | Deposit | `hl_deposits` | | Withdrawal | `hl_withdrawals` | | Delegation | `hl_delegations` | | Validator Rewards | `hl_validator_rewards` | | Funding | `hl_funding` | | Ledger Update | `hl_ledger_updates` | ### hl_deposits | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `user` | STRING | Depositor address | | `amount` | STRING | Deposit amount | ### hl_withdrawals | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `user` | STRING | Withdrawer address | | `amount` | STRING | Withdrawal amount | | `is_finalized` | BOOLEAN | Whether withdrawal is finalized | ### hl_delegations | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `user` | STRING | Delegator address | | `validator` | STRING | Validator address | | `amount` | STRING | Delegation amount | | `is_undelegate` | BOOLEAN | Whether this is an undelegation | ### hl_validator_rewards | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `validator` | STRING | Validator address | | `reward` | STRING | Reward amount | ### hl_funding | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `coin` | STRING | Funding coin | | `szi` | STRING | Size | | `funding_rate` | STRING | Funding rate | | `funding_amount` | STRING | Funding amount | | `user` | STRING | Trader address | ### hl_ledger_updates | Column | Type | Description | | --- | --- | --- | | `block_number` | UINT64 | Block number | | `block_time` | STRING | Block timestamp | | `hash` | STRING | Event hash | | `users` | JSON | Array of user addresses | | `delta_type` | STRING | Ledger delta variant name | | `delta_json` | JSON | Serialized ledger delta details | > **Note:** The `delta_type` field identifies the ledger operation. Supported types include: Withdraw, Deposit, VaultCreate, VaultDeposit, VaultWithdraw, VaultDistribution, VaultLeaderCommission, Liquidation, InternalTransfer, SubAccountTransfer, SpotTransfer, SpotGenesis, RewardsClaim, AccountActivationGas, AccountClassTransfer, PerpDexClassTransfer, DeployGasAuction, Send, CStakingTransfer, and BorrowLend. --- ## 25. Normalizers Overview **Path:** goldrush-pipeline-api/normalizers/overview **Metadata:** ```yaml title: Normalizers Overview sidebarTitle: Overview description: Understand how normalizers convert raw blockchain data into structured, typed rows for downstream consumption. ``` **Content:** ## What are normalizers? Normalizers are the transformation layer in the GoldRush Pipeline. They convert raw blockchain data into structured, typed rows that can be written to any configured destination. Each normalizer is responsible for a single entity type and produces one or more output tables with a well-defined column schema. ### Key properties - **Auto-resolved**: Each normalizer is automatically resolved from the topic entity name. There is no manual mapping or registration step required. - **One normalizer per entity type**: The mapping between entity names and normalizers is 1:1. Subscribing to a topic with entity `blocks` will always route through `BlocksNormalizer`. - **Typed columns**: Every output column carries an explicit type. Downstream destinations use these types for schema creation, serialization, and query optimization. ## Column types All normalizer output columns use one of the following types: | Type | Description | |---|---| | `STRING` | UTF-8 string value | | `UINT64` | Unsigned 64-bit integer | | `INT64` | Signed 64-bit integer | | `UINT32` | Unsigned 32-bit integer | | `INT32` | Signed 32-bit integer | | `BOOLEAN` | Boolean (`true` / `false`) | | `BYTES` | Raw byte array | | `DOUBLE` | 64-bit IEEE 754 floating-point number | | `TIMESTAMP` | Timestamp value (ISO 8601) | | `STRING_ARRAY` | Array of strings | | `JSON` | Arbitrary JSON value | ## Normalizer registry The table below lists every normalizer, the entity name that triggers it, the output table(s) it produces, and the chain family it belongs to. {/* BEGIN:REGISTRY — auto-generated by s/convert-normalizers.js. Do not edit manually. */} | Entity | Normalizer | Output Table | Chain | |---|---|---|---| | `blocks` | BlocksNormalizer | `blocks` | EVM | | `traces` | TracesNormalizer | `traces` | EVM | | `transactions` | TransactionsNormalizer | `transactions` | EVM | | `logs` | LogsNormalizer | `logs` | EVM | | `receipts` | ReceiptsNormalizer | `receipts` | EVM | | `transfers` | TransfersNormalizer | `transfers` | EVM | | `swaps` | SwapsNormalizer | `swaps` | EVM | | `fills` | FillsNormalizer | `hl_fills` | HyperCore | | `trades` | TradesNormalizer | `hl_trades`, `hl_enriched_trades` | HyperCore | | `orders` | OrdersNormalizer | `hl_orders` | HyperCore | | `miscevents` | MiscEventsNormalizer | `hl_deposits`, `hl_withdrawals`, `hl_delegations`, `hl_validator_rewards`, `hl_funding`, `hl_ledger_updates` | HyperCore | | `swaps` | SwapsNormalizer | `swaps` | Solana | | `transfers` | TransfersNormalizer | `transfers` | Solana | {/* END:REGISTRY */} > **Note:** Some normalizers produce multiple output tables by routing records based on an event type discriminator within the raw data. See the chain-specific reference pages for full column schemas. --- ## 26. Solana Normalizers **Path:** goldrush-pipeline-api/normalizers/solana **Metadata:** ```yaml title: Solana Normalizers sidebarTitle: Solana description: Schema reference for Solana normalizers covering DEX trades, PumpFun events, Raydium, Moonshot, Meteora, SPL transfers, and wallet positions. ``` **Content:** Solana normalizers process decoded DeFi protocol data into structured tables. The data covers DEX trades across multiple protocols, token launch events, pool creation, SPL token transfers, and wallet position tracking. ## SwapsNormalizer **Entity:** `swaps` | **Table:** `swaps` Aggregated DEX trade events across all supported Solana protocols. Each row is a single trade with unified fields regardless of the originating protocol. | Column | Type | Description | | --- | --- | --- | | `block_date` | STRING | Block date | | `block_time` | INT64 | Block timestamp | | `block_slot` | UINT64 | Slot number | | `tx_id` | STRING | Transaction signature | | `signer` | STRING | Transaction signer | | `pool_address` | STRING | DEX pool address | | `base_mint` | STRING | Base token mint address | | `quote_mint` | STRING | Quote token mint address | | `base_vault` | STRING | Base token vault | | `quote_vault` | STRING | Quote token vault | | `base_amount` | DOUBLE | Base token amount | | `quote_amount` | DOUBLE | Quote token amount | | `is_inner_instruction` | BOOLEAN | Whether this is an inner instruction | | `instruction_index` | UINT32 | Instruction index | | `instruction_type` | STRING | Instruction type | | `inner_instruction_index` | UINT32 | Inner instruction index | | `outer_program` | STRING | Outer program ID | | `inner_program` | STRING | Inner program ID | | `txn_fee_lamports` | UINT64 | Transaction fee in lamports | | `signer_lamports_change` | INT64 | Signer SOL balance change | | `trader` | STRING | Trader address | | `spl_token_decimals` | INT32 | SPL token decimals | | `user_spl_token_pre_balance` | UINT64 | Pre-trade token balance (optional) | | `user_spl_token_post_balance` | UINT64 | Post-trade token balance (optional) | | `liquidity_sol` | UINT64 | Pool SOL liquidity (optional) | | `liquidity_token` | UINT64 | Pool token liquidity (optional) | | `sequence_number` | UINT64 | Sequence number | | `protocol_name` | STRING | DEX protocol name | | `price` | DOUBLE | Trade price | | `volume` | DOUBLE | Trade volume | | `price_usd` | DOUBLE | Trade price in USD | | `volume_usd` | DOUBLE | Trade volume in USD | ## TransfersNormalizer **Entity:** `transfers` | **Table:** `transfers` SPL token transfers with full source and destination account details. | Column | Type | Description | | --- | --- | --- | | `block_time` | INT64 | Block timestamp | | `block_slot` | UINT64 | Slot number | | `slot` | UINT64 | Slot number | | `tx_hash` | STRING | Transaction signature | | `transfer_index` | UINT64 | Transfer sequence number | | `mint` | STRING | Token mint address | | `amount` | UINT64 | Transfer amount (raw) | | `is_raw_amount` | BOOLEAN | Whether amount is in raw units | | `token_decimals` | UINT32 | Token decimals | | `source_address` | STRING | Source token account | | `source_owner` | STRING | Source account owner | | `source_pre_balance` | UINT64 | Source pre-transfer balance | | `source_post_balance` | UINT64 | Source post-transfer balance | | `source_pre_balance_ui` | DOUBLE | Source pre-balance (UI amount) | | `source_post_balance_ui` | DOUBLE | Source post-balance (UI amount) | | `destination_address` | STRING | Destination token account | | `destination_owner` | STRING | Destination account owner | | `destination_pre_balance` | UINT64 | Dest pre-transfer balance | | `destination_post_balance` | UINT64 | Dest post-transfer balance | | `destination_pre_balance_ui` | DOUBLE | Dest pre-balance (UI amount) | | `destination_post_balance_ui` | DOUBLE | Dest post-balance (UI amount) | --- ## 27. Pipeline API Overview **Path:** goldrush-pipeline-api/overview **Metadata:** ```yaml title: Pipeline API Overview sidebarTitle: 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. ``` **Content:** The Pipeline API pushes structured blockchain data directly to your infrastructure. Instead of polling an API, you configure a pipeline once and data flows continuously into your database, warehouse, queue, or webhook - decoded, transformed, and ready to query. ## Architecture ```mermaid graph LR subgraph Source A[Covalent Database] end subgraph Pipeline["GoldRush Pipeline"] B[Normalization] --> C[ABI Decoding] C --> D[SQL Transforms] end subgraph Destinations["Your Destination"] E[ClickHouse] F[Postgres] G[Kafka] H[S3 / GCS / R2] I[SQS] J[Webhook] end A --> B D --> E D --> F D --> G D --> H D --> I D --> J ``` ## How It Works **Create a New Pipeline** Log in to the [GoldRush Platform](https://goldrush.dev/platform/) and navigate to **Manage Pipelines**. Click **Create New Pipeline**. **Select your Destination Type** Select a destination type - ClickHouse, Postgres, Kafka, Object Storage (S3/GCS/R2), AWS SQS, or Webhook - and provide your connection credentials. You can also test if the Pipeline API can connect to your destination successfully. **Select your Data Object Type** Choose a chain and data type. Pick from event logs, transactions, token transfers, or protocol-specific data streams like HyperCore fills or Solana DEX trades. **Select your Data Range** Configure the block range for your pipeline. Your pipeline can run in both bounded (with start/end block heights) as well as unbounded mode for continuously delivering data. **Apply SQL transforms and ABI decoding** Optionally add SQL transforms to filter rows, select specific columns, or compute derived fields before data reaches your destination. Aditionally you can also provide ABI definitions to decode raw event logs or call data into structured, typed columns. **Deploy and monitor** Review your configuration, deploy the pipeline, and monitor throughput and status from the Pipelines dashboard. Data begins flowing in real time. ## Destination Types ### ClickHouse Stream data into ClickHouse for high-performance analytical queries over large volumes of blockchain data. [Read more](/goldrush-pipeline-api/destinations/clickhouse) ### Postgres Push decoded blockchain data into Postgres for application backends and transactional workloads. [Read more](/goldrush-pipeline-api/destinations/postgres) ### Kafka Publish raw data to Kafka topics for downstream consumers, stream processing, and event-driven architectures. [Read more](/goldrush-pipeline-api/destinations/kafka) ### Object Storage Write data to S3, GCS, or Cloudflare R2 as Parquet or JSON files for data lake and batch processing workflows. [Read more](/goldrush-pipeline-api/destinations/object-storage) ### AWS SQS Deliver events to SQS queues for reliable, decoupled message processing with at-least-once delivery. [Read more](/goldrush-pipeline-api/destinations/sqs) ### Webhook Receive HTTP POST callbacks for each event, enabling lightweight integrations without managing infrastructure. [Read more](/goldrush-pipeline-api/destinations/webhook) ## Key Features ### ABI Decoding Automatically decode raw EVM event logs into structured, typed columns using standard Solidity ABI definitions. [Read more](/goldrush-pipeline-api/abi-decoding/overview) ### SQL Transforms Apply SQL expressions to filter rows, select specific columns, or compute derived fields before data reaches your destination. Reduce storage costs and processing overhead at the source. [Read more](/goldrush-pipeline-api/sql-transforms) ### Protocol-Native Schemas Purpose-built normalizers for HyperCore and Solana DEX data that produce clean, protocol-aware tables and not raw byte arrays. [Read more](/goldrush-pipeline-api/normalizers/overview) ## Manage pipelines programmatically Pipelines can be managed through the [GoldRush Platform UI](https://goldrush.dev/platform/) or the [Pipeline REST API](/goldrush-pipeline-api/rest-api/overview). The REST API exposes the same operations - create, update, pause, resume, delete, and inspect status, logs, metrics, and destination health - and is authenticated with a [ServiceKey](/goldrush-pipeline-api/service-keys). ## Supported Chains {/* BEGIN:CHAINS — auto-generated by s/convert-normalizers.js. Do not edit by hand. */} | Chain | Status | | --- | --- | | Ethereum | Live | | Polygon | Live | | BNB Smart Chain (BSC) | Live | | Avalanche C-Chain | Live | | Optimism | Live | | Fantom | Live | | ADI Chain | Live | | Arbitrum | Live | | Axie/Ronin | Live | | Base | Live | | Blast | Live | | Celo | Live | | HyperCore | Live | | HyperEVM | Live | | Ink | Live | | Monad | Live | | Moonbeam | Live | | Scroll | Live | | Solana | Live | | zkSync Era | Live | {/* END:CHAINS */} > **Note:** For the full list of supported chains and available data entities, see the [Supported Chains](/goldrush-pipeline-api/supported-chains) page. ## Pipeline API vs Foundational and Streaming Each GoldRush API serves a different access pattern. Choose based on how your application consumes data. | | Foundational API | Streaming API | Pipeline API | | --- | --- | --- | --- | | **Pattern** | Pull (REST) | Push (WebSocket) | Push (to your infra) | | **Best for** | On-demand queries, wallet lookups, historical data | Real-time UI updates, trading bots, live feeds | Data warehousing, analytics, ETL, backend indexing | | **Data delivery** | Request/response | WebSocket subscription | Continuous destination delivery | | **Destination** | Your application | Your application | Your database, warehouse, queue, or webhook | | **Transforms** | None (query parameters only) | None (filter on subscribe) | SQL transforms, ABI decoding, normalizers | > **Tip:** Use the **Foundational API** when you need data on demand. Use the **Streaming API** when you need real-time events in your application. Use the **Pipeline API** when you need blockchain data flowing continuously into your own infrastructure. --- ## 28. Pipeline API Quickstart **Path:** goldrush-pipeline-api/quickstart **Metadata:** ```yaml title: Pipeline API Quickstart sidebarTitle: Quickstart description: Learn how to create your first GoldRush Pipeline to stream blockchain data into your own database. ``` **Content:** ## Prerequisites Using any of the GoldRush developer tools requires an API key. ### Vibe Coders $10/mo - Built for solo builders and AI-native workflows. [Read more](https://goldrush.dev/platform/auth/register/?plan=vibe) ### Teams $250/mo - Production-grade with 50 RPS and priority support. [Read more](https://goldrush.dev/platform/auth/register/?plan=professional) You will also need a running Postgres instance that is accessible from the internet. Have your connection host, port, database name, username, and password ready. ## Create Your First Pipeline This walkthrough creates a pipeline that streams decoded EVM log events from Base Mainnet into a Postgres database. Log in to the [GoldRush Platform](https://goldrush.dev/platform/) and navigate to **Manage Pipelines** in the left sidebar. Click **Create New Pipeline** to open the pipeline builder. Select the PostgreSQL Destination Type Configure your PostgreSQL Connection with your connection url, username and password. Test your connection to see if the Pipeline API can connect to your PostgreSQL. Under EVM Chains, pick **Base** as your chain and EVM Log Events as your object type. Choose a source topic to define what blockchain data your pipeline will ingest. Select **Base Mainnet** as the chain and **EVM Block Logs** as the data type. This maps to the topic `base.mainnet.ref.block.logs`, which emits every log event from every block on Base Mainnet in real time. Since we want to continuously stream data, we will pick **Unbounded** and set the starting block height to be 30,000,000. Pick an existing project (or create a new project) to group this pipeline under. For the ABI decoding, upload the [ERC20 ABI](https://gist.github.com/veox/8800debbf56e24718f9f483e1e40c35c). Review your configuration and click "Create Pipeline" to deploy your pipeline. ## Under the Hood ### Generated YAML Configuration The platform UI generates a YAML configuration for each pipeline. The pipeline you just created produces a config equivalent to this: ```yaml # Pipeline Configuration project: "research" topic: "base.mainnet.ref.block.logs" # Destination destination: type: "postgres" url: "postgresql://hosted.postgreshost.com" user: "goldrush" password: "••••••••" # Execution execution: mode: "unbounded" start_from: "earliest" # ABI Decoding abi: files: - "erc20.json" unmatched: "skip" ``` The `topic` field determines the chain and data type. Destination credentials are injected as environment variables at deploy time so they are never stored in plaintext. ## Next Steps ### ABI Decoding Automatically decode raw log data into human-readable event fields. [Read more](/goldrush-pipeline-api/abi-decoding/overview) ### SQL Transforms Filter and reshape data in-flight with SQL before it reaches your destination. [Read more](/goldrush-pipeline-api/sql-transforms) ### Destination Types Explore all supported destination types beyond Postgres. [Read more](/goldrush-pipeline-api/destinations/overview) ### Guides End-to-end tutorials for common pipeline patterns. [Read more](/goldrush-pipeline-api/guides/decode-uniswap-swaps) ### REST API Manage pipelines programmatically with a [ServiceKey](/goldrush-pipeline-api/service-keys) - create, update, monitor, and delete from CI/CD or scripts. [Read more](/goldrush-pipeline-api/rest-api/overview) --- ## 29. Pipeline REST API **Path:** goldrush-pipeline-api/rest-api/overview **Metadata:** ```yaml title: Pipeline REST API sidebarTitle: Overview description: The Pipeline REST API lets you create, update, monitor, and delete pipelines programmatically - everything the Platform UI does, scripted. ``` **Content:** The Pipeline REST API exposes the same operations as the **Manage Pipelines** view in the GoldRush Platform: list pipelines, create new ones, edit configuration, pause and resume, and inspect runtime state. Use it when you want pipelines to be managed by code - infrastructure-as-code, CI/CD, internal tooling - rather than by hand in the UI. ## Base URL ``` https://api.covalenthq.com/platform/pipeline-api/ ``` ## Authentication All endpoints require a [ServiceKey](/goldrush-pipeline-api/service-keys) sent as a bearer token. Regular GoldRush API keys are rejected with `403`. ```bash curl https://api.covalenthq.com/platform/pipeline-api/ \ -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" ``` ## Endpoints ### List pipelines `GET /platform/pipeline-api/` - paginated list of pipelines visible to your ServiceKey. [Read more](/api-reference/pipeline-api/list-pipelines) ### Create a pipeline `POST /platform/pipeline-api/` - create from a JSON config that mirrors the YAML schema. [Read more](/api-reference/pipeline-api/create-pipeline) ### Get a pipeline `GET /platform/pipeline-api/{id}/` - fetch a single pipeline. Secrets returned as `******`. [Read more](/api-reference/pipeline-api/get-pipeline) ### Set pipeline status `PUT /platform/pipeline-api/{id}/` - pause or resume by flipping `status`. [Read more](/api-reference/pipeline-api/set-pipeline-status) ### Update a pipeline `PATCH /platform/pipeline-api/{id}/` - partial update of any writeable field. [Read more](/api-reference/pipeline-api/update-pipeline) ### Delete a pipeline `DELETE /platform/pipeline-api/{id}/` - permanent removal. [Read more](/api-reference/pipeline-api/delete-pipeline) ### Status `GET /platform/pipeline-api/{id}/status/` - runtime deployment phase. [Read more](/api-reference/pipeline-api/get-pipeline-status) ### Logs `GET /platform/pipeline-api/{id}/logs/` - recent worker log lines. [Read more](/api-reference/pipeline-api/get-pipeline-logs) ### Metrics `GET /platform/pipeline-api/{id}/metrics/` - throughput and lag snapshot. [Read more](/api-reference/pipeline-api/get-pipeline-metrics) ### Destination health `GET /platform/pipeline-api/{id}/destination-health/` - last connectivity check. [Read more](/api-reference/pipeline-api/get-pipeline-destination-health) ## Response envelope Every response follows the standard GoldRush envelope: ```json { "data": { /* endpoint-specific payload */ }, "error": false, "error_message": null, "error_code": null } ``` List endpoints add `pagination` alongside `items`: ```json { "data": { "items": [ /* ... */ ], "pagination": { "page_number": 1, "page_size": 100, "total_count": 28, "has_more": false }, "updated_at": "2026-04-29T05:53:16.294857+00:00" }, "error": false, "error_message": null, "error_code": null } ``` ## End-to-end example The flow below creates a pipeline that streams Base swap logs into Postgres, waits for the runtime to come up, and then pauses it. **Create the pipeline** ```bash curl https://api.covalenthq.com/platform/pipeline-api/ \ -X POST \ -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Base swaps to Postgres", "project": "analytics-prod", "description": "Uniswap v3 swaps on Base, unbounded", "topic": "base.mainnet.ref.block.swap.v3", "destination_type": "postgres", "destination_config": { "type": "postgres", "url": "postgresql://db.example.com:5432/analytics", "user": "goldrush", "password": "REDACTED" }, "transforms": { "swaps": "SELECT chain_name, block_height, tx_hash, protocol, pair_address, token0, token1 FROM swaps WHERE protocol = '\''uniswap_v3'\''" }, "execution_mode": "unbounded", "execution_start_from": "44745000" }' ``` The response includes the new `id` (e.g. `pipe_3e8678c5fc9e48a7bf9879ca729`). **Wait for it to come up** Poll the status endpoint until `status == "RUNNING"` and `ready == replicas`: ```bash curl https://api.covalenthq.com/platform/pipeline-api/pipe_3e8678c5fc9e48a7bf9879ca729/status/ \ -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" ``` **Pause it** ```bash curl https://api.covalenthq.com/platform/pipeline-api/pipe_3e8678c5fc9e48a7bf9879ca729/ \ -X PATCH \ -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "paused"}' ``` ## Two notions of "status" The API exposes two distinct status fields. Don't confuse them: | Where | Field | Values | Meaning | | --- | --- | --- | --- | | Pipeline object (`GET /{id}/`) | `status` | `running`, `paused` | User intent. What the user asked for. | | Status endpoint (`GET /{id}/status/`) | `status` | `DEPLOYING`, `RUNNING`, `PAUSED`, `FAILED`, `STOPPING`, `STOPPED` | Runtime phase. What the worker is actually doing. | A pipeline you just created via `POST` has `status: "running"` immediately, but the status endpoint will show `DEPLOYING` for several seconds until the worker comes up. Use the status endpoint when you need to know whether the pipeline is actually live. ## Secrets are masked on read Destination credentials (passwords, tokens, secret access keys) are returned as `******` from `GET` endpoints. To rotate a secret, send a `PATCH` with the new value in `destination_config` - never send the masked `******` back. ## See also - [Service Keys](/goldrush-pipeline-api/service-keys) - how to create and rotate the credential. - [Configuration Reference](/goldrush-pipeline-api/configuration) - the YAML schema that the JSON request bodies mirror. - [Destinations](/goldrush-pipeline-api/destinations/overview) - the shape of `destination_config` for each `destination_type`. --- ## 30. Service Keys **Path:** goldrush-pipeline-api/service-keys **Metadata:** ```yaml title: Service Keys sidebarTitle: 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. ``` **Content:** A **ServiceKey** is a programmatic credential issued from the GoldRush Platform that authenticates against the [Pipeline REST API](/api-reference/pipeline-api/list-pipelines). Regular GoldRush API keys are read-only and are rejected by the Pipeline REST endpoints. ## Why a separate credential? Pipelines are stateful infrastructure - creating one provisions a worker, opens a connection to your destination, and starts consuming data. We use a different credential type so that: 1. **Read-only API keys** (which may be embedded in client-side code, CLI scripts, or shared between teammates) cannot accidentally create, modify, or delete pipelines. 2. **ServiceKeys** can be rotated independently of the API keys your application already uses to call the Foundational and Streaming APIs. 3. Pipeline mutations are auditable - every CRUD action is attributed to the user who issued the ServiceKey. ## Creating a ServiceKey 1. Sign in to the [GoldRush Platform](https://goldrush.dev/platform/). 2. Open your account settings and select **Service Keys**. 3. Click **Create Service Key**, give it a name, and copy the value shown. > **Warning:** The ServiceKey value is shown **once**, at creation. Store it in a secret manager (e.g. AWS Secrets Manager, GCP Secret Manager, 1Password, Vault). If you lose it, revoke the key and create a new one. ## Using a ServiceKey Send the key as a bearer token on every Pipeline REST request: ```bash curl https://api.covalenthq.com/platform/pipeline-api/ \ -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" ``` ```python import os, requests resp = requests.get( "https://api.covalenthq.com/platform/pipeline-api/", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_SERVICE_KEY']}"}, ) resp.raise_for_status() print(resp.json()) ``` ```javascript const resp = await fetch("https://api.covalenthq.com/platform/pipeline-api/", { headers: { Authorization: `Bearer ${process.env.GOLDRUSH_SERVICE_KEY}` }, }); const body = await resp.json(); console.log(body); ``` ## Scope and permissions | Capability | Allowed | | --- | --- | | List, get, create, update, delete pipelines in your group | Yes | | Read pipeline status, logs, metrics, destination-health | Yes | | Call Foundational, Streaming, CLI, or x402 APIs | No - use a regular API key | | Sign in to the Platform UI | No - use email/password or SSO | | Manage billing | No - use the Platform UI | ServiceKeys inherit the group of the user who created them. Two users in different groups cannot see each other's pipelines through the API, even if both have a ServiceKey. ## Rotation and revocation Rotate a ServiceKey at any time by creating a new one and revoking the old one: 1. Create a new ServiceKey on the Platform. 2. Update your secret store / CI variables to use the new key. 3. Verify your pipelines still respond (`GET /platform/pipeline-api/`). 4. Revoke the old key on the Platform. Revocation is immediate - subsequent requests with the revoked key return `401 Unauthorized`. > **Tip:** Use a separate ServiceKey per environment (dev, staging, prod) and per CI system. This keeps the blast radius small if a key is leaked. ## Common errors | Status | Cause | Fix | | --- | --- | --- | | `401 Unauthorized` | Header missing, malformed, or the key has been revoked. | Confirm `Authorization: Bearer ` and that the key is still active on the Platform. | | `403 Forbidden` | The credential supplied is a regular API key, not a ServiceKey. | Create a ServiceKey and retry. | | `403 Forbidden` (with valid ServiceKey) | The pipeline belongs to a different group. | Confirm the `pipeline_id` belongs to your group. | | `404 Not Found` | The pipeline does not exist or has been deleted. | Re-list with [`GET /platform/pipeline-api/`](/api-reference/pipeline-api/list-pipelines). | --- ## 31. SQL Transforms **Path:** goldrush-pipeline-api/sql-transforms **Metadata:** ```yaml title: SQL Transforms sidebarTitle: 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. ``` **Content:** ## Overview SQL transforms let you reshape, filter, and enrich row streams between the normalization/ABI decoding stage and the destination. Each transform is a standard SQL `SELECT` statement scoped to a single output table. Transforms are optional. When no transform is configured for a table, the full row stream passes through to the destination unchanged. ## How It Works **Typed row streams are produced** The normalizer or ABI decoder emits typed row streams for each output table. **SQL transform executes** If a SQL transform is configured for a given table, the query runs against that table's row stream. **Result replaces the original stream** The query result becomes the new row stream for that table, replacing the original. **Stream flows to the destination** The final (possibly transformed) stream is delivered to the configured destination. ## Configuration Define transforms in your pipeline configuration under the `transforms` key. Each key must match a normalizer or ABI decoder output table name, and the `FROM` clause in the query must reference the same table name. ```yaml transforms: table_name: > SELECT ... FROM table_name WHERE ... ``` ## Supported Operations The following SQL operations are available in transforms: | Operation | Example | |---|---| | Column projection | `SELECT col1, col2 FROM t` | | Column aliases | `SELECT user AS depositor FROM t` | | Filtering | `WHERE amount != '0'` | | Logical operators | `WHERE a > 0 AND b **Warning:** If any validation rule fails, the pipeline will not start. Check the error message for details on which rule was violated and which table or column is affected. ## Examples ### Filter zero-value deposits Remove deposit events where the amount is zero, and project only the columns you need. ```yaml transforms: hl_deposits: > SELECT block_number, block_time, user, amount FROM hl_deposits WHERE amount != '0' ``` ### Rename and project columns Rename `user` to `depositor` and cast `amount` from a string to a double-precision number. ```yaml transforms: hl_deposits: > SELECT block_number, block_time, user AS depositor, CAST(amount AS DOUBLE) AS amount_numeric FROM hl_deposits ``` ### Filter by contract address Keep only swap events emitted by a specific Uniswap V3 router contract. ```yaml transforms: evt_swap: > SELECT block_height, tx_hash, contract_address, sender, recipient, amount0, amount1 FROM evt_swap WHERE contract_address = '0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45' ``` ### Computed columns with arithmetic Add a computed `txn_fee_sol` column that converts lamports to SOL, and filter out low-volume trades. ```yaml transforms: sol_dex_trades: > SELECT block_slot, tx_id, pool_address, base_mint, quote_mint, base_amount, quote_amount, price_usd, volume_usd, txn_fee_lamports * 0.000000001 AS txn_fee_sol FROM sol_dex_trades WHERE volume_usd > 100 ``` ### Conditional logic for trade direction Map side codes to human-readable labels, provide a default for null `builder_fee`, and filter to specific coins. ```yaml transforms: hl_fills: > SELECT block_number, block_time, user_address, coin, px, sz, fee, CASE WHEN side = 'B' THEN 'buy' WHEN side = 'S' THEN 'sell' ELSE side END AS trade_side, COALESCE(builder_fee, '0') AS builder_fee FROM hl_fills WHERE coin IN ('ETH', 'BTC', 'SOL') ``` --- ## 32. Supported Chains **Path:** goldrush-pipeline-api/supported-chains **Metadata:** ```yaml title: Supported Chains sidebarTitle: Supported Chains description: GoldRush Pipeline API supports multiple blockchains including Base, HyperCore, and Solana with structured, per-block data topics for each chain. ``` **Content:** {/* Auto-generated by s/convert-normalizers.js — do not edit manually. */} The GoldRush Pipeline API delivers structured blockchain data across multiple chains. Each chain exposes a set of topics that you can subscribe to, covering everything from raw block data and transaction logs to decoded DEX trades and protocol-specific events. ## Ethereum (EVM) Ethereum supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `eth.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `eth.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `eth.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `eth.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Polygon (EVM) Polygon supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `matic.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `matic.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `matic.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `matic.mainnet.ref.block.transfers` | Token and native transfers | Live | ## BNB Smart Chain (BSC) (EVM) BNB Smart Chain (BSC) supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `bsc.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `bsc.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `bsc.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `bsc.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Avalanche C-Chain (EVM) Avalanche C-Chain supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `avalanche.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `avalanche.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `avalanche.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `avalanche.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Optimism (EVM) Optimism supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `optimism.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `optimism.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `optimism.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `optimism.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Fantom (EVM) Fantom supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `fantom.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `fantom.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `fantom.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `fantom.mainnet.ref.block.transfers` | Token and native transfers | Live | ## ADI Chain (EVM) ADI Chain supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `adi.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `adi.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `adi.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `adi.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Arbitrum (EVM) Arbitrum supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `arbitrum.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `arbitrum.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `arbitrum.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `arbitrum.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Axie/Ronin (EVM) Axie/Ronin supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `axie.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `axie.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `axie.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `axie.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Base (EVM) Base supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `base.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Traces | `base.mainnet.ref.block.traces` | Internal call traces | Live | | Transactions | `base.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `base.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Receipts | `base.mainnet.ref.block.receipts` | Transaction receipts with status and gas usage | Live | | Transfers | `base.mainnet.ref.block.transfers` | Token and native transfers | Live | | Swaps | `base.mainnet.ref.block.swaps` | DEX swap events | Live | ## Blast (EVM) Blast supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `blast.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `blast.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `blast.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `blast.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Celo (EVM) Celo supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `celo.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `celo.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `celo.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `celo.mainnet.ref.block.transfers` | Token and native transfers | Live | ## HyperCore HyperCore supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Fills | `hypercore.mainnet.ref.block.fills` | Order fill events | Live | | Trades | `hypercore.mainnet.ref.block.trades` | Executed trade records | Live | | Orders | `hypercore.mainnet.ref.block.orders` | Order placement and cancellation events | Live | | Misc Events | `hypercore.mainnet.ref.block.miscevents` | Miscellaneous protocol events | Live | ## HyperEVM (EVM) HyperEVM supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `hyperevm.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `hyperevm.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `hyperevm.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `hyperevm.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Ink (EVM) Ink supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `ink.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `ink.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `ink.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `ink.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Monad (EVM) Monad supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `monad.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `monad.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `monad.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `monad.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Moonbeam (EVM) Moonbeam supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `moonbeam.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `moonbeam.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `moonbeam.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `moonbeam.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Scroll (EVM) Scroll supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `scroll.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `scroll.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `scroll.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `scroll.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Solana Solana supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | DEX Swaps | `solana.mainnet.ref.block.swaps` | DEX swap events | Live | | SPL Token Transfers | `solana.mainnet.ref.block.transfers` | Token transfer records | Live | ## zkSync Era (EVM) zkSync Era supports the following data topics: | Entity | Topic | Description | Status | | --- | --- | --- | --- | | Blocks | `zksync.mainnet.ref.block.blocks` | Block headers and metadata | Live | | Transactions | `zksync.mainnet.ref.block.transactions` | Full transaction data | Live | | Logs | `zksync.mainnet.ref.block.logs` | Event logs emitted by contracts | Live | | Transfers | `zksync.mainnet.ref.block.transfers` | Token and native transfers | Live | ## Topic Naming Convention All topics follow a consistent naming pattern: ``` {chain}.{network}.{qualifier}.block.{entity} ``` | Component | Description | Examples | | --- | --- | --- | | `chain` | The blockchain identifier | `base`, `hypercore`, `solana` | | `network` | The network environment | `mainnet` | | `qualifier` | The data processing level | `ref` (structured), `raw` (unprocessed) | | `block` | Fixed segment indicating block-level data | `block` | | `entity` | The specific data type | `blocks`, `transactions`, `swaps`, `fills` | For example, the topic `solana.mainnet.ref.block.swaps` delivers structured, block-level DEX trade data from Solana mainnet. --- # Hyperliquid API Documentation GoldRush Hyperliquid API is the 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, Pipeline delivery for HyperCore data, and HyperEVM coverage through the Foundational API. ## 1. Live Analytics App **Path:** goldrush-hyperliquid/analytics-app **Metadata:** ```yaml title: Live Analytics App sidebarTitle: Live Tools 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. ``` **Content:** We built a live Hyperliquid analytics app on top of the same APIs documented here, both as a reference implementation and a tool you can use directly. ### hyperliquid.goldrush.dev → Open the live app. [Read more](https://hyperliquid.goldrush.dev) ## What's inside ### HIP-3 Market Screener Real-time screener for every builder-deployed perp market. For each market: - **Tick-level trades** as they happen. - **Order flow** - net buying vs selling pressure. - **Maker/taker classification** for every fill. - **Position reconstruction** - top wallets and their notional exposure per market. Powered by [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) + [HIP-3 and HIP-4 OHLCV streams](/goldrush-hyperliquid/streaming/hip3-markets). ### Liquidation Cascade Map Live liquidation feed with cascade reconstruction: - **Cascade chains** - tracks when one liquidation triggers further liquidations. - **Per-market vulnerability scoring** - current risk level for each market. - **Forward-looking liquidation level estimation** - projected price levels where significant liquidations would occur, derived from real positions. Powered by [`HypercoreFillTransaction.liquidation`](/api-reference/streaming-api/types/hypercore-fill-transaction) + per-wallet [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) aggregation. ### Market Health Score Composite **A+ to D** grade per market across six axes: - **Liquidity** - depth, spread, recent fills. - **Oracle** - mark vs oracle price drift, premium stability. - **Activity** - fills per minute, unique traders. - **Risk** - open interest, leverage distribution, current liquidation pressure. - **Order Flow** - net direction, maker/taker balance. - **Builder Economics** - for HIP-3 and HIP-4, builder fee revenue and trader economics. Useful for: ranking markets, vetting new HIP-3 and HIP-4 launches, surfacing healthy markets to users. ### Macro feeds Live TV feeds (Bloomberg, CNBC, CNN, Al Jazeera) embedded alongside market views - useful when trading commodity and equity HIP-3 and HIP-4 markets that move on macro news. ## Build similar features yourself Everything in the app is built on the public GoldRush API. The capabilities map directly to docs: | App feature | Underlying API | |---|---| | HIP-3 screener trades | [Wallet firehose](/goldrush-hyperliquid/streaming/wallet-firehose) | | HIP-3 candles | [HIP-3 markets](/goldrush-hyperliquid/streaming/hip3-markets) | | Liquidation cascade | [Liquidations & vaults](/goldrush-hyperliquid/streaming/liquidations-vaults) | | Account snapshots | [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) | | Market snapshot | [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) | | Warehouse-backed analytics | [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) | --- ## 2. Early Builders Program **Path:** goldrush-hyperliquid/early-builders-program **Metadata:** ```yaml title: Early Builders Program sidebarTitle: 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. ``` **Content:** import HyperliquidSurfaces from "/snippets/hyperliquid-surfaces.mdx"; The **Early Builders Program** gives pre-revenue Hyperliquid teams free access to the GoldRush API - up to **1 million credits over 12 months**. We run monthly cohorts with limited spots, so we can actually get to know the teams we're backing. GoldRush has been indexing onchain data since 2018. Hyperliquid is one of the most data-rich environments in crypto, and this program puts the full surface in your hands from day one - no infra to run, no schemas to design. ### Apply now ~5 minutes. We respond as soon as we've reviewed your application. [Read more](https://airtable.com/appsVoyJQcuAMCCAl/pagepKVg4q9RiS5yx/form) ## Who can apply Two tracks. Apply on the one that fits. ### Data-native apps You're building an app where data is the core value - portfolio tracker, trader analytics, leaderboard, alert system, or similar. - Must be **non-custodial**. - Must not include trading execution. ### Builder code apps You're building an app you plan to monetize, but can't commit to a paid plan today. - Share your app, your team, and your **Hyperliquid builder address**. - Get full GoldRush API and WebSocket access while you build. - Billing starts when your builder wallet starts generating revenue from users. ## What's included Approved teams get the same surfaces our paid customers use: Plus 100+ chains under the same API and key - see [Supported Chains](/goldrush-foundational-api/supported-chains). ## How it works **Apply** Fill out the [application form](https://airtable.com/appsVoyJQcuAMCCAl/pagepKVg4q9RiS5yx/form) with what you're building, your team size, and (for builder code apps) your builder address. **We review** Every application is read by a person on our team. We respond as soon as the review is done. **Build** Approved teams get an API key, the credit allocation, and a direct line to our team for support. ## Program details - **Cost.** Free while you qualify. Up to 1 million credits per team across cohorts, redeemable over 12 months. - **Eligibility.** Strictly pre-revenue teams. Either data-native (non-custodial, no trade execution) or builder code (with a builder address). - **Rate limits.** No public Hyperliquid `/info` rate limits and no GoldRush WebSocket subscription cap during the program. See [Hyperliquid API limitations addressed by GoldRush](/goldrush-hyperliquid/overview#hyperliquid-api-limitations-addressed-by-goldrush). - **After 12 months or first revenue.** You move to a paid plan that fits your usage. We reach out before that happens with options based on your traffic shape and (for builder code apps) your builder revenue. - **Review SLA.** We don't queue applications for weeks. If you've applied and haven't heard back, ping us. ## Next ### Hyperliquid API Overview Everything GoldRush ships for Hyperliquid - Info API, Streaming, Pipeline, HyperEVM. [Read more](/goldrush-hyperliquid/overview) ### Quickstart Three 5-minute paths - drop-in upgrade, wallet streams, warehouse fills. [Read more](/goldrush-hyperliquid/quickstart) --- ## 3. Limits, Caching, and Polling **Path:** goldrush-hyperliquid/info-api/limits **Metadata:** ```yaml title: Limits, Caching, and Polling sidebarTitle: Limits & Caching description: The GoldRush Hyperliquid Info API has no rate limits. Learn how response caching works and recommended polling cadences. ``` **Content:** ## No rate limits The GoldRush Hyperliquid Info API has **no per-IP, per-key, or per-address rate limits**. The 1200 weight/min cap on the public Hyperliquid `/info` API does not apply. You can: - Poll any user-state endpoint as fast as your code wants. - Open as many concurrent connections as your client supports. - Pull state for thousands of wallets in tight loops. For wallet-level real-time updates without polling at all, use the [Streaming API `walletTxs` subscription](/goldrush-hyperliquid/streaming/wallet-firehose) instead - push-based, also no rate limits. ## How caching works Responses are served from a real-time cache that's kept fresh by direct ingestion from Hyperliquid. The cache is transparent to your client code - same JSON in, same JSON out. | Cache layer | Typical freshness | |---|---| | User-state types (`clearinghouseState`, `spotClearinghouseState`, `frontendOpenOrders`) | Sub-second after each user event. | | Market types (`metaAndAssetCtxs`) | Sub-second on every mark-price tick. | ## Recommended polling cadences You're not rate-limited, but polling smartly saves your own bandwidth. | Endpoint | Recommended interval | Notes | |---|---|---| | `metaAndAssetCtxs` | 1 second | Mark prices update on every tick - for sub-second freshness, use the Streaming API. | | `clearinghouseState` | 1 second per user, OR push via [`walletTxs`](/goldrush-hyperliquid/streaming/wallet-firehose) | Account state only changes on a user event; push is far more efficient than polling. | | `spotClearinghouseState` | 5 seconds | Spot balances change less frequently than perp positions. | | `frontendOpenOrders` | 1 second per user, OR push via `walletTxs` | Same as `clearinghouseState`. | ## Watch out for client-side limits GoldRush has no rate limits, but the rest of your stack might: - **Browser fetch concurrency** - most browsers cap at ~6 concurrent requests per host. Use connection pooling on the server side or batch requests. - **HTTP/2 stream limits** - most clients allow 100+ concurrent streams per connection by default. Bump if you're saturating. - **OS file descriptor limits** - if you're opening thousands of connections, raise `ulimit -n`. For multi-wallet fan-out, use the [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state) and [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state) endpoints, which accept up to 50 wallets per call. For more than 50 wallets, issue multiple calls. ## Network and TLS - **HTTP/2** keep-alive is supported and recommended. - **TLS 1.2+** required. - **`Accept-Encoding: gzip`** is honored. `zstd` support is on the roadmap. ## Need higher guarantees? Enterprise SLA, dedicated capacity, regional pinning, and on-prem options are all available. [Email sales](mailto:sales@goldrush.dev?subject=Hyperliquid%20API%20-%20Enterprise%20Inquiry). --- ## 4. Info API Migration Guide **Path:** goldrush-hyperliquid/info-api/migration **Metadata:** ```yaml title: Info API Migration Guide sidebarTitle: 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. ``` **Content:** Moving from the public Hyperliquid `/info` API to GoldRush is two changes: 1. **URL** - replace `api.hyperliquid.xyz/info` with `hypercore.goldrushdata.com/info`. 2. **Header** - add `Authorization: Bearer `. That's it. The request body and response shape are byte-for-byte identical. ## Side-by-side ### cURL ```bash Public Hyperliquid curl -X POST https://api.hyperliquid.xyz/info \ -H "Content-Type: application/json" \ -d '{ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```bash GoldRush curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ### JavaScript / TypeScript ```typescript Public Hyperliquid const response = await fetch("https://api.hyperliquid.xyz/info", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "metaAndAssetCtxs", dex: "", }), }); const data = await response.json(); ``` ```typescript GoldRush const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "metaAndAssetCtxs", dex: "", }), }); const data = await response.json(); ``` ### Python ```python Public Hyperliquid import requests response = requests.post( "https://api.hyperliquid.xyz/info", json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` ```python GoldRush import os import requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` ## Behavioral notes Things to be aware of when you cut over. ### Response is byte-equal, modulo live drift For implemented types, the response body matches Hyperliquid byte-for-byte - same keys, same nesting, same value types. Numeric fields update independently on each side, so a market-price field will diverge by tens of milliseconds, but the schema is identical. ### Unsupported types return a JSON error Types that GoldRush doesn't natively serve return `{"error":"unsupported_type","type":""}` with HTTP 400. They are not forwarded to upstream Hyperliquid. See the [Info API overview](/goldrush-hyperliquid/info-api/overview) for the current list of supported types and the [Roadmap](/goldrush-hyperliquid/roadmap) for what's shipping next. ### Auth errors return JSON A missing or invalid key returns `401` with body `{"error":"unauthorized"}`. Public Hyperliquid has no auth and never returns 401. ### Existing SDKs work after a `baseUrl` override The two most-used SDKs work unchanged: - `nomeida/hyperliquid` (JavaScript) - `hyperliquid-dex/hyperliquid-python-sdk` (Python) See [SDK compatibility](/goldrush-hyperliquid/info-api/sdk-compatibility) for the override snippets. ## Authentication The Info API uses your standard GoldRush API key. The same key works against the [Foundational API](/goldrush-foundational-api/authentication), the [Streaming API](/goldrush-streaming-api/authentication), and the [Pipeline API](/goldrush-pipeline-api/authentication). If you don't have one yet, [sign up here](https://goldrush.dev/platform/auth/register/). Never hardcode keys in source. Use environment variables or a secrets manager. ## What you gain - **No rate limits.** No 1200 weight/min cap, no per-address throttling, no IP buckets. - **Faster reads.** Sub-150 ms p50 target for warm responses; orderbook reads driven from a live WebSocket-fed cache. - **More types.** Batched user state, builder-attribution data, liquidation feed, and composites are on the [Roadmap](/goldrush-hyperliquid/roadmap). - **HIP-3 and HIP-4 first-class.** Deployer-prefix syntax (`xyz:GOLD-USDC`) is supported across `meta` and `metaAndAssetCtxs` when a `dex` is provided. - **One key for everything Hyperliquid.** The same API key unlocks Streaming, Pipeline, and HyperEVM via the Foundational API. --- ## 5. Info API Overview **Path:** goldrush-hyperliquid/info-api/overview **Metadata:** ```yaml title: Info API Overview sidebarTitle: 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. ``` **Content:** The GoldRush Hyperliquid Info API is a **drop-in replacement** for `POST https://api.hyperliquid.xyz/info`. The request body, the response shape, and the JSON keys are byte-for-byte identical to the public Hyperliquid API. The only differences are the URL and the authentication header. Eighteen `type` values are supported today across market metadata, user state, user history, vaults, and staking - plus two GoldRush-native batch endpoints with no upstream equivalent. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Comparison with the public Hyperliquid API | | Public API | GoldRush | |---|---|---| | URL| `https://api.hyperliquid.xyz/info` | `https://hypercore.goldrushdata.com/info`| | Auth | None | `Authorization: Bearer ` | | Rate limit | 1200 weight/min/IP | None | | Orderbook latency target | `p50`: `~280 ms` | `p50`: `"}` instead of being forwarded | ## Available types The Info API supports the wire-compatible drop-in types below, organized by what they return. Two GoldRush-native batch endpoints (`batchClearinghouseState`, `batchSpotClearinghouseState`) have no upstream Hyperliquid equivalent. ### Market metadata | Type | Body | Returns | |---|---|---| | [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) | `{"type": "metaAndAssetCtxs", "dex": ""}` | Tuple `[meta, assetCtxs[]]` - perp universe + per-asset live mark price, funding, OI, day volume. | | [`spotMetaAndAssetCtxs`](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs) | `{"type": "spotMetaAndAssetCtxs"}` | Tuple `[spotMeta, assetCtxs[]]` - spot universe + per-pair live mark price, mid, day volume. | | [`outcomeMeta`](/api-reference/hyperliquid-info/outcome-meta) | `{"type": "outcomeMeta"}` | Active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and `sideSpecs` (`Yes` / `No`). | ### User account state | Type | Body | Returns | |---|---|---| | [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) | `{"type": "clearinghouseState", "user": "0x…", "dex": ""}` | Perp account: positions, margin summary, account value, withdrawable. | | [`spotClearinghouseState`](/api-reference/hyperliquid-info/spot-clearinghouse-state) | `{"type": "spotClearinghouseState", "user": "0x…", "dex": ""}` | Spot balances per token, total USD value. | | [`frontendOpenOrders`](/api-reference/hyperliquid-info/frontend-open-orders) | `{"type": "frontendOpenOrders", "user": "0x…", "dex": ""}` | Open orders + trigger metadata (TP/SL, `isPositionTpsl`, `reduceOnly`, `orderType`). | | [`subAccounts`](/api-reference/hyperliquid-info/sub-accounts) | `{"type": "subAccounts", "user": "0x…"}` | List of sub-accounts owned by a master, each with its inlined perp and spot state. | ### User history | Type | Body | Returns | |---|---|---| | [`userFills`](/api-reference/hyperliquid-info/user-fills) | `{"type": "userFills", "user": "0x…"}` | Most recent fills for a wallet (up to 2,000). | | [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) | `{"type": "userFillsByTime", "user": "0x…", "startTime": …}` | Fills bounded by a time window. | | [`userTwapSliceFills`](/api-reference/hyperliquid-info/user-twap-slice-fills) | `{"type": "userTwapSliceFills", "user": "0x…"}` | Most recent TWAP slice fills, each tagged with the parent `twapId`. | | [`userFunding`](/api-reference/hyperliquid-info/user-funding) | `{"type": "userFunding", "user": "0x…", "startTime": …}` | Funding payment history with rate, applied size, and USDC delta per event. | | [`userNonFundingLedgerUpdates`](/api-reference/hyperliquid-info/user-non-funding-ledger-updates) | `{"type": "userNonFundingLedgerUpdates", "user": "0x…", "startTime": …}` | Ledger events except funding - deposits, withdrawals, transfers, vault flows, liquidations. | ### Vaults & staking | Type | Body | Returns | |---|---|---| | [`userVaultEquities`](/api-reference/hyperliquid-info/user-vault-equities) | `{"type": "userVaultEquities", "user": "0x…"}` | Per-vault locked equity with unlock timestamps. | | [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary) | `{"type": "delegatorSummary", "user": "0x…"}` | Current delegated, undelegated, and pending-withdrawal HYPE totals. | | [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history) | `{"type": "delegatorHistory", "user": "0x…"}` | Delegate, undelegate, deposit, and withdrawal staking events. | | [`delegatorRewards`](/api-reference/hyperliquid-info/delegator-rewards) | `{"type": "delegatorRewards", "user": "0x…"}` | Accrued staking rewards (delegation and validator commission). | ### GoldRush-native batch | Type | Body | Returns | |---|---|---| | [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state) | `{"type": "batchClearinghouseState", "users": ["0x…", …], "dex": ""}` | Array of `clearinghouseState` slots. **GoldRush-native**, 1 to 50 wallets per call. | | [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state) | `{"type": "batchSpotClearinghouseState", "users": ["0x…", …]}` | Array of `spotClearinghouseState` slots. **GoldRush-native**, 1 to 50 wallets per call. | If you send a `type` that isn't in the table above, the response body is `{"error":"unsupported_type","type":""}`. Requests are not forwarded to upstream Hyperliquid. Type expansion is tracked on the [Roadmap](/goldrush-hyperliquid/roadmap). See the [Roadmap](/goldrush-hyperliquid/roadmap) for what's shipping next. ## How clients see it Existing Hyperliquid SDKs work unchanged after a `baseUrl` override. See [SDK compatibility](/goldrush-hyperliquid/info-api/sdk-compatibility) for `nomeida/hyperliquid` (JS) and `hyperliquid-dex/hyperliquid-python-sdk` setup snippets. ## Errors | Status | Body | Cause | |---|---|---| | `400` | `{"error":"invalid request"}` | Malformed body. | | `400` | `{"error":"unsupported_type","type":""}` | The `type` field isn't one of the natively-supported types. | | `401` | `{"error":"unauthorized"}` | Missing or invalid `Authorization` header. | | `5xx` | Server error | Internal server error. | ## Networks Mainnet only. Testnet support is deferred. ## Next ### Migration guide Side-by-side examples - change one URL and one header. [Read more](/goldrush-hyperliquid/info-api/migration) ### SDK compatibility Drop-in setup for `nomeida/hyperliquid` and `hyperliquid-python-sdk`. [Read more](/goldrush-hyperliquid/info-api/sdk-compatibility) ### Limits and caching No rate limits - what to know about caching and recommended polling cadences. [Read more](/goldrush-hyperliquid/info-api/limits) ### API reference Per-endpoint request and response schemas. [Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs) --- ## 6. SDK Compatibility **Path:** goldrush-hyperliquid/info-api/sdk-compatibility **Metadata:** ```yaml title: SDK Compatibility sidebarTitle: 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. ``` **Content:** The most popular Hyperliquid SDKs work against GoldRush after a one-line `baseUrl` override and adding an `Authorization` header. ## JavaScript / TypeScript: `nomeida/hyperliquid` ### Install ```bash npm npm install hyperliquid ``` ```bash yarn yarn add hyperliquid ``` ### Configure ```typescript import { Hyperliquid } from "hyperliquid"; const sdk = new Hyperliquid({ // Point at GoldRush baseUrl: "https://hypercore.goldrushdata.com", // Inject the Authorization header on every request headers: { Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`, }, }); // Existing methods work unchanged const ctxs = await sdk.info.metaAndAssetCtxs(); const account = await sdk.info.clearinghouseState({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); const spot = await sdk.info.spotClearinghouseState({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); const orders = await sdk.info.frontendOpenOrders({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); ``` > **Note:** If your SDK version doesn't expose a `headers` option, wrap `fetch` to inject the header globally before instantiating the SDK. See the patch pattern below. ### Header injection fallback ```typescript const originalFetch = globalThis.fetch; globalThis.fetch = (input, init = {}) => { const headers = new Headers(init.headers); if (typeof input === "string" && input.startsWith("https://hypercore.goldrushdata.com")) { headers.set("Authorization", `Bearer ${process.env.GOLDRUSH_API_KEY}`); } return originalFetch(input, { ...init, headers }); }; ``` ## Python: `hyperliquid-dex/hyperliquid-python-sdk` ### Install ```bash pip install hyperliquid-python-sdk ``` ### Configure ```python import os from hyperliquid.info import Info # Point Info at GoldRush info = Info(base_url="https://hypercore.goldrushdata.com", skip_ws=True) # Inject the Authorization header on the underlying session info.session.headers.update({ "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}" }) # Existing methods work unchanged ctxs = info.meta_and_asset_ctxs() account = info.user_state("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") spot = info.spot_user_state("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") orders = info.frontend_open_orders("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") ``` > **Tip:** `skip_ws=True` is recommended when using the Info API only - it skips the WebSocket connection that the SDK opens by default to upstream Hyperliquid. For real-time event streams, use the [GoldRush Streaming API](/goldrush-streaming-api/overview) instead. ## Verification After cutover, confirm everything is wired correctly: 1. **Diff a known wallet** - call `clearinghouseState` for the same wallet against both endpoints; the JSON shape (keys, nesting, types) should match exactly. 2. **Confirm auth** - remove the API key and confirm you get a `401` with body `{"error":"unauthorized"}`. If you get any other response, your request isn't reaching GoldRush. ## Other SDKs The pattern is the same for any HTTP client: override the base URL to `https://hypercore.goldrushdata.com` and attach `Authorization: Bearer `. If you run into a specific SDK that doesn't expose either knob, [email us](mailto:support@covalenthq.com) - we'll publish a recipe. --- ## 7. Hyperliquid API Overview **Path:** goldrush-hyperliquid/overview **Metadata:** ```yaml title: Hyperliquid API Overview sidebarTitle: 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. ``` **Content:** import HyperliquidSurfaces from "/snippets/hyperliquid-surfaces.mdx"; GoldRush is the **complete data layer for Hyperliquid**. It aggregates everything you need to build on Hyperliquid - HyperCore, HIP-3, HIP-4, and HyperEVM - under one API key. ### Drop-in Hyperliquid API replacement Drop-in replacement for both the public `/info` REST API and `/ws` WebSocket. Change one URL to remove rate limits and unlock more data. Hosted at `hypercore.goldrushdata.com`. [Read more](/goldrush-hyperliquid/info-api/overview) ### Real-time Streaming Wallet firehose, OHLCV for every HIP-3 and HIP-4 market the moment it goes live, and pre-decoded liquidations and vault events. [Read more](/goldrush-hyperliquid/streaming/wallet-firehose) ### Pipeline to your warehouse Land `hl_fills`, `hl_trades`, `hl_orders`, `hl_funding`, and more directly in ClickHouse, BigQuery, Postgres, Kafka, or S3. [Read more](/goldrush-pipeline-api/normalizers/hypercore) ### HyperEVM coverage Token balances, transfers, approvals, NFTs, and gas for HyperEVM - same shape as every other EVM chain on GoldRush. [Read more](/chains/hyperevm) ## Drop-in coverage: REST + WebSocket GoldRush replaces **both** of Hyperliquid's public surfaces with a single host - `hypercore.goldrushdata.com`. Same request bodies, same response shapes, same subscription payloads as the public API. Swap the URL, add one `Authorization` header, and your existing clients work unchanged - with no rate limits and no per-IP subscription caps. ### REST /info API Drop-in replacement for `POST https://api.hyperliquid.xyz/info`. 17 wire-compatible `type` values plus GoldRush-native batch endpoints (`batchClearinghouseState`, `batchSpotClearinghouseState`) for up to 50 wallets per call. [Read more](/goldrush-hyperliquid/info-api/overview) ### WebSocket API Drop-in replacement for `wss://api.hyperliquid.xyz/ws` with no 1000-subscription-per-IP cap. Subscribe to `l2Book` (aggregated snapshots - omit `coin` to stream **every asset** on one subscription) or to the GoldRush-native `l4Book` (per-order snapshot plus per-block diffs with `user`, `oid`, `cloid`, and trigger metadata exposed). [Read more](/goldrush-hyperliquid/websocket-api/overview) ## Hyperliquid API limitations addressed by GoldRush The public Hyperliquid `/info` API is generous, but it has hard limits that most production apps run into: - **1200 weight/min/IP** rate limits per address. - **1000 WebSocket subscriptions per IP** - not enough to track every active trader. - **WebSocket subscription filters are required** - every subscription must specify an asset (e.g. `coin` on `l2Book`), forcing per-asset fan-out that burns through the 1000-subscription cap. GoldRush makes these filters **optional** so a single wildcard subscription streams every asset. - **No batch address endpoints** - account-state calls are single-wallet only; GoldRush adds `batchClearinghouseState` and `batchSpotClearinghouseState` for up to 50 wallets per request. - **`userFills` capped at ~10,000 rows** - active traders blow through that in weeks. - **Liquidations buried inside fills** as a thin stub; vault, staking, and delegation data arrives untyped. - **HIP-3 and HIP-4 discovery is manual** - `candleSnapshot` is poll-based and effectively limited to mainstream markets. - **No HyperEVM concept at all** - DEXes, NFT mints, and lending live on chain `999` and the `/info` API doesn't see them. GoldRush closes every one of these gaps. See [GoldRush vs Hyperliquid public API](/resources/differentiate-your-hyperliquid-app) for the full breakdown. ## What's included ## Infrastructure - **Dedicated Hyperliquid nodes in Tokyo** - co-located with Hyperliquid's validator infrastructure for low-latency reads. - **Private backbone** for high-throughput data ingestion. - **No rate limits** - bypass the public `/info` and WebSocket constraints entirely. - **Full historical backfill** - every fill, funding payment, and ledger event back to HyperCore block `676,607,001` (`2025-07-27T01:49:59Z`). HyperEVM coverage goes back to genesis. ## Quickstart Here are three "first 5 minutes" quickstarts. Pick whichever maps to what you are building. ### Upgrade from the public Hyperliquid API Already using `api.hyperliquid.xyz/info`? Change the URL and add one header. [Read more](/goldrush-hyperliquid/quickstart#1-drop-in-info-api) ### Watch wallets Subscribe to thousands of HyperCore wallets in one connection. [Read more](/goldrush-hyperliquid/quickstart#2-stream-wallet-activity) ### Pipe orderbook fills into your warehouse Stream `hl_fills` into ClickHouse, BigQuery, or Postgres. [Read more](/goldrush-hyperliquid/quickstart#3-pipe-fills-to-your-warehouse) --- ## 8. Hyperliquid API Quickstart **Path:** goldrush-hyperliquid/quickstart **Metadata:** ```yaml title: Hyperliquid API Quickstart sidebarTitle: Quickstart description: Three 5-minute paths to get Hyperliquid data with GoldRush - drop-in Info API, real-time wallet streams, and warehouse delivery. ``` **Content:** Pick the path that matches what you're building. All three use the same GoldRush API key. ## Prerequisites A GoldRush API key. Sign up at [goldrush.dev/platform](https://goldrush.dev/platform/auth/register/). ### Vibe Coders $10/mo - Built for solo builders and AI-native workflows. [Read more](https://goldrush.dev/platform/auth/register/?plan=vibe) ### Teams $250/mo - Production-grade with priority support. [Read more](https://goldrush.dev/platform/auth/register/?plan=professional) --- ## 1. Drop-in Info API If your code already calls `POST https://api.hyperliquid.xyz/info`, swap the URL to `https://hypercore.goldrushdata.com/info` and add an `Authorization: Bearer` header. The request body and response shape stay byte-for-byte identical. ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"type": "metaAndAssetCtxs"}' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "clearinghouseState", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const data = await response.json(); console.log(data); ``` ```python Python import os import requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={ "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}", "Content-Type": "application/json", }, json={ "type": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` That's it. No rate limits, faster reads, and the response is byte-equal to Hyperliquid (modulo live-value drift). See the full migration guide for SDK overrides and behavioral notes: ### Info API Migration Guide Side-by-side examples in JS, Python, and cURL - including how to point existing SDKs at GoldRush. [Read more](/goldrush-hyperliquid/info-api/migration) --- ## 2. Stream wallet activity Subscribe to one or many HyperCore wallets in real time over WebSocket. Pre-decoded events include fills with liquidation context, funding payments, vault actions, and 20+ ledger subtypes. ```typescript GoldRush SDK import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const SUBSCRIPTION_QUERY = ` subscription { walletTxs( wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"] chain_name: HYPERCORE_MAINNET ) { tx_hash block_signed_at decoded_details { ... on HypercoreFillTransaction { coin side price size closed_pnl liquidation { method liquidated_user market_price } } ... on HypercoreFundingEvent { coin funding_rate funding_amount } } } } `; client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (err) => console.error(err), complete: () => console.log("done"), } ); ``` ```bash Install npm install @covalenthq/client-sdk ``` The `walletTxs` subscription has zero rate limits and scales to thousands of concurrent wallet subscriptions per connection. See [Wallet firehose](/goldrush-hyperliquid/streaming/wallet-firehose) for the full pattern. --- ## 3. Pipe fills to your warehouse Stream HyperCore fills into ClickHouse, BigQuery, Postgres, Kafka, or S3 with one config - no ETL on your side. **Create a pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. **Pick HyperCore + Fills** Choose **Hyperliquid** as the chain and **Fills** as the data type. **Choose your destination** Connect ClickHouse, BigQuery, Postgres, Kafka, S3/GCS/R2, SQS, or a Webhook. **Deploy** Fills begin flowing within seconds. Full walkthrough with sample SQL: [Stream Hyperliquid trades to ClickHouse](/goldrush-pipeline-api/guides/hyperliquid-trades). --- ## 4. Fan out across many wallets Need account state for many wallets at once? `batchClearinghouseState` and `batchSpotClearinghouseState` accept **1 to 50 wallets per call** and fan them out in parallel against our private node. There is no equivalent on the public Hyperliquid `/info` API. Each slot in the response is either the raw upstream object for that wallet (success) or a thin error envelope (`{error, user, message}`) when an individual wallet fails. The HTTP status stays `200 OK` even on partial failure - always check for the `error` key on each slot. ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "batchClearinghouseState", users: [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b", ], }), }); const slots = await response.json(); for (const [i, slot] of slots.entries()) { if ("error" in slot) { console.warn(`wallet ${slot.user} failed: ${slot.message}`); continue; } console.log(`wallet ${i}: ${slot.withdrawable} USD withdrawable`); } ``` ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "batchSpotClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] }' ``` Duplicates in `users` are removed (case-insensitive); input order is preserved for the survivors. For batches larger than 50, issue multiple calls. Use cases: portfolio dashboards, multi-wallet PnL aggregators, fleet-level liquidation risk monitoring, treasury balance reconciliation. Full reference: [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state), [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state). --- ## What's next ### HIP-3 markets Real-time OHLCV for every builder-deployed perp market - equities, commodities, niche assets. [Read more](/goldrush-hyperliquid/streaming/hip3-markets) ### Liquidations & vault events Pre-decoded `LedgerLiquidation`, `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and 17 more subtypes. [Read more](/goldrush-hyperliquid/streaming/liquidations-vaults) ### Roadmap Time-travel queries, cross-venue unification, signed responses - what's shipping next. [Read more](/goldrush-hyperliquid/roadmap) ### Live analytics HIP-3 Market Screener, Liquidation Cascade Map, Market Health Score. [Read more](/goldrush-hyperliquid/analytics-app) --- ## 9. Hyperliquid API Roadmap **Path:** goldrush-hyperliquid/roadmap **Metadata:** ```yaml title: Hyperliquid API Roadmap sidebarTitle: 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. ``` **Content:** The GoldRush Hyperliquid API ships in phases. Available endpoints are documented under [Info API](/goldrush-hyperliquid/info-api/overview); this page covers what's coming. ## Available now The Info API ships with seventeen types: fifteen wire-compatible drop-ins covering market metadata, user state, user history, vaults, and HYPE staking (including HIP-4 outcome metadata), plus two GoldRush-native batch endpoints. | Type | Description | |---|---| | [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) | Perp universe + per-asset live mark price, funding, OI, and day volume. | | [`spotMetaAndAssetCtxs`](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs) | Spot universe + per-pair live mark price, mid, prior-day price, and day volume. | | [`outcomeMeta`](/api-reference/hyperliquid-info/outcome-meta) | Active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and `sideSpecs` (`Yes` / `No`). | | [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) | Perp account: positions, margin summary, account value, withdrawable. | | [`spotClearinghouseState`](/api-reference/hyperliquid-info/spot-clearinghouse-state) | Spot balances per token, total USD value. | | [`frontendOpenOrders`](/api-reference/hyperliquid-info/frontend-open-orders) | Open orders + trigger metadata (TP/SL, reduceOnly, orderType). | | [`subAccounts`](/api-reference/hyperliquid-info/sub-accounts) | Sub-accounts of a master, each with inlined perp and spot state. | | [`userFills`](/api-reference/hyperliquid-info/user-fills) | A user's most recent fills (up to 2,000). | | [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) | User fills bounded by a `[startTime, endTime)` window. | | [`userFunding`](/api-reference/hyperliquid-info/user-funding) | Funding payment history with rate, applied size, and USDC delta per event. | | [`userNonFundingLedgerUpdates`](/api-reference/hyperliquid-info/user-non-funding-ledger-updates) | Ledger events except funding - deposits, withdrawals, transfers, vault flows, liquidations. | | [`userVaultEquities`](/api-reference/hyperliquid-info/user-vault-equities) | Per-vault locked equity with unlock timestamps. | | [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary) | Current delegated, undelegated, and pending-withdrawal HYPE totals. | | [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history) | Delegate, undelegate, deposit, and withdrawal staking events. | | [`delegatorRewards`](/api-reference/hyperliquid-info/delegator-rewards) | Accrued staking rewards (delegation and validator commission). | | [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state) | Perp account state for 1 to 50 wallets in one request. **GoldRush-native**, no upstream equivalent. | | [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state) | Spot balances for 1 to 50 wallets in one request. **GoldRush-native**, no upstream equivalent. | Real-time streaming, Pipeline API delivery to warehouses, and full HyperEVM coverage are also live today - see the [Hyperliquid API Overview](/goldrush-hyperliquid/overview). --- ## Next: remaining `/info` types We're filling in the rest of the most-used types on the public Hyperliquid `/info` surface. Backed by data we already ingest in real time. | Category | Types | Notes | |---|---|---| | **Meta** | `meta`, `spotMeta` | Perp and spot universe metadata without live contexts. | | **Prices** | `allMids` | All-asset mark prices. | | **Orderbook** | `l2Book` | Sub-150 ms p50 target. | | **Trades** | `recentTrades`, `candleSnapshot` | Backed by the same fills we already stream. | | **User orders & fills** | `openOrders`, `historicalOrders`, `orderStatus` | No 10,000-row cap - full history. | | **User ledger** | `fundingHistory` | Funding rate history per asset. | | **Misc** | `userFees`, `userRateLimit`, `referral`, `portfolio` | Coming soon. | Until a type is implemented natively, requests for it return `{"error":"unsupported_type","type":""}`. Email us at [support@covalenthq.com](mailto:support@covalenthq.com) to prioritize a specific type. --- ## Then: Power-user endpoints Capabilities that go beyond the public `/info` surface, addressable from the same `POST /info` body. | Type | What it adds | |---|---| | `builderFills` | Fills attributed to a specific builder code address. | | `builderLiquidations` | Liquidations attributed to a specific builder. | | `liquidationFills` | Market-wide liquidation feed, paged. | | `webData2` (composite) | One call returns `clearinghouseState` + `openOrders` + `meta` + `assetCtxs` + recent fills. Saves 4–5 round trips for dashboards. | | `perpDexs` | List of all HIP-3 and HIP-4 builder-deployed perp DEXes. First-class HIP-3 and HIP-4 coverage across `meta` and `metaAndAssetCtxs` when `dex` is provided. | ### Historical depth - Extended retention on `hl_trades` and `hl_fills`. - Bulk archive export - `GET /archive/{type}.parquet?from=…&to=…` returns a presigned URL for backfill into your warehouse. ### Ergonomics - `Accept-Encoding: zstd` for smaller payloads. - Optional `?fields=` parameter for response field projection. --- ## Best-in-class differentiators Capabilities no other Hyperliquid data provider offers today. ### Time-travel info (`asOfMs`) Every user-state and market type accepts an optional `asOfMs` parameter. Replay any wallet's state at any past timestamp using the same `/info` request body. **Use cases:** historical PnL audits, snapshot for tax reports, "what did this account look like before liquidation," backtest harnesses. ### Cross-venue unified perpetuals New types `unifiedMeta` and `unifiedClearinghouseState` merge Hyperliquid + Drift + dYdX + Aevo positions for a wallet into one response. **Use cases:** multi-venue portfolio dashboards, cross-margin monitoring, unified risk engines. ### Streaming mirror via SSE and gRPC Mirror every WebSocket subscription as: - **Server-Sent Events** (`GET /info/stream?type=…`) - works through corporate proxies and serverless edges where WS is blocked. - **gRPC with Protobuf** - 3–5× lower bandwidth, hard typing for institutional clients. ### Smart-money and ML-derived analytics Types not derivable from raw Hyperliquid data: | Type | Description | |---|---| | `whaleFlow` | Net 1h/24h delta for top-N PnL wallets per coin. | | `predictedFunding` | Funding forecast extending Hyperliquid's next-epoch-only horizon. | | `liquidationHeatmap` | Clustered liquidation prices by coin. | | `walletScore` | Risk, PnL, and Sharpe per wallet. | --- ## Have a request? Need a type or capability that isn't on this list? [Email us](mailto:support@covalenthq.com) - we prioritize against real customer use cases. --- ## 10. HIP-3 Markets **Path:** goldrush-hyperliquid/streaming/hip3-markets **Metadata:** ```yaml title: HIP-3 Markets sidebarTitle: HIP-3 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. ``` **Content:** HIP-3 lets builders deploy their own perp markets on Hyperliquid - equities, commodities, niche assets - and new ones appear constantly. The public `candleSnapshot` is poll-based and effectively limited to mainstream markets, and discovering HIP-3 markets means stitching market IDs by hand. GoldRush's `ohlcvCandlesForPair` and `ohlcvCandlesForToken` are real-time WebSocket streams that address HIP-3 markets natively with the **deployer-prefix syntax**. List, chart, or stream any market the moment it goes live. ## Address syntax HIP-3 markets are addressed with a deployer-prefix: | Stream | Address format | Examples | |---|---|---| | **OHLCV Pairs** | `:` | `xyz:GOLD-USDC`, `flx:OIL-USDH`, `BTC-USDC` | | **OHLCV Tokens** | `` (no prefix) | `GOLD`, `OIL`, `BTC`, `HYPE` | For `BTC-USDC`-style canonical Hyperliquid markets, no prefix is needed. ## Stream OHLCV for a HIP-3 pair ```typescript GoldRush SDK import { GoldRushClient, StreamingChain, StreamingInterval, StreamingTimeframe, } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); client.StreamingService.subscribeToOHLCVPairs( { chain_name: StreamingChain.HYPERCORE_MAINNET, pair_addresses: ["xyz:GOLD-USDC", "flx:OIL-USDH"], interval: StreamingInterval.ONE_MINUTE, timeframe: StreamingTimeframe.ONE_HOUR, }, { next: (data) => console.log("OHLCV:", data), error: (err) => console.error(err), complete: () => console.log("done"), } ); ``` ```bash Install npm install @covalenthq/client-sdk ``` ## Stream OHLCV for a token (across all markets) ```typescript client.StreamingService.subscribeToOHLCVTokens( { chain_name: StreamingChain.HYPERCORE_MAINNET, token_addresses: ["GOLD", "OIL", "HYPE"], interval: StreamingInterval.ONE_MINUTE, timeframe: StreamingTimeframe.ONE_HOUR, }, { next: (data) => console.log("Token OHLCV:", data), error: (err) => console.error(err), } ); ``` This aggregates across all DEXes and HIP-3 deployers carrying that token. ## Patterns ### "New markets" discovery tab When a HIP-3 deployer launches a new market, the OHLCV stream picks it up the moment a candle starts forming. Combine [`ohlcvCandlesForPair`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) with periodic listing logic to surface new markets in a "trending" tab. ### Deployer-scoped leaderboards Group `HypercoreFillTransaction` events from [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) by HIP-3 deployer prefix. Compute per-deployer volume, fee revenue, top traders. ### Cross-deployer charting A single chart widget that "just works" on `xyz:GOLD-USDC`, `BTC-USDC`, or any future HIP-3 market without special-casing the request. Pass the address through unchanged. ## Historical depth and warehouse delivery Every HIP-3 fill is captured in the same `hl_fills` and `hl_enriched_trades` tables that power canonical perp and spot history. Use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) to land HIP-3 trades directly in ClickHouse, BigQuery, Postgres, Kafka, or S3 - no separate connector required. ### Filter to HIP-3 trades with a SQL transform The `TradesNormalizer` enriches every matched trade with an `is_hip3` boolean on the [`hl_enriched_trades`](/goldrush-pipeline-api/normalizers/hypercore#hl-enriched-trades) table. Add a [SQL transform](/goldrush-pipeline-api/sql-transforms) to keep only builder-deployed perp rows and project the columns you care about - useful for a deployer-scoped warehouse without ingesting the full canonical perp + spot firehose. ```yaml HIP-3 trades transform transforms: hl_enriched_trades: > SELECT block_number, block_time, coin, market_name, px, sz, side, time, tid, hash, buyer_address, seller_address, usd_amount FROM hl_enriched_trades WHERE is_hip3 = true ``` The `coin` column preserves the full `:` form (e.g. `nanofunds:USDAI`), so you can split downstream tables per deployer with a `SUBSTRING` or `LIKE` predicate, or partition on `coin` directly in your warehouse. ## Reference - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) - [HIP-4 outcome markets](/goldrush-hyperliquid/streaming/hip4-markets) - same address syntax, applied to prediction-market outcomes. - [HyperCore chain page](/chains/hypercore) - full HIP-3 example addresses and Hyperliquid Explorer references. - [Live HIP-3 Market Screener](https://hyperliquid.goldrush.dev) - the public app we built on top of these streams. ## On the roadmap A `perpDexs` Info API type that lists all HIP-3 builder-deployed perp DEXes with metadata. See the [Roadmap](/goldrush-hyperliquid/roadmap). --- ## 11. HIP-4 Outcome Markets **Path:** goldrush-hyperliquid/streaming/hip4-markets **Metadata:** ```yaml title: HIP-4 Outcome Markets sidebarTitle: HIP-4 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. ``` **Content:** HIP-4 launched on Hyperliquid mainnet on **2 May 2026** and added a new asset class to HyperCore: **outcome markets**. Outcomes are fully-collateralized binary contracts that trade on the same CLOB as spot and perps, settle in USDH, and resolve to either `0` or `1` against an authorized oracle at expiry. Because outcome markets ride the same matching engine as every other HyperCore market, you don't need a new client, a new WebSocket, or a new schema to stream them. Every primitive in this section - [`ohlcvCandlesForPair`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream), [`ohlcvCandlesForToken`](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream), and [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - works on HIP-4 markets from the moment they go live. ## HIP-4 in 60 seconds | Property | Value | |---|---| | **Contract type** | Binary outcome (`Yes` / `No`), USDH-collateralized, no liquidation. | | **Price range** | `0.001` to `0.999`. The price *is* the implied probability. | | **Settlement** | Resolves to `0` or `1` against an authorized oracle at the resolution timestamp. PnL settles in USDH. | | **Lifecycle** | Opening auction (~15 min single-price clearing) → continuous CLOB trading → oracle settlement → halt + auto-settle. | | **Fees** | Zero to open. Fees apply on close, burn, or settlement. | | **Deployment** | Initial markets are curated and validator-deployed. Permissionless builder deployment follows in stages, mirroring HIP-3's rollout. | | **Market encoding** | `encoding = 10 * outcome + side`. Each side of an outcome is its own tradeable market - `outcome 123, side 0` becomes encoding `1230`, `outcome 123, side 1` becomes `1231`. Use the encoding prefixed with a '#' to reference HIP-4 markets in the OHLCV endpoints. | The first live market is a recurring **daily BTC binary outcome** that resolves against the HyperCore BTC mark price at a fixed UTC timestamp. > **Tip:** Read the canonical spec: [HIP-4: Outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets). ## Discover live HIP-4 markets HIP-4 ships its own dedicated Info type, [**`outcomeMeta`**](/api-reference/hyperliquid-info/outcome-meta) - separate from `metaAndAssetCtxs` (which covers perps and spot). It returns the active outcome universe: each entry carries an integer `outcome` ID, a `name`, a structured `description`, and a `sideSpecs` array. ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type": "outcomeMeta"}' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "outcomeMeta" }), }); const { outcomes } = await response.json(); ``` ```json outcomeMeta response { "outcomes": [ { "outcome": 123, "name": "Recurring", "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m", "sideSpecs": [ { "name": "Yes" }, { "name": "No" } ] } ] } ``` The `description` is a pipe-delimited spec. Parse it once and you get the full market definition: | Field | Example | Meaning | |---|---|---| | `class` | `priceBinary` | Market class (binary outcome on a price threshold). | | `underlying` | `HYPE` | Asset the outcome resolves against. | | `expiry` | `20260310-1100` | Resolution timestamp, `YYYYMMDD-HHMM` UTC. | | `targetPrice` | `34.5` | Threshold the underlying is compared against at expiry. | | `period` | `3m` | Recurrence cadence for repeating markets. | A typical discovery flow: 1. Call `outcomeMeta` to enumerate live `outcome` IDs and parse each `description`. 2. Compute the encoding for each side: `encoding = 10 * outcome + side`. Each side trades as its own market, so an outcome with `Yes` (side 0) and `No` (side 1) yields two encodings. Reference the market with the encoding prefixed with a '#'. 3. Subscribe to OHLCV for the encodings you want to track. 4. Stream fills via `walletTxs` for any address active on those markets. > **Tip:** `outcomeMeta` is now available on the GoldRush drop-in Info API at `POST https://hypercore.goldrushdata.com/info`, wire-equal to upstream Hyperliquid. See the full [API reference](/api-reference/hyperliquid-info/outcome-meta). ## Stream live probabilities (OHLCV) Outcome prices are bounded between `0` and `1`, so an OHLCV candle on a HIP-4 market is, by construction, a **probability candle**. Multiply by 100 for percent. ```typescript GoldRush SDK import { GoldRushClient, StreamingChain, StreamingInterval, StreamingTimeframe, } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); client.StreamingService.subscribeToOHLCVPairs( { chain_name: StreamingChain.HYPERCORE_MAINNET, // HIP-4 encoding = 10 * outcome + side. Use the value(s) computed from `outcomeMeta`. pair_addresses: ["#1230"], interval: StreamingInterval.ONE_MINUTE, timeframe: StreamingTimeframe.ONE_HOUR, }, { next: (candle) => { const probabilityPct = (candle.close * 100).toFixed(2); console.log(`${candle.pair_address} implied: ${probabilityPct}%`); }, error: (err) => console.error(err), } ); ``` ```graphql GraphQL Subscription subscription { ohlcvCandlesForPair( chain_name: HYPERCORE_MAINNET pair_addresses: ["1230"] interval: ONE_MINUTE timeframe: ONE_HOUR ) { pair_address open high low close volume timestamp } } ``` For a broader feed - every outcome market that references a given underlying - subscribe at the **token** level: ```typescript client.StreamingService.subscribeToOHLCVTokens( { chain_name: StreamingChain.HYPERCORE_MAINNET, token_addresses: ["BTC"], interval: StreamingInterval.ONE_MINUTE, timeframe: StreamingTimeframe.ONE_HOUR, }, { next: (data) => console.log("BTC-referenced markets:", data), error: (err) => console.error(err), } ); ``` ## Stream fills on an outcome market Every fill on a HIP-4 market arrives as a [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) inside `walletTxs`. The `coin` field carries the outcome symbol, `price` is the implied probability at fill time, and `closed_pnl` realises in USDH against the `0` / `1` settlement boundary. ```typescript import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const SUBSCRIPTION_QUERY = ` subscription { walletTxs( wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"] chain_name: HYPERCORE_MAINNET ) { tx_hash block_signed_at from_address decoded_details { ... on HypercoreFillTransaction { coin side price size closed_pnl fee fee_token builder builder_fee } ... on HypercoreLedgerEvent { ledger_type time delta { ... on LedgerSpotTransfer { token amount usdc_value } } } } } } `; client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (err) => console.error(err), } ); ``` ## Detect settlement When an outcome resolves, three things happen in quick succession on-chain: 1. Trading on the market halts. 2. Open orders cancel. 3. Each holder's position settles to USDH PnL against the final outcome (`0` or `1`). Hyperliquid hasn't published a dedicated ledger-event subtype for outcome settlement, so today the reliable detection pattern is derived from the primitives that *are* exposed: - The **last fill** on a HIP-4 market closes at price `0` or `1`. - Followed by a **USDH ledger delta** on every position-holder's account corresponding to their settled PnL. ```typescript function isSettlementFill(fill) { return fill.price === 1 || fill.price === 0; } ``` Combine this with periodic [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) snapshots if you need to reconcile post-settlement balances. ## Patterns ### Live probability tape Subscribe to [`ohlcvCandlesForPair`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) at `ONE_MINUTE` interval. Render each candle as `close * 100 %` to drive a Polymarket-style probability sparkline. ### Outcome leaderboards Subscribe to a curated wallet list with `walletTxs`, filter `HypercoreFillTransaction` events whose `coin` matches a HIP-4 symbol, and aggregate notional (`price * size`) per wallet per market. Surface the largest open positions on each outcome. ### Settlement-PnL feed For each position-holder on a market, capture the USDH ledger delta in the resolution window. Rank by realised PnL to produce a "biggest winners / losers on this outcome" feed every time a market resolves. ### Cross-market cohort stream Subscribe to every active HIP-4 symbol in a single `ohlcvCandlesForPair` request. One connection, many markets - lets you build a full HIP-4 dashboard without sharding. ### "New outcomes" discovery Once permissionless builder deployment opens, new outcomes appear in `outcomeMeta` the moment they're registered. Poll `outcomeMeta` on a short cadence and diff the `outcome` IDs against the previous snapshot; subscribe to OHLCV for any new entry. The candle stream picks up the opening auction the instant a price prints. ## Historical depth and warehouse delivery Every HIP-4 fill is captured in the same `hl_fills` and `hl_misc_events` tables that power perp and spot history. Use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) to land outcome trades, settlements, and USDH ledger deltas directly in ClickHouse, BigQuery, Postgres, Kafka, or S3 - no separate connector required. ### Filter to HIP-4 trades with a SQL transform The `TradesNormalizer` enriches every matched trade with an `is_hip4` boolean on the [`hl_enriched_trades`](/goldrush-pipeline-api/normalizers/hypercore#hl-enriched-trades) table. Add a [SQL transform](/goldrush-pipeline-api/sql-transforms) to keep only outcome-market rows and project the columns you care about - useful for a dedicated prediction-market warehouse without ingesting the full perp + spot firehose. ```yaml HIP-4 trades transform transforms: hl_enriched_trades: > SELECT block_number, block_time, coin, market_name, px, sz, side, time, tid, hash, buyer_address, seller_address, usd_amount FROM hl_enriched_trades WHERE is_hip4 = true ``` Combine this with `market_type = 'prediction'` if you want to defensively guard against schema drift, or drop the predicate entirely and partition downstream tables by `market_type` to keep perp, spot, and prediction rows side by side in one pipeline. ## Reference - [HIP-4: Outcome markets (Hyperliquid official spec)](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets) - [`outcomeMeta` Info API reference](/api-reference/hyperliquid-info/outcome-meta) - request and response schema. - [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) - full type reference. - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) / [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - [HIP-3 markets recipe](/goldrush-hyperliquid/streaming/hip3-markets) - identical address syntax, useful for builder-deployer prefixes. - [Pipeline API HyperCore normalizers](/goldrush-pipeline-api/normalizers/hypercore) ## On the roadmap - Parsed `description` fields on `outcomeMeta` (class, underlying, expiry, targetPrice, period) returned alongside the raw string. - Multi-outcome (non-binary) market support, tracking the upstream HIP-4 rollout. --- ## 12. Liquidations and Vault Events **Path:** goldrush-hyperliquid/streaming/liquidations-vaults **Metadata:** ```yaml title: Liquidations and Vault Events sidebarTitle: Liquidations & Vaults description: Pre-decoded liquidation, vault, staking, delegation, and borrow/lend events from HyperCore - typed and ready to consume, with no parsing required. ``` **Content:** The public Hyperliquid `/info` API surfaces raw building blocks; you write the parser. **Liquidations** are buried inside fills as a thin stub, and **vault, staking, and delegation** activity arrives as untyped ledger updates you have to classify yourself. GoldRush ships every one of these pre-decoded and typed. ## What's pre-decoded ### Liquidations Inline with the fill that triggered them, with full context: | Field | Description | |---|---| | `method` | `Market` or `Backstop`. | | `liquidated_user` | The wallet whose position was liquidated. | | `market_price` | Mark price at the moment of liquidation. | | `liquidated_positions[]` | Every position closed by the liquidation (coin + size). | | `account_value` | Account value at the time of liquidation. | | `leverage_type` | Cross or isolated. | ### 20+ ledger event subtypes | Subtype | Description | |---|---| | `LedgerLiquidation` | Standalone liquidation ledger event with full position list. | | `LedgerVaultDeposit` | Deposit into a vault. | | `LedgerVaultWithdraw` | Withdrawal request from a vault, with commission and basis. | | `LedgerVaultLeaderCommission` | Commission earned by a vault leader. | | `LedgerVaultDistribution` | Distribution from a vault to depositors. | | `LedgerVaultCreate` | New vault creation event. | | `LedgerCStakingTransfer` | Hyperliquid staking deposit/withdrawal. | | `LedgerBorrowLend` | Borrow or lend operation. | | `LedgerRewardsClaim` | Validator or program reward claim. | | `LedgerDeposit`, `LedgerWithdraw` | Bridge in/out. | | `LedgerInternalTransfer` | Sub-account transfer. | | `LedgerSpotTransfer` | Spot token transfer with USDC value. | | `LedgerSubAccountTransfer` | Sub-account funds movement. | | `LedgerSend` | Cross-DEX send (with `source_dex` and `destination_dex`). | | `LedgerAccountClassTransfer` | Account-class movement (perp/spot). | | `LedgerAccountActivationGas` | Activation gas charged on first deposit. | | `LedgerSpotGenesis` | Spot token genesis allocation. | | `LedgerDeployGasAuction` | HIP-3 market deployment gas auction. | | `LedgerPerpDexClassTransfer` | Transfer between HIP-3 perp DEXes and core perp. | See [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) for the full type with all fields. ### Funding, deposits, withdrawals, delegations Each gets its own typed event: - [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event) - funding rate payment with coin, rate, and amount. - [`HypercoreDepositEvent`](/api-reference/streaming-api/types/hypercore-deposit-event) - cross-chain deposit into HyperCore. - [`HypercoreWithdrawalEvent`](/api-reference/streaming-api/types/hypercore-withdrawal-event) - finalized cross-chain withdrawal. - [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event) - staking delegation or undelegation with validator address. ## Subscribe Pull liquidations, fills, and ledger events for a wallet (or many) in one stream: ```typescript import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const SUBSCRIPTION_QUERY = ` subscription { walletTxs( wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"] chain_name: HYPERCORE_MAINNET ) { tx_hash block_signed_at decoded_details { ... on HypercoreFillTransaction { coin side price size closed_pnl liquidation { method liquidated_user market_price } } ... on HypercoreLedgerEvent { ledger_type time delta { ... on LedgerLiquidation { account_value leverage_type liquidated_ntl_pos liquidated_positions { coin szi } } ... on LedgerVaultDeposit { vault user usdc } ... on LedgerVaultWithdraw { vault user requested_usd commission basis closing_cost } ... on LedgerVaultLeaderCommission { vault usdc } ... on LedgerVaultDistribution { vault usdc } ... on LedgerCStakingTransfer { token amount is_deposit } ... on LedgerBorrowLend { token amount interest_amount operation } ... on LedgerRewardsClaim { amount } } } } } } `; client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (err) => console.error(err), } ); ``` ## Patterns ### Live liquidation tape Filter the stream on `HypercoreFillTransaction` where `liquidation` is non-null. Display each liquidation in a chronological feed with the user, mark price, method, and total position value. ### "X just got liquidated for $Y" notifications Push every non-null `liquidation` to a notification channel. Use `account_value` to compute the dollar size and `liquidated_positions[]` to list the markets. ### Position-risk warnings Combine [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) (read `liquidationPx`, `marginUsed`, `accountValue`) with live `LedgerLiquidation` events for similar wallets to flag at-risk positions before they liquidate. ### Vault leaderboards Aggregate `LedgerVaultLeaderCommission` and `LedgerVaultDistribution` events per vault address. Surface top-performing vaults by commission earned or distribution payout. ### Staking and rewards tabs Subscribe to `LedgerCStakingTransfer`, `HypercoreDelegationEvent`, and `LedgerRewardsClaim` for a user. Display delegation history, current stake, and rewards earned. ### Borrow/lend position trackers Filter on `LedgerBorrowLend` for `operation: "borrow" | "repay" | "open" | "close"`. Display per-token borrow positions with cumulative interest. ## Historical depth Every fill, funding payment, and ledger event is retained back to HyperCore block **676,607,001** (2025-07-27T01:49:59Z). For warehouse delivery - every ledger event landing in your database continuously - use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) (`hl_misc_events`). ## Reference - [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) - [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) - [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event) - [`HypercoreDepositEvent`](/api-reference/streaming-api/types/hypercore-deposit-event) - [`HypercoreWithdrawalEvent`](/api-reference/streaming-api/types/hypercore-withdrawal-event) - [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event) - [Decoded Events Guide](/goldrush-streaming-api/decoded-events) - every type, every subtype. --- ## 13. Wallet Firehose **Path:** goldrush-hyperliquid/streaming/wallet-firehose **Metadata:** ```yaml title: Wallet Firehose sidebarTitle: 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. ``` **Content:** The public Hyperliquid WebSocket caps you at **1000 subscriptions per IP**, and every REST endpoint is weight-rate-limited per IP and per address. That's nowhere near enough to track every active trader on Hyperliquid in real time - exactly what copy-trade, whale alerts, and "follow the flow" features need. GoldRush's `walletTxs` subscription has **zero rate limits** and scales to thousands of concurrent wallet subscriptions on a single connection. ## What you get - **One connection, many wallets.** Pass an array of wallet addresses; updates for any of them come through the same stream. - **Pre-decoded events.** Fills, funding, vault actions, ledger events, deposits, withdrawals, and delegations come through as typed GraphQL union members - no parsing. - **Liquidation context inline.** When a fill is part of a liquidation, the `liquidation` block is attached directly. - **Sub-second latency.** Tokyo-colocated, validator-peered ingestion. ## Subscribe ```typescript GoldRush SDK import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY); const SUBSCRIPTION_QUERY = ` subscription { walletTxs( wallet_addresses: [ "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "0x5078c2fbea2b2ad61bc840bc023ecb5df8b5ecaf", "0xba1ad77b1c46a7c2c43cf5e10c14e8f0d7d6d5e3" ] chain_name: HYPERCORE_MAINNET ) { tx_hash block_signed_at from_address decoded_details { ... on HypercoreFillTransaction { coin side price size closed_pnl fee fee_token builder builder_fee liquidation { method liquidated_user market_price } } ... on HypercoreFundingEvent { coin funding_rate funding_amount } ... on HypercoreDepositEvent { amount } ... on HypercoreWithdrawalEvent { amount } ... on HypercoreDelegationEvent { validator amount is_undelegate } } } } `; client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (err) => console.error(err), complete: () => console.log("done"), } ); ``` ```python Python import asyncio import os from gql import gql, Client from gql.transport.websockets import WebsocketsTransport WS_URL = "wss://streaming.goldrushdata.com/graphql" SUBSCRIPTION = gql(""" subscription { walletTxs( wallet_addresses: [ "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "0x5078c2fbea2b2ad61bc840bc023ecb5df8b5ecaf" ] chain_name: HYPERCORE_MAINNET ) { tx_hash block_signed_at from_address decoded_details { ... on HypercoreFillTransaction { coin side price size closed_pnl fee liquidation { method liquidated_user market_price } } ... on HypercoreFundingEvent { coin funding_rate funding_amount } } } } """) async def main(): transport = WebsocketsTransport( url=WS_URL, init_payload={"GOLDRUSH_API_KEY": os.environ["GOLDRUSH_API_KEY"]}, ) async with Client(transport=transport, fetch_schema_from_transport=False) as session: async for result in session.subscribe(SUBSCRIPTION): print(result) asyncio.run(main()) ``` ## Patterns ### Copy-trading Subscribe to a curated list of high-PnL wallets. Filter the incoming stream on `HypercoreFillTransaction`, then mirror the `coin`, `side`, and `size` to your own execution layer. ### Live whale feed Subscribe to the top-N wallets by balance or notional position. Display every fill, liquidation, and large transfer in a chronological tape. ### Liquidation alerts Filter the stream on `HypercoreFillTransaction` events where `liquidation` is non-null. Push the event payload to a notification channel (Discord, Telegram, push). Each event includes the liquidated user, mark price, and method (`Market` vs `Backstop`). ### Position monitoring Pair the stream with periodic [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) calls to maintain accurate per-wallet position state without polling between fills. ## Scaling | Scale | Approach | |---|---| | Up to ~1,000 wallets | One subscription with the full address list. | | 1,000 – 10,000+ wallets | Shard across multiple subscriptions on the same connection. The SDK reuses one WebSocket. | | Live cohort changes | Unsubscribe and resubscribe with the new address list - no need to tear down the connection. | For very high fan-out, contact us about dedicated capacity. ## Related - [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) - full type reference. - [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) - vault, staking, borrow/lend, rewards subtypes. - [Liquidations and vault events](/goldrush-hyperliquid/streaming/liquidations-vaults) - full decoded-event walkthrough. - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - subscription reference. --- ## 14. Build with the L2 Order Book **Path:** goldrush-hyperliquid/websocket-api/l2-order-book-recipe **Metadata:** ```yaml title: Build with the L2 Order Book sidebarTitle: L2 Order Book 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. ``` **Content:** The `l2Book` channel on `wss://hypercore.goldrushdata.com/ws?key=` is wire-equal to the public Hyperliquid feed but with `coin` made optional and the per-IP subscription cap removed. This recipe shows how to turn that stream into common trading and analytics building blocks. For the raw subscription shape see the [`l2Book` reference](/api-reference/hyperliquid-websocket/l2-order-book); for the connection model see the [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview). ## What you get - **Complete snapshots, not diffs.** Every `l2Book` message contains the current `time`, `coin`, and a full `[bids, asks]` tuple in best-first order, with `px` / `sz` / `n` per level. Consume each message in isolation - no sequence numbers to track, no diff replay buffer, no REST snapshot to bootstrap. - **Self-healing on packet loss.** Drop a message, reconnect mid-session, or restart your process - the next message arrives with the full book state, so your in-memory view is correct on the very next tick. - **Upstream-compatible aggregation knobs.** `nSigFigs` accepts `2`, `3`, `4`, `5`, or `null` (full precision). `mantissa` accepts `1`, `2`, or `5`, and is only valid when `nSigFigs` is `5`. - **Wildcard coverage.** Omit `coin` to stream every asset's book over a single subscription, instead of fanning out one subscription per asset. ## Subscribe and hold book state The pattern below keeps a `Map` in memory. Each incoming message replaces the entry for its `coin`, so the map is always current and never needs reconciliation. ```typescript TypeScript import WebSocket from "ws"; type Level = { px: string; sz: string; n: number }; type Snapshot = { time: number; bids: Level[]; asks: Level[] }; const books = new Map(); const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { // Omit `coin` to stream every asset on one subscription. ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.channel !== "l2Book") return; const { coin, time, levels: [bids, asks] } = msg.data; books.set(coin, { time, bids, asks }); console.log(coin, time, "bid:", bids[0]?.px, "ask:", asks[0]?.px); }); ``` ```python Python import asyncio, json, os import websockets books: dict[str, dict] = {} async def main(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" async with websockets.connect(uri) as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}, })) async for raw in ws: msg = json.loads(raw) if msg.get("channel") != "l2Book": continue data = msg["data"] coin, time = data["coin"], data["time"] bids, asks = data["levels"] books[coin] = {"time": time, "bids": bids, "asks": asks} print(coin, time, "bid:", bids[0]["px"], "ask:", asks[0]["px"]) asyncio.run(main()) ``` ## Patterns ### Top-of-book tracker Read `bids[0]` and `asks[0]` directly from each message. The spread is `Number(asks[0].px) - Number(bids[0].px)`. No state required - every message is self-contained, so a single-line transformation gives you a live ticker. ### Depth-weighted mid quote Sum `px * sz` across the first `K` levels on each side, then average. This produces a fair-value mid that's robust to thin top-of-book liquidity, and is useful as a hedging or pricing reference. ```typescript TypeScript function depthWeightedMid(snap: Snapshot, k = 5): number { const side = (levels: Level[]) => { let num = 0, den = 0; for (const { px, sz } of levels.slice(0, k)) { const p = Number(px), s = Number(sz); num += p * s; den += s; } return den > 0 ? num / den : NaN; }; return (side(snap.bids) + side(snap.asks)) / 2; } ``` ### Slippage / impact estimator Walk levels on the relevant side until cumulative `sz` covers the requested notional. Return the size-weighted average fill price - the difference vs the top-of-book is your expected slippage. ```typescript TypeScript function estimateFill(levels: Level[], targetSize: number): number { let remaining = targetSize, notional = 0; for (const { px, sz } of levels) { const take = Math.min(remaining, Number(sz)); notional += take * Number(px); remaining -= take; if (remaining 0 ? NaN : notional / targetSize; } // Buying 10 BTC against current asks: const avgFill = estimateFill(books.get("BTC")!.asks, 10); ``` ### Liquidity heatmap On each message, append `[time, coin, side, px, sz]` rows to your time-series store (Clickhouse, TimescaleDB, Parquet). Because every message is a complete snapshot of the top levels, the heatmap rebuilds correctly from any contiguous slice of history - you don't need a separate "initial book" record to seed the visualisation. ## Handling reconnects Reconnect logic is a one-liner: open a new socket and resend the same `subscribe` payload. The first message after subscribe is a full book snapshot, so your `books` map is correct on the next tick - there's nothing to replay, nothing to buffer, and no sequence numbers to reconcile against a separately-fetched REST snapshot. ```typescript TypeScript function connect() { const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, }))); ws.on("close", () => setTimeout(connect, 1000)); return ws; } ``` ## Related - [`l2Book` API reference](/api-reference/hyperliquid-websocket/l2-order-book) - full subscription and message schema. - [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview) - endpoint URL, auth, and limits. - [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) - pair the live book with per-account position and margin state. - [OHLCV pairs stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) - candles instead of raw book state. --- ## 15. Build with the L4 Order Book **Path:** goldrush-hyperliquid/websocket-api/l4-order-book-diff **Metadata:** ```yaml title: Build with the L4 Order Book sidebarTitle: L4 Order Book 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. ``` **Content:** The `l4Book` channel on `wss://hypercore.goldrushdata.com/ws?key=` is a GoldRush-exclusive stream - it has no equivalent on `wss://api.hyperliquid.xyz/ws`. After subscribing, the server sends a single `Snapshot` of every resting order, then per-block `Updates` carrying lifecycle events and per-order book changes. Each order arrives with its `user`, `oid`, `cloid`, `tif`, and trigger metadata, so you can reconstruct queue position, attribute flow to specific wallets, and run microstructure analytics that `l2Book`'s aggregated `{px, sz, n}` view hides. For the raw subscription shape see the [`l4Book` reference](/api-reference/hyperliquid-websocket/l4-order-book-diff); for the connection model see the [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview). ## What you get - **Per-order visibility.** Every level in the snapshot is an individual order keyed by `oid`, with `user`, `cloid`, `tif`, `orderType`, and trigger metadata attached. `l2Book` only exposes `{px, sz, n}` per price level. - **Snapshot + diff transport.** One full `Snapshot` on subscribe, then per-block `Updates` containing `order_statuses` (lifecycle events) and `book_diffs` (per-order changes). Apply diffs to local state. - **Per-block cadence.** Updates fire on each HyperCore block where the book for the subscribed `coin` changed. The `time` and `block_height` fields anchor each message to a specific block. - **GoldRush-exclusive.** Not available on the public Hyperliquid WebSocket - this stream surfaces user attribution and per-order metadata the public feed never exposes. - **One coin per subscription.** Unlike `l2Book`, `coin` is required. To cover multiple assets, open one `l4Book` subscription per asset on the same connection. ## Subscribe and maintain book state The pattern below keeps a `Map` per coin. The snapshot seeds the map; each `Updates` message applies `book_diffs` against it. Reconnects drop the map and re-seed from the next snapshot. ```typescript TypeScript import WebSocket from "ws"; type Order = { user: string | null; coin: string; side: "B" | "A"; limitPx: string; sz: string; oid: number; timestamp: number; triggerCondition: string; isTrigger: boolean; triggerPx: string; isPositionTpsl: boolean; reduceOnly: boolean; orderType: string; tif: string; cloid: string | null; }; const orders = new Map(); const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l4Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.channel !== "l4Book") return; if (msg.data.Snapshot) { orders.clear(); const [bids, asks] = msg.data.Snapshot.levels; for (const o of [...bids, ...asks]) orders.set(o.oid, o); console.log("seeded from snapshot:", orders.size, "orders"); return; } if (msg.data.Updates) { const { order_statuses, book_diffs } = msg.data.Updates; for (const s of order_statuses) { // Re-attach the parent `user` since the nested order has user=null. orders.set(s.order.oid, { ...s.order, user: s.user }); } for (const d of book_diffs) { const existing = orders.get(d.oid); if (!existing) continue; if (d.raw_book_diff.new) { orders.set(d.oid, { ...existing, sz: d.raw_book_diff.new.sz }); } // Other raw_book_diff shapes (deletes, modifies) belong here. } } }); ``` ```python Python import asyncio, json, os import websockets orders: dict[int, dict] = {} async def main(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" async with websockets.connect(uri) as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l4Book", "coin": "BTC"}, })) async for raw in ws: msg = json.loads(raw) if msg.get("channel") != "l4Book": continue data = msg["data"] if "Snapshot" in data: orders.clear() bids, asks = data["Snapshot"]["levels"] for o in bids + asks: orders[o["oid"]] = o print("seeded from snapshot:", len(orders), "orders") continue if "Updates" in data: for s in data["Updates"]["order_statuses"]: o = {**s["order"], "user": s["user"]} orders[o["oid"]] = o for d in data["Updates"]["book_diffs"]: existing = orders.get(d["oid"]) if not existing: continue new = d["raw_book_diff"].get("new") if new: existing["sz"] = new["sz"] asyncio.run(main()) ``` ## Patterns ### Track individual orders by `oid` `oid` is the Hyperliquid order id, stable for the lifetime of the order - use it as the primary key in your local map. `cloid` is the client-supplied id (may be `null`); index on it when you need to correlate fills back to a specific trading bot's instructions. ### Per-user flow attribution Every order entry carries `user`. Group orders by wallet to surface market-maker behavior, identify spoofing patterns, or build a per-trader heatmap of resting size. Pair this with `clearinghouseState` for per-user position and margin context. ```typescript TypeScript function sizeByUser(orders: Map) { const totals = new Map(); for (const o of orders.values()) { if (!o.user) continue; totals.set(o.user, (totals.get(o.user) ?? 0) + Number(o.sz)); } return totals; } ``` ### Reconstruct aggregated price levels If a downstream consumer expects an `l2Book`-style aggregated view, sum `sz` across all orders sharing a `limitPx` on the same `side`. Going the other way isn't possible - `l2Book` collapses the per-order detail you'd lose. ```typescript TypeScript function aggregate(orders: Map) { const bids = new Map(); const asks = new Map(); for (const o of orders.values()) { const book = o.side === "B" ? bids : asks; book.set(o.limitPx, (book.get(o.limitPx) ?? 0) + Number(o.sz)); } return { bids, asks }; } ``` ## Handling reconnects On reconnect, resend the same `subscribe` payload. The first message back is always a fresh `Snapshot` - drop your local `orders` map and re-seed from it. **Do not attempt to replay missed `Updates`** - the snapshot is authoritative and supersedes anything you held before the disconnect. ```typescript TypeScript function connect() { const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l4Book", coin: "BTC" }, }))); ws.on("close", () => { orders.clear(); setTimeout(connect, 1000); }); return ws; } ``` ## Related - [`l4Book` API reference](/api-reference/hyperliquid-websocket/l4-order-book-diff) - full subscription, snapshot, and update schema. - [`l2Book` reference](/api-reference/hyperliquid-websocket/l2-order-book) - aggregated price-level snapshots when per-order detail isn't needed. - [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview) - endpoint URL, auth, and limits. - [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) - pair per-user resting orders with position and margin state. --- ## 16. Limits and Connections **Path:** goldrush-hyperliquid/websocket-api/limits **Metadata:** ```yaml title: Limits and Connections sidebarTitle: Limits & Connections description: The GoldRush Hyperliquid WebSocket API has no per-IP subscription cap and supports wildcard subscriptions. Learn about connection management and reconnection. ``` **Content:** ## No subscription cap The GoldRush Hyperliquid WebSocket API has **no per-IP, per-key, or per-connection subscription cap**. The 1000-subscription-per-IP limit on the public Hyperliquid WebSocket does not apply. You can: - Open as many concurrent subscriptions as your client supports. - Multiplex hundreds of `l2Book` subscriptions on a single connection. - Track every active wallet, market, and asset from one process. ## Wildcard subscriptions Filter parameters that the public Hyperliquid WebSocket **requires** are **optional** on GoldRush. Omit them to stream the entire channel on one subscription instead of fanning out one subscription per asset. | Channel | Public Hyperliquid | GoldRush | |---|---|---| | `l2Book` | `coin` required - one subscription per asset | `coin` optional - omit it to stream the **full L2 order book across every asset** on a single subscription | So a single connection can stream Hyperliquid's full live book state without any client-side fan-out logic. ## How streaming works Messages are pushed directly from a live Hyperliquid ingestion pipeline - no polling, no cache delay. Latency from upstream Hyperliquid event to your client is dominated by network round-trip from our Tokyo nodes. | Channel | Push trigger | |---|---| | `l2Book` | Every L2 update on the subscribed coin (or every coin, if wildcard). | ## Connection management You're not rate-limited, but a few client-side defaults are worth tuning. | Behavior | Recommended client setting | |---|---| | **Reconnect** | On unexpected close, reconnect with exponential backoff capped at ~30 seconds. Re-send your subscription messages after the new socket opens. | | **Heartbeat** | Send an application-level `ping` every 30 seconds. The server replies with `pong`. Most WebSocket libraries handle this automatically; verify yours does. | | **Max message size** | L2 book snapshots for wildcard subscriptions can exceed 1 MB. Raise your client's `maxPayload` (Node `ws` library) or `max_size` (Python `websockets`) if you're receiving truncated messages. | | **Backpressure** | If your handler can't keep up with incoming messages, your client buffer will fill. Drain to a queue or downstream consumer; don't block the read loop on application work. | ### Reconnect sketch ```typescript TypeScript import WebSocket from "ws"; function connect() { const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, { maxPayload: 8 * 1024 * 1024 }, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book" }, // wildcard - all assets })); }); ws.on("close", () => setTimeout(connect, Math.min(30_000, backoff *= 2))); ws.on("error", () => ws.close()); ws.on("message", handle); } let backoff = 1_000; connect(); ``` ```python Python import asyncio, json, os import websockets async def consume(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" backoff = 1 while True: try: async with websockets.connect(uri, max_size=8 * 1024 * 1024, ping_interval=30) as ws: backoff = 1 await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l2Book"}, # wildcard })) async for raw in ws: handle(json.loads(raw)) except Exception: await asyncio.sleep(min(30, backoff)) backoff *= 2 asyncio.run(consume()) ``` ## Watch out for client-side limits GoldRush has no caps, but the rest of your stack might: - **OS file descriptor limits** - if you're opening many connections in parallel, raise `ulimit -n`. - **Reverse proxy idle timeouts** - if you're terminating WS through nginx, HAProxy, or a cloud load balancer, set the idle timeout above your heartbeat interval (typically 60 seconds minimum). - **Browser concurrency** - browsers limit WebSocket connections per origin; one connection multiplexing many subscriptions is always preferable to many connections. ## Network and TLS - **HTTP/1.1 Upgrade** to WSS is supported (standard WebSocket handshake). - **TLS 1.2+** required. - **Compression (`permessage-deflate`)** is negotiated when offered by the client. ## Need higher guarantees? Enterprise SLA, dedicated capacity, regional pinning, and on-prem options are all available. [Email sales](mailto:sales@goldrush.dev?subject=Hyperliquid%20WebSocket%20API%20-%20Enterprise%20Inquiry). --- ## 17. WebSocket API Migration Guide **Path:** goldrush-hyperliquid/websocket-api/migration **Metadata:** ```yaml title: WebSocket API Migration Guide sidebarTitle: Migration description: Move from the public Hyperliquid WebSocket to GoldRush by changing one URL. Step-by-step examples in wscat, JavaScript, and Python. ``` **Content:** Moving from the public Hyperliquid WebSocket to GoldRush is one change: 1. **URL** - replace `wss://api.hyperliquid.xyz/ws` with `wss://hypercore.goldrushdata.com/ws?key=`. That's it. Subscription payloads, channel names, and the streamed message shape are byte-for-byte identical. Authentication is a required `key` query parameter, so no header swap is needed in your client. ## Side-by-side ### wscat ```bash Public Hyperliquid wscat -c wss://api.hyperliquid.xyz/ws > {"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}} ``` ```bash GoldRush wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY" > {"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}} ``` ### JavaScript / TypeScript ```typescript Public Hyperliquid import WebSocket from "ws"; const ws = new WebSocket("wss://api.hyperliquid.xyz/ws"); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { console.log(JSON.parse(raw.toString())); }); ``` ```typescript GoldRush import WebSocket from "ws"; const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { console.log(JSON.parse(raw.toString())); }); ``` ### Python ```python Public Hyperliquid import asyncio, json import websockets async def main(): async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}, })) async for raw in ws: print(json.loads(raw)) asyncio.run(main()) ``` ```python GoldRush import asyncio, json, os import websockets async def main(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" async with websockets.connect(uri) as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}, })) async for raw in ws: print(json.loads(raw)) asyncio.run(main()) ``` ## Behavioral notes Things to be aware of when you cut over. ### Stream payloads are byte-equal, modulo live drift The `channel` name and `data` shape match Hyperliquid byte-for-byte - same keys, same nesting, same value types. Numeric fields update independently on each side, so a price level may differ by tens of milliseconds, but the schema is identical. ### Auth errors close the connection A missing or invalid `key` query param returns HTTP `401` on the upgrade handshake, so the WebSocket never opens. Public Hyperliquid has no auth and never rejects the handshake. ### Filter parameters are optional on GoldRush Parameters that the public Hyperliquid WebSocket **requires** (e.g. `coin` on `l2Book`) are **optional** on GoldRush. Omit them to stream the entire channel on a single subscription instead of fanning out one subscription per asset. See [Limits](/goldrush-hyperliquid/websocket-api/limits#wildcard-subscriptions). ### Existing SDKs work after a `wsUrl` override Most popular Hyperliquid SDKs accept a WebSocket base URL override - point them at `wss://hypercore.goldrushdata.com/ws?key=` and the rest of the SDK works unchanged. See [SDK compatibility](/goldrush-hyperliquid/websocket-api/sdk-compatibility) for the override snippets. ## Authentication The WebSocket API uses your standard GoldRush API key, passed as a `key` query parameter at connection time. The same key works against the [Foundational API](/goldrush-foundational-api/authentication), the [Streaming API](/goldrush-streaming-api/authentication), the [Pipeline API](/goldrush-pipeline-api/authentication), and the [Info API](/goldrush-hyperliquid/info-api/overview). If you don't have one yet, [sign up here](https://goldrush.dev/platform/auth/register/). Never hardcode keys in source. Use environment variables or a secrets manager. ## What you gain - **No subscription cap.** No 1000-subscription-per-IP limit; multiplex hundreds of subscriptions on a single connection. - **Wildcard subscriptions.** Omit filter parameters to stream the entire channel - e.g. the full L2 order book across every asset on one subscription. - **One key for everything Hyperliquid.** The same API key unlocks Streaming, Pipeline, the Info API, and HyperEVM via the Foundational API. --- ## 18. WebSocket API Overview **Path:** goldrush-hyperliquid/websocket-api/overview **Metadata:** ```yaml title: WebSocket API Overview sidebarTitle: 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. ``` **Content:** The GoldRush Hyperliquid WebSocket API is a **drop-in replacement** for `wss://api.hyperliquid.xyz/ws`. Subscription payloads, channel names, and message shapes are byte-for-byte identical to the public Hyperliquid feed. The only difference is the connection URL - authentication is a required `key` query parameter, so no header changes are needed in your client. ## Endpoint ``` wss://hypercore.goldrushdata.com/ws?key= ``` Your GoldRush API key. Passed as a query parameter at connection time. ## Comparison with the public Hyperliquid WebSocket | | Public WebSocket | GoldRush | |---|---|---| | URL | `wss://api.hyperliquid.xyz/ws` | `wss://hypercore.goldrushdata.com/ws?key=` | | Auth | None | `key` query parameter (required) | | Subscriptions per IP | 1000 | No cap | | Wire compatibility | n/a (it's the source) | Byte-for-byte | | Available channels | See [Hyperliquid Docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket) | See [Available subscriptions](#available-subscriptions) | ## Available subscriptions | Channel | Subscription body | Returns | |---|---|---| | [`l2Book`](/api-reference/hyperliquid-websocket/l2-order-book) | `{"type": "l2Book", "coin": "BTC"}` | Real-time L2 order book snapshots - bids and asks aggregated by significant figures. `coin` is optional - omit it to stream every asset on one subscription. | | [`l4Book`](/api-reference/hyperliquid-websocket/l4-order-book-diff) | `{"type": "l4Book", "coin": "BTC"}` | GoldRush-native order-level book stream - initial `Snapshot` of every resting order plus per-block `Updates` with `order_statuses` and `book_diffs`. Exposes `user`, `oid`, `cloid`, `tif`, and trigger metadata per order. `coin` is required. Not available on the public Hyperliquid WebSocket. | ## Limits No 1000-subscription-per-IP cap. On `l2Book`, filter parameters are optional - omit `coin` to stream the full L2 book across every asset on a single subscription. `l4Book` requires `coin` and is one-asset-per-subscription. See [Limits & Connections](/goldrush-hyperliquid/websocket-api/limits) for details. For richer real-time analytics (pre-decoded HyperCore fills, liquidations, vault events, OHLCV across every HIP-3/HIP-4 market), pair the WebSocket with the GraphQL [Streaming API](/goldrush-streaming-api/overview). --- ## 19. SDK Compatibility **Path:** goldrush-hyperliquid/websocket-api/sdk-compatibility **Metadata:** ```yaml title: SDK Compatibility sidebarTitle: 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. ``` **Content:** The most popular Hyperliquid SDKs work against the GoldRush WebSocket API after a one-line URL override. Authentication is a `key` query parameter on the connection URL - no header injection is needed. ## JavaScript / TypeScript: `nomeida/hyperliquid` ### Install ```bash npm npm install hyperliquid ``` ```bash yarn yarn add hyperliquid ``` ### Configure ```typescript import { Hyperliquid } from "hyperliquid"; const sdk = new Hyperliquid({ // Point at GoldRush - REST and WebSocket baseUrl: "https://hypercore.goldrushdata.com", wsUrl: `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, // REST still needs the Authorization header headers: { Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`, }, }); // Existing subscription methods work unchanged sdk.subscriptions.subscribeToL2Book("BTC", (book) => { console.log(book.coin, book.time, book.levels[0][0]); }); sdk.subscriptions.subscribeToL2Book("ETH", (book) => { console.log(book.coin, book.time, book.levels[0][0]); }); ``` > **Note:** If your SDK version doesn't expose a `wsUrl` option, instantiate the WebSocket client manually and pass it to the SDK, or patch the constant the SDK uses. See the override fallback below. ### Manual WebSocket fallback When the SDK doesn't expose a `wsUrl` knob, bypass it and drive the raw socket yourself: ```typescript import WebSocket from "ws"; const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.channel === "l2Book") { // Hand off to your application } }); ``` ## Python: `hyperliquid-dex/hyperliquid-python-sdk` ### Install ```bash pip install hyperliquid-python-sdk ``` ### Configure ```python import os from hyperliquid.info import Info # Point Info at GoldRush. skip_ws=False opens the WebSocket on init. info = Info( base_url="https://hypercore.goldrushdata.com", skip_ws=False, ) # Override the WebSocket URL on the underlying client so it includes the key info.ws_manager.ws_url = ( f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" ) # Inject the Authorization header for REST calls info.session.headers.update({ "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}" }) # Existing subscription methods work unchanged def on_book(msg): print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1]) info.subscribe({"type": "l2Book", "coin": "BTC"}, on_book) ``` > **Tip:** The SDK's `Info` class manages both REST and WebSocket. If you only need WebSocket, you can skip the `session.headers.update(...)` line. If you only need REST, pass `skip_ws=True` instead. ## Verification After cutover, confirm everything is wired correctly: 1. **Diff a known subscription** - subscribe to `l2Book` for the same coin against both endpoints; the streamed `channel` and `data` shape (keys, nesting, types) should match exactly. 2. **Confirm auth** - remove the `key` query parameter and confirm the WebSocket upgrade fails with HTTP `401`. If the socket opens, your request isn't reaching GoldRush. 3. **Confirm wildcard** - subscribe to `l2Book` **without** a `coin` and confirm you receive book snapshots for multiple assets. This call would be rejected on the public Hyperliquid WebSocket. ## Other SDKs The pattern is the same for any WebSocket client: override the connection URL to `wss://hypercore.goldrushdata.com/ws?key=`. If you run into a specific SDK that doesn't expose a URL override, [email us](mailto:support@covalenthq.com) - we'll publish a recipe. --- ## 20. batchClearinghouseState **Path:** api-reference/hyperliquid-info/batch-clearinghouse-state **Metadata:** ```yaml title: batchClearinghouseState description: Fetch perpetuals account state for 1 to 50 wallets in a single request. GoldRush-native batch wrapper around clearinghouseState; no upstream Hyperliquid equivalent. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Fetches perpetuals account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet, so polling N wallets means N round trips; this endpoint fans them out in parallel against our private node and returns a single combined response. This is a **GoldRush-native extension**. There is no equivalent on `api.hyperliquid.xyz/info`. The wrapped slots return exactly the same shape as Hyperliquid's native single-wallet `clearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"batchClearinghouseState"`. | | `users` | `array` | Yes | List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries. | | `dex` | `string` | No | Optional perpetuals DEX name. Forwarded unchanged to each per-wallet upstream call. Omit for the primary DEX. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "batchClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b" ] }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "batchClearinghouseState", users: [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b", ], }), }); const slots = await response.json(); for (const [i, slot] of slots.entries()) { if ("error" in slot) { console.warn(`wallet ${slot.user} failed: ${slot.message}`); continue; } console.log(`wallet ${i}: ${slot.withdrawable} USD withdrawable`); } ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "batchClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b", ], }, ) slots = response.json() for i, slot in enumerate(slots): if "error" in slot: print(f"wallet {slot['user']} failed: {slot['message']}") continue print(f"wallet {i}: {slot['withdrawable']} USD withdrawable") ``` ## Response ``` HTTP/2 200 OK Content-Type: application/json ``` The body is a JSON array. **Element `i` corresponds to the i-th unique wallet in the deduplicated input order.** Each element is either: - The raw upstream Hyperliquid response object for that wallet (success), or - A slot-level error object (failure for that wallet only, see below). ### All success Example success body for `batchClearinghouseState` with 3 wallets: one empty account, one with a single cross-margin position, one with a single isolated-margin position. ```json [ { "user": "0x.....", "marginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "0.0", "assetPositions": [], "time": 1777671895013 }, { "user": "0x.....", "marginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"}, "crossMarginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"}, "crossMaintenanceMarginUsed": "6.715183", "withdrawable": "6.464613", "assetPositions": [ { "type": "oneWay", "position": { "coin": "SUI", "szi": "-145.8", "leverage": { "type": "cross", "value": 6 }, "entryPx": "0.91652", "positionValue": "134.30367", "unrealizedPnl": "-0.674997", "returnOnEquity": "-0.0303077319", "liquidationPx": "1.0657275328", "marginUsed": "22.383945", "maxLeverage": 10, "cumFunding": { "allTime": "0.348217", "sinceOpen": "0.234102", "sinceChange": "0.206894" } } } ], "time": 1777671895076 }, { "user": "0x.....", "marginSummary": {"accountValue":"681.226963","totalNtlPos":"1353.54306","totalRawUsd":"-672.316097","totalMarginUsed":"681.226963"}, "crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "0.0", "assetPositions": [ { "type": "oneWay", "position": { "coin": "BTC", "szi": "0.01734", "leverage": { "type": "isolated", "value": 2, "rawUsd": "-672.316097" }, "entryPx": "77441.3", "positionValue": "1353.54306", "unrealizedPnl": "10.710288", "returnOnEquity": "0.0159517823", "liquidationPx": "39263.3464441622", "marginUsed": "681.226963", "maxLeverage": 40, "cumFunding": { "allTime": "0.326319", "sinceOpen": "0.271556", "sinceChange": "-0.026742" } } } ], "time": 1777671895076 } ] ``` ### Mixed result (one wallet failed) When a single wallet fails (upstream timeout, transport failure, parse failure, etc.), only its slot is replaced with an error object. The rest of the batch is unaffected. The HTTP status is still `200 OK`. ```json [ { "withdrawable": "13104.514502", "...": "..." }, { "error": "upstream_error", "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "message": "overall batch timeout exceeded" }, { "withdrawable": "0.0", "...": "..." } ] ``` ### Per-wallet error slot | Field | Type | Description | | --- | --- | --- | | `error` | `string` | Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field. | | `user` | `string` | The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order. | | `message` | `string` | Human-readable description: `upstream_error: `, `upstream returned HTTP `, `overall batch timeout exceeded`, or similar. | ## clearinghouseState slot field reference Each success slot mirrors Hyperliquid's native `clearinghouseState` response: `assetPositions[]`, `crossMarginSummary`, `marginSummary`, `crossMaintenanceMarginUsed`, `time`, `withdrawable`. There is no schema imposition - it's the raw upstream object. For full per-field types and notes (including the two `leverage` shapes and the nullable `liquidationPx`), see the single-wallet endpoint: ### clearinghouseState field reference Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot. [Read more](/api-reference/hyperliquid-info/clearinghouse-state) For the canonical upstream documentation, see Hyperliquid's [Perpetuals info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals). ## Notes - **No upstream equivalent.** This endpoint exists only on `hypercore.goldrushdata.com`. It is not a passthrough. - **Deduplication is case-insensitive.** Two addresses that differ only in case (`0xAbC...` vs `0xabc...`) collapse to a single slot in the output, at the position of the first occurrence in the input. - **Order preservation.** The order of slots in the response matches the order of unique wallets in the input. - **Partial failure is normal.** HTTP `200 OK` is returned even when individual slots are error envelopes. Always check for the `error` key on each slot before using its fields. - **No cursor or pagination.** All requested wallets are fanned out in parallel. For batches larger than 50, issue multiple calls. - **Use cases:** portfolio dashboards, multi-wallet PnL aggregators, fleet-level liquidation risk monitoring, copy-trade source-wallet inventory. --- ## 21. batchSpotClearinghouseState **Path:** api-reference/hyperliquid-info/batch-spot-clearinghouse-state **Metadata:** ```yaml title: batchSpotClearinghouseState description: Fetch spot balances for 1 to 50 wallets in a single request. GoldRush-native batch wrapper around spotClearinghouseState; no upstream Hyperliquid equivalent. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Fetches spot account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet; this endpoint fans the requests out in parallel against our private node and returns a combined response. This is a **GoldRush-native extension**. There is no equivalent on `api.hyperliquid.xyz/info`. The wrapped slots return exactly the same shape as Hyperliquid's native single-wallet `spotClearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"batchSpotClearinghouseState"`. | | `users` | `array` | Yes | List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries. | | `dex` | `string` | No | Reserved for future HIP-3 spot DEX support. Pass empty string or omit. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "batchSpotClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "batchSpotClearinghouseState", users: [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", ], }), }); const slots = await response.json(); for (const [i, slot] of slots.entries()) { if ("error" in slot) { console.warn(`wallet ${slot.user} failed: ${slot.message}`); continue; } console.log(`wallet ${i}: ${slot.balances.length} tokens`); } ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "batchSpotClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", ], }, ) slots = response.json() for i, slot in enumerate(slots): if "error" in slot: print(f"wallet {slot['user']} failed: {slot['message']}") continue print(f"wallet {i}: {len(slot['balances'])} tokens") ``` ## Response ``` HTTP/2 200 OK Content-Type: application/json ``` The body is a JSON array. **Element `i` corresponds to the i-th unique wallet in the deduplicated input order.** Each element is either: - The raw upstream Hyperliquid response object for that wallet (success), or - A slot-level error object (failure for that wallet only, see below). ### All success Example success body for `batchSpotClearinghouseState` with 3 wallets: one empty wallet, one with a single USDC balance, one with multiple tokens including held amounts. ```json [ { "user": "0x.....", "balances": [] }, { "user": "0x.....", "balances": [ { "coin": "USDC", "token": 0, "total": "0.001124", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDE", "token": 235, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDT0", "token": 268, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDH", "token": 360, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" } ], "tokenToAvailableAfterMaintenance": [[0, "0.001124"]] }, { "user": "0x.....", "balances": [ { "coin": "USDC", "token": 0, "total": "129411.68874505", "hold": "73888.84763", "entryNtl": "0.0" }, { "coin": "HYPE", "token": 150, "total": "959.37146013", "hold": "0.0", "entryNtl": "33092.4684" }, { "coin": "UBTC", "token": 197, "total": "0.2104009544", "hold": "0.0", "entryNtl": "16128.2486005" }, { "coin": "UETH", "token": 221, "total": "20.87812637", "hold": "7.0018", "entryNtl": "49605.34810641" } ] } ] ``` ### Mixed result (one wallet failed) When a single wallet fails (upstream timeout, transport failure, parse failure, etc.), only its slot is replaced with an error object. The rest of the batch is unaffected. The HTTP status is still `200 OK`. ```json [ { "balances": [...] }, { "error": "upstream_error", "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "message": "overall batch timeout exceeded" } ] ``` ### Per-wallet error slot | Field | Type | Description | | --- | --- | --- | | `error` | `string` | Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field. | | `user` | `string` | The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order. | | `message` | `string` | Human-readable description: `upstream_error: `, `upstream returned HTTP `, `overall batch timeout exceeded`, or similar. | ## spotClearinghouseState slot field reference Each success slot mirrors Hyperliquid's native `spotClearinghouseState` response: `balances[]` plus the optional `tokenToAvailableAfterMaintenance` field. There is no schema imposition - it's the raw upstream object. The `tokenToAvailableAfterMaintenance` field is **optional** and only present when at least one token has a non-zero margin-deduction-aware balance. Wallets without this field can simply ignore it; absence is normal for empty or inactive wallets. For full per-field types and notes, see the single-wallet endpoint: ### spotClearinghouseState field reference Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot. [Read more](/api-reference/hyperliquid-info/spot-clearinghouse-state) For the canonical upstream documentation, see Hyperliquid's [Spot info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot). ## Notes - **No upstream equivalent.** This endpoint exists only on `hypercore.goldrushdata.com`. It is not a passthrough. - **Deduplication is case-insensitive.** Two addresses that differ only in case collapse to a single slot at the position of the first occurrence in the input. - **Order preservation.** Slots in the response are in the order of unique wallets in the input. - **Partial failure is normal.** HTTP `200 OK` is returned even when individual slots are error envelopes. Always check for the `error` key on each slot before using its fields. - **No cursor or pagination.** All requested wallets are fanned out in parallel. For batches larger than 50, issue multiple calls. - **Use cases:** token treasury monitoring, holder analytics, balance reconciliation, multi-wallet airdrop eligibility checks. --- ## 22. clearinghouseState **Path:** api-reference/hyperliquid-info/clearinghouse-state **Metadata:** ```yaml title: clearinghouseState description: Returns a user's perpetuals account state - open positions, margin summary, account value, and withdrawable balance. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's perpetuals account state: every open position, margin summary, account value, and withdrawable balance. User-keyed: pass a wallet address. Cached and kept fresh by a per-user WebSocket subscription to upstream Hyperliquid, so updates are sub-second after any user event. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"clearinghouseState"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) returns canonical Hyperliquid perp state. Pass a builder code to query a HIP-3 deployer's perp DEX. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "clearinghouseState", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const state = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) state = response.json() ``` ## Response ```json { "marginSummary": { "accountValue": "12450.83", "totalNtlPos": "8500.00", "totalRawUsd": "5200.50", "totalMarginUsed": "1700.00" }, "crossMarginSummary": { "accountValue": "12450.83", "totalNtlPos": "8500.00", "totalRawUsd": "5200.50", "totalMarginUsed": "1700.00" }, "crossMaintenanceMarginUsed": "850.00", "withdrawable": "10750.83", "assetPositions": [ { "type": "oneWay", "position": { "coin": "ETH", "szi": "2.5", "leverage": { "type": "cross", "value": 5 }, "entryPx": "3400.0", "positionValue": "8500.00", "unrealizedPnl": "120.50", "returnOnEquity": "0.07", "liquidationPx": "2800.5", "marginUsed": "1700.00", "maxLeverage": 50, "cumFunding": { "allTime": "12.30", "sinceOpen": "1.50", "sinceChange": "0.50" } } } ], "time": 1735689600000 } ``` ### Field descriptions > **Note:** All numeric fields below (account value, position size, prices, funding amounts, etc.) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `marginSummary` | `object` | Top-level account margin and value summary. | | `marginSummary.accountValue` | `string` | Total account value in USD. | | `marginSummary.totalNtlPos` | `string` | Total notional position size. | | `marginSummary.totalRawUsd` | `string` | Raw USDC balance excluding unrealized PnL. | | `marginSummary.totalMarginUsed` | `string` | Margin currently committed to open positions. | | `crossMarginSummary` | `object` | Cross-margin subset of the margin summary. Same fields. | | `crossMaintenanceMarginUsed` | `string` | Maintenance margin currently used for cross positions. | | `withdrawable` | `string` | Amount currently withdrawable, in USD. | | `assetPositions` | `array` | Open positions, one entry per coin. | | `assetPositions.type` | `string` | Position type - `"oneWay"` for the standard mode. | | `assetPositions.position` | `object` | __RESPONSE_ROW__coin string Asset symbol. __RESPONSE_ROW__assetPositions.szi string Signed position size (positive = long, negative = short). __RESPONSE_ROW__assetPositions.leverage object Two shapes: - Cross: `{ "type": "cross", "value": int }` - Isolated: `{ "type": "isolated", "value": int, "rawUsd": string }` `rawUsd` is **only present** for isolated leverage and may be negative. __RESPONSE_ROW__assetPositions.entryPx string Volume-weighted entry price. __RESPONSE_ROW__assetPositions.positionValue string Current notional value. __RESPONSE_ROW__assetPositions.unrealizedPnl string Unrealized PnL in USD. __RESPONSE_ROW__assetPositions.returnOnEquity string Unrealized return on margin used. __RESPONSE_ROW__assetPositions.liquidationPx string \| null Liquidation price. **May be literal JSON `null`** when no near-term liquidation applies (e.g. cross-margin with deep cushion). __RESPONSE_ROW__assetPositions.marginUsed string Margin committed to this position. __RESPONSE_ROW__assetPositions.maxLeverage int Maximum leverage for this asset. __RESPONSE_ROW__assetPositions.cumFunding object Cumulative funding paid: `allTime`, `sinceOpen`, `sinceChange`. | | `time` | `int` | Snapshot timestamp in milliseconds since Unix epoch. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "clearinghouseState", "user": "..."}`. - For real-time push instead of polling, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) with the same wallet address. - The optional `dex` field returns state on a HIP-3 deployer's perp DEX. --- ## 23. delegatorHistory **Path:** api-reference/hyperliquid-info/delegator-history **Metadata:** ```yaml title: delegatorHistory description: Returns a user's HYPE staking event history - delegate, undelegate, deposit, and withdrawal events with timestamps and validator addresses. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a user's HYPE staking event history: every delegate, undelegate, staking-account deposit, and unstake withdrawal, ordered by `time`. Use this to reconstruct the sequence behind the totals shown in [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary). User-keyed. Each entry carries a `delta` whose discriminator describes the event variant. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"delegatorHistory"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "delegatorHistory", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "delegatorHistory", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const events = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorHistory", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) events = response.json() ``` ## Response An array of staking event objects. ```json [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "delegate": { "validator": "0x5ac99df645f3414876c816caa18b2d234024b487", "amount": "1000.5", "isUndelegate": false } } } ] ``` ### Field descriptions > **Note:** `delta.delegate.amount` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float. | Field | Type | Description | | --- | --- | --- | | `time` | `int` | Unix timestamp in milliseconds when the event was applied. | | `hash` | `string` | L1 transaction hash that produced the event. | | `delta` | `object` | Event-specific payload. The example above shows a `delegate` variant; other variants observed in the wild include `cDeposit` (staking-account deposit) and `withdrawal` (unstake withdrawal). The shape changes per variant. | | `delta.delegate.validator` | `string` | Validator address the delegation targets. | | `delta.delegate.amount` | `string` | HYPE amount delegated or undelegated. | | `delta.delegate.isUndelegate` | `boolean` | `true` for an undelegate, `false` for a delegate. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorHistory", "user": "..."}`. - For totals (delegated, undelegated, pending withdrawal sums), use [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary). - For accrued staking and commission rewards, use [`delegatorRewards`](/api-reference/hyperliquid-info/delegator-rewards). - For real-time push of staking events, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event) entries. --- ## 24. delegatorRewards **Path:** api-reference/hyperliquid-info/delegator-rewards **Metadata:** ```yaml title: delegatorRewards description: Returns a user's accrued HYPE staking rewards - delegation rewards and validator commission earnings, one entry per accrual. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's accrued HYPE staking rewards: one entry per accrual, with the timestamp, the source (delegation reward versus validator commission), and the amount. User-keyed. Use this for tax reports, reward attribution dashboards, and validator P&L; use [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history) for the underlying delegate / undelegate events and [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary) for current totals. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"delegatorRewards"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "delegatorRewards", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "delegatorRewards", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const rewards = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorRewards", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) rewards = response.json() ``` ## Response An array of reward entries. ```json [ { "time": 1735689600000, "source": "delegation", "totalAmount": "1.5234" }, { "time": 1735776000000, "source": "commission", "totalAmount": "0.8791" } ] ``` ### Field descriptions > **Note:** `totalAmount` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float. | Field | Type | Description | | --- | --- | --- | | `time` | `int` | Unix timestamp in milliseconds when the reward accrued. | | `source` | `string` | Reward source. `"delegation"` for rewards earned by delegating to a validator; `"commission"` for commission earned as a validator on others' delegations. | | `totalAmount` | `string` | Reward amount in HYPE. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorRewards", "user": "..."}`. - For the underlying delegate / undelegate / withdrawal events, use [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history). - For current totals (delegated, undelegated, pending withdrawal sums), use [`delegatorSummary`](/api-reference/hyperliquid-info/delegator-summary). - For real-time push of rewards-claim events, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerRewardsClaim` entries. --- ## 25. delegatorSummary **Path:** api-reference/hyperliquid-info/delegator-summary **Metadata:** ```yaml title: delegatorSummary description: Returns a user's HYPE staking summary - currently delegated and undelegated amounts plus pending withdrawal totals. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's HYPE staking summary: the amount currently delegated, the amount sitting undelegated in the staking account, the total of any pending withdrawals, and how many such withdrawals are pending. User-keyed. Use this for a one-shot snapshot; for the underlying sequence of delegate / undelegate / deposit / withdrawal events, use [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history). ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"delegatorSummary"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "delegatorSummary", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "delegatorSummary", user: "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }), }); const summary = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorSummary", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }, ) summary = response.json() ``` ## Response ```json { "delegated": "1500.50", "undelegated": "250.00", "totalPendingWithdrawal": "100.00", "nPendingWithdrawals": 2 } ``` ### Field descriptions > **Note:** `delegated`, `undelegated`, and `totalPendingWithdrawal` are returned as **decimal strings**. Do not parse them as floats. | Field | Type | Description | | --- | --- | --- | | `delegated` | `string` | HYPE currently delegated to validators. | | `undelegated` | `string` | HYPE in the staking account but not delegated. | | `totalPendingWithdrawal` | `string` | Sum of HYPE in any in-flight unstake withdrawals. | | `nPendingWithdrawals` | `int` | Count of in-flight unstake withdrawals. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorSummary", "user": "..."}`. - For the sequence of delegation events behind these totals, use [`delegatorHistory`](/api-reference/hyperliquid-info/delegator-history). - For accrued staking and commission rewards, use [`delegatorRewards`](/api-reference/hyperliquid-info/delegator-rewards). --- ## 26. frontendOpenOrders **Path:** api-reference/hyperliquid-info/frontend-open-orders **Metadata:** ```yaml title: frontendOpenOrders description: Returns a user's open orders enriched with frontend-only metadata - TP/SL trigger info, isPositionTpsl, reduceOnly, and orderType. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's currently open orders, enriched with the **frontend-only metadata** the Hyperliquid web UI uses: TP/SL trigger info, whether the order is a position-level TP/SL, reduce-only flag, and the human-readable order type. User-keyed. Updated on every order placement, cancellation, or fill. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"frontendOpenOrders"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string returns orders on the canonical Hyperliquid perp DEX. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "frontendOpenOrders", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const orders = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) orders = response.json() ``` ## Response An array of open orders. Each order object includes the standard `openOrders` fields plus the `frontend*` enrichment fields. ```json [ { "coin": "ETH", "side": "B", "limitPx": "3300.0", "sz": "0.5", "oid": 95012345, "timestamp": 1735689600000, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "children": [], "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "origSz": "0.5", "tif": "Gtc", "cloid": null }, { "coin": "ETH", "side": "A", "limitPx": "3800.0", "sz": "2.5", "oid": 95012346, "timestamp": 1735689700000, "triggerCondition": "Mark price >= 3800.0", "isTrigger": true, "triggerPx": "3800.0", "children": [], "isPositionTpsl": true, "reduceOnly": true, "orderType": "Take Profit Market", "origSz": "2.5", "tif": null, "cloid": null } ] ``` ### Field descriptions | Field | Type | Description | | --- | --- | --- | | `coin` | `string` | Asset symbol. | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `limitPx` | `string` | Limit price. | | `sz` | `string` | Remaining order size. | | `oid` | `int` | Numeric order ID. | | `timestamp` | `int` | Order placement time in milliseconds since Unix epoch. | | `triggerCondition` | `string` | Human-readable trigger condition. `"N/A"` for non-trigger orders. | | `isTrigger` | `boolean` | `true` for stop-loss, take-profit, and other conditional orders. | | `triggerPx` | `string` | Trigger price for conditional orders. `"0.0"` for limits. | | `children` | `array` | Child orders attached to this parent (e.g. bracket orders). | | `isPositionTpsl` | `boolean` | `true` if this is a position-level TP/SL (closes the entire position when triggered). | | `reduceOnly` | `boolean` | `true` if this order can only reduce, not increase, position size. | | `orderType` | `string` | Human-readable order type - `"Limit"`, `"Take Profit Market"`, `"Stop Limit"`, etc. | | `origSz` | `string` | Original order size before any partial fills. | | `tif` | `string` | Time-in-force - `"Gtc"`, `"Ioc"`, `"Alo"`, or `null` for trigger orders. | | `cloid` | `string` | Client order ID (null if not provided at placement). | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "frontendOpenOrders", "user": "..."}`. - Use `frontendOpenOrders` instead of `openOrders` when you need the trigger metadata and human-readable order type - exactly what the Hyperliquid web UI displays. - For a real-time stream of order placement and cancellation events, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream). --- ## 27. metaAndAssetCtxs **Path:** api-reference/hyperliquid-info/meta-and-asset-ctxs **Metadata:** ```yaml title: metaAndAssetCtxs description: Returns the perpetuals universe metadata plus per-asset live mark price, funding, open interest, and day volume. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a tuple `[meta, assetCtxs[]]` covering the entire Hyperliquid perpetuals universe - every coin's metadata plus a live snapshot of mark price, funding rate, open interest, and 24-hour volume. This is a global, non-user-keyed type. A single cache entry is shared across all callers and is refreshed continuously from upstream Hyperliquid. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"metaAndAssetCtxs"`. | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) returns the canonical Hyperliquid perp universe. Pass a builder code (e.g. `"xyz"`) to query a HIP-3 deployer's universe. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "metaAndAssetCtxs", "dex": "" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "metaAndAssetCtxs", dex: "", }), }); const [meta, assetCtxs] = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "metaAndAssetCtxs", "dex": ""}, ) meta, asset_ctxs = response.json() ``` ## Response A two-element JSON array. Element 0 is the universe metadata; element 1 is an array of per-asset contexts indexed identically to the `universe` array. ```json [ { "universe": [ { "name": "BTC", "szDecimals": 5, "maxLeverage": 50 }, { "name": "ETH", "szDecimals": 4, "maxLeverage": 50 }, { "name": "SOL", "szDecimals": 2, "maxLeverage": 20 } ] }, [ { "funding": "0.0000125", "openInterest": "12345.67", "prevDayPx": "67500.0", "dayNtlVlm": "894500000.0", "premium": "0.00001", "oraclePx": "68210.5", "markPx": "68215.0", "midPx": "68214.0", "impactPxs": ["68210.0", "68220.0"], "dayBaseVlm": "13130.45" }, { "funding": "0.0000050", "openInterest": "9876.54", "...": "..." }, { "funding": "0.0000200", "openInterest": "543210.98", "...": "..." } ] ] ``` ### Element 0: `meta` | Field | Type | Description | | --- | --- | --- | | `universe` | `array` | Array of perp asset metadata, indexed identically to element 1's `assetCtxs`. | | `universe.name` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"`. For HIP-3 markets, includes the deployer prefix. | | `universe.szDecimals` | `int` | Number of decimals for size precision. | | `universe.maxLeverage` | `int` | Maximum leverage for this asset. | | `universe.onlyIsolated` | `boolean` | If true, the asset only supports isolated margin. | ### Element 1: `assetCtxs[]` Array of per-asset live context, indexed identically to `universe`. | Field | Type | Description | | --- | --- | --- | | `funding` | `string` | Current funding rate (decimal string). | | `openInterest` | `string` | Open interest in base units. | | `prevDayPx` | `string` | Mark price 24 hours ago. | | `dayNtlVlm` | `string` | 24-hour notional volume in USD. | | `premium` | `string` | Mark vs oracle premium. | | `oraclePx` | `string` | Current oracle price. | | `markPx` | `string` | Current mark price. | | `midPx` | `string` | Current orderbook mid price. | | `impactPxs` | `array` | Bid/ask impact prices `[bidImpact, askImpact]`. | | `dayBaseVlm` | `string` | 24-hour volume in base units. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "metaAndAssetCtxs"}`. - For real-time mark-price updates, use the [Streaming API OHLCV streams](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) instead of polling. --- ## 28. outcomeMeta **Path:** api-reference/hyperliquid-info/outcome-meta **Metadata:** ```yaml title: outcomeMeta description: Returns the active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and side specs for every binary outcome market on HyperCore. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns the live HIP-4 outcome universe: every active binary outcome market on HyperCore with its integer `outcome` ID, human-readable `name`, structured `description`, and `sideSpecs` (`Yes` / `No`). This is a global, non-user-keyed type. A single cache entry is shared across all callers and is refreshed continuously from upstream Hyperliquid. `outcomeMeta` is HIP-4's dedicated metadata type - separate from [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs), which covers perps and spot. Use it to discover live outcome IDs and compute per-side market encodings (`encoding = 10 * outcome + side`) before subscribing to OHLCV or fills. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"outcomeMeta"`. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "outcomeMeta" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "outcomeMeta", }), }); const { outcomes } = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "outcomeMeta"}, ) outcomes = response.json()["outcomes"] ``` ## Response ```json { "outcomes": [ { "outcome": 123, "name": "Recurring", "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m", "sideSpecs": [ { "name": "Yes" }, { "name": "No" } ] } ] } ``` ### Field descriptions | Field | Type | Description | | --- | --- | --- | | `outcomes` | `array` | Array of active outcome markets. | | `outcomes.outcome` | `int` | Integer outcome ID. Combine with a side index to compute the tradeable market encoding: `encoding = 10 * outcome + side`. An outcome with `Yes` (side 0) and `No` (side 1) yields two encodings (e.g. `1230` and `1231`). | | `outcomes.name` | `string` | Human-readable label for the market - for example, `"Recurring"` for repeating daily/weekly markets. | | `outcomes.description` | `string` | Pipe-delimited spec describing the market. Parse it once to extract the full definition: \| Field \| Example \| Meaning \| \|---\|---\|---\| \| `class` \| `priceBinary` \| Market class (binary outcome on a price threshold). \| \| `underlying` \| `HYPE` \| Asset the outcome resolves against. \| \| `expiry` \| `20260310-1100` \| Resolution timestamp, `YYYYMMDD-HHMM` UTC. \| \| `targetPrice` \| `34.5` \| Threshold the underlying is compared against at expiry. \| \| `period` \| `3m` \| Recurrence cadence for repeating markets. \| | | `outcomes.sideSpecs` | `array` | Tradeable sides of the outcome, ordered by side index. For binary outcomes, index 0 is `Yes` and index 1 is `No`. __RESPONSE_ROW__name string Side label - typically `"Yes"` or `"No"` for binary outcomes. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "outcomeMeta"}`. - For real-time price updates on a discovered outcome, subscribe to [`ohlcvCandlesForPair`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) using the per-side encoding. See the [HIP-4 markets recipe](/goldrush-hyperliquid/streaming/hip4-markets) for end-to-end discovery and streaming patterns. - HIP-4 launched on Hyperliquid mainnet on **2 May 2026**. Read the canonical spec: [HIP-4: Outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets). --- ## 29. spotClearinghouseState **Path:** api-reference/hyperliquid-info/spot-clearinghouse-state **Metadata:** ```yaml title: spotClearinghouseState description: Returns a user's spot balances per token, including total USD value. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's spot account state - token-by-token balances and the total USD value. User-keyed. Cached and kept fresh by a per-user WebSocket subscription, so updates are sub-second after any user event. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"spotClearinghouseState"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | Reserved for future HIP-3 spot DEX support. Pass empty string. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "spotClearinghouseState", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const state = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) state = response.json() ``` ## Response ```json { "balances": [ { "coin": "USDC", "token": 0, "hold": "0.0", "total": "5000.00", "entryNtl": "5000.00" }, { "coin": "HYPE", "token": 150, "hold": "0.0", "total": "320.45", "entryNtl": "1530.00" }, { "coin": "PURR", "token": 1, "hold": "0.0", "total": "12500.0", "entryNtl": "375.00" } ], "tokenToAvailableAfterMaintenance": [[0, "5000.00"]] } ``` ### Field descriptions > **Note:** All numeric balance fields (`total`, `hold`, `entryNtl`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `balances` | `array` | One entry per token the wallet has interacted with on Hyperliquid spot. May be empty (`[]`) for wallets with no spot history. | | `balances.coin` | `string` | Token ticker symbol (e.g. `"USDC"`, `"PURR"`, `"HYPE"`). | | `balances.token` | `int` | Numeric token index assigned by Hyperliquid. The pair `(coin, token)` together identifies the asset. | | `balances.hold` | `string` | Portion of `total` currently locked in open spot orders. Withdrawable balance is `total - hold`. | | `balances.total` | `string` | Total balance (held + free). | | `balances.entryNtl` | `string` | Entry notional value at acquisition, in USD. | | `tokenToAvailableAfterMaintenance` | `array` | **Optional.** Present only when at least one token has a non-zero margin-deduction-aware balance. Each tuple is `[tokenId, availableAmountString]` where `tokenId` references `balances[].token`. Wallets without this field can ignore it; absence is normal for empty or inactive wallets. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotClearinghouseState", "user": "..."}`. - USDC balance is returned as `token: 0`. - For real-time push of spot transfers, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerSpotTransfer` events. --- ## 30. spotMetaAndAssetCtxs **Path:** api-reference/hyperliquid-info/spot-meta-and-asset-ctxs **Metadata:** ```yaml title: spotMetaAndAssetCtxs description: Returns the spot universe metadata, token configuration, and per-pair live mark price, mid, and 24-hour volume. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a tuple `[spotMeta, assetCtxs[]]` covering the entire Hyperliquid spot universe - every pair's universe entry, every token's metadata, and a live snapshot of mark price, mid price, prior-day price, and 24-hour notional volume per pair. This is the spot counterpart of [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs). Global, non-user-keyed; a single cache entry is shared across all callers and refreshed continuously from upstream Hyperliquid. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"spotMetaAndAssetCtxs"`. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "spotMetaAndAssetCtxs" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "spotMetaAndAssetCtxs", }), }); const [spotMeta, assetCtxs] = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "spotMetaAndAssetCtxs"}, ) spot_meta, asset_ctxs = response.json() ``` ## Response A two-element JSON array. Element 0 is the spot universe and token metadata; element 1 is an array of per-pair live contexts indexed identically to element 0's `universe`. ```json [ { "universe": [ { "name": "PURR/USDC", "tokens": [1, 0], "index": 0, "isCanonical": true } ], "tokens": [ { "name": "USDC", "szDecimals": 8, "weiDecimals": 8, "index": 0, "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054", "isCanonical": true, "evmContract": null, "fullName": null }, { "name": "PURR", "szDecimals": 0, "weiDecimals": 5, "index": 1, "tokenId": "0xc1fb593aeffbeb02f85e0308e9956a90", "isCanonical": true, "evmContract": null, "fullName": null } ] }, [ { "coin": "PURR/USDC", "markPx": "0.5250", "midPx": "0.5245", "prevDayPx": "0.4800", "dayNtlVlm": "1250000.0", "dayBaseVlm": "2380952.38", "circulatingSupply": "1000000000.0" } ] ] ``` ### Element 0: `spotMeta` | Field | Type | Description | | --- | --- | --- | | `universe` | `array` | Array of spot pairs, indexed identically to element 1's `assetCtxs`. | | `universe.name` | `string` | Pair label - e.g. `"PURR/USDC"`. | | `universe.tokens` | `array` | Two-element array of token indices `[base, quote]` referencing entries in `tokens[].index`. | | `universe.index` | `int` | Numeric pair index. The spot encoding for trading subscriptions is `10000 + index`. | | `universe.isCanonical` | `boolean` | `true` for pairs in the canonical Hyperliquid spot universe. | | `tokens` | `array` | Token configuration referenced by `universe[].tokens`. | | `tokens.name` | `string` | Token symbol - e.g. `"USDC"`, `"PURR"`. | | `tokens.szDecimals` | `int` | Number of decimals used for size precision. | | `tokens.weiDecimals` | `int` | Number of decimals used for the on-chain wei representation. | | `tokens.index` | `int` | Token index. `(coin, index)` together identifies the asset. | | `tokens.tokenId` | `string` | Hyperliquid token identifier (hex). | | `tokens.isCanonical` | `boolean` | `true` for tokens deployed in the canonical Hyperliquid spot universe. | | `tokens.evmContract` | `object | null` | EVM contract address if the token has an HyperEVM mapping; `null` otherwise. | | `tokens.fullName` | `string | null` | Optional full token name. | ### Element 1: `assetCtxs[]` Array of per-pair live context, indexed identically to `universe`. > **Note:** All numeric fields below are returned as **decimal strings**. Do not parse them as floats. | Field | Type | Description | | --- | --- | --- | | `coin` | `string` | Pair symbol - matches `universe[].name`. | | `markPx` | `string` | Current mark price. | | `midPx` | `string` | Current orderbook mid price. | | `prevDayPx` | `string` | Mark price 24 hours ago. | | `dayNtlVlm` | `string` | 24-hour notional volume in USDC. | | `dayBaseVlm` | `string` | 24-hour volume in base units. | | `circulatingSupply` | `string` | Circulating supply of the base token. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotMetaAndAssetCtxs"}`. - For perp universe + live contexts, use [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) instead. - For real-time mark-price updates on a discovered spot pair, use the [Streaming API OHLCV pair stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream). --- ## 31. subAccounts **Path:** api-reference/hyperliquid-info/sub-accounts **Metadata:** ```yaml title: subAccounts description: Returns a master account's sub-accounts with each sub-account's perp clearinghouse and spot state. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns the sub-accounts owned by a master wallet, with each sub-account's perp [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) and spot [`spotClearinghouseState`](/api-reference/hyperliquid-info/spot-clearinghouse-state) inlined per slot - so a single call returns the full balance picture across the master plus its sub-accounts. User-keyed. The result is `null` for wallets that aren't master accounts. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"subAccounts"`. | | `user` | `string` | Yes | The master wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "subAccounts", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "subAccounts", user: "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }), }); const subAccounts = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "subAccounts", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }, ) sub_accounts = response.json() ``` ## Response An array of sub-account objects, or `null` if the queried wallet is not a master account. ```json [ { "name": "trading-bot-1", "subAccountUser": "0x2b804617c6f63c040377e95bb276811747006f4b", "master": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", "clearinghouseState": { "marginSummary": { "accountValue": "5000.00", "totalNtlPos": "0.0", "totalRawUsd": "5000.00", "totalMarginUsed": "0.0" }, "crossMarginSummary": { "accountValue": "5000.00", "totalNtlPos": "0.0", "totalRawUsd": "5000.00", "totalMarginUsed": "0.0" }, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "5000.00", "assetPositions": [], "time": 1735689600000 }, "spotState": { "balances": [ { "coin": "USDC", "token": 0, "hold": "0.0", "total": "1000.00", "entryNtl": "1000.00" } ] } } ] ``` ### Field descriptions | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Optional human-readable label assigned to the sub-account. | | `subAccountUser` | `string` | The sub-account's wallet address (0x-prefixed hex). | | `master` | `string` | The master wallet address that owns this sub-account. | | `clearinghouseState` | `object` | Perp account state for this sub-account. Identical shape to the single-wallet [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) response - margin summaries, asset positions, withdrawable balance, snapshot timestamp. | | `spotState` | `object` | Spot account state for this sub-account. Identical shape to the single-wallet [`spotClearinghouseState`](/api-reference/hyperliquid-info/spot-clearinghouse-state) response - per-token balances and the optional `tokenToAvailableAfterMaintenance` array. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "subAccounts", "user": "..."}`. - For per-sub-account real-time updates, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) on each `subAccountUser` returned here. - For multi-wallet polling without traversing master/sub-account hierarchy, see [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state) and [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state). --- ## 32. userFillsByTime **Path:** api-reference/hyperliquid-info/user-fills-by-time **Metadata:** ```yaml title: userFillsByTime description: Returns a user's fills bounded by a start and end time - the time-windowed variant of userFills. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's fills bounded by a `[startTime, endTime)` window in milliseconds. Use this when you want fills since a specific moment - daily P&L recaps, post-deploy backfills, or rebuilding a tax ledger - rather than the most recent N fills. User-keyed. The upstream Hyperliquid API caps each response at **2,000 fills** and only retains the **10,000 most recent** fills per wallet; window queries that span more than that are truncated. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userFillsByTime"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | Yes | Unix timestamp in milliseconds. Inclusive lower bound. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | | `aggregateByTime` | `boolean` | No | When `true`, partial fills sharing the same timestamp are consolidated into one row. Default `false`. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userFillsByTime", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000 }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userFillsByTime", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, }), }); const fills = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFillsByTime", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, }, ) fills = response.json() ``` ## Response An array of fill objects ordered by `time`. ```json [ { "coin": "BTC", "px": "43250.5", "sz": "0.1", "side": "B", "time": 1735689600000, "startPosition": "0", "dir": "Open Long", "closedPnl": "0", "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "oid": 95012345, "tid": 678900012345, "crossed": true, "fee": "2.16", "feeToken": "USDC" } ] ``` ### Field descriptions > **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | `px` | `string` | Fill execution price. | | `sz` | `string` | Fill size. | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `time` | `int` | Unix timestamp in milliseconds when the fill executed. | | `startPosition` | `string` | Signed position size on the same coin immediately before this fill. | | `dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | `closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). | | `hash` | `string` | L1 transaction hash that included this fill. | | `oid` | `int` | Parent order ID. | | `tid` | `int` | Unique trade ID. | | `crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. | | `fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. | | `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | `builderFee` | `string` | Optional. Builder fee paid for this fill if the order routed through a builder code. | | `twapId` | `int | null` | Optional TWAP order ID if this fill is a slice of a TWAP order. | | `cloid` | `string | null` | Optional client order ID if one was set at order placement. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFillsByTime", "user": "...", "startTime": ...}`. - Each response contains at most **2,000 fills**; widen the window in chunks if you need more. Hyperliquid retains only the **10,000 most recent** fills per wallet. - For real-time push instead of windowed polling, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events. - Use [`userFills`](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals) (no `Time` suffix) when you only need the most recent N fills without specifying a window. --- ## 33. userFills **Path:** api-reference/hyperliquid-info/user-fills **Metadata:** ```yaml title: userFills description: Returns a user's most recent fills (up to 2,000), with no time window. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's most recent fills, ordered most-recent-first. Use this for recent-activity feeds, last-N-fills displays, or any view where you want the latest trades without specifying a window. Reach for [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) when you need fills inside a specific `[startTime, endTime)` range. User-keyed. The upstream Hyperliquid API caps each response at **2,000 fills** and only retains the **10,000 most recent** fills per wallet. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userFills"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `aggregateByTime` | `boolean` | No | When `true`, partial fills sharing the same timestamp are consolidated into one row. Default `false`. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userFills", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const fills = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) fills = response.json() ``` ## Response An array of fill objects ordered most-recent-first. ```json [ { "coin": "BTC", "px": "43250.5", "sz": "0.1", "side": "B", "time": 1735689600000, "startPosition": "0", "dir": "Open Long", "closedPnl": "0", "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "oid": 95012345, "tid": 678900012345, "crossed": true, "fee": "2.16", "feeToken": "USDC" } ] ``` ### Field descriptions > **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | `px` | `string` | Fill execution price. | | `sz` | `string` | Fill size. | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `time` | `int` | Unix timestamp in milliseconds when the fill executed. | | `startPosition` | `string` | Signed position size on the same coin immediately before this fill. | | `dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | `closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). | | `hash` | `string` | L1 transaction hash that included this fill. | | `oid` | `int` | Parent order ID. | | `tid` | `int` | Unique trade ID. | | `crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. | | `fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. | | `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | `builderFee` | `string` | Optional. Builder fee paid for this fill if the order routed through a builder code. | | `twapId` | `int | null` | Optional TWAP order ID if this fill is a slice of a TWAP order. | | `cloid` | `string | null` | Optional client order ID if one was set at order placement. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFills", "user": "..."}`. - Each response contains at most **2,000 fills**, and Hyperliquid retains only the **10,000 most recent** fills per wallet. Use [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) to walk arbitrary time windows for deeper history. - For real-time push instead of polling, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events. --- ## 34. userFunding **Path:** api-reference/hyperliquid-info/user-funding **Metadata:** ```yaml title: userFunding description: Returns a user's per-coin funding payment history with funding rate, applied size, and USDC amount per event. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's funding payment history within a `[startTime, endTime)` window. Each entry is one funding application: a coin, the rate that was applied, the position size at the time, and the resulting USDC delta (negative = paid, positive = received). User-keyed. Use this for funding-only P&L attribution; use [`userNonFundingLedgerUpdates`](/api-reference/hyperliquid-info/user-non-funding-ledger-updates) for everything else. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userFunding"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | No | Unix timestamp in milliseconds. Inclusive lower bound for the window. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userFunding", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, "endTime": 1735776000000 }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userFunding", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, endTime: 1735776000000, }), }); const events = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFunding", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, "endTime": 1735776000000, }, ) events = response.json() ``` ## Response An array of funding event objects, one per applied funding interval and coin. ```json [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "type": "funding", "coin": "BTC", "usdc": "-50.25", "szi": "1.5", "fundingRate": "0.0001", "nSamples": null } } ] ``` ### Field descriptions > **Note:** All numeric `delta` fields are returned as **decimal strings**. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `time` | `int` | Unix timestamp in milliseconds when the funding payment was applied. | | `hash` | `string` | L1 transaction hash that included the funding application. | | `delta` | `object` | Funding-event payload. | | `delta.type` | `string` | Always `"funding"` for entries returned by this endpoint. | | `delta.coin` | `string` | Asset symbol the funding rate applied to. | | `delta.usdc` | `string` | USDC delta credited to or debited from the account. Negative values are paid, positive values are received. | | `delta.szi` | `string` | Signed position size at the time of application (positive = long, negative = short). | | `delta.fundingRate` | `string` | The funding rate applied (decimal string, e.g. `"0.0001"` for 1 bp). | | `delta.nSamples` | `int | null` | Optional - number of samples used by the upstream funding calculation. May be `null`. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFunding", "user": "..."}`. - For real-time push, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event) entries. - Use [`userNonFundingLedgerUpdates`](/api-reference/hyperliquid-info/user-non-funding-ledger-updates) for deposits, withdrawals, transfers, vault flows, liquidations, and other balance-moving events. --- ## 35. userNonFundingLedgerUpdates **Path:** api-reference/hyperliquid-info/user-non-funding-ledger-updates **Metadata:** ```yaml title: userNonFundingLedgerUpdates description: Returns a user's ledger events except funding payments - deposits, withdrawals, transfers, vault flows, liquidations, and other balance-changing events. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's USDC and account ledger history within a `[startTime, endTime)` window, **excluding** funding payments. Funding events are intentionally separated into their own type, [`userFunding`](/api-reference/hyperliquid-info/user-funding), so applications can render fee accruals separately from balance-moving events. User-keyed. Each entry carries a `delta` whose `type` discriminates the event variant - deposits, withdrawals, internal transfers, sub-account transfers, vault flows, liquidations, rewards claims, and similar. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userNonFundingLedgerUpdates"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | No | Unix timestamp in milliseconds. Inclusive lower bound for the window. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userNonFundingLedgerUpdates", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000 }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userNonFundingLedgerUpdates", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, }), }); const events = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userNonFundingLedgerUpdates", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, }, ) events = response.json() ``` ## Response An array of ledger event objects. Each entry has `time`, `hash`, and a `delta` discriminated by `delta.type`. ```json [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "type": "vaultWithdraw", "vault": "0x1962905b0a2d0ce8907a92ed5f7a17fef3e1b53e", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "requestedUsd": "1000.50", "commission": "10.00", "closingCost": "5.25", "basis": "950.00", "netWithdrawnUsd": "985.25" } } ] ``` ### Field descriptions > **Note:** All numeric `delta` fields are returned as **decimal strings**. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `time` | `int` | Unix timestamp in milliseconds when the event was applied. | | `hash` | `string` | L1 transaction hash that produced the event. | | `delta` | `object` | Event-specific payload. The shape depends on `delta.type`. The example above shows a `vaultWithdraw`; common discriminators include `deposit`, `withdraw`, `accountClassTransfer`, `internalTransfer`, `subAccountTransfer`, `spotTransfer`, `vaultDeposit`, `vaultWithdraw`, `vaultDistribution`, `vaultLeaderCommission`, `liquidation`, `rewardsClaim`, and others. See the [Hyperliquid `nonFundingLedgerUpdates` reference](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint) for the full discriminator table. | | `delta.type` | `string` | Discriminator. Always present on every variant. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userNonFundingLedgerUpdates", "user": "..."}`. - Funding payments are **not** included here - use [`userFunding`](/api-reference/hyperliquid-info/user-funding). - For real-time push of the same events, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream); the `delta.type` discriminator on the polled response maps 1:1 to the streamed `LedgerDelta` interface in the Streaming API. --- ## 36. userTwapSliceFills **Path:** api-reference/hyperliquid-info/user-twap-slice-fills **Metadata:** ```yaml title: userTwapSliceFills description: Returns a user's most recent TWAP slice fills, each tagged with the parent TWAP order ID. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns a single user's most recent TWAP slice fills - each individual slice executed as part of a larger TWAP (Time-Weighted Average Price) order. Every entry is a `{fill, twapId}` pair, where `twapId` ties the slice back to its parent TWAP order. Multiple slices from the same TWAP share the same `twapId`. User-keyed. Use this when you want execution-quality data for TWAP orders specifically - slippage per slice, fills-per-TWAP, realized average price - rather than the unified fills feed from [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time). ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userTwapSliceFills"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userTwapSliceFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userTwapSliceFills", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const slices = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userTwapSliceFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) slices = response.json() ``` ## Response An array of TWAP slice fill objects, most recent first. ```json [ { "fill": { "closedPnl": "0.0", "coin": "AVAX", "crossed": true, "dir": "Open Long", "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "oid": 90542681, "px": "18.435", "side": "B", "startPosition": "26.86", "sz": "93.53", "time": 1681222254710, "fee": "0.01", "feeToken": "USDC", "tid": 118906512037719 }, "twapId": 3156 } ] ``` ### Field descriptions > **Note:** All numeric `fill` fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `fill` | `object` | The slice's fill payload - the same shape as one entry from [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time). | | `fill.coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | `fill.px` | `string` | Fill execution price for this slice. | | `fill.sz` | `string` | Slice fill size. | | `fill.side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `fill.time` | `int` | Unix timestamp in milliseconds when the slice executed. | | `fill.startPosition` | `string` | Signed position size on the same coin immediately before this slice. | | `fill.dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | `fill.closedPnl` | `string` | Realized PnL in USDC attributable to this slice (zero when the slice opens or extends a position). | | `fill.hash` | `string` | All-zero (`0x000…000`) for TWAP slice fills - the distinguishing marker versus regular fills, which carry an L1 transaction hash. | | `fill.oid` | `int` | Order ID for the slice. | | `fill.tid` | `int` | Unique trade ID for the slice. | | `fill.crossed` | `boolean` | `true` when the slice came from the taker side, `false` when it was the maker side. | | `fill.fee` | `string` | Trading fee paid for this slice, denominated in `feeToken`. | | `fill.feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | `twapId` | `int` | Identifier of the parent TWAP order. Multiple slice fills from the same TWAP share this value - group by `twapId` to reconstruct per-TWAP execution. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userTwapSliceFills", "user": "..."}`. - Each response contains at most **2,000 most recent** TWAP slice fills. Older slices beyond that window are not retrievable from this endpoint. - TWAP slice fills have a `hash` of all zeros - use that, or the presence of `twapId`, to distinguish them from regular fills. - Use [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) when you want all fills (regular + TWAP slices) for a wallet within a time window; each TWAP slice there carries the same `twapId` field. --- ## 37. userVaultEquities **Path:** api-reference/hyperliquid-info/user-vault-equities **Metadata:** ```yaml title: userVaultEquities description: Returns a user's locked vault equity per vault address, with the unlock timestamp for each entry. api: POST https://hypercore.goldrushdata.com/info ``` **Content:** Returns the wallet's per-vault equity: one entry per vault the user has deposited into, with the locked amount and the timestamp at which that equity becomes unlockable. User-keyed. The result is `[]` for wallets that haven't deposited into any vault. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `type` | `string` | Yes | Always `"userVaultEquities"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```bash cURL curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "userVaultEquities", "user": "0x2b804617c6f63c040377e95bb276811747006f4b" }' ``` ```typescript TypeScript const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "userVaultEquities", user: "0x2b804617c6f63c040377e95bb276811747006f4b", }), }); const equities = await response.json(); ``` ```python Python import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userVaultEquities", "user": "0x2b804617c6f63c040377e95bb276811747006f4b", }, ) equities = response.json() ``` ## Response An array of vault equity entries. ```json [ { "vaultAddress": "0x1962905b0a2d0ce8907a92ed5f7a17fef3e1b53e", "equity": "5000.50", "lockedUntilTimestamp": 1741132800000 } ] ``` ### Field descriptions > **Note:** `equity` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float - keep it as a string or use a fixed-precision decimal type. | Field | Type | Description | | --- | --- | --- | | `vaultAddress` | `string` | Vault contract address (0x-prefixed hex). | | `equity` | `string` | User's equity in this vault, in USD. | | `lockedUntilTimestamp` | `int` | Unix timestamp in milliseconds at which this equity becomes unlockable. | ## Notes - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userVaultEquities", "user": "..."}`. - For real-time push of vault deposit, withdrawal, and distribution events, subscribe to [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and `LedgerVaultDistribution` entries. --- ## 38. L2 Order Book **Path:** api-reference/hyperliquid-websocket/l2-order-book **Metadata:** ```yaml title: L2 Order Book sidebarTitle: L2 Order Book description: Subscribe to real-time L2 order book snapshots for any Hyperliquid perp or spot asset over WebSocket. ``` **Content:** Subscribe to a continuous stream of L2 order book snapshots for any Hyperliquid perp or spot asset. The payload is **wire-equal** to the public Hyperliquid `l2Book` WebSocket subscription - same channel name, same `levels` shape, same aggregation parameters. Point your client at `wss://hypercore.goldrushdata.com/ws?key=` and the rest of your code stays the same. ## Endpoint ``` wss://hypercore.goldrushdata.com/ws?key= ``` Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used. ## Subscribe Send this JSON message after the connection is established: | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `method` | `string` | Yes | Always `"subscribe"`. | | `subscription` | `object` | Yes | __RESPONSE_ROW__type string Always `"l2Book"`. __RESPONSE_ROW__coin string Asset symbol - e.g. `"BTC"`, `"ETH"`, `"@107"` for spot pairs. For HIP-3 markets, include the deployer prefix. Omit to receive snapshots for **all** assets in the order book. __RESPONSE_ROW__nSigFigs int Significant figures used for price aggregation. One of `2`, `3`, `4`, `5`, or `null` for full precision. Defaults to `null`. __RESPONSE_ROW__mantissa int When `nSigFigs` is 5, controls the mantissa rounding. One of `1`, `2`, or `5`. Not allowed for other `nSigFigs` values. | ### Example ```bash wscat wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY" > {"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}} ``` ```typescript TypeScript import WebSocket from "ws"; const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.channel === "l2Book") { const { coin, time, levels: [bids, asks] } = msg.data; console.log(coin, time, "top bid:", bids[0], "top ask:", asks[0]); } }); ``` ```python Python import asyncio, json, os import websockets async def main(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" async with websockets.connect(uri) as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}, })) async for raw in ws: msg = json.loads(raw) if msg.get("channel") == "l2Book": print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1]) asyncio.run(main()) ``` ## Unsubscribe Send the same `subscription` body with `method: "unsubscribe"`: ```json { "method": "unsubscribe", "subscription": { "type": "l2Book", "coin": "BTC" } } ``` ## Streamed message Each message has `channel: "l2Book"` and a `data` payload with the current book snapshot for the subscribed coin. ```json { "channel": "l2Book", "data": { "coin": "BTC", "time": 1762450000123, "block_height": 996629014, "levels": [ [ { "px": "68210.0", "sz": "1.2345", "n": 3 }, { "px": "68209.5", "sz": "4.5670", "n": 5 }, { "px": "68209.0", "sz": "2.1100", "n": 2 } ], [ { "px": "68215.0", "sz": "0.8900", "n": 2 }, { "px": "68215.5", "sz": "3.4500", "n": 4 }, { "px": "68216.0", "sz": "1.2300", "n": 1 } ] ] } } ``` | Field | Type | Description | | --- | --- | --- | | `channel` | `string` | Always `"l2Book"`. | | `data` | `object` | | | `data.coin` | `string` | Asset symbol the snapshot belongs to. | | `data.time` | `int` | HyperCore block timestamp in milliseconds. | | `data.block_height` | `int` | HyperCore block height the snapshot was taken at. | | `data.levels` | `array>` | Tuple `[bids, asks]`. Each side is an array of price levels in best-first order. __RESPONSE_ROW__px string Price for this level (decimal string). __RESPONSE_ROW__data.sz string Aggregate size resting at this level (decimal string, base units). __RESPONSE_ROW__data.n int Number of orders aggregated into this level. | ## Notes - Wire-compatible with `wss://api.hyperliquid.xyz/ws` `l2Book` subscriptions - same channel name, same `levels` shape. - **`coin` is optional on GoldRush.** Omit it to stream the **entire L2 order book across every asset** on a single subscription. The public Hyperliquid API requires `coin` and locks each subscription to one asset at a time. - No 1000-subscription-per-IP cap - multiplex hundreds of `l2Book` subscriptions on a single connection. - For OHLCV candles instead of raw book state, use the [Streaming API OHLCV streams](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream). --- ## 39. L4 Order Book Diff **Path:** api-reference/hyperliquid-websocket/l4-order-book-diff **Metadata:** ```yaml title: L4 Order Book Diff sidebarTitle: 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. ``` **Content:** Subscribe to a GoldRush-native order-level view of the Hyperliquid book. Unlike `l2Book`, which emits a full aggregated snapshot every tick, `l4Book` emits a single **`Snapshot`** of every resting order on subscribe and then per-block **`Updates`** carrying individual `order_statuses` and `book_diffs`. Each order in the stream includes its `user`, `oid`, `cloid`, `orderType`, `tif`, and trigger metadata - enough to reconstruct queue position, per-trader flow, and microstructure. This channel is **not available on `wss://api.hyperliquid.xyz/ws`** - it is exclusive to `wss://hypercore.goldrushdata.com/ws`. ## Endpoint ``` wss://hypercore.goldrushdata.com/ws?key= ``` Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used. ## Subscribe Send this JSON message after the connection is established: | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `method` | `string` | Yes | Always `"subscribe"`. | | `subscription` | `object` | Yes | __RESPONSE_ROW__type string Always `"l4Book"`. __RESPONSE_ROW__coin string Asset symbol - e.g. `"BTC"`, `"ETH"`, `"@107"` for spot pairs. For HIP-3 markets, include the deployer prefix. **Required** - unlike `l2Book`, `l4Book` does not support wildcard subscriptions; each subscription is locked to a single asset. | ### Example ```bash wscat wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY" > {"method":"subscribe","subscription":{"type":"l4Book","coin":"BTC"}} ``` ```typescript TypeScript import WebSocket from "ws"; const ws = new WebSocket( `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`, ); ws.on("open", () => { ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l4Book", coin: "BTC" }, })); }); ws.on("message", (raw) => { const msg = JSON.parse(raw.toString()); if (msg.channel !== "l4Book") return; if (msg.data.Snapshot) { const { coin, time, block_height, levels: [bids, asks] } = msg.data.Snapshot; console.log("snapshot", coin, time, block_height, "bids:", bids.length, "asks:", asks.length); } else if (msg.data.Updates) { const { time, block_height, order_statuses, book_diffs } = msg.data.Updates; console.log("updates", time, block_height, "statuses:", order_statuses.length, "diffs:", book_diffs.length); } }); ``` ```python Python import asyncio, json, os import websockets async def main(): uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}" async with websockets.connect(uri) as ws: await ws.send(json.dumps({ "method": "subscribe", "subscription": {"type": "l4Book", "coin": "BTC"}, })) async for raw in ws: msg = json.loads(raw) if msg.get("channel") != "l4Book": continue data = msg["data"] if "Snapshot" in data: snap = data["Snapshot"] bids, asks = snap["levels"] print("snapshot", snap["coin"], snap["time"], snap["block_height"], "bids:", len(bids), "asks:", len(asks)) elif "Updates" in data: upd = data["Updates"] print("updates", upd["time"], upd["block_height"], "statuses:", len(upd["order_statuses"]), "diffs:", len(upd["book_diffs"])) asyncio.run(main()) ``` ## Unsubscribe Send the same `subscription` body with `method: "unsubscribe"`: ```json { "method": "unsubscribe", "subscription": { "type": "l4Book", "coin": "BTC" } } ``` ## Streamed messages Every message has `channel: "l4Book"`. The `data` payload contains **exactly one** of two variants: a `Snapshot` (emitted once, immediately after subscribe) or an `Updates` (emitted on each subsequent HyperCore block where the book for `coin` changed). ### Initial snapshot The first message after subscribe carries the full resting book at the current block. Each entry in `levels[0]` (bids) and `levels[1]` (asks) is an **individual order** - not an aggregated price level. ```json { "channel": "l4Book", "data": { "Snapshot": { "coin": "BTC", "time": 1778865761968, "block_height": 997719816, "levels": [ [ { "user": "0xa62b923a112d50d03e1e096bbd53422490dac104", "coin": "BTC", "side": "B", "limitPx": "79242", "sz": "0.74831", "oid": 427632406005, "timestamp": 1778865761305, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "tif": "Alo", "cloid": "0x00000000000000000000019e2c8b7d66" } ], [ { "user": "0xfcf104006bfff47695c1dc21dad3e9de1e72098e", "coin": "BTC", "side": "A", "limitPx": "79250", "sz": "0.2961", "oid": 427632406032, "timestamp": 1778865761305, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "tif": "Gtc", "cloid": null } ] ] } } } ``` ### Incremental updates Subsequent messages carry only what changed since the previous block. `order_statuses` describes order lifecycle events (`open`, etc.); `book_diffs` carries the corresponding price-level changes. ```json { "channel": "l4Book", "data": { "Updates": { "time": 1778865761768, "block_height": 997719813, "order_statuses": [ { "time": "2026-05-15T17:22:41.768005701", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "status": "open", "order": { "user": null, "coin": "BTC", "side": "B", "limitPx": "79242.0", "sz": "0.00867", "oid": 427632416336, "timestamp": 1778865761768, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "tif": "Alo", "cloid": null } } ], "book_diffs": [ { "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "oid": 427632416336, "px": "79242.0", "coin": "BTC", "raw_book_diff": { "new": { "sz": "0.00867" } } } ] } } } ``` ### Response fields | Field | Type | Description | | --- | --- | --- | | `channel` | `string` | Always `"l4Book"`. | | `data` | `object` | Contains exactly one of `Snapshot` or `Updates`. | | `data.coin` | `string` | Asset symbol the snapshot belongs to. | | `data.time` | `int` | HyperCore block timestamp in milliseconds. | | `data.block_height` | `int` | HyperCore block height the snapshot was taken at. | | `data.levels` | `array>` | Tuple `[bids, asks]`. Each side is an array of individual **Order** objects (see below), in queue order at their respective price. | | `data.time` | `int` | HyperCore block timestamp in milliseconds. | | `data.block_height` | `int` | HyperCore block height. | | `data.order_statuses` | `array` | Order lifecycle events at this block. __RESPONSE_ROW__time string ISO-8601 timestamp with nanosecond precision. __RESPONSE_ROW__data.user string Wallet address that owns the order. __RESPONSE_ROW__data.status string Lifecycle status (e.g. `"open"`). __RESPONSE_ROW__data.order Order The order, in the same shape as a snapshot entry. `user` inside this nested object is `null` because it duplicates the parent `user`. __RESPONSE_ROW__book_diffs array Per-order book changes at this block. __RESPONSE_ROW__book_diffs.user string Wallet address that owns the order. __RESPONSE_ROW__book_diffs.oid int Order id the diff applies to. __RESPONSE_ROW__book_diffs.px string Price level the diff applies to (decimal string). __RESPONSE_ROW__book_diffs.coin string Asset symbol. __RESPONSE_ROW__book_diffs.raw_book_diff object The change descriptor. Observed shape: `{ "new": { "sz": "" } }` for a newly resting order. Other shapes may carry size deltas or cancellations - inspect the keys to discriminate. | ### Order object The **Order** type appears inside `Snapshot.levels[*][*]` and `Updates.order_statuses[*].order`. | Field | Type | Description | | --- | --- | --- | | `user` | `string | null` | Wallet address that owns the order. `null` when the order is nested inside an `order_status` (the parent already carries it). | | `coin` | `string` | Asset symbol. | | `side` | `string` | `"B"` for bid, `"A"` for ask. | | `limitPx` | `string` | Limit price (decimal string). | | `sz` | `string` | Resting size (decimal string, base units). | | `oid` | `int` | Hyperliquid order id - stable for the lifetime of the order. | | `timestamp` | `int` | Order-placement timestamp in HyperCore milliseconds. | | `triggerCondition` | `string` | Trigger condition string (e.g. `"N/A"` for plain limit orders). | | `isTrigger` | `boolean` | True if this is a stop / take-profit trigger order. | | `triggerPx` | `string` | Trigger price (decimal string, `"0.0"` for non-trigger orders). | | `isPositionTpsl` | `boolean` | True if this is a position-level TP/SL. | | `reduceOnly` | `boolean` | True if the order is flagged reduce-only. | | `orderType` | `string` | Hyperliquid order type (e.g. `"Limit"`). | | `tif` | `string` | Time-in-force (e.g. `"Alo"`, `"Gtc"`, `"Ioc"`). | | `cloid` | `string | null` | Client-supplied order id (hex string), or `null` if none was provided. | ## Notes - **GoldRush-native.** `l4Book` is not exposed on `wss://api.hyperliquid.xyz/ws`. Pointing a client at the public endpoint with this subscription type will fail. - **`coin` is required.** Unlike `l2Book`, you cannot omit `coin` to stream every asset. Open one subscription per asset. - **Snapshot, then diffs.** The first message is always a `Snapshot`; every message thereafter is an `Updates`. Clients must seed local book state from the snapshot and apply diffs from there. On reconnect, drop local state and re-seed from the next snapshot. - **Per-order detail.** Each entry exposes `user`, `oid`, `cloid`, `tif`, and trigger metadata - enabling queue-position reconstruction, per-trader flow attribution, and microstructure analytics that are not possible with `l2Book`. - See the [L4 Order Book recipe](/goldrush-hyperliquid/websocket-api/l4-order-book-diff) for patterns to maintain book state, attribute flow by `user`, or reconstruct aggregated price levels. For aggregated `{px, sz, n}` snapshots without per-order detail, use [`l2Book`](/api-reference/hyperliquid-websocket/l2-order-book). --- # x402 API Documentation GoldRush x402 is a payment-gated proxy that provides access to the full GoldRush blockchain data API using the x402 protocol. AI agents pay per request with stablecoins on Base -no API keys, accounts, or subscriptions required. Only a wallet is needed. ## Overview | Item | Value | |------|-------| | **Base URL** | `https://x402.goldrush.dev/v1` | | **Protocol** | x402 (HTTP 402 Payment Required) | | **Authentication** | None -payment replaces API keys | | **Payment Network** | Base Sepolia testnet (Base mainnet coming soon) | | **Payment Method** | Stablecoins on Base | | **Rate Limit** | 100 requests/minute per wallet | | **Available Endpoints** | 60+ Foundational API endpoints | | **Client Libraries** | `@x402/core`, `@x402/evm` | | **x402 Protocol Spec** | https://x402.org | ## How It Works 1. **Request:** Agent calls a GoldRush endpoint on `x402.goldrush.dev` without payment 2. **402 Response:** Server responds with HTTP 402 (Payment Required) including payment instructions (amount, token, recipient) 3. **Payment:** Agent pays with stablecoins on Base and retries the request with proof of payment 4. **Validation:** The proxy validates the request *before* charging -malformed addresses or unsupported chains are rejected without payment 5. **Data:** Server returns the requested blockchain data The entire payment flow occurs in a single request-response cycle when using the x402 client libraries. ## Pricing Model ### Fixed-Price Endpoints One price, one call, one response. Used for endpoints like token balances and NFT holdings. ### Tiered Pricing (Variable-Length Data) For endpoints returning variable amounts of data (e.g., transaction history), pricing uses tiers: | Tier | Items Returned | Use Case | |------|---------------|----------| | Small | 1-50 | Quick lookups, recent activity | | Medium | 51-200 | Standard queries | | Large | 201-500 | Detailed analysis | | XL | 501+ | Full history, comprehensive data | Select tier via query parameter: `?tier=small` ### Response Caching Cached responses cost less than fresh requests. Cache TTLs: - **Balances:** 30 seconds - **Pricing data:** 5 minutes ## Discovery Endpoints (Free) These endpoints require no payment and are used to explore available x402 endpoints. ### List All Available Endpoints **Endpoint:** `GET /v1/x402/endpoints` **Cost:** Free ```bash curl https://x402.goldrush.dev/v1/x402/endpoints | jq ``` Returns a list of all 60+ available endpoints with their pricing and descriptions. ### Search Endpoints by Keyword **Endpoint:** `GET /v1/x402/search?q={query}` **Cost:** Free ```bash curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq ``` Returns endpoints matching the search query. ### Get Endpoint Details **Endpoint:** `GET /v1/x402/endpoints/{endpoint-name}` **Cost:** Free ```bash curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq ``` Returns full details for a specific endpoint including pricing, parameters, and response schema. ## Data Endpoints (Paid via x402) All 60+ Foundational API endpoints are accessible through the x402 proxy. The endpoint paths mirror the Foundational API -prepend `https://x402.goldrush.dev` instead of `https://api.covalenthq.com`. ### Key Endpoints - **Token Balances:** `GET /v1/{chainName}/address/{walletAddress}/balances_v2/` (fixed-price) - **Transaction History:** `GET /v1/{chainName}/address/{walletAddress}/transactions_v3/?tier=small` (tiered) - **NFT Holdings:** `GET /v1/{chainName}/address/{walletAddress}/balances_nft/` (fixed-price) - **Token Prices:** `GET /v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/` (fixed-price) - **Block Details:** `GET /v1/{chainName}/block_v2/{blockHeight}/` (fixed-price) - **Token Approvals:** `GET /v1/{chainName}/approvals/{walletAddress}/` (fixed-price) For the complete list, use the free discovery endpoint: `GET /v1/x402/endpoints` ## Code Example ```typescript import { HTTPClient } from "@x402/core"; import { ExactEvmScheme } from "@x402/evm"; const client = new HTTPClient({ scheme: new ExactEvmScheme({ network: "eip155:84532", // Base Sepolia privateKey: process.env.AGENT_WALLET_KEY, }), }); const BASE = "https://x402.goldrush.dev/v1"; // Step 1: Discover available endpoints (free) const { endpoints } = await client.get(`${BASE}/x402/endpoints`); // Step 2: Check token balances across chains const chains = ["eth-mainnet", "base-mainnet", "arbitrum-mainnet"]; const balances = await Promise.all( chains.map((chain) => client.get(`${BASE}/${chain}/address/${walletAddress}/balances_v2/`) ) ); // Step 3: Pull transaction history with tier const txns = await client.get( `${BASE}/eth-mainnet/address/${walletAddress}/transactions_v3/?tier=small` ); ``` ## x402 vs Traditional API Access | Feature | Traditional (API Key) | x402 (Pay-Per-Request) | |---------|----------------------|----------------------| | **Authentication** | API key (Bearer token) | Wallet-based payment | | **Setup** | Account signup required | No account needed | | **Billing** | Monthly subscription | Per-request payment | | **Best for** | Applications, backends | AI agents, autonomous systems | | **Rate Limit** | Tier-dependent (4-50 req/s) | 100 requests/minute per wallet | | **Payment** | Credit card | Stablecoins on Base | --- # Chain Documentation ## Support Levels ### Foundational Chains 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 Chains 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 Chains 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 Chains Previously supported blockchain networks that are now in archived status with limited data availability. No live data is available for these chains. --- ## 1. ADI Chain **Path:** chains/adi-chain **Metadata:** ```yaml title: ADI Chain sidebarTitle: ADI Chain description: Get token balances and transactions for ADI Chain. 22 endpoints supported. Testnet supported. chain_name: adi-mainnet chain_id: 36900 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** ADI Chain is a compliance-native L2 backed by UAE institutions, enabling governments and regulated institutions to launch stablecoins, health systems, land registries and payment rails without sacrificing speed, efficiency, security or regulatory compliance. GoldRush offers the most comprehensive ADI Chain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our ADI Chain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `adi-mainnet` | | **Chain ID** | `36900` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [ADI Block Explorer](https://explorer.adifoundation.ai/) | | **Official Website** | [ADI Chain Website](https://www.adi.foundation/) | | **Native Gas Token** | ADI | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `adi-testnet` | | **Chain ID** | `99999` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [ADI Testnet Block Explorer](https://explorer.testnet.adifoundation.ai/) | | **Official Website** | [ADI Testnet Website](https://www.adi.foundation/) | | **Native Gas Token** | ADI | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `adi-mainnet` (mainnet) - `adi-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/adi-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (ADI Testnet) curl -X GET "https://api.covalenthq.com/v1/adi-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "adi-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (ADI Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "adi-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#adi-chain-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#adi-chain-evm) - [Logs](/goldrush-pipeline-api/supported-chains#adi-chain-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#adi-chain-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 2. ApeChain **Path:** chains/apechain **Metadata:** ```yaml title: ApeChain sidebarTitle: ApeChain description: Get token balances and transactions for ApeChain. 23 endpoints supported. chain_name: apechain-mainnet chain_id: 33139 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Discover ApeChain, an Arbitrum Orbit L3 by ApeCoin, Horizen Labs & Caldera. Explore chain details, API access, and robust support to kickstart your project now. GoldRush offers the most comprehensive ApeChain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our ApeChain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `apechain-mainnet` | | **Chain ID** | `33139` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [ApeChain Explorer](https://apechain.calderaexplorer.xyz/) | | **Official Website** | [ApeChain Website](https://apechain.com/) | | **Native Gas Token** | APE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `apechain-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/apechain-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "apechain-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 3. Arbitrum Nova **Path:** chains/arbitrum-nova **Metadata:** ```yaml title: Arbitrum Nova sidebarTitle: Arbitrum Nova description: Get token balances and transactions for Arbitrum Nova. 22 endpoints supported. chain_name: arbitrum-nova-mainnet chain_id: 42170 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Arbitrum Nova is a blockchain that features ultra-low transaction costs with high security. GoldRush offers the most comprehensive Arbitrum Nova Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Arbitrum Nova Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `arbitrum-nova-mainnet` | | **Chain ID** | `42170` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Nova Arbiscan](https://nova.arbiscan.io/) | | **Official Website** | [Arbitrum Nova Website](https://nova.arbitrum.io/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `arbitrum-nova-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/arbitrum-nova-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "arbitrum-nova-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) - [AppChain Documentation](https://goldrush.dev/docs/appchains/) --- ## 4. Arbitrum **Path:** chains/arbitrum **Metadata:** ```yaml title: Arbitrum sidebarTitle: Arbitrum description: Get token balances and transactions for Arbitrum. 23 endpoints supported. Testnet supported. chain_name: arbitrum-mainnet chain_id: 42161 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Arbitrum is Ethereum's leading L2 rollup, combining full EVM equivalence with dramatically lower fees. Trusted by major DeFi protocols for secure, scalable smart contract execution. > **Note:** Note about how we calculate transaction fees on Arbitrum: Generally, the `fees_paid` in our transaction response is simply the product of `gas_price` and `gas_spent` . However for Arbitrum, the `fees_paid` in our transaction response is the sum of multiple L1 and L2 fees associated with the function call, transaction execution and storage. To calculate the same `fees_paid` provided in our transaction response from [Arbiscan](https://arbiscan.io/tx/0x24ba19119fa5c10ef1e92cc3f02519c5bc675fc4f3dfb4c9c2ca7744070b9e3c) , take the product of their Gas Price Bid and Gas Usage. GoldRush offers the most comprehensive Arbitrum Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Arbitrum Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `arbitrum-mainnet` | | **Chain ID** | `42161` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Arbiscan](https://arbiscan.io/) | | **Official Website** | [Arbitrum Website](https://arbitrum.io/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `arbitrum-sepolia` | | **Chain ID** | `421614` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Sepolia Arbiscan](https://sepolia.arbiscan.io/) | | **Official Website** | [Arbitrum Sepolia Testnet Website](https://docs.arbitrum.io/for-devs/concepts/public-chains#arbitrum-sepolia) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `arbitrum-mainnet` (mainnet) - `arbitrum-sepolia` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/arbitrum-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Arbitrum Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/arbitrum-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "arbitrum-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Arbitrum Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "arbitrum-sepolia", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#arbitrum-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#arbitrum-evm) - [Logs](/goldrush-pipeline-api/supported-chains#arbitrum-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#arbitrum-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 5. Arc Testnet **Path:** chains/arc **Metadata:** ```yaml title: Arc Testnet sidebarTitle: Arc Testnet description: Get token balances and transactions for Arc Testnet. 22 endpoints supported. Testnet supported. chain_name: arc-testnet chain_id: 5042002 support_level: frontier network_type: testnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Arc is an open L1 blockchain purpose-built to unite programmable money and onchain innovation with real-world economic activity. GoldRush offers the most comprehensive Arc Testnet Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Arc Testnet Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Network Details | Property | Value | |----------|-------| | **Chain Name** | `arc-testnet` | | **Chain ID** | `5042002` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Arc Testnet Explorer](https://testnet.arcscan.app/) | | **Official Website** | [Arc Testnet Website](https://www.arc.network/) | | **Native Gas Token** | USDC | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `arc-testnet` | | **Chain ID** | `5042002` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Arc Testnet Explorer](https://testnet.arcscan.app/) | | **Official Website** | [Arc Testnet Website](https://www.arc.network/) | | **Native Gas Token** | USDC | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `arc-testnet` (testnet) #### Example API Calls ```bash Chain Name curl -X GET "https://api.covalenthq.com/v1/arc-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "arc-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 6. Avalanche C-Chain **Path:** chains/avalanche-c-chain **Metadata:** ```yaml title: Avalanche C-Chain sidebarTitle: Avalanche C-Chain description: Get token balances and transactions for Avalanche C-Chain. 22 endpoints supported. Testnet supported. chain_name: avalanche-mainnet chain_id: 43114 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Avalanche is an open-source platform for launching decentralized applications and enterprise blockchain deployments in one interoperable, highly scalable ecosystem. Avalanche is the first smart contracts platform that processes 4,500+ transactions/second and instantly confirms transactions. Ethereum developers can quickly build on Avalanche as Solidity works out-of-the-box. A key difference between Avalanche and other decentralized networks is the consensus protocol. Over time, people have come to a false understanding that blockchains have to be slow and not scalable. The Avalanche protocol employs a novel approach to consensus to achieve its strong safety guarantees, quick finality, and high-throughput, without compromising decentralization. GoldRush offers the most comprehensive Avalanche C-Chain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Avalanche C-Chain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `avalanche-mainnet` | | **Chain ID** | `43114` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://avascan.info/blockchain/c/) | | **Official Website** | [Avalanche C-Chain Website](https://www.avax.network/) | | **Native Gas Token** | AVAX | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `avalanche-testnet` | | **Chain ID** | `43113` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://testnet.avascan.info/) | | **Native Gas Token** | AVAX | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `avalanche-mainnet` (mainnet) - `avalanche-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/avalanche-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Avalanche Fuji Testnet) curl -X GET "https://api.covalenthq.com/v1/avalanche-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "avalanche-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Avalanche Fuji Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "avalanche-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#avalanche-c-chain-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#avalanche-c-chain-evm) - [Logs](/goldrush-pipeline-api/supported-chains#avalanche-c-chain-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#avalanche-c-chain-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 7. Axie/Ronin **Path:** chains/axie-ronin **Metadata:** ```yaml title: Axie/Ronin sidebarTitle: Axie/Ronin description: Get token balances and transactions for Axie/Ronin. 22 endpoints supported. chain_name: axie-mainnet chain_id: 2020 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Discover Ronin, the Ethereum-linked side-chain for Axie Infinity. Earn tokens with skilled gameplay and community contributions. Get started today! GoldRush offers the most comprehensive Axie/Ronin Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Axie/Ronin Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `axie-mainnet` | | **Chain ID** | `2020` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://explorer.roninchain.com/) | | **Official Website** | [Axie/Ronin Website](https://www.skymavis.com/products) | | **Native Gas Token** | RON | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `axie-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/axie-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "axie-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#axie-ronin-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#axie-ronin-evm) - [Logs](/goldrush-pipeline-api/supported-chains#axie-ronin-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#axie-ronin-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 8. Base **Path:** chains/base **Metadata:** ```yaml title: Base sidebarTitle: Base description: Get token balances, transactions, and OHLCV pricing data for Base. 37 endpoints supported. Testnet supported. chain_name: base-mainnet chain_id: 8453 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** Base is Coinbase's secure, low-cost L2 built on the OP Stack. With native Coinbase integrations and a thriving developer ecosystem, Base is bringing the next billion users onchain. GoldRush offers the most comprehensive Base Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Base Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `base-mainnet` (Foundational API) / `BASE_MAINNET` (Streaming API) | | **Chain ID** | `8453` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [Base Explorer](https://basescan.org/) | | **Official Website** | [Base Website](https://base.org/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `base-sepolia-testnet` | | **Chain ID** | `84532` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [Base Sepolia Explorer](https://base-sepolia.blockscout.com/) | | **Official Website** | [Base Sepolia Testnet Website](https://docs.base.org/base-contracts/#base-testnet-goerli--sepolia) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `base-mainnet` / `BASE_MAINNET` (mainnet) - `base-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/base-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Base Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/base-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "base-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Base Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "base-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **9** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Pipeline API Support This chain supports **7** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#base-evm) - [Traces](/goldrush-pipeline-api/supported-chains#base-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#base-evm) - [Logs](/goldrush-pipeline-api/supported-chains#base-evm) - [Receipts](/goldrush-pipeline-api/supported-chains#base-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#base-evm) - [Swaps](/goldrush-pipeline-api/supported-chains#base-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 9. Berachain **Path:** chains/berachain **Metadata:** ```yaml title: Berachain sidebarTitle: Berachain description: Get token balances and transactions for Berachain. 22 endpoints supported. Testnet supported. chain_name: berachain-mainnet chain_id: 80094 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Berachain is a high-performance EVM-compatible blockchain built on Proof-of-Liquidity consensus. GoldRush offers the most comprehensive Berachain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Berachain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `berachain-mainnet` | | **Chain ID** | `80094` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Berachain Explorer](https://berascan.com/) | | **Official Website** | [Berachain Website](https://www.berachain.com/) | | **Native Gas Token** | BERA | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `berachain-testnet` | | **Chain ID** | `80084` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://bartio.beratrail.io/) | | **Official Website** | [Berachain Testnet Website](https://www.berachain.com/) | | **Native Gas Token** | BERA | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `berachain-mainnet` (mainnet) - `berachain-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/berachain-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Berachain Testnet) curl -X GET "https://api.covalenthq.com/v1/berachain-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "berachain-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Berachain Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "berachain-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 10. Bitcoin **Path:** chains/bitcoin **Metadata:** ```yaml title: Bitcoin sidebarTitle: Bitcoin description: Get token balances and transactions for Bitcoin. 3 endpoints supported. chain_name: btc-mainnet chain_id: 20090103 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Bitcoin is the original blockchain and the world's largest cryptocurrency by market cap. GoldRush provides enhanced Bitcoin support including UTXO tracking and historical balances for HD and non-HD addresses. GoldRush offers the most comprehensive Bitcoin Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Bitcoin Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `btc-mainnet` | | **Chain ID** | `20090103` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://blockstream.info/) | | **Official Website** | [Bitcoin Website](https://bitcoin.org/en/) | | **Native Gas Token** | BTC | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `btc-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/btc-mainnet/address/34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "btc-mainnet", walletAddress: "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo" }); ``` ## Foundational API Support This chain supports **3** GoldRush Foundational APIs: #### Wallet API - **[Get Bitcoin balance for non-HD address](/api-reference/foundational-api/balances/get-bitcoin-balance-for-address)** - **[Get Bitcoin balances for HD address](/api-reference/foundational-api/balances/get-bitcoin-balances-for-hd-address)** #### Activity Feed API - **[Get transactions for Bitcoin address](/api-reference/foundational-api/transactions/get-transactions-for-bitcoin-address)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 11. Blast **Path:** chains/blast **Metadata:** ```yaml title: Blast sidebarTitle: Blast description: Get token balances and transactions for Blast. 22 endpoints supported. chain_name: blast-mainnet chain_id: 81457 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Blast is an Ethereum L2 with native yield for ETH and Stablecoins. GoldRush offers the most comprehensive Blast Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Blast Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `blast-mainnet` | | **Chain ID** | `81457` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://blastexplorer.io/) | | **Official Website** | [Blast Website](https://blast.io/en) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `blast-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/blast-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "blast-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#blast-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#blast-evm) - [Logs](/goldrush-pipeline-api/supported-chains#blast-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#blast-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 12. BNB Smart Chain (BSC) **Path:** chains/bnb-smart-chain-bsc **Metadata:** ```yaml title: BNB Smart Chain (BSC) sidebarTitle: BNB Smart Chain (BSC) description: Get token balances, transactions, and OHLCV pricing data for BNB Smart Chain (BSC). 37 endpoints supported. Testnet supported. chain_name: bsc-mainnet chain_id: 56 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** BNB Smart Chain (BSC) combines fast block times with low transaction costs, making it one of the most active chains for DeFi and token launches. Full EVM compatibility for easy deployment. GoldRush offers the most comprehensive BNB Smart Chain (BSC) Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our BNB Smart Chain (BSC) Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `bsc-mainnet` (Foundational API) / `BSC_MAINNET` (Streaming API) | | **Chain ID** | `56` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [BscScan](https://bscscan.com/) | | **Official Website** | [BNB Smart Chain (BSC) Website](https://www.bnbchain.org/en) | | **Native Gas Token** | BNB | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `bsc-testnet` | | **Chain ID** | `97` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [Bsc Testnet Scan](https://testnet.bscscan.com/) | | **Native Gas Token** | gwei | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `bsc-mainnet` / `BSC_MAINNET` (mainnet) - `bsc-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/bsc-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (BNB Smart Chain (BSC) Testnet) curl -X GET "https://api.covalenthq.com/v1/bsc-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "bsc-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (BNB Smart Chain (BSC) Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "bsc-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **9** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#bnb-smart-chain-bsc-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#bnb-smart-chain-bsc-evm) - [Logs](/goldrush-pipeline-api/supported-chains#bnb-smart-chain-bsc-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#bnb-smart-chain-bsc-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 13. Canto **Path:** chains/canto **Metadata:** ```yaml title: Canto sidebarTitle: Canto description: Get token balances and transactions for Canto. 22 endpoints supported. chain_name: canto-mainnet chain_id: 7700 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Canto is a general-purpose blockchain running the Ethereum Virtual Machine (EVM). It is focused on DeFi, making new systems will be made accessible, transparent, decentralized, and free. GoldRush offers the most comprehensive Canto Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Canto Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `canto-mainnet` | | **Chain ID** | `7700` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://evm.explorer.canto.io/) | | **Official Website** | [Canto Website](https://canto.io/) | | **Native Gas Token** | Canto | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `canto-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/canto-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "canto-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 14. Celo **Path:** chains/celo **Metadata:** ```yaml title: Celo sidebarTitle: Celo description: Get token balances and transactions for Celo. 22 endpoints supported. chain_name: celo-mainnet chain_id: 42220 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Celo is an EVM-compatible Layer-1 protocol. The Celo platform offers a decentralized address-based identity layer that makes it easy to send payments. GoldRush offers the most comprehensive Celo Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Celo Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `celo-mainnet` | | **Chain ID** | `42220` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://explorer.celo.org/mainnet/) | | **Official Website** | [Celo Website](https://docs.celo.org/) | | **Native Gas Token** | CELO | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `celo-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/celo-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "celo-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#celo-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#celo-evm) - [Logs](/goldrush-pipeline-api/supported-chains#celo-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#celo-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 15. Covalent Onchain Data API **Path:** chains/covalent **Metadata:** ```yaml title: Covalent Onchain Data API sidebarTitle: Covalent description: Get token balances and transactions for Covalent. ``` **Content:** ## Overview > **Tip:** The Covalent Network serves as the universal data model for multi-chain indexing and querying. The Covalent Network represents the progressive decentralization of Covalent toward a community-owned and community-run protocol. Read more to understand the supply side, demand side, and roles of network operators in the network section of our docs. GoldRush offers the most comprehensive Covalent Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Covalent Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `covalent-internal-network-v1` | | **Chain ID** | `1131378225` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://cqtscan.com/#/) | | **Official Website** | [Covalent Website](https://covalenthq.com/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `covalent-internal-network-v1` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/covalent-internal-network-v1/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "covalent-internal-network-v1", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 16. Cronos zkEVM **Path:** chains/cronos-zkevm **Metadata:** ```yaml title: Cronos zkEVM sidebarTitle: Cronos zkEVM description: Get token balances and transactions for Cronos zkEVM. 22 endpoints supported. chain_name: cronos-zkevm-mainnet chain_id: 388 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Cronos zkEVM Mainnet is a zero-knowledge layer 2 network that was launched in a partnership between Cronos Labs and Matter Labs (the team behind zkSync) and Crypto.com. GoldRush offers the most comprehensive Cronos zkEVM Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Cronos zkEVM Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `cronos-zkevm-mainnet` | | **Chain ID** | `388` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://explorer.zkevm.cronos.org) | | **Official Website** | [Cronos zkEVM Website](https://docs.cronos.org/cronos-zkevm/cronos-zkevm) | | **Native Gas Token** | zkCRO | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `cronos-zkevm-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/cronos-zkevm-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "cronos-zkevm-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 17. Cronos **Path:** chains/cronos **Metadata:** ```yaml title: Cronos sidebarTitle: Cronos description: Get token balances and transactions for Cronos. chain_name: cronos-mainnet chain_id: 25 support_level: archived network_type: mainnet apis: {"foundational":false,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Cronos is the first Ethereum-compatible blockchain network built on Cosmos SDK technology. An open-source and permission-less Layer 1 chain which runs in parallel to the Crypto.org Chain, Cronos aims to massively scale the DeFi, GameFi, and overall Web3 user community by providing builders with the ability to instantly port apps and crypto assets from other chains while benefiting from low transaction fees, high throughput, and fast finality. > **Note:** Chain is archived. GoldRush offers the most comprehensive Cronos Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Cronos Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `cronos-mainnet` | | **Chain ID** | `25` | | **Network Type** | Archived Chain | | **Support Level** | archived | | **Block Explorer** | [Explorer](https://cronoscan.com/) | | **Official Website** | [Cronos Website](https://cronos.org/) | | **Native Gas Token** | CRO | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `cronos-mainnet` (mainnet) #### Example Streaming Subscription ```graphql GraphQL Subscription subscription { walletTxs( chain_name: CRONOS_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"] ) { block_signed_at block_height tx_hash tx_offset successful decoded_type } } ``` ```typescript TypeScript SDK import { GoldRushClient, StreamingChain } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); client.StreamingService.subscribeToWalletTxs( { chain_name: StreamingChain.CRONOS_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"], }, { next: (data) => console.log("Received data:", data), error: (error) => console.error("Error:", error), complete: () => console.log("Stream completed"), } ); ``` > **Note:** Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key in the connection parameters. See the [Streaming API Quickstart](/goldrush-streaming-api/quickstart) for full setup details. ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 18. Ethereum **Path:** chains/ethereum **Metadata:** ```yaml title: Ethereum sidebarTitle: Ethereum description: Get token balances, transactions, and OHLCV pricing data for Ethereum. 37 endpoints supported. Testnet supported. chain_name: eth-mainnet chain_id: 1 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** Ethereum is the foundational smart contract platform powering the majority of DeFi, NFTs, and Web3 innovation. The most secure and decentralized programmable blockchain. GoldRush offers the most comprehensive Ethereum Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Ethereum Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `eth-mainnet` (Foundational API) / `ETH_MAINNET` (Streaming API) | | **Chain ID** | `1` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [Etherscan](https://etherscan.io/) | | **Official Website** | [Ethereum Website](https://ethereum.org) | | **Native Gas Token** | ETH | ## Testnets ### Holesky Testnet | Property | Value | |----------|-------| | **Chain Name** | `eth-holesky` | | **Chain ID** | `17000` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Holesky Etherscan](https://holesky.etherscan.io/) | | **Official Website** | [Holesky Testnet Website](https://github.com/eth-clients/holesky) | | **Native Gas Token** | ETH | ### Ethereum Sepolia Testnet | Property | Value | |----------|-------| | **Chain Name** | `eth-sepolia` | | **Chain ID** | `11155111` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [Sepolia Etherscan](https://sepolia.etherscan.io/) | | **Official Website** | [Ethereum Sepolia Testnet Website](https://ethereum.org/en/developers/docs/networks/#ethereum-testnets) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `eth-mainnet` / `ETH_MAINNET` (mainnet) - `eth-holesky` (testnet) - `eth-sepolia` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/eth-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Holesky Testnet) curl -X GET "https://api.covalenthq.com/v1/eth-holesky/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` ```bash Chain Name (Ethereum Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/eth-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "eth-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Holesky Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "eth-holesky", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Ethereum Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "eth-sepolia", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **9** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#ethereum-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#ethereum-evm) - [Logs](/goldrush-pipeline-api/supported-chains#ethereum-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#ethereum-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 19. Fantom **Path:** chains/fantom **Metadata:** ```yaml title: Fantom sidebarTitle: Fantom description: Get token balances and transactions for Fantom. 22 endpoints supported. Testnet supported. chain_name: fantom-mainnet chain_id: 250 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Fantom is a fast, high-throughput open-source smart contract platform for digital assets and dApps. Founded in 2018, Fantom is designed to overcome the limitations of previous-generation blockchain platforms. Fantom is permissionless, decentralized, and open-source while achieving fast finality (1-2 second transaction confirmation) and low fees ($0.00001). Furthermore, Fantom is EVM-compatible. Fantom code is completely open source. Anyone can read it, check on the progress, comment on it, and contribute. Fantom integrates industry-leaders oracle providers Chainlink and Band Protocol for maximum flexibility to access price feeds. GoldRush offers the most comprehensive Fantom Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Fantom Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `fantom-mainnet` | | **Chain ID** | `250` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://ftmscan.com/) | | **Official Website** | [Fantom Website](https://fantom.foundation/) | | **Native Gas Token** | FTM | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `fantom-testnet` | | **Chain ID** | `4002` | | **Purpose** | Development and testing network | | **Support Level** | community | | **Block Explorer** | [Explorer](https://testnet.ftmscan.com/) | | **Native Gas Token** | gwei | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `fantom-mainnet` (mainnet) - `fantom-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/fantom-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Fantom Testnet) curl -X GET "https://api.covalenthq.com/v1/fantom-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "fantom-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Fantom Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "fantom-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#fantom-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#fantom-evm) - [Logs](/goldrush-pipeline-api/supported-chains#fantom-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#fantom-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 20. Gnosis **Path:** chains/gnosis **Metadata:** ```yaml title: Gnosis sidebarTitle: Gnosis description: Get token balances and transactions for Gnosis. 30 endpoints supported. Testnet supported. chain_name: gnosis-mainnet chain_id: 100 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Discover Gnosis Chain - a community-run Ethereum sidechain for decentralized prediction, governance, and efficient dApps. GoldRush offers the most comprehensive Gnosis Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Gnosis Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `gnosis-mainnet` | | **Chain ID** | `100` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [Gnosis Blockscout](https://gnosis.blockscout.com/) | | **Official Website** | [Gnosis Website](https://docs.gnosischain.com/) | | **Native Gas Token** | xDAI | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `gnosis-testnet` | | **Chain ID** | `10200` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [Gnosis Chiado Blockscout](https://gnosis-chiado.blockscout.com/) | | **Official Website** | [Chiado Testnet Website](https://docs.gnosischain.com/about/networks/chiado) | | **Native Gas Token** | xDAI | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `gnosis-mainnet` (mainnet) - `gnosis-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/gnosis-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Chiado Testnet) curl -X GET "https://api.covalenthq.com/v1/gnosis-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "gnosis-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Chiado Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "gnosis-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **2** GoldRush Streaming APIs: - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 21. Harmony **Path:** chains/harmony **Metadata:** ```yaml title: Harmony sidebarTitle: Harmony description: Get token balances and transactions for Harmony. Testnet supported. chain_name: harmony-mainnet chain_id: 1666600000 support_level: archived network_type: mainnet apis: {"foundational":false,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Explore Harmony, the open blockchain with 2-second finality, low fees, and secure cross-chain bridges for Ethereum apps. Dive into historical data now! GoldRush offers the most comprehensive Harmony Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Harmony Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `harmony-mainnet` | | **Chain ID** | `1666600000` | | **Network Type** | Archived Chain | | **Support Level** | archived | | **Block Explorer** | [Explorer](https://explorer.harmony.one/) | | **Official Website** | [Harmony Website](https://www.harmony.one/) | | **Native Gas Token** | ONE | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `harmony-testnet` | | **Chain ID** | `1666700000` | | **Purpose** | Development and testing network | | **Support Level** | archived | | **Block Explorer** | [Explorer](https://explorer.testnet.harmony.one/) | | **Official Website** | [Harmony Testnet Website](https://www.harmony.one/) | | **Native Gas Token** | ONE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `harmony-mainnet` (mainnet) - `harmony-testnet` (testnet) #### Example Streaming Subscription ```graphql GraphQL Subscription subscription { walletTxs( chain_name: HARMONY_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"] ) { block_signed_at block_height tx_hash tx_offset successful decoded_type } } ``` ```typescript TypeScript SDK import { GoldRushClient, StreamingChain } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); client.StreamingService.subscribeToWalletTxs( { chain_name: StreamingChain.HARMONY_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"], }, { next: (data) => console.log("Received data:", data), error: (error) => console.error("Error:", error), complete: () => console.log("Stream completed"), } ); ``` > **Note:** Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key in the connection parameters. See the [Streaming API Quickstart](/goldrush-streaming-api/quickstart) for full setup details. ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 22. HyperCore **Path:** chains/hypercore **Metadata:** ```yaml title: HyperCore sidebarTitle: HyperCore description: Get token balances, transactions, and OHLCV pricing data for HyperCore. chain_name: hypercore-mainnet chain_id: na support_level: frontier network_type: mainnet apis: {"foundational":false,"streaming":true} capabilities: {} ``` **Content:** import { Overview, StreamingApiSupport, StreamingApiDecodedEvents, AdditionalResources } from "/snippets/chain-extras/hypercore.mdx"; import { OhlcvChartSnippet } from "/snippets/ohlcv-chart.mdx"; ## Overview > **Tip:** HyperCore powers fully onchain perpetual futures and spot order books with 200,000 orders/second throughput. The backbone of Hyperliquid's high-performance trading infrastructure. GoldRush offers the most comprehensive HyperCore Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our HyperCore Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `HYPERCORE_MAINNET` | | **Chain ID** | `na` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Hyperliquid Explorer](https://app.hyperliquid.xyz/explorer) | | **Official Website** | [HyperCore Website](https://hyperfoundation.org/) | | **Native Gas Token** | HYPE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `HYPERCORE_MAINNET` (mainnet) #### Example Streaming Subscription ```graphql GraphQL Subscription subscription { walletTxs( wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"] chain_name: HYPERCORE_MAINNET ) { decoded_details { ... on ErrorDetails { message } ... on HypercoreDelegationEvent { type hash time is_undelegate amount validator } ... on HypercoreDepositEvent { type hash time amount } ... on HypercoreFillTransaction { type liquidation { market_price method liquidated_user } twap_id builder_fee side cloid closed_pnl fee fee_token oid dir start_position tid size price builder time crossed hash coin } ... on HypercoreFundingEvent { type hash time szi funding_amount coin funding_rate } ... on HypercoreLedgerEvent { type delta { ... on LedgerSubAccountTransfer { destination usdc user } ... on LedgerWithdraw { fee usdc nonce } ... on LedgerLiquidation { liquidated_ntl_pos account_value liquidated_positions { szi coin } leverage_type } ... on LedgerSpotTransfer { amount usdc_value native_token_fee fee destination fee_token nonce user token } ... on LedgerVaultLeaderCommission { usdc vault } ... on LedgerSend { amount usdc_value destination_dex native_token_fee fee destination fee_token nonce user source_dex token } ... on LedgerVaultDeposit { usdc user vault } ... on LedgerInternalTransfer { fee destination usdc user } ... on LedgerAccountClassTransfer { amount token } ... on LedgerAccountActivationGas { amount token } ... on LedgerVaultCreate { fee usdc vault } ... on LedgerBorrowLend { amount interest_amount operation token } ... on LedgerRewardsClaim { amount } ... on LedgerDeposit { usdc } ... on LedgerPerpDexClassTransfer { amount dex to_perp token } ... on LedgerCStakingTransfer { amount is_deposit token } ... on LedgerSpotGenesis { amount token } ... on LedgerDeployGasAuction { amount token } ... on LedgerVaultDistribution { usdc vault } ... on LedgerVaultWithdraw { requested_usd commission basis closing_cost user vault } } hash ledger_type time } ... on HypercoreWithdrawalEvent { type hash time amount } } gas_used block_hash to_address tx_hash block_height decoded_type miner_address tx_offset block_signed_at from_address logs { data emitter_address log_offset topics } value chain_name successful } } ``` ```typescript TypeScript SDK import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("YOUR_API_KEY"); const SUBSCRIPTION_QUERY = ` subscription { walletTxs( wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"] chain_name: HYPERCORE_MAINNET ) { decoded_details { ... on ErrorDetails { message } ... on HypercoreDelegationEvent { hash time is_undelegate amount validator } ... on HypercoreDepositEvent { hash time amount } ... on HypercoreFillTransaction { liquidation { market_price method liquidated_user } twap_id builder_fee side cloid closed_pnl fee fee_token oid dir start_position tid size price builder time crossed hash coin } ... on HypercoreFundingEvent { hash time szi funding_amount coin funding_rate } ... on HypercoreLedgerEvent { delta { ... on LedgerSubAccountTransfer { destination usdc user } ... on LedgerWithdraw { fee usdc nonce } ... on LedgerLiquidation { liquidated_ntl_pos account_value liquidated_positions { szi coin } leverage_type } ... on LedgerSpotTransfer { amount usdc_value native_token_fee fee destination fee_token nonce user token } ... on LedgerVaultLeaderCommission { usdc vault } ... on LedgerSend { amount usdc_value destination_dex native_token_fee fee destination fee_token nonce user source_dex token } ... on LedgerVaultDeposit { usdc user vault } ... on LedgerInternalTransfer { fee destination usdc user } ... on LedgerAccountClassTransfer { amount token } ... on LedgerAccountActivationGas { amount token } ... on LedgerVaultCreate { fee usdc vault } ... on LedgerBorrowLend { amount interest_amount operation token } ... on LedgerRewardsClaim { amount } ... on LedgerDeposit { usdc } ... on LedgerPerpDexClassTransfer { amount dex to_perp token } ... on LedgerCStakingTransfer { amount is_deposit token } ... on LedgerSpotGenesis { amount token } ... on LedgerDeployGasAuction { amount token } ... on LedgerVaultDistribution { usdc vault } ... on LedgerVaultWithdraw { requested_usd commission basis closing_cost user vault } } hash ledger_type time } ... on HypercoreWithdrawalEvent { hash time amount } } gas_used block_hash to_address tx_hash block_height decoded_type miner_address tx_offset block_signed_at from_address logs { data emitter_address log_offset topics } value chain_name successful } } `; const unsubscribe = client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (error) => console.error("Error:", error), complete: () => console.log("Stream completed"), } ); ``` > **Note:** Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key in the connection parameters. See the [Streaming API Quickstart](/goldrush-streaming-api/quickstart) for full setup details. ## Streaming API Support This chain supports **3** GoldRush Streaming APIs: - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) ## Decoded Event Types ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Fills](/goldrush-pipeline-api/supported-chains#hypercore) - [Trades](/goldrush-pipeline-api/supported-chains#hypercore) - [Orders](/goldrush-pipeline-api/supported-chains#hypercore) - [Misc Events](/goldrush-pipeline-api/supported-chains#hypercore) ## Additional Resources --- ## 23. HyperEVM **Path:** chains/hyperevm **Metadata:** ```yaml title: HyperEVM sidebarTitle: HyperEVM description: Get token balances, transactions, and OHLCV pricing data for HyperEVM. 28 endpoints supported. chain_name: hyperevm-mainnet chain_id: 999 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** HyperEVM brings Solidity smart contracts to the Hyperliquid ecosystem. Deploy familiar EVM dApps on a blockchain built for institutional-grade trading performance. GoldRush offers the most comprehensive HyperEVM Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our HyperEVM Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `hyperevm-mainnet` (Foundational API) / `HYPEREVM_MAINNET` (Streaming API) | | **Chain ID** | `999` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [HyperEVM Explorer](https://hyperevmscan.io/) | | **Official Website** | [HyperEVM Website](https://hyperfoundation.org/) | | **Native Gas Token** | HYPE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `hyperevm-mainnet` / `HYPEREVM_MAINNET` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/hyperevm-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "hyperevm-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **6** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#hyperevm-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#hyperevm-evm) - [Logs](/goldrush-pipeline-api/supported-chains#hyperevm-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#hyperevm-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 24. Ink **Path:** chains/ink **Metadata:** ```yaml title: Ink sidebarTitle: Ink description: Get token balances and transactions for Ink. 22 endpoints supported. Testnet supported. chain_name: ink-mainnet chain_id: 57073 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Ink is a cutting-edge L2 blockchain built on Optimism’s Superchain and released by Kraken. GoldRush offers the most comprehensive Ink Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Ink Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `ink-mainnet` | | **Chain ID** | `57073` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Ink Explorer](https://explorer-sepolia.inkonchain.com/) | | **Official Website** | [Ink Website](https://inkonchain.com/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `ink-sepolia-testnet` | | **Chain ID** | `763373` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Ink Sepolia Explorer](https://explorer-sepolia.inkonchain.com/) | | **Official Website** | [Ink Testnet Website](https://inkonchain.com/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `ink-mainnet` (mainnet) - `ink-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/ink-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Ink Testnet) curl -X GET "https://api.covalenthq.com/v1/ink-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "ink-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Ink Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "ink-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#ink-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#ink-evm) - [Logs](/goldrush-pipeline-api/supported-chains#ink-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#ink-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 25. Linea **Path:** chains/linea **Metadata:** ```yaml title: Linea sidebarTitle: Linea description: Get token balances and transactions for Linea. 23 endpoints supported. Testnet supported. chain_name: linea-mainnet chain_id: 59144 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Linea is a type 2 zero knowledge Ethereum Virtual Machine that replicates an Ethereum environment by using rollups. GoldRush offers the most comprehensive Linea Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Linea Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `linea-mainnet` | | **Chain ID** | `59144` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://lineascan.build/) | | **Official Website** | [Linea Website](https://linea.build/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `linea-sepolia-testnet` | | **Chain ID** | `59141` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://sepolia.lineascan.build/) | | **Official Website** | [Linea Sepolia Testnet Website](https://linea.build/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `linea-mainnet` (mainnet) - `linea-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/linea-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Linea Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/linea-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "linea-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Linea Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "linea-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 26. Lisk Onchain Data API **Path:** chains/lisk **Metadata:** ```yaml title: Lisk Onchain Data API sidebarTitle: Lisk description: Get token balances and transactions for Lisk. Testnet supported. ``` **Content:** ## Overview GoldRush offers the most comprehensive Lisk Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Lisk Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ## Mainnet | Property | Value | | --- | --- | | Chain Name | lisk-mainnet | | Chain ID | 1135 | | Network Type | Archived Chain | | Support Level | archived | | Block Explorer | Explorer | | Official Website | Lisk Website | | Native Gas Token | ETH | ## Testnet | Property | Value | | --- | --- | | Chain Name | lisk-sepolia-testnet | | Chain ID | 4202 | | Purpose | Development and testing network | | Support Level | archived | | Block Explorer | Explorer | | Official Website | Lisk Sepolia Testnet Website | | Native Gas Token | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `lisk-mainnet` (mainnet) - `lisk-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/lisk-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Lisk Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/lisk-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "lisk-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Lisk Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "lisk-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 27. Manta Pacific Testnet **Path:** chains/manta-pacific **Metadata:** ```yaml title: Manta Pacific Testnet sidebarTitle: Manta Pacific Testnet description: Get token balances and transactions for Manta Pacific Testnet. 22 endpoints supported. Testnet supported. chain_name: manta-sepolia-testnet chain_id: 3441006 support_level: community network_type: testnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Manta Pacific is an EVM-native modular execution layer for zk applications, making zk accessible to everyone. GoldRush offers the most comprehensive Manta Pacific Testnet Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Manta Pacific Testnet Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Network Details | Property | Value | |----------|-------| | **Chain Name** | `manta-sepolia-testnet` | | **Chain ID** | `3441006` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://pacific-explorer.manta.network/) | | **Official Website** | [Manta Pacific Testnet Website](https://pacific-explorer.testnet.manta.network/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `manta-sepolia-testnet` | | **Chain ID** | `3441006` | | **Purpose** | Development and testing network | | **Support Level** | community | | **Block Explorer** | [Explorer](https://pacific-explorer.manta.network/) | | **Official Website** | [Manta Pacific Testnet Website](https://pacific-explorer.testnet.manta.network/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `manta-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name curl -X GET "https://api.covalenthq.com/v1/manta-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "manta-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 28. Mantle **Path:** chains/mantle **Metadata:** ```yaml title: Mantle sidebarTitle: Mantle description: Get token balances and transactions for Mantle. 23 endpoints supported. chain_name: mantle-mainnet chain_id: 5000 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Mantle is a high-performance Ethereum layer-2 network built with modular architecture delivering low fees and high security. GoldRush offers the most comprehensive Mantle Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Mantle Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `mantle-mainnet` | | **Chain ID** | `5000` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://explorer.mantle.xyz/) | | **Official Website** | [Mantle Website](https://www.mantle.xyz/) | | **Native Gas Token** | MNT | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `mantle-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/mantle-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "mantle-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 29. MegaETH **Path:** chains/megaeth **Metadata:** ```yaml title: MegaETH sidebarTitle: MegaETH description: Get token balances, transactions, and OHLCV pricing data for MegaETH. 31 endpoints supported. chain_name: megaeth-mainnet chain_id: 4326 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** MegaETH is real-time Ethereum, streaming transactions at lightning speed: sub-millisecond latency and over 100,000 transactions per second. > **Note:** This chain leverages major token prices (BTC, ETH, SOL) powered by Redstone Bolt, offering ultra-low-latency CEX price feeds updated every 2.4ms (~400 updates/sec), sourced from Binance, Coinbase, OKX, Bitget, and Kraken via co-located Bolt nodes. These price feeds are incorporated into the [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream#supported-token-price-feeds). GoldRush offers the most comprehensive MegaETH Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our MegaETH Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `megaeth-mainnet` (Foundational API) / `MEGAETH_MAINNET` (Streaming API) | | **Chain ID** | `4326` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [MEGA Mainnet Explorer](https://megaeth.blockscout.com/) | | **Official Website** | [MegaETH Website](https://www.megaeth.com/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `megaeth-mainnet` / `MEGAETH_MAINNET` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/megaeth-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "megaeth-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **9** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 30. Monad **Path:** chains/monad **Metadata:** ```yaml title: Monad sidebarTitle: Monad description: Get token balances, transactions, and OHLCV pricing data for Monad. 29 endpoints supported. Testnet supported. chain_name: monad-mainnet chain_id: 143 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** Monad redefines L1 scalability with 10,000 TPS, 1-second finality, and near-zero gas fees while maintaining full EVM compatibility. The next generation of high-performance blockchains. GoldRush offers the most comprehensive Monad Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Monad Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `monad-mainnet` (Foundational API) / `MONAD_MAINNET` (Streaming API) | | **Chain ID** | `143` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Monad Blockchain Explorer](https://monadexplorer.com/) | | **Official Website** | [Monad Website](https://www.monad.xyz/) | | **Native Gas Token** | MON | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `monad-testnet` | | **Chain ID** | `10143` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Monad Blockchain Explorer](https://testnet.monadexplorer.com/) | | **Official Website** | [Monad Testnet Website](https://www.monad.xyz/) | | **Native Gas Token** | MON | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `monad-mainnet` / `MONAD_MAINNET` (mainnet) - `monad-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/monad-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Monad Testnet) curl -X GET "https://api.covalenthq.com/v1/monad-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "monad-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Monad Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "monad-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **7** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#monad-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#monad-evm) - [Logs](/goldrush-pipeline-api/supported-chains#monad-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#monad-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 31. Moonbeam **Path:** chains/moonbeam **Metadata:** ```yaml title: Moonbeam sidebarTitle: Moonbeam description: Get token balances and transactions for Moonbeam. 22 endpoints supported. chain_name: moonbeam-mainnet chain_id: 1284 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Explore Moonbeam, an Ethereum-compatible parachain on Polkadot with enhanced governance, staking, and cross-chain integrations. Get started now! GoldRush offers the most comprehensive Moonbeam Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Moonbeam Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `moonbeam-mainnet` | | **Chain ID** | `1284` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://moonscan.io/) | | **Official Website** | [Moonbeam Website](https://moonbeam.network/) | | **Native Gas Token** | GLMR | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `moonbeam-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/moonbeam-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "moonbeam-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#moonbeam-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#moonbeam-evm) - [Logs](/goldrush-pipeline-api/supported-chains#moonbeam-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#moonbeam-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 32. Moonriver **Path:** chains/moonriver **Metadata:** ```yaml title: Moonriver sidebarTitle: Moonriver description: Get token balances and transactions for Moonriver. 22 endpoints supported. chain_name: moonbeam-moonriver chain_id: 1285 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Moonriver is an Ethereum-compatible Solidity Smart Contracts Parachain on Kusama. Moonriver is a companion network to Moonbeam and provides a permanently incentivized canary network. New code ships to Moonriver first, where it can be tested and verified under real economic conditions. Once proven, the same code ships to Moonbeam on Polkadot. Moonriver is a Community-Led Sister Parachain on Kusama. GoldRush offers the most comprehensive Moonriver Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Moonriver Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `moonbeam-moonriver` | | **Chain ID** | `1285` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://moonriver.moonscan.io/) | | **Official Website** | [Moonriver Website](https://moonbeam.network/networks/moonriver/) | | **Native Gas Token** | MOVR | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `moonbeam-moonriver` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/moonbeam-moonriver/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "moonbeam-moonriver", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 33. Oasis Sapphire **Path:** chains/oasis-sapphire **Metadata:** ```yaml title: Oasis Sapphire sidebarTitle: Oasis Sapphire description: Get token balances and transactions for Oasis Sapphire. 22 endpoints supported. chain_name: oasis-sapphire-mainnet chain_id: 23294 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** The Sapphire ParaTime is the official confidential EVM Compatible ParaTime providing a smart contract development environment with EVM compatibility. Oasis Sapphire allows for a confidential state, end-to-end encryption, and confidential randomness GoldRush offers the most comprehensive Oasis Sapphire Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Oasis Sapphire Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `oasis-sapphire-mainnet` | | **Chain ID** | `23294` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://explorer.sapphire.oasis.io/) | | **Official Website** | [Oasis Sapphire Website](https://docs.oasis.io/dapp/sapphire/) | | **Native Gas Token** | ROSE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `oasis-sapphire-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/oasis-sapphire-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "oasis-sapphire-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) - [AppChain Documentation](https://goldrush.dev/docs/appchains/) --- ## 34. Oasis **Path:** chains/oasis **Metadata:** ```yaml title: Oasis sidebarTitle: Oasis description: Get token balances and transactions for Oasis. 22 endpoints supported. chain_name: emerald-paratime-mainnet chain_id: 42262 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** The Oasis Emerald ParaTime is the official EVM compatible ParaTime providing smart contract environment with full EVM compatibility. GoldRush offers the most comprehensive Oasis Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Oasis Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `emerald-paratime-mainnet` | | **Chain ID** | `42262` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://explorer.emerald.oasis.dev/) | | **Official Website** | [Oasis Website](https://oasisprotocol.org/) | | **Native Gas Token** | ROSE | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `emerald-paratime-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/emerald-paratime-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "emerald-paratime-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 35. opBNB **Path:** chains/opbnb **Metadata:** ```yaml title: opBNB sidebarTitle: opBNB description: Get token balances and transactions for opBNB. 22 endpoints supported. chain_name: bnb-opbnb-mainnet chain_id: 204 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** opBNB is an optimized L2 solution that offers low fees and high throughput for BNB Chain. GoldRush offers the most comprehensive opBNB Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our opBNB Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `bnb-opbnb-mainnet` | | **Chain ID** | `204` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://opbnbscan.com/) | | **Official Website** | [opBNB Website](https://opbnb.bnbchain.org/en) | | **Native Gas Token** | BNB | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `bnb-opbnb-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/bnb-opbnb-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "bnb-opbnb-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) - [AppChain Documentation](https://goldrush.dev/docs/appchains/) --- ## 36. Optimism **Path:** chains/optimism **Metadata:** ```yaml title: Optimism sidebarTitle: Optimism description: Get token balances and transactions for Optimism. 30 endpoints supported. Testnet supported. chain_name: optimism-mainnet chain_id: 10 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Optimism is a low-cost and lightning-fast Ethereum L2 blockchain. GoldRush offers the most comprehensive Optimism Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Optimism Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `optimism-mainnet` | | **Chain ID** | `10` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [Optimistic Etherscan](https://optimistic.etherscan.io/) | | **Official Website** | [Optimism Website](https://www.optimism.io/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `optimism-sepolia` | | **Chain ID** | `11155420` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [OP Sepolia Explorer](https://optimism-sepolia.blockscout.com/) | | **Official Website** | [Optimism Sepolia Testnet Website](https://community.optimism.io/docs/useful-tools/networks/#parameters-for-node-operators-2) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `optimism-mainnet` (mainnet) - `optimism-sepolia` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/optimism-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Optimism Sepolia Testnet) curl -X GET "https://api.covalenthq.com/v1/optimism-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "optimism-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Optimism Sepolia Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "optimism-sepolia", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **2** GoldRush Streaming APIs: - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#optimism-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#optimism-evm) - [Logs](/goldrush-pipeline-api/supported-chains#optimism-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#optimism-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 37. Plasma **Path:** chains/plasma **Metadata:** ```yaml title: Plasma sidebarTitle: Plasma description: Get token balances and transactions for Plasma. 22 endpoints supported. Testnet supported. chain_name: plasma-mainnet chain_id: 9745 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Plasma is a high-performance layer 1 blockchain purpose-built for stablecoins. It powers near instant, fee-free payments with institutional-grade security. GoldRush offers the most comprehensive Plasma Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Plasma Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `plasma-mainnet` | | **Chain ID** | `9745` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Plasma Explorer](https://plasmascan.to/) | | **Official Website** | [Plasma Website](https://www.plasma.to/) | | **Native Gas Token** | XPL | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `plasma-testnet` | | **Chain ID** | `9746` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Plasma Testnet Explorer](https://testnet.plasmascan.to/) | | **Official Website** | [Plasma Testnet Website](https://www.plasma.to/) | | **Native Gas Token** | XPL | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `plasma-mainnet` (mainnet) - `plasma-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/plasma-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Plasma Testnet) curl -X GET "https://api.covalenthq.com/v1/plasma-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "plasma-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Plasma Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "plasma-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 38. Polygon **Path:** chains/polygon **Metadata:** ```yaml title: Polygon sidebarTitle: Polygon description: Get token balances, transactions, and OHLCV pricing data for Polygon. 37 endpoints supported. Testnet supported. chain_name: matic-mainnet chain_id: 137 support_level: foundational network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** Polygon PoS is the most battle-tested Ethereum scaling solution with 1.3B+ transactions, 130M wallets, and 2.7M monthly active users. The proven choice for production-grade applications. GoldRush offers the most comprehensive Polygon Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Polygon Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `matic-mainnet` (Foundational API) / `MATIC_MAINNET` (Streaming API) | | **Chain ID** | `137` | | **Network Type** | Foundational Chain | | **Support Level** | foundational | | **Block Explorer** | [PolygonScan](https://polygonscan.com/) | | **Official Website** | [Polygon Website](https://polygon.technology/) | | **Native Gas Token** | MATIC | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `polygon-amoy-testnet` | | **Chain ID** | `80002` | | **Purpose** | Development and testing network | | **Support Level** | foundational | | **Block Explorer** | [Amoy PolygonScan](https://amoy.polygonscan.com/) | | **Official Website** | [Polygon Amoy Testnet Website](https://polygon.technology/blog/introducing-the-amoy-testnet-for-polygon-pos) | | **Native Gas Token** | gwei | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `matic-mainnet` / `MATIC_MAINNET` (mainnet) - `polygon-amoy-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/matic-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Polygon Amoy Testnet) curl -X GET "https://api.covalenthq.com/v1/polygon-amoy-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "matic-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Polygon Amoy Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "polygon-amoy-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **28** GoldRush Foundational APIs: #### Wallet API - **[Get token holders as of any block height (v2)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)** - **[Get historical token balances for address](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)** - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** - **[Check ownership in NFT collection](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)** - **[Check ownership in NFT collection for specific token](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)** #### Pricing API - **[Get pool spot prices](/api-reference/foundational-api/utility/get-pool-spot-prices/)** - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Streaming API Support This chain supports **9** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) - [Top Trader Wallets for Token Query](/api-reference/streaming-api/queries/upnl-for-token-query/) - [Wallet PnL by Token Query](/api-reference/streaming-api/queries/upnl-for-wallet-query/) ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#polygon-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#polygon-evm) - [Logs](/goldrush-pipeline-api/supported-chains#polygon-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#polygon-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 39. Redstone **Path:** chains/redstone **Metadata:** ```yaml title: Redstone sidebarTitle: Redstone description: Get token balances and transactions for Redstone. 22 endpoints supported. chain_name: redstone-mainnet chain_id: 690 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Redstone is a blockchain built for onchain games and autonomous worlds. GoldRush offers the most comprehensive Redstone Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Redstone Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `redstone-mainnet` | | **Chain ID** | `690` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://explorer.redstone.xyz/) | | **Official Website** | [Redstone Website](https://redstone.xyz/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `redstone-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/redstone-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "redstone-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 40. Scroll **Path:** chains/scroll **Metadata:** ```yaml title: Scroll sidebarTitle: Scroll description: Get token balances and transactions for Scroll. 23 endpoints supported. chain_name: scroll-mainnet chain_id: 534352 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Discover Scroll, an L2 solution extending Ethereum with zero knowledge tech and EVM equivalence. Sign up for a free Covalent API key and start building today! GoldRush offers the most comprehensive Scroll Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Scroll Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `scroll-mainnet` | | **Chain ID** | `534352` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://blockscout.scroll.io/) | | **Official Website** | [Scroll Website](https://scroll.io/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `scroll-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/scroll-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "scroll-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#scroll-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#scroll-evm) - [Logs](/goldrush-pipeline-api/supported-chains#scroll-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#scroll-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 41. Sei **Path:** chains/sei **Metadata:** ```yaml title: Sei sidebarTitle: Sei description: Get token balances and transactions for Sei. 22 endpoints supported. chain_name: sei-mainnet chain_id: 1329 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Sei is the first parallelized EVM, known for being extremely fast and processing multiple transactions at the same time. GoldRush offers the most comprehensive Sei Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Sei Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `sei-mainnet` | | **Chain ID** | `1329` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://seistream.app/) | | **Official Website** | [Sei Website](https://www.sei.io/) | | **Native Gas Token** | SEI | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `sei-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/sei-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "sei-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 42. Solana **Path:** chains/solana **Metadata:** ```yaml title: Solana sidebarTitle: Solana description: Get token balances, transactions, and OHLCV pricing data for Solana. 9 endpoints supported. chain_name: solana-mainnet chain_id: 1399811149 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":true} capabilities: {} ``` **Content:** ## Overview > **Tip:** Solana delivers 400ms block times and sub-cent transaction fees, making it the chain of choice for high-frequency trading, gaming, and consumer applications at scale. GoldRush offers the most comprehensive Solana Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Solana Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured spot data such as token balances. Use cases: Wallets, portfolio trackers [Read more](/goldrush-foundational-api) ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `solana-mainnet` (Foundational API) / `SOLANA_MAINNET` (Streaming API) | | **Chain ID** | `1399811149` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://explorer.solana.com/) | | **Official Website** | [Solana Website](https://solana.com/) | | **Native Gas Token** | SOL | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `solana-mainnet` / `SOLANA_MAINNET` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "solana-mainnet", walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY" }); ``` ## Foundational API Support This chain supports **1** GoldRush Foundational API: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address)** ## Streaming API Support This chain supports **6** GoldRush Streaming APIs: - [New DEX Pairs Stream](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/) - [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/) - [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/) - [Update Pairs Stream](/api-reference/streaming-api/subscriptions/update-pairs-stream/) - [Update Tokens Stream](/api-reference/streaming-api/subscriptions/update-tokens-stream/) - [Token Search Query](/api-reference/streaming-api/queries/token-search-query/) ## Pipeline API Support This chain supports **2** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [DEX Swaps](/goldrush-pipeline-api/supported-chains#solana) - [SPL Token Transfers](/goldrush-pipeline-api/supported-chains#solana) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 43. Sonic **Path:** chains/sonic **Metadata:** ```yaml title: Sonic sidebarTitle: Sonic description: Get token balances and transactions for Sonic. 22 endpoints supported. chain_name: sonic-mainnet chain_id: 146 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Sonic is the highest-performing EVM L1, combining speed, incentives, and world-class infrastructure for DeFi. GoldRush offers the most comprehensive Sonic Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Sonic Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `sonic-mainnet` | | **Chain ID** | `146` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Sonic Explorer](https://sonicscan.org/) | | **Official Website** | [Sonic Website](https://www.soniclabs.com/) | | **Native Gas Token** | S | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `sonic-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/sonic-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "sonic-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 44. Taiko **Path:** chains/taiko **Metadata:** ```yaml title: Taiko sidebarTitle: Taiko description: Get token balances and transactions for Taiko. 22 endpoints supported. chain_name: taiko-mainnet chain_id: 167000 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Taiko is a Type 1 (Ethereum-equivalent) zkEVM that is open source and decentralized. GoldRush offers the most comprehensive Taiko Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Taiko Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `taiko-mainnet` | | **Chain ID** | `167000` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://taikoscan.network/) | | **Official Website** | [Taiko Website](https://taiko.xyz/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `taiko-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/taiko-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "taiko-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 45. Tempo Onchain Data API **Path:** chains/tempo **Metadata:** ```yaml title: Tempo Onchain Data API sidebarTitle: Tempo description: Get token balances, transactions, and OHLCV pricing data for Tempo. ``` **Content:** ## Overview > **Tip:** Tempo is a general-purpose blockchain optimized for payments. GoldRush offers the most comprehensive Tempo Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Tempo Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Streaming API Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets. Track token transfers, DEX activity, wallet movements, and OHLCV candlestick data across fast chains like Base and Solana. **Use cases: Trading bots & dashboards, gaming, and AI Agents.** [Read more](/goldrush-streaming-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `TEMPO_MAINNET` | | **Chain ID** | `4217` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Tempo Explorer](https://explore.tempo.xyz/) | | **Official Website** | [Tempo Website](https://tempo.xyz/) | | **Native Gas Token** | Multiple Stablecoins | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `TEMPO_MAINNET` (mainnet) #### Example Streaming Subscription ```graphql GraphQL Subscription subscription { walletTxs( chain_name: TEMPO_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"] ) { block_signed_at block_height tx_hash tx_offset successful decoded_type } } ``` ```typescript TypeScript SDK import { GoldRushClient, StreamingChain } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); client.StreamingService.subscribeToWalletTxs( { chain_name: StreamingChain.TEMPO_MAINNET, wallet_addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"], }, { next: (data) => console.log("Received data:", data), error: (error) => console.error("Error:", error), complete: () => console.log("Stream completed"), } ); ``` > **Note:** Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key in the connection parameters. See the [Streaming API Quickstart](/goldrush-streaming-api/quickstart) for full setup details. ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 46. Unichain **Path:** chains/unichain **Metadata:** ```yaml title: Unichain sidebarTitle: Unichain description: Get token balances and transactions for Unichain. 22 endpoints supported. Testnet supported. chain_name: unichain-mainnet chain_id: 130 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Unichain is a DeFi-native Ethereum L2, built to be the home for liquidity across chains. GoldRush offers the most comprehensive Unichain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Unichain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `unichain-mainnet` | | **Chain ID** | `130` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Unichain Explorer](https://unichain.blockscout.com/) | | **Official Website** | [Unichain Website](https://www.unichain.org/) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `unichain-sepolia-testnet` | | **Chain ID** | `1301` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [Unichain Sepolia Testnet Explorer](https://sepolia.uniscan.xyz/) | | **Official Website** | [Unichain Testnet Website](https://www.unichain.org/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `unichain-mainnet` (mainnet) - `unichain-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/unichain-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (Unichain Testnet) curl -X GET "https://api.covalenthq.com/v1/unichain-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "unichain-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (Unichain Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "unichain-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 47. Viction **Path:** chains/viction **Metadata:** ```yaml title: Viction sidebarTitle: Viction description: Get token balances and transactions for Viction. 22 endpoints supported. chain_name: viction-mainnet chain_id: 88 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** Viction, previously known as TomoChain, is a scalable, highly decentralized blockchain network that takes a community-driven approach to development and adoption. GoldRush offers the most comprehensive Viction Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our Viction Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `viction-mainnet` | | **Chain ID** | `88` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://www.vicscan.xyz/) | | **Official Website** | [Viction Website](https://viction.xyz/) | | **Native Gas Token** | TOMO | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `viction-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/viction-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "viction-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 48. World Chain **Path:** chains/world-chain **Metadata:** ```yaml title: World Chain sidebarTitle: World Chain description: Get token balances and transactions for World Chain. 22 endpoints supported. Testnet supported. chain_name: world-mainnet chain_id: 480 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** World Chain is a blockchain designed for humans, offering features like free gas fees, native mobile distribution through mini-apps, simplified crypto transactions and Sybil resistance via World ID. GoldRush offers the most comprehensive World Chain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our World Chain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `world-mainnet` | | **Chain ID** | `480` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [World Chain Mainnet Explorer](https://worldscan.org/) | | **Official Website** | [World Chain Website](https://world.org/world-chain) | | **Native Gas Token** | ETH | ## Testnet | Property | Value | |----------|-------| | **Chain Name** | `world-sepolia-testnet` | | **Chain ID** | `4801` | | **Purpose** | Development and testing network | | **Support Level** | frontier | | **Block Explorer** | [World Chain Sepolia Explorer](https://worldchain-sepolia.explorer.alchemy.com/) | | **Official Website** | [World Chain Testnet Website](https://world.org/world-chain) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `world-mainnet` (mainnet) - `world-sepolia-testnet` (testnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/world-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash Chain Name (World Chain Testnet) curl -X GET "https://api.covalenthq.com/v1/world-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` ```bash ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "world-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ```typescript TypeScript SDK (World Chain Testnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "world-sepolia-testnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 49. ZetaChain **Path:** chains/zetachain **Metadata:** ```yaml title: ZetaChain sidebarTitle: ZetaChain description: Get token balances and transactions for ZetaChain. 22 endpoints supported. chain_name: zetachain-mainnet chain_id: 7000 support_level: community network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** ZetaChain is an EVM-compatible L1 blockchain for cross-chain apps. GoldRush offers the most comprehensive ZetaChain Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our ZetaChain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `zetachain-mainnet` | | **Chain ID** | `7000` | | **Network Type** | Community Chain | | **Support Level** | community | | **Block Explorer** | [Explorer](https://explorer.zetachain.com/) | | **Official Website** | [ZetaChain Website](https://www.zetachain.com/) | | **Native Gas Token** | ZETA | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `zetachain-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/zetachain-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "zetachain-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **22** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) --- ## 50. zkSync Era **Path:** chains/zksync-era **Metadata:** ```yaml title: zkSync Era sidebarTitle: zkSync Era description: Get token balances and transactions for zkSync Era. 23 endpoints supported. chain_name: zksync-mainnet chain_id: 324 support_level: frontier network_type: mainnet apis: {"foundational":true,"streaming":false} capabilities: {} ``` **Content:** ## Overview > **Tip:** zkSync Era is a Layer-2 protocol that scales Ethereum with cutting-edge ZK tech. GoldRush offers the most comprehensive zkSync Era Data API suite for developers, analysts, and enterprises. Whether you're building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, our zkSync Era Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. ### Supported APIs ### Foundational API Access structured historical blockchain data across 100+ chains using REST APIs. Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more. **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.** [Read more](/goldrush-foundational-api) ### Pipeline API Stream blockchain data directly to your own infrastructure. Push decoded blocks, transactions, event logs, and protocol-specific data into your database, warehouse, queue, or webhook with ABI decoding and SQL transforms built in. **Use cases: Data warehousing, analytics dashboards, ETL pipelines, and backend indexing.** [Read more](/goldrush-pipeline-api) ## Mainnet | Property | Value | |----------|-------| | **Chain Name** | `zksync-mainnet` | | **Chain ID** | `324` | | **Network Type** | Frontier Chain | | **Support Level** | frontier | | **Block Explorer** | [Explorer](https://explorer.zksync.io/) | | **Official Website** | [zkSync Era Website](https://zksync.io/) | | **Native Gas Token** | ETH | ## API Usage To use this blockchain network in GoldRush API calls, use: #### Chain Name - `zksync-mainnet` (mainnet) #### Example API Calls ```bash Chain Name (Mainnet) curl -X GET "https://api.covalenthq.com/v1/zksync-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` #### SDK Usage ```typescript TypeScript SDK (Mainnet) import { GoldRushClient } from "@covalenthq/client-sdk"; const client = new GoldRushClient("API_KEY"); const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ chainName: "zksync-mainnet", walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` ## Foundational API Support This chain supports **23** GoldRush Foundational APIs: #### Wallet API - **[Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address/)** - **[Get native token balance for address](/api-reference/foundational-api/balances/get-native-token-balance/)** - **[Get historical portfolio value over time](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)** - **[Get ERC20 token transfers for address](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)** #### NFT API - **[Get NFTs for address](/api-reference/foundational-api/nft/get-nfts-for-address/)** #### Pricing API - **[Get historical token prices](/api-reference/foundational-api/utility/get-historical-token-prices/)** #### Security API - **[Get token approvals for address](/api-reference/foundational-api/security/get-token-approvals-for-address/)** #### Activity Feed API - **[Get a transaction](/api-reference/foundational-api/transactions/get-a-transaction/)** - **[Get transaction summary for address](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)** - **[Get earliest transactions for address (v3) ](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** - **[Get recent transactions for address (v3)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** - **[Get paginated transactions for address (v3)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** - **[Get bulk time bucket transactions for address (v3)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)** - **[Get all transactions in a block (v3)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)** - **[Get all transactions in a block by page (v3) ](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)** #### Block Explorer API - **[Get a block](/api-reference/foundational-api/utility/get-a-block/)** - **[Get all chain statuses](/api-reference/foundational-api/utility/get-all-chain-statuses/)** - **[Get all chains](/api-reference/foundational-api/utility/get-all-chains/)** - **[Get block heights](/api-reference/foundational-api/utility/get-block-heights/)** - **[Get gas prices](/api-reference/foundational-api/utility/get-gas-prices/)** - **[Get log events by contract address](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)** - **[Get log events by topic hash(es)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)** - **[Get logs](/api-reference/foundational-api/utility/get-logs/)** ## Pipeline API Support This chain supports **4** GoldRush Pipeline API data objects that can be streamed to your infrastructure: - [Blocks](/goldrush-pipeline-api/supported-chains#zksync-era-evm) - [Transactions](/goldrush-pipeline-api/supported-chains#zksync-era-evm) - [Logs](/goldrush-pipeline-api/supported-chains#zksync-era-evm) - [Transfers](/goldrush-pipeline-api/supported-chains#zksync-era-evm) ## Additional Resources - [GoldRush API Documentation](https://goldrush.dev/docs/) - [Supported Chains List](https://goldrush.dev/chains/) - [API Reference](https://goldrush.dev/docs/api-reference/) ---