# 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) - 11 GraphQL endpoints
- [Pipeline API](#pipeline-api-documentation) - 32 pages (normalizers, destinations, guides)
- [Hyperliquid API](#hyperliquid-api-documentation) - 58 pages (Info API, streaming recipes, and API reference)
- [Solana API](#solana-api-documentation) - 9 pages (Foundational walkthroughs, streaming recipes, warehouse recipes)
- [x402 API](#x402-api-documentation) - Pay-per-request access for AI agents (60+ endpoints)
- [Chain Documentation](#chain-documentation) - 51 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 | HB | 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 <GOLDRUSH_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: <GOLDRUSH_API_KEY>"

# CORRECT
curl -H "Authorization: Bearer <GOLDRUSH_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 <GOLDRUSH_API_KEY>" header
4. Pagination returns 100 items per page. If result has 100 items, more pages likely exist
5. Base URL: https://api.covalenthq.com/v1
6. Always check resp.error before accessing resp.data
7. Ethereum addresses: 0x + 40 hex chars, or ENS names
8. For detailed integration guidance, refer to the LLM Integration Guide
```

---

**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 <GOLDRUSH_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/
description: Fetch Bitcoin balance for a non-HD address. Response includes spot prices and other metadata.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-bitcoin-balance-for-address).

---

## 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/
description: Fetch balances for each active child address derived from a Bitcoin HD wallet. 
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-bitcoin-balances-for-hd-address).

> **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/
description: Commonly used to render the transfer-in and transfer-out of a token along with historical prices from an address.
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<object>` |  |

### 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-erc20-token-transfers-for-address).

---

## 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/
description: Commonly used to fetch the historical Bitcoin balance held by an address at a given block height or date. Response includes daily prices and other metadata.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-historical-bitcoin-balance-for-address).

---

## 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/
description: Commonly used to render a daily portfolio balance for an address broken down by the token. The timeframe is user-configurable, defaults to 30 days.
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 30 days
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<object>` |  |


**Content:**

**Credit Cost:** 2 per 30 days

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-historical-portfolio-value-over-time).

> **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/
description: Commonly used to fetch the historical native and fungible (ERC20) tokens held by an address at a given block height or date. Response includes daily prices and other metadata.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-historical-token-balances-for-address).

> **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/
description: Lightweight endpoint to just get the native token balance for an EVM address. 
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-native-token-balance).

> **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/
description: Commonly used to fetch the native and fungible (ERC20) tokens held by an address. Response includes spot prices and other metadata.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-token-balances-for-address).

> **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/
description: Used to get a paginated list of current or historical token holders for a specified ERC20 or ERC721 token. 
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","arbitrum-mainnet","linea-mainnet","mantle-mainnet","plasma-mainnet","taiko-mainnet","unichain-mainnet","world-mainnet","berachain-mainnet","avalanche-mainnet","apechain-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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-token-holders-as-of-any-block-height-v2).

> **Note:** The endpoint returns the latest token holders snapshot for: Ethereum, Polygon, BSC, Optimism, Base, Gnosis, ApeChain, Arbitrum, Avalanche, Berachain, Linea, Mantle, Plasma, Taiko, Unichain, and World Chain.

Querying historical snapshots via `block-height` or `date` is supported only on the [Foundational Chains](https://goldrush.dev/chains/). On other chains, supplying these parameters returns a `400` error.

Page size is either `100` (default) or `1000`.

---

## 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/
description: Commonly used to locate chains which an address is active on with a single API call.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fcross-chain%2Fget-address-activity).

---

## 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/
description: Fetch paginated spot & historical native and token balances for a single address on up to 10 EVM chains with one API call.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fcross-chain%2Fget-allchains-balances).

> **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/
description: Fetch paginated transactions for up to 10 EVM addresses and 10 EVM chains with one API call. Useful for building Activity Feeds. 
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. |
| `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<object>` | The block explorer links for this transaction. |
| `log_events` | `array<object>` | Event logs generated by the transaction. |


**Content:**

**Credit Cost:** 0.25 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fcross-chain%2Fget-allchains-transactions).

> **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.

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}/
description: Commonly used to verify ownership of a specific token (ERC-721 or ERC-1155) within a collection.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fnft%2Fcheck-ownership-in-nft-collection-token).

### 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}/
description: Commonly used to verify ownership of NFTs (including ERC-721 and ERC-1155) within a collection.
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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fnft%2Fcheck-ownership-in-nft-collection).

### 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/
description: Commonly used to render the NFTs (including ERC721 and ERC1155) held by an address.
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<string>` | 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<object>` |  |


**Content:**

**Credit Cost:** 1 per call

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fnft%2Fget-nfts-for-address).

---

## 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}/
description: Commonly used to get a list of approvals across all token contracts categorized by spenders for a wallet’s assets.
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<object>` | Contracts with non-zero approvals for this token. |


**Content:**

**Credit Cost:** 2 per call

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Fsecurity%2Fget-token-approvals-for-address).

---

## 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}/
description: Used to fetch and render a single transaction including its decoded event logs. For foundational chains, can also retrieve internal transactions, state changes and method ID where available. 
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. |

### 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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per call

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-a-transaction).

> **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.

Internal transactions are included in the response by using `with-internal` and cost `0.05` credits/item.

### 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}/
description: Commonly used to fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.
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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-all-transactions-in-a-block-by-page).

> **Note:** Requests that return status `200` and no data cost `0.1` credits.

Enabling `no-logs` reduces request cost to `0.05` credits/item.

---

## 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/
description: Commonly used to fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.
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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-all-transactions-in-a-block).

> **Note:** Requests that return status `200` and no data cost `0.1` credits.

Enabling `no-logs` reduces request cost to `0.05` credits/item.

### 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}/
description: Commonly used to fetch and render the earliest transactions involving an address. Frequently seen in wallet applications.
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. |
| `with-internal` | boolean | No | - | Whether to include internal transfers/transactions. |

### 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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-earliest-transactions-for-address-v3).

> **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.

Calls with `no-logs` cost `0.05` credits/item.

Internal transactions are included in the response by using `with-internal` and cost `0.05` credits/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}/
description: Commonly used to fetch the transactions involving an address including the decoded log events in a paginated fashion.
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. |
| `with-internal` | boolean | No | - | Whether to include internal transfers/transactions. |

### 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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-paginated-transactions-for-address-v3).

> **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` credits/item.

Internal transactions are included in the response by using `with-internal` and cost `0.05` credits/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/
description: Commonly used to fetch and render the most recent transactions involving an address. Frequently seen in wallet applications.
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. |
| `with-internal` | boolean | No | - | Whether to include internal transfers/transactions. |

### 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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-recent-transactions-for-address-v3).

> **Note:** Requests that return status `200` and no data cost `0.1` credits.

Enabling `no-logs` reduces request cost to `0.05` credits/item.

Internal transactions are included in the response by using `with-internal` and cost `0.05` credits/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}/
description: Commonly used to fetch all transactions including their decoded log events in a 15-minute time bucket interval.
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<object>` | The explorer links for this transaction. |
| `log_events` | `array<object>` | The log events. |
| `internal_transfers` | `array<object>` | List of internal transfers/transactions associated with the wallet address. |


**Content:**

**Credit Cost:** 0.1 per item

**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-time-bucket-transactions-for-address-v3).

> **Note:** Requests that return status `200` and no data cost `0.1` credits.

Enabling `no-logs` reduces request cost to `0.05` credits/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/
description: Used to fetch the earliest and latest transactions, and the transaction count for a wallet. Also enriched with gas expenditure details and total ERC20 token transfers count.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-transaction-summary-for-address).

> **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/
description: Used to fetch the full transaction history of a Bitcoin non-HD wallet address. 
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Ftransactions%2Fget-transactions-for-bitcoin-address).

> **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}/
description: Commonly used to fetch and render a single block for a block explorer.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-a-block).

---

## 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/
description: Commonly used to build internal status dashboards of all supported chains.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-all-chain-statuses).

---

## 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/
description: Commonly used to build internal dashboards for all supported chains on Covalent.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-all-chains).

---

## 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}/
description: Commonly used to get all the block heights within a particular date range. Useful for rendering a display where you sort blocks by day.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-block-heights).

---

## 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/
description: Get real-time gas estimates for different transaction speeds on a specific network, enabling users to optimize transaction costs and confirmation times.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-gas-prices).

> **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}/
description: Get the historical prices of one (or many) large cap ERC20 tokens between specified date ranges. Also supports native tokens.
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-historical-token-prices).

> **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}/
description: Commonly used to get all the event logs emitted from a particular contract address. Useful for building dashboards that examine on-chain interactions.
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<string>` | 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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-log-events-by-contract-address).

---

## 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}/
description: Commonly used to get all event logs of the same topic hash across all contracts within a particular chain. Useful for cross-sectional analysis of event logs that are emitted on-chain.
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<string>` | 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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-log-events-by-topic-hash).

---

## 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/
description: Commonly used to get all the event logs of the latest block, or for a range of blocks. Includes sender contract metadata as well as decoded logs.
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<string>` | 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<string>` | 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-logs).

> **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}/
description: Get the spot token pair prices for a specified pool contract address. Supports pools on Uniswap V2, V3 and their forks. 
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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-pool-spot-prices).

> **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/
description: Commonly used to resolve ENS, RNS and Unstoppable Domains addresses. Only supports the resolution of a registered domain to an 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

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Ffoundational-api%2Futility%2Fget-resolved-address-for-registered-address).

### 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. OHLCV Pairs Query

**Path:** api-reference/streaming-api/queries/ohlcv-pairs-query

**Operation Identity:**
- Operation ID: `ohlcvCandlesForPair`
- GraphQL Type: `graphql-query`
- GraphQL Field: `ohlcvCandlesForPair`

**Metadata:**
```yaml
title: OHLCV Pairs Query
category: streaming
api_type: graphql-query
operation_identity: {"operation_id":"ohlcvCandlesForPair","type":"graphql-query","field":"ohlcvCandlesForPair"}
endpoint_role: primary
credit_cost: 1 per call
chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","hypercore-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"]
beta: false
related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"]
```

**Content:**

The OHLCV Pairs query returns historical Open, High, Low, Close prices and Volume for **one or many token pairs** at configurable intervals as a one-shot response. Use this when you need a historical fetch rather than a live stream - the request and response shapes are identical to the [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) subscription. The `pair_addresses` input is limited to a **maximum of 5 addresses** per query.

**Credit Cost:** 1 per call

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPERCORE_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Fohlcv-pairs-query).

## 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 |

## Query

You can query the `ohlcvCandlesForPair` endpoint to fetch a historical batch of OHLCV candles in a single response.

```graphql
query {
  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) |

---

## 2. OHLCV Tokens Query

**Path:** api-reference/streaming-api/queries/ohlcv-tokens-query

**Operation Identity:**
- Operation ID: `ohlcvCandlesForToken`
- GraphQL Type: `graphql-query`
- GraphQL Field: `ohlcvCandlesForToken`

**Metadata:**
```yaml
title: OHLCV Tokens Query
category: streaming
api_type: graphql-query
operation_identity: {"operation_id":"ohlcvCandlesForToken","type":"graphql-query","field":"ohlcvCandlesForToken"}
endpoint_role: primary
credit_cost: 1 per call
chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hypercore-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"]
beta: false
related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"]
```

**Content:**

The OHLCV Tokens query returns historical Open, High, Low, Close prices and Volume for **one or many tokens** at configurable intervals as a one-shot response. Use this when you need a historical fetch rather than a live stream - the request and response shapes are identical to the [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) subscription. The `token_addresses` input is limited to a **maximum of 5 addresses** per query.

**Credit Cost:** 1 per call

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPERCORE_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Fohlcv-tokens-query).

## Supported Token Price Feeds

In addition to DEX-sourced prices, this query 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 |

## Query

You can query the `ohlcvCandlesForToken` endpoint to fetch a historical batch of OHLCV candles in a single response.

```graphql
query {
  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) |

---

## 3. 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
category: streaming
api_type: graphql-query
operation_identity: {"operation_id":"searchToken","type":"graphql-query","field":"searchToken"}
endpoint_role: primary
credit_cost: 1 per call
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["defi-dashboards","trading-intelligence","market-analytics"]
beta: false
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:** 1 per call

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Ftoken-search-query).

## 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 |

---

## 4. 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
category: streaming
api_type: graphql-query
operation_identity: {"operation_id":"upnlForToken","type":"graphql-query","field":"upnlForToken"}
endpoint_role: specialized
credit_cost: 1 per call
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","matic-mainnet","gnosis-mainnet","optimism-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["defi-dashboards","trading-intelligence","market-analytics","automation-and-agents"]
beta: false
related: ["ohlcv-tokens-stream","ohlcv-pairs-stream","new-dex-pairs-stream"]
```

**Content:**

This GraphQL query returns the top 20 trader wallets - ranked by trading volume over the last 30 days - for a specific token, along with detailed information about their holdings, transaction activity, and realized and unrealized profit/loss metrics.

**Credit Cost:** 1 per call

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `GNOSIS_MAINNET`
- `MEGAETH_MAINNET`
- `OPTIMISM_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Fupnl-for-token-query).

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain_name` | `enum` | Yes | Blockchain network to filter events |
| `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 |

---

## 5. 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
category: streaming
api_type: graphql-query
operation_identity: {"operation_id":"upnlForWallet","type":"graphql-query","field":"upnlForWallet"}
endpoint_role: specialized
credit_cost: 1 per call
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","matic-mainnet","gnosis-mainnet","optimism-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["trading-intelligence","accounting-tax-reporting","portfolio-tracking"]
beta: false
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:** 1 per call

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `GNOSIS_MAINNET`
- `MEGAETH_MAINNET`
- `OPTIMISM_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Fupnl-for-wallet-query).

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain_name` | `enum` | Yes | Blockchain network to filter events |
| `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 |

---

## 6. 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
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: 1 per minute
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["trading-intelligence","price-discovery-feeds","defi-dashboards","automation-and-agents"]
beta: false
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:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fnew-dex-pairs-stream).

## 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 |

---

## 7. 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
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: 1 per minute
chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","hypercore-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"]
beta: false
related: ["ohlcv-tokens-stream","new-dex-pairs-stream","update-pairs-stream"]
```

**Content:**

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. The `pair_addresses` input is limited to a **maximum of 5 addresses** per subscription.

**Credit Cost:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPERCORE_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fohlcv-pairs-stream).

## 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) |

---

## 8. 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
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: 1 per minute
chains: ["base-mainnet","bsc-mainnet","eth-mainnet","solana-mainnet","monad-mainnet","hypercore-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","automation-and-agents"]
beta: false
related: ["ohlcv-pairs-stream","new-dex-pairs-stream","update-pairs-stream"]
```

**Content:**

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. The `token_addresses` input is limited to a **maximum of 5 addresses** per subscription.

**Credit Cost:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPERCORE_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fohlcv-tokens-stream).

## 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) |

---

## 9. 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
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: 1 per minute
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","defi-dashboards","automation-and-agents"]
beta: false
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. The `pair_addresses` input is limited to a **maximum of 5 addresses** per subscription.

**Credit Cost:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fupdate-pairs-stream).

## 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) |

---

## 10. 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
category: streaming
api_type: graphql-subscription
operation_identity: {"operation_id":"updateTokens","type":"graphql-subscription","field":"updateTokens"}
endpoint_role: primary
credit_cost: 1 per minute
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","solana-mainnet","monad-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["price-discovery-feeds","trading-intelligence","defi-dashboards","automation-and-agents"]
beta: false
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. The `token_addresses` input is limited to a **maximum of 5 addresses** per subscription.

**Credit Cost:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`
- `SOLANA_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fupdate-tokens-stream).

## 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) |

---

## 11. 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
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: 1 per minute
chains: ["base-mainnet","eth-mainnet","bsc-mainnet","monad-mainnet","hypercore-mainnet","hyperevm-mainnet","matic-mainnet","megaeth-mainnet","robinhood-mainnet"]
use_cases: ["trading-intelligence","automation-and-agents","onchain-gaming-infrastructure","defi-dashboards"]
beta: false
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. The `wallet_addresses` input is limited to a **maximum of 1000 addresses** per subscription on HyperCore, and a **maximum of 100 addresses** per subscription on EVM chains and Solana.

**Credit Cost:** 1 per minute

**Supported Chains:** - `BASE_MAINNET`
- `BSC_MAINNET`
- `ETH_MAINNET`
- `HYPERCORE_MAINNET`
- `HYPEREVM_MAINNET`
- `MEGAETH_MAINNET`
- `MONAD_MAINNET`
- `POLYGON_MAINNET`
- `ROBINHOOD_MAINNET`

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fsubscriptions%2Fwallet-activity-stream).

## 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 LedgerAccountActivationGas {
            amount
            token
          }
          ... on LedgerAccountClassTransfer {
            amount
            token
          }
          ... on LedgerBorrowLend {
            amount
            interest_amount
            operation
            token
          }
          ... on LedgerCStakingTransfer {
            amount
            is_deposit
            token
          }
          ... on LedgerDeployGasAuction {
            amount
            token
          }
          ... on LedgerDeposit {
            usdc
          }
          ... on LedgerInternalTransfer {
            fee
            destination
            usdc
            user
          }
          ... on LedgerLiquidation {
            liquidated_ntl_pos
            account_value
            liquidated_positions {
              szi
              coin
            }
            leverage_type
          }
          ... on LedgerPerpDexClassTransfer {
            amount
            dex
            to_perp
            token
          }
          ... on LedgerRewardsClaim {
            amount
          }
          ... on LedgerSend {
            amount
            usdc_value
            destination_dex
            native_token_fee
            fee
            destination
            fee_token
            nonce
            user
            source_dex
            token
          }
          ... on LedgerSpotGenesis {
            amount
            token
          }
          ... on LedgerSpotTransfer {
            amount
            usdc_value
            native_token_fee
            fee
            destination
            fee_token
            nonce
            user
            token
          }
          ... on LedgerSubAccountTransfer {
            destination
            usdc
            user
          }
          ... on LedgerVaultCreate {
            fee
            usdc
            vault
          }
          ... on LedgerVaultDeposit {
            usdc
            user
            vault
          }
          ... on LedgerVaultDistribution {
            usdc
            vault
          }
          ... on LedgerVaultLeaderCommission {
            usdc
            vault
          }
          ... on LedgerVaultWithdraw {
            requested_usd
            commission
            basis
            closing_cost
            user
            vault
          }
          ... on LedgerWithdraw {
            fee
            usdc
            nonce
          }
        }
        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.amount` | `string` | Gas fee amount |
| `delta.token` | `string` | Token used for gas payment |
| `delta.amount` | `string` | Transfer amount |
| `delta.token` | `string` | Token identifier |
| `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.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` | Auction amount |
| `delta.token` | `string` | Token identifier |
| `delta.usdc` | `string` | Deposit amount in USDC |
| `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.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.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` | Claimed rewards amount |
| `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.amount` | `string` | Genesis distribution amount |
| `delta.token` | `string` | Token identifier |
| `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.destination` | `string` | Destination sub-account address |
| `delta.usdc` | `string` | Transfer amount in USDC |
| `delta.user` | `string` | Source user address |
| `delta.fee` | `string` | Vault creation fee |
| `delta.usdc` | `string` | Initial deposit amount in USDC |
| `delta.vault` | `string` | Vault address |
| `delta.usdc` | `string` | Deposit amount in USDC |
| `delta.user` | `string` | Depositor address |
| `delta.vault` | `string` | Vault address |
| `delta.usdc` | `string` | Distribution amount in USDC |
| `delta.vault` | `string` | Vault address |
| `delta.usdc` | `string` | Commission 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 |
| `delta.fee` | `string` | Withdrawal fee |
| `delta.usdc` | `string` | Withdrawal amount in USDC |
| `delta.nonce` | `string` | Withdrawal nonce |
| `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.

## What is an ABI?

An **ABI** (Application Binary Interface) is the JSON description of a smart contract's interface: its functions and events, with the name and Solidity type of every input and output. EVM logs and transaction calldata are emitted as raw, unlabeled hex, and the ABI is the schema that says how to decode that hex back into named, typed fields. Block explorers use a contract's ABI to display human-readable events and function calls instead of raw bytes.

The Pipeline API applies the same idea at stream scale: you supply an ABI, and matching logs and calldata are decoded into structured, typed rows automatically.

## 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

```
                                                                                                          ╔═ Your Destination ═══╗
                          ╔═ GoldRush Pipeline ═══════════════════════════════════════════╗               ║                      ║░
                          ║                                                               ║░              ║   · ClickHouse       ║░
╔══════════╗              ║   ╔═══════════════╗    ╔══════════════╗    ╔════════════════╗ ║░              ║   · Postgres         ║░
║ Covalent ║░             ║   ║ Normalization ║ ─▶ ║ ABI Decoding ║ ─▶ ║ SQL Transforms ║ ║░              ║   · Kafka            ║░
║ Database ║░ ──stream──▶ ║   ╚═══════════════╝    ╚══════════════╝    ╚════════════════╝ ║░ ──deliver──▶ ║   · S3 / GCS / R2    ║░
╚══════════╝░             ║                                                               ║░              ║   · SQS              ║░
 ░░░░░░░░░░░░             ╚═══════════════════════════════════════════════════════════════╝░              ║   · Webhook          ║░
                           ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░              ║                      ║░
                                                                                                          ╚══════════════════════╝░
                                                                                                           ░░░░░░░░░░░░░░░░░░░░░░░░
```

## 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. Pipeline API Supported Chains

**Path:** goldrush-pipeline-api/supported-chains

**Metadata:**
```yaml
title: Pipeline API 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:**

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. Hyperliquid API Rate Limits, Caching & Polling

**Path:** goldrush-hyperliquid/info-api/limits

**Metadata:**
```yaml
title: Hyperliquid API Rate Limits, Caching & Polling
sidebarTitle: Rate Limits & Caching
description: The public Hyperliquid /info API is capped at 1200 request weight per minute per IP. The GoldRush Hyperliquid Info API removes that rate limit entirely - poll any endpoint as fast as you need.
```

**Content:**

## Hyperliquid API rate limits

The **public Hyperliquid `/info` API** is rate limited to **1200 request weight per minute per IP address**. Every `/info` request carries a weight cost, so heavy usage - polling many wallets, refreshing market state frequently, or running a fleet of workers behind one IP - hits the cap quickly and starts getting throttled.

**The GoldRush Hyperliquid Info API removes this limit entirely.** It's a [drop-in `/info` replacement](/goldrush-hyperliquid/info-api/migration) on `hypercore.goldrushdata.com/info` with byte-for-byte identical request and response shapes, but **no per-IP, per-key, or per-address rate limits**.

## No rate limits with GoldRush

With no weight cap and no per-IP throttling, 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.

### 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.
- **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` REST API - fetch user trades (`userFills`), perp and spot account state (`clearinghouseState`), market metadata, and more with no rate limits and faster reads.
```

**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.

Twenty-six wire-compatible `type` values are supported today across market metadata, user state, user history, vaults, and staking - plus four GoldRush-native types (two batched state lookups and two builder-keyed fill feeds) with no upstream equivalent.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## The most-requested reads

Most Hyperliquid apps start from the same REST calls - a user's **trades** and their **account state**. Over the drop-in `/info` API that is:

- **User trades (fills)** - [`userFills`](/api-reference/hyperliquid-info/user-fills) for the latest fills, or [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) for a time window (GoldRush serves these past upstream's ~10,000-fill retention limit).
- **Perp account state** - [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) for a single wallet, or [`batchClearinghouseState`](/api-reference/hyperliquid-info/batch-clearinghouse-state) for up to 50 wallets in one request.
- **Spot balances** - [`spotClearinghouseState`](/api-reference/hyperliquid-info/spot-clearinghouse-state), or [`batchSpotClearinghouseState`](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state) for many wallets at once.

Every type below is called the same way - `POST /info` with a `type` field - so these are the same requests you already make against `api.hyperliquid.xyz`, pointed at a faster, unthrottled host.

## 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. Four GoldRush-native types (`batchClearinghouseState`, `batchSpotClearinghouseState`, `builderFills`, `builderFillsByTime`) 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. |
| [`meta`](/api-reference/hyperliquid-info/meta) | `{"type": "meta", "dex": ""}` | Perp universe metadata only - size decimals, max leverage, margin tiers. No live context. |
| [`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. |
| [`spotMeta`](/api-reference/hyperliquid-info/spot-meta) | `{"type": "spotMeta"}` | Spot universe metadata only - pairs and the full token registry. No live context. |
| [`outcomeMeta`](/api-reference/hyperliquid-info/outcome-meta) | `{"type": "outcomeMeta"}` | Active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and `sideSpecs` (`Yes` / `No`). |
| [`settledOutcome`](/api-reference/hyperliquid-info/settled-outcome) | `{"type": "settledOutcome", "outcome": 1}` | Resolution data for a settled HIP-4 outcome - the original `spec`, `settleFraction` paid to `Yes`, and `details` describing how the outcome resolved. |
| [`l2Book`](/api-reference/hyperliquid-info/l2-book) | `{"type": "l2Book", "coin": "BTC"}` | Aggregated Level-2 order book snapshot for one coin - bids and asks as `{px, sz, n}` levels. |
| [`candleSnapshot`](/api-reference/hyperliquid-info/candle-snapshot) | `{"type": "candleSnapshot", "req": {"coin": "BTC", "interval": "1h", "startTime": …}}` | Historical OHLCV candles for a coin and interval over a time window. |
| [`fundingHistory`](/api-reference/hyperliquid-info/funding-history) | `{"type": "fundingHistory", "coin": "BTC", "startTime": …}` | Market-wide historical funding rates and premiums for a coin over a time window. |
| [`perpDexs`](/api-reference/hyperliquid-info/perp-dexs) | `{"type": "perpDexs"}` | List of HIP-3 builder-deployed perp DEXes (index `0` = canonical Hyperliquid; each entry has `name`, `full_name`, `deployer`, `oracle_updater`). |

### 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`). |
| [`activeAssetData`](/api-reference/hyperliquid-info/active-asset-data) | `{"type": "activeAssetData", "user": "0x…", "coin": "ETH"}` | Per-user, per-asset trading state: leverage, directional max trade sizes, available-to-trade amounts, and mark price. |
| [`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. |
| [`webData2`](/api-reference/hyperliquid-info/web-data2) | `{"type": "webData2", "user": "0x…"}` | Composite frontend snapshot for a wallet - `clearinghouseState`, `openOrders`, perp `meta`/`assetCtxs`, `spotAssetCtxs`, TWAP and vault state in a single round-trip. |

### 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`. |
| [`userTwapSliceFillsByTime`](/api-reference/hyperliquid-info/user-twap-slice-fills-by-time) | `{"type": "userTwapSliceFillsByTime", "user": "0x…", "startTime": …}` | TWAP slice fills bounded by a time window. Served from GoldRush's historical store so windows extend past upstream's 10,000-fill retention. |
| [`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). |

### Builder activity

| Type | Body | Returns |
|---|---|---|
| [`builderFills`](/api-reference/hyperliquid-info/builder-fills) | `{"type": "builderFills", "builder": "0x…"}` | Most recent fills attributed to a builder address (up to 2,000). **GoldRush-native**, no upstream equivalent. |
| [`builderFillsByTime`](/api-reference/hyperliquid-info/builder-fills-by-time) | `{"type": "builderFillsByTime", "builder": "0x…", "startTime": …}` | Builder-attributed fills bounded by a time window. **GoldRush-native**, no upstream equivalent. |

### 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.

## 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. |
| `429` | n/a | **Not returned.** GoldRush has no per-IP rate limit on `/info` - any retry logic you carried over from `api.hyperliquid.xyz` can stay in place but won't fire. |
| `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`](https://github.com/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`](https://github.com/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, low-latency data infrastructure for Hyperliquid - the indexer and API provider behind a drop-in `/info` API replacement with no rate limits, real-time order book and wallet streams for HIP-3 and HIP-4 markets, warehouse delivery via Pipeline API, and full HyperEVM coverage.
```

**Content:**

GoldRush is the **complete, low-latency data layer for Hyperliquid** - the indexer and data provider that aggregates everything you need to build on Hyperliquid - HyperCore, HIP-3, HIP-4, and HyperEVM - under one API key.

> **Note:** **Hyperliquid - HyperCore historical coverage starts at block `606,858,021` (`2025-05-25T14:32:53Z`).**

Every data type (fill, order, trade, funding, and ledger event) from that block onward is retained and queryable.


### 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 the GoldRush API key, and your existing clients work unchanged - with no rate limits and no per-IP subscription caps.

> **Note:** **Auth differs between REST and WebSocket.** REST takes an `Authorization: Bearer ` header. The WebSocket takes a `?key=` query parameter (most WebSocket clients can't send headers during the upgrade handshake). Same key for both.


### 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), the GoldRush-native `l2BookDiff` (snapshot plus per-block diffs of changed `{px, sz, n}` levels - accepts a single coin, a list, or wildcard), or 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

GoldRush runs its own Hyperliquid indexing infrastructure - purpose-built to be the fastest, most reliable Hyperliquid data provider for production apps and quant desks:

- **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 `606,858,021` (`2025-05-25T14:32:53Z`). 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: Four 5-minute paths to get Hyperliquid data with GoldRush - drop-in Info API, real-time wallet streams, warehouse delivery, and batched account state.
```

**Content:**

Pick the path that matches what you're building. All four use the same GoldRush API key.

## Prerequisites

A GoldRush API key. Sign up at [goldrush.dev/platform](https://goldrush.dev/platform/auth/register/), or apply to the Early Builders Program for free credits.

### 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)

### Early Builders

Pre-revenue? Up to 1M credits over 12 months, free.

[Read more](/goldrush-hyperliquid/early-builders-program)

---

## 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


### WebSocket API

Drop-in `wss://` replacement with `l2Book`, `l2BookDiff`, and the GoldRush-native `l4Book` order-level stream. No per-IP subscription cap.

[Read more](/goldrush-hyperliquid/websocket-api/overview)


### 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)


### Live analytics

HIP-3 Market Screener, Liquidation Cascade Map, Market Health Score.

[Read more](/goldrush-hyperliquid/analytics-app)

---

## 9. 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.

## 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.

---

## 10. 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.

---

## 11. 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 **606,858,021** (2025-05-25T14:32:53Z). 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.

---

## 12. Track Every Hyperliquid Wallet: the Wallet Firehose

**Path:** goldrush-hyperliquid/streaming/wallet-firehose

**Metadata:**
```yaml
title: Track Every Hyperliquid Wallet: the Wallet Firehose
sidebarTitle: Wallet Firehose
description: Hyperliquid has no public leaderboard or all-users API. GoldRush surfaces every active trader instead - stream fills from every wallet on HyperCore, then follow any set of addresses in one connection with zero rate limits. 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.

## No public "all users" or leaderboard endpoint

Hyperliquid's public `/info` API has no endpoint that lists every user, and the leaderboard you see in the frontend is backed by an internal endpoint that isn't part of the documented API - so there's no supported way to enumerate or scrape all addresses upstream. GoldRush gives you two supported paths instead:

- **Discover active traders in real time.** The [`allFills`](/api-reference/hyperliquid-websocket/all-fills) channel streams every fill on HyperCore across every wallet - each entry carries the trader's address, so the live tape doubles as a rolling census of who is active right now. [`liquidationFills`](/api-reference/hyperliquid-websocket/liquidation-fills) does the same for every liquidation.
- **Follow a cohort at scale.** Once you have a set of addresses (top traders, whales, a copy-trade list), the `walletTxs` firehose below streams all of their activity over a single connection with no per-IP or per-address limit - something the public 1000-subscription cap makes impossible.

For bulk historical address data - every fill and ledger event for a large wallet set landed in your own warehouse - use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore).

## 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.

## Production considerations

The happy-path example above is enough to prototype. Three things to add before shipping:

- **Reconnect on close or error.** The `complete` callback fires on a clean stream close; `error` fires on transport errors. In both cases, re-invoke the subscribe function with backoff so the firehose self-heals after network blips:

```typescript TypeScript
function subscribe() {
  client.StreamingService.rawQuery(
    SUBSCRIPTION_QUERY,
    {},
    {
      next: (data) => handleEvent(data),
      error: (err) => { console.error(err); setTimeout(subscribe, 1000); },
      complete: () => setTimeout(subscribe, 1000),
    },
  );
}

subscribe();
```

- **Validate addresses up front.** Malformed wallet addresses can surface via `error` and tear down the whole subscription. Pre-filter the input list with `/^0x[a-fA-F0-9]{40}$/` (or your library's validator) before passing it in.
- **No gap-fill on reconnect.** The subscription delivers events from the moment it opens - events that occurred during a disconnect are not replayed. For continuity across the gap, query [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) over the disconnect window after reconnecting.

## 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.

---

## 13. Build with the L2 Order Book Diff

**Path:** goldrush-hyperliquid/websocket-api/l2-book-diff

**Metadata:**
```yaml
title: Build with the L2 Order Book Diff
sidebarTitle: Scalable Depth Tracking (L2 Order Book Diff)
description: Build cross-asset depth dashboards, market scanners, and arbitrage engines that track live aggregated book state across one coin, a fixed list, or every Hyperliquid asset on a single subscription - with bandwidth proportional to what changed each block, not the size of the book.
```

**Content:**

The `l2BookDiff` 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 emits one `Snapshot` per subscribed coin, then per-block `Updates` carrying only the price levels that changed. The shape per level is the same `{px, sz, n}` you already get from `l2Book`, so book-state code only needs to learn how to apply diffs - and `coin` accepts a single asset, a list, or can be omitted to stream every asset on one subscription. For the raw subscription shape see the [`l2BookDiff` reference](/api-reference/hyperliquid-websocket/l2-book-diff); for the connection model see the [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview).

## What you get

- **Snapshot + diff transport.** One full `Snapshot` per subscribed coin on subscribe, then per-block `Updates` containing only the levels that changed. Apply diffs to local state.
- **Aggregated `{px, sz, n}` shape.** Identical to `l2Book` levels - reuse your existing aggregated-book types and just add a level-apply function.
- **Multi-coin / wildcard friendly.** `coin` accepts a single asset, an array of assets, or can be omitted to stream every asset on one subscription. When `coin` is omitted, `marketTypes` defaults to `["perp"]` - pass `["spot"]`, `["outcome"]`, a mix, or `["*"]` to opt into spot, outcome, and future market types. `l4Book` is one-coin-per-subscription; `l2Book` requires per-asset fan-out on the public feed.
- **Bandwidth proportional to change.** Quiet markets cost almost nothing; only the levels that actually moved arrive over the wire, instead of a full re-snapshot every tick.
- **GoldRush-exclusive.** Public Hyperliquid has no L2-diff transport - `l2Book` is full-snapshot only.

## Subscribe and maintain book state

The pattern below keeps a `Map, asks: Map }>`. Each `Snapshot` seeds the per-coin entry; each `book_diff` inside `Updates` either deletes a level (when `sz === "0"`) or replaces it with the new `{sz, n}`.

```typescript TypeScript
import WebSocket from "ws";

type Level = { px: string; sz: string; n: number };
type Side = Map;
type Book = { bids: Side; asks: Side };

const books = new Map();

function applyLevels(side: Side, levels: Level[]) {
  for (const lvl of levels) {
    if (lvl.sz === "0") side.delete(lvl.px);
    else side.set(lvl.px, lvl);
  }
}

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: "l2BookDiff", coin: "HYPE" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "l2BookDiff") return;

  if (msg.data.Snapshot) {
    const { coin, levels: [bids, asks] } = msg.data.Snapshot;
    const book: Book = { bids: new Map(), asks: new Map() };
    for (const l of bids) book.bids.set(l.px, l);
    for (const l of asks) book.asks.set(l.px, l);
    books.set(coin, book);
    return;
  }

  if (msg.data.Updates) {
    for (const diff of msg.data.Updates.book_diffs) {
      const book = books.get(diff.coin);
      if (!book) continue;
      const [bidLevels, askLevels] = diff.levels;
      applyLevels(book.bids, bidLevels);
      applyLevels(book.asks, askLevels);
    }
  }
});
```

```python Python
import asyncio, json, os
import websockets

books: dict[str, dict] = {}

def apply_levels(side: dict, levels: list[dict]) -> None:
    for lvl in levels:
        if lvl["sz"] == "0":
            side.pop(lvl["px"], None)
        else:
            side[lvl["px"]] = lvl

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": "l2BookDiff", "coin": "HYPE"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l2BookDiff":
                continue
            data = msg["data"]

            if "Snapshot" in data:
                snap = data["Snapshot"]
                bids, asks = snap["levels"]
                books[snap["coin"]] = {
                    "bids": {l["px"]: l for l in bids},
                    "asks": {l["px"]: l for l in asks},
                }
                continue

            if "Updates" in data:
                for diff in data["Updates"]["book_diffs"]:
                    book = books.get(diff["coin"])
                    if not book:
                        continue
                    bid_levels, ask_levels = diff["levels"]
                    apply_levels(book["bids"], bid_levels)
                    apply_levels(book["asks"], ask_levels)

asyncio.run(main())
```

## Patterns

### Single coin, list, or wildcard

All three subscription shapes share the same handler - only the payload sent at `subscribe` time changes. Use whichever matches your coverage requirements.

```typescript TypeScript
// Single coin
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: { type: "l2BookDiff", coin: "HYPE" },
}));

// Fixed list of coins
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: { type: "l2BookDiff", coin: ["HYPE", "BTC", "ETH"] },
}));

// Every perp asset on one subscription (perps is the default when coin is omitted)
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: { type: "l2BookDiff" },
}));

// Spot only, or any mix; pass ["*"] for perps + spot + outcomes plus auto-opt-in to future types
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: { type: "l2BookDiff", marketTypes: ["spot"] },
}));
ws.send(JSON.stringify({
  method: "subscribe",
  subscription: { type: "l2BookDiff", marketTypes: ["*"] },
}));
```

A list or wildcard subscription receives one `Snapshot` per live coin before diffs begin, so the `books` map fills in over the first few messages rather than all at once. `marketTypes` is only valid when `coin` is omitted; it defaults to `["perp"]`, so spot and outcome markets require explicit opt-in. A second `subscribe` with a different `marketTypes` value replaces the previous filter rather than coexisting with it.

### Reconstruct a top-of-book stream

After each diff is applied, the best bid is the highest `px` in `book.bids` and the best ask is the lowest `px` in `book.asks`. Emit only when the top level changes to avoid noise.

```typescript TypeScript
function bestLevels(book: Book) {
  let bestBid: string | null = null;
  for (const px of book.bids.keys()) if (!bestBid || Number(px) > Number(bestBid)) bestBid = px;
  let bestAsk: string | null = null;
  for (const px of book.asks.keys()) if (!bestAsk || Number(px)  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "l2BookDiff", coin: "HYPE" },
  })));
  ws.on("close", () => {
    books.clear();
    setTimeout(connect, 1000);
  });
  return ws;
}
```

## Related

- [`l2BookDiff` API reference](/api-reference/hyperliquid-websocket/l2-book-diff) - full subscription, snapshot, and update schema.
- [`l2Book` reference](/api-reference/hyperliquid-websocket/l2-book) - full-snapshot transport when diff replay isn't desirable.
- [`l4Book` reference](/api-reference/hyperliquid-websocket/l4-book) - order-level stream with `user`, `oid`, `cloid`, `tif`, and trigger metadata.
- [WebSocket API overview](/goldrush-hyperliquid/websocket-api/overview) - endpoint URL, auth, and limits.

---

## 14. Build with the L2 Order Book

**Path:** goldrush-hyperliquid/websocket-api/l2-book

**Metadata:**
```yaml
title: Build with the L2 Order Book
sidebarTitle: L2 Order Book
description: The Hyperliquid L2 order book over WebSocket - build top-of-book quote feeds, depth-weighted mid prices, slippage and market-impact estimators, and liquidity heatmaps from self-contained L2 snapshots, 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-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. The wildcard defaults to perps only (`marketTypes: ["perp"]`); pass `["spot"]`, `["outcome"]`, a mix, or `["*"]` to opt into spot, outcome, and future market types.

## 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-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-book

**Metadata:**
```yaml
title: Build with the L4 Order Book
sidebarTitle: Detailed Trader Flows (L4 Order Book)
description: Build per-trader flow attribution, queue-position estimators, smart-money trackers, and microstructure analytics from individual Hyperliquid orders - with `user`, `oid`, `cloid`, `tif`, and trigger metadata exposed on every resting order.
```

**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 and price-time priority, 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-book); 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-book) - full subscription, snapshot, and update schema.
- [`l2Book` reference](/api-reference/hyperliquid-websocket/l2-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. Hyperliquid WebSocket Rate Limits & Connection Limits

**Path:** goldrush-hyperliquid/websocket-api/limits

**Metadata:**
```yaml
title: Hyperliquid WebSocket Rate Limits & Connection Limits
sidebarTitle: Rate Limits & Connections
description: The public Hyperliquid WebSocket caps subscriptions at 1000 per IP. The GoldRush Hyperliquid WebSocket API removes that limit and adds wildcard subscriptions - stream every asset on one connection.
```

**Content:**

## Hyperliquid WebSocket rate limits

The **public Hyperliquid WebSocket** (`wss://api.hyperliquid.xyz/ws`) caps each IP at **1000 active subscriptions**, and most channels require one subscription per asset - so tracking the full market means fanning out hundreds of subscriptions and risking the cap.

**The GoldRush Hyperliquid WebSocket API removes that cap.** It's a [drop-in replacement](/goldrush-hyperliquid/websocket-api/migration) with **no per-IP, per-key, or per-connection subscription limit**, plus [wildcard subscriptions](#wildcard-subscriptions) that stream an entire channel over a single subscription.

## No subscription cap

With no subscription limit, 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: The Hyperliquid order book API over WebSocket - stream real-time L2 and L4 order book data for every asset on one connection, plus live wallet fills, with no per-IP subscription cap. A drop-in replacement for the public Hyperliquid WebSocket on `hypercore.goldrushdata.com`.
```

**Content:**

The GoldRush Hyperliquid WebSocket API is a **drop-in replacement** for `wss://api.hyperliquid.xyz/ws`. For the [channels GoldRush supports](#available-subscriptions), 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

### Order book

Stream the Hyperliquid order book in real time - three channels, from aggregated L2 snapshots to full order-level (L4) detail. Omit `coin` on `l2Book` or `l2BookDiff` to stream **every asset on a single subscription**, which the public WebSocket's 1000-subscription-per-IP cap makes impractical.

| Channel | Subscription body | Returns |
|---|---|---|
| [`l2Book`](/api-reference/hyperliquid-websocket/l2-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. |
| [`l2BookDiff`](/api-reference/hyperliquid-websocket/l2-book-diff) | `{"type": "l2BookDiff", "coin": "HYPE"}` | GoldRush-native L2 diff transport - initial `Snapshot` per coin plus per-block `Updates` carrying only changed `{px, sz, n}` levels. `coin` accepts a single asset, an array of assets, or can be omitted to stream every asset. Not available on the public Hyperliquid WebSocket. |
| [`l4Book`](/api-reference/hyperliquid-websocket/l4-book) | `{"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. |

### Wallet activity

| Channel | Subscription body | Returns |
|---|---|---|
| [`userFills`](/api-reference/hyperliquid-websocket/user-fills) | `{"type": "userFills", "addresses": ["0x…"]}` | Live trade fills for one or more wallets, batched per block as `[address, fill]` tuples. Aliases `user` / `users` also accepted. |
| [`orderUpdates`](/api-reference/hyperliquid-websocket/order-updates) | `{"type": "orderUpdates", "addresses": ["0x…"]}` | Live order lifecycle events (placements, fills, cancels, rejections) for one or more wallets, batched per block as an `updates` array of objects, each tagged with the originating `user`. Aliases `user` / `users` also accepted. |
| [`liquidationFills`](/api-reference/hyperliquid-websocket/liquidation-fills) | `{"type": "liquidationFills"}` | Global stream of every liquidation fill on HyperCore. Same shape as `userFills` with a non-null `liquidation` object on every entry. **GoldRush-native**, no upstream equivalent. |
| [`allFills`](/api-reference/hyperliquid-websocket/all-fills) | `{"type": "allFills"}` | Global stream of every fill on HyperCore. Optional `coin` filter narrows to a single market. Same per-fill shape as `userFills`. **GoldRush-native**, no upstream equivalent. |
| [`builderFills`](/api-reference/hyperliquid-websocket/builder-fills) | `{"type": "builderFills", "builder": "0x…"}` | Live attributed fills for one or more builder addresses, with `builder` and `builderFee` on every entry. Accepts `builder` (single) or `addresses` (array). **GoldRush-native**, no upstream equivalent. |
| [`userNonFundingLedgerUpdates`](/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates) | `{"type": "userNonFundingLedgerUpdates", "addresses": ["0x…"]}` | Live non-funding ledger events (deposits, withdrawals, transfers, liquidations, vault actions, staking, rewards) for one or more wallets. |

> **Note:** **Looking for `candle`, `trades`, `bbo`, or `allMids`?** These public Hyperliquid market-data channels aren't mirrored on the GoldRush WebSocket - use the GoldRush equivalents instead:

  - **OHLCV candles** - the Info API [`candleSnapshot`](/api-reference/hyperliquid-info/candle-snapshot) endpoint for historical candles, or the Streaming API [OHLCV Pairs](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) / [OHLCV Tokens](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) subscriptions for real-time candles across every HIP-3/HIP-4 market.
  - **Trade tape** - [`allFills`](/api-reference/hyperliquid-websocket/all-fills) streams every fill on HyperCore (the global trade tape); [`userFills`](/api-reference/hyperliquid-websocket/user-fills) narrows it to specific wallets.
  - **Best bid/offer and mids** - derive top-of-book from [`l2Book`](/api-reference/hyperliquid-websocket/l2-book), or read mark and mid prices for the full universe from [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs).

## Limits

No 1000-subscription-per-IP cap. On `l2Book` and `l2BookDiff`, filter parameters are optional - omit `coin` to stream the full L2 book across every asset on a single subscription. The wildcard defaults to **perps only** (`marketTypes: ["perp"]`); pass `["spot"]`, `["outcome"]`, a mix, or `["*"]` to opt into spot, outcome, and future market types. `l2BookDiff` additionally accepts an array of coin symbols for a fixed multi-asset 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`](https://github.com/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`](https://github.com/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. activeAssetData | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/active-asset-data

**Metadata:**
```yaml
title: activeAssetData | Hyperliquid Info API
keywords: ["activeAssetData","Hyperliquid activeAssetData","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: activeAssetData
description: Hyperliquid activeAssetData: fetch a user's active trading limits, leverage setting, available size, and mark price for a single Hyperliquid perpetual asset.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "activeAssetData"` is used to fetch a user's active trading limits, leverage setting, available size, and mark price for a single Hyperliquid perpetual asset.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Factive-asset-data).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "activeAssetData", "user": "...", "coin": "ETH"}`.
- `coin` accepts the Hyperliquid asset identifier for the target perp market. For HIP-3 markets, pass the same dex-qualified coin string used by Hyperliquid for that asset.
- `maxTradeSzs` and `availableToTrade` are returned as two directional decimal-string values. Preserve the upstream array order and use fixed-precision decimal handling.
- For whole-account position and margin state, use `clearinghouseState`; this endpoint is scoped to one user and one active asset.

Returns per-user, per-asset trading state for one active perpetual market: the user's leverage setting, directional max trade sizes, directional available-to-trade amounts, and the current mark price.

User-keyed and coin-keyed. Use this when a trading UI needs to show how much size a wallet can open or close on a specific asset before placing an order. For full account margin and open positions, use [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state); for market metadata and asset context, use [metaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs).

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"activeAssetData"`. |
| `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). |
| `coin` | `string` | Yes | The perp asset identifier, e.g. `"ETH"` or `"APT"`. For HIP-3 markets, pass the same dex-qualified coin string used by Hyperliquid for that asset. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "activeAssetData",
    "user": "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb",
    "coin": "APT"
  }'
```

```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: "activeAssetData",
    user: "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb",
    coin: "APT",
  }),
});

const activeAsset = 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": "activeAssetData",
        "user": "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb",
        "coin": "APT",
    },
)

active_asset = response.json()
```

## Response

A single JSON object with the user's active trading configuration and directional trading capacity for the requested asset.

```json
{
  "user": "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb",
  "coin": "APT",
  "leverage": {
    "type": "cross",
    "value": 3
  },
  "maxTradeSzs": ["24836370.4400000013", "24836370.4400000013"],
  "availableToTrade": ["37019438.0284740031", "37019438.0284740031"],
  "markPx": "4.4716"
}
```

### Field descriptions

> **Note:** Prices, sizes, and available amounts 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 |
| --- | --- | --- |
| `user` | `string` | Wallet address the active asset data was computed for. |
| `coin` | `string` | Hyperliquid asset identifier, such as `"APT"` or `"ETH"`. |
| `leverage` | `object` | User's configured leverage for this asset. |
| `leverage.type` | `string` | Leverage mode, usually `"cross"` or `"isolated"`. |
| `leverage.value` | `int` | Configured leverage multiplier. |
| `maxTradeSzs` | `array` | Directional maximum trade sizes for this wallet and asset, returned as decimal strings. |
| `availableToTrade` | `array` | Directional available-to-trade amounts for this wallet and asset, returned as decimal strings. |
| `markPx` | `string` | Current mark price for the asset. |

{/* generated:hl-footer-start */}

## Related endpoints


### metaAndAssetCtxs

fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

[Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs)


### spotMetaAndAssetCtxs

fetch the spot universe metadata, token configuration, and live market data in a single call.

[Read more](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs)

_Last reviewed: 2026-07-08_

{/* generated:hl-footer-end */}

---

## 21. batchClearinghouseState | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/batch-clearinghouse-state

**Metadata:**
```yaml
title: batchClearinghouseState | Hyperliquid Info API
keywords: ["batchClearinghouseState","Hyperliquid batchClearinghouseState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: batchClearinghouseState
description: Hyperliquid batchClearinghouseState: fetch perpetuals account state for up to 50 wallets in a single request.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 25 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "batchClearinghouseState"` is used to fetch perpetuals account state for up to 50 wallets in a single request.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbatch-clearinghouse-state).

> **Note:** - 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.

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).

{/* generated:hl-footer-start */}

## Related endpoints


### batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state)


### clearinghouseState

fetch a single user's perpetuals account state by wallet address.

[Read more](/api-reference/hyperliquid-info/clearinghouse-state)


### spotClearinghouseState

fetch a single user's spot account balances by wallet address.

[Read more](/api-reference/hyperliquid-info/spot-clearinghouse-state)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 22. batchSpotClearinghouseState | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/batch-spot-clearinghouse-state

**Metadata:**
```yaml
title: batchSpotClearinghouseState | Hyperliquid Info API
keywords: ["batchSpotClearinghouseState","Hyperliquid batchSpotClearinghouseState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: batchSpotClearinghouseState
description: Hyperliquid batchSpotClearinghouseState: fetch spot account balances for up to 50 wallets in a single request.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 25 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "batchSpotClearinghouseState"` is used to fetch spot account balances for up to 50 wallets in a single request.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbatch-spot-clearinghouse-state).

> **Note:** - 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.

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).

{/* generated:hl-footer-start */}

## Related endpoints


### batchClearinghouseState

fetch perpetuals account state for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-clearinghouse-state)


### spotClearinghouseState

fetch a single user's spot account balances by wallet address.

[Read more](/api-reference/hyperliquid-info/spot-clearinghouse-state)


### clearinghouseState

fetch a single user's perpetuals account state by wallet address.

[Read more](/api-reference/hyperliquid-info/clearinghouse-state)


### spotMeta

fetch the spot universe metadata and full token configuration without live market context.

[Read more](/api-reference/hyperliquid-info/spot-meta)

_Last reviewed: 2026-05-21_

{/* generated:hl-footer-end */}

---

## 23. builderFillsByTime | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/builder-fills-by-time

**Metadata:**
```yaml
title: builderFillsByTime | Hyperliquid Info API
keywords: ["builderFillsByTime","Hyperliquid builderFillsByTime","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: builderFillsByTime
description: Hyperliquid builderFillsByTime: fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "builderFillsByTime"` is used to fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbuilder-fills-by-time).

> **Note:** - GoldRush-native: No `POST api.hyperliquid.xyz/info` equivalent. Available only via `POST hypercore.goldrushdata.com/info`.
- Each response contains at most 2,000 fills; widen the window in chunks or page by advancing `startTime` if you need more.
- GoldRush serves this `type` from a dedicated HyperCore historical store, so windows can extend back to GoldRush’s full HyperCore coverage.
- Use [`builderFills`](https://goldrush.dev/docs/api-reference/hyperliquid-info/builder-fills) (no `Time` suffix) when you only need the most recent N fills without specifying a window.
- For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events.

Returns fills attributed to a builder address bounded by a `[startTime, endTime]` window in milliseconds. Use this for builder revenue reports, monthly fee reconciliation, or rebuilding historical builder order-flow.

Builder-keyed. GoldRush-native as there is no upstream Hyperliquid `/info` equivalent. Served from a dedicated HyperCore historical store, so windows can extend back to GoldRush’s full HyperCore coverage.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"builderFillsByTime"`. |
| `builder` | `string` | Yes | The builder address that orders were routed through. Must be a `0x`-prefixed 42-character hex address. |
| `startTime` | `int` | Yes | Unix timestamp in milliseconds. Inclusive lower bound. Required unless `cursor` is supplied. |
| `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`. |
| `cursor` | `string` | No | Pagination cursor - a Unix timestamp in milliseconds encoded as a string. When set, returns fills strictly before this time and overrides `startTime`. Use the `time` value of the oldest fill in the previous page to fetch the next page. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "builderFillsByTime",
    "builder": "0x0000000000000000000000000000000000000000",
    "startTime": 1781000000000
  }'
```

```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: "builderFillsByTime",
    builder: "0x0000000000000000000000000000000000000000",
    startTime: 1781000000000,
  }),
});

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": "builderFillsByTime",
        "builder": "0x0000000000000000000000000000000000000000",
        "startTime": 1781000000000,
    },
)

fills = response.json()
```

## Response

An array of fill objects ordered by `time`. Each entry is a fill from an order that was routed through the builder address within the window.

```json
[
  {
    "user": "0x73f9c53a8b15e43056d5599f6488ac9a8730f85d",
    "coin": "HYPE",
    "px": "66.977",
    "sz": "0.69",
    "side": "B",
    "time": 1781518798259,
    "startPosition": "0",
    "dir": "Open Long",
    "closedPnl": "0",
    "hash": "0x2b7bd2df9499dfef2cf5043dc500b402068500c52f9cfec1cf447e32539db9d9",
    "oid": 469533808540,
    "crossed": true,
    "fee": "0.048524",
    "tid": 332575399132451,
    "feeToken": "USDC",
    "builderFee": "0.027728",
    "cloid": "0xff8ffaa775354e8faf1eaa18127d6b5e"
  }
]
```

### Field descriptions

> **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings** with full upstream precision (up to 18 decimal places). Do not parse them as floats - keep them as strings or use a fixed-precision decimal type.

| Field | Type | Description |
| --- | --- | --- |
| `user` | `string` | The trader's wallet address - the account that placed the order routed through the builder code. |
| `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`); HIP-3 markets use the deployer-prefixed form. |
| `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 the trader held on this coin immediately before this fill. |
| `dir` | `string` | Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`. |
| `closedPnl` | `string` | Realized PnL in USDC attributable to this fill for the trader (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 by the trader for this fill, denominated in `feeToken`. |
| `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. |
| `builderFee` | `string` | Optional. Builder fee earned for this fill, denominated in `feeToken`. Omitted when no builder fee was charged. |
| `cloid` | `string` | Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement. |
| `liquidation` | `object` | Optional. Present only when this fill closed a position as part of a liquidation event. |
| `liquidation.liquidatedUser` | `string` | The wallet whose position was liquidated. |
| `liquidation.markPx` | `string` | Mark price at the time of liquidation. |
| `liquidation.method` | `string` | Liquidation method - e.g. `"Market"`. |

{/* generated:hl-footer-start */}

## Related endpoints


### builderFills

fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.

[Read more](/api-reference/hyperliquid-info/builder-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### userTwapSliceFillsByTime

fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic…

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills-by-time)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 24. builderFills | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/builder-fills

**Metadata:**
```yaml
title: builderFills | Hyperliquid Info API
keywords: ["builderFills","Hyperliquid builderFills","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: builderFills
description: Hyperliquid builderFills: fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "builderFills"` is used to fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbuilder-fills).

> **Note:** - GoldRush-native: No `POST api.hyperliquid.xyz/info` equivalent. Available only via `POST hypercore.goldrushdata.com/info`.
- Each response contains at most 2,000 fills, ordered most-recent first.
- For windowed queries for revenue reports and monthly reconciliation, use [`builderFillsByTime`](https://goldrush.dev/docs/api-reference/hyperliquid-info/builder-fills-by-time).
- For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events.

Returns the 2,000 most recent fills attributed to a builder address. Use this when you operate a builder code and want to inspect the order flow routed through it without specifying a time window.

Builder-keyed. GoldRush-native so there is no upstream Hyperliquid `/info` equivalent.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"builderFills"`. |
| `builder` | `string` | Yes | The builder address that orders were routed through. Must be a `0x`-prefixed 42-character hex address. |
| `aggregateByTime` | `boolean` | No | When `true`, partial fills sharing the same timestamp are consolidated into one row. Default `false`. |
| `cursor` | `string` | No | Pagination cursor — a Unix timestamp in milliseconds encoded as a string. When set, returns fills strictly before this time. Use the `time` value of the oldest fill in the previous page to fetch the next page. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "builderFills",
    "builder": "0x0000000000000000000000000000000000000000"
  }'
```

```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: "builderFills",
    builder: "0x0000000000000000000000000000000000000000",
  }),
});

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": "builderFills",
        "builder": "0x0000000000000000000000000000000000000000",
    },
)

fills = response.json()
```

## Response

An array of fill objects ordered most-recent-first. Each entry is a fill from an order that was routed through the builder address.

```json
[
  {
    "user": "0x73f9c53a8b15e43056d5599f6488ac9a8730f85d",
    "coin": "HYPE",
    "px": "66.977",
    "sz": "0.69",
    "side": "B",
    "time": 1781518798259,
    "startPosition": "0",
    "dir": "Open Long",
    "closedPnl": "0",
    "hash": "0x2b7bd2df9499dfef2cf5043dc500b402068500c52f9cfec1cf447e32539db9d9",
    "oid": 469533808540,
    "crossed": true,
    "fee": "0.048524",
    "tid": 332575399132451,
    "feeToken": "USDC",
    "builderFee": "0.027728",
    "cloid": "0xff8ffaa775354e8faf1eaa18127d6b5e"
  }
]
```

### Field descriptions

> **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings** with full upstream precision (up to 18 decimal places). Do not parse them as floats - keep them as strings or use a fixed-precision decimal type.

| Field | Type | Description |
| --- | --- | --- |
| `user` | `string` | The trader's wallet address - the account that placed the order routed through the builder code. |
| `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`); HIP-3 markets use the deployer-prefixed form. |
| `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 the trader held on this coin immediately before this fill. |
| `dir` | `string` | Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`. |
| `closedPnl` | `string` | Realized PnL in USDC attributable to this fill for the trader (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 by the trader for this fill, denominated in `feeToken`. |
| `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. |
| `builderFee` | `string` | Optional. Builder fee earned for this fill, denominated in `feeToken`. Omitted when no builder fee was charged. |
| `cloid` | `string` | Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement. |
| `liquidation` | `object` | Optional. Present only when this fill closed a position as part of a liquidation event. |
| `liquidation.liquidatedUser` | `string` | The wallet whose position was liquidated. |
| `liquidation.markPx` | `string` | Mark price at the time of liquidation. |
| `liquidation.method` | `string` | Liquidation method - e.g. `"Market"`. |

{/* generated:hl-footer-start */}

## Related endpoints


### builderFillsByTime

fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.

[Read more](/api-reference/hyperliquid-info/builder-fills-by-time)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### userTwapSliceFills

fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 25. candleSnapshot | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/candle-snapshot

**Metadata:**
```yaml
title: candleSnapshot | Hyperliquid Info API
keywords: ["candleSnapshot","Hyperliquid candleSnapshot","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: candleSnapshot
description: Hyperliquid candleSnapshot: fetch historical OHLCV candles for a coin and interval over a time window for charting and backtesting.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "candleSnapshot"` is used to fetch historical OHLCV candles for a coin and interval over a time window for charting and backtesting.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fcandle-snapshot).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "candleSnapshot", "req": {...}}`. Note the nested `req` object.
- Each response contains at most 5,000 candles (per-response cap, not a retention limit); page by advancing `startTime` for longer ranges.
- GoldRush serves candles from a dedicated HyperCore historical store, so candles older than the upstream window can extend back to GoldRush’s full HyperCore coverage.
- For live, push-based candles, including HIP-3 and HIP-4 markets, use the [Streaming API OHLCV streams](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) instead of polling.

Returns an array of OHLCV candles for a single coin and interval, bounded by a `[startTime, endTime]` window. Each candle carries the open/close timestamps, the coin, the interval, open/high/low/close prices, base volume, and trade count. Use it for chart backfills, indicator computation, and backtests.

This is a global, non-user-keyed type. **NOT LIMITED TO THE MOST RECENT 5,000 CANDLES**. GoldRush serves it from a dedicated HyperCore historical store so candles older than the upstream window remain available; page through time by advancing `startTime`.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

The request parameters are nested inside a `req` object.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"candleSnapshot"`. |
| `req` | `object` | Yes | The candle query parameters.   The asset symbol, e.g. `"BTC"`. HIP-3 markets use the deployer-prefixed form. |
| `interval` | `string` | Yes | Candle interval. One of `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"8h"`, `"12h"`, `"1d"`, `"3d"`, `"1w"`, `"1M"`. |
| `startTime` | `int` | Yes | 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": "candleSnapshot",
    "req": {
      "coin": "BTC",
      "interval": "1h",
      "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: "candleSnapshot",
    req: {
      coin: "BTC",
      interval: "1h",
      startTime: 1735689600000,
      endTime: 1735776000000,
    },
  }),
});

const candles = 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": "candleSnapshot",
        "req": {
            "coin": "BTC",
            "interval": "1h",
            "startTime": 1735689600000,
            "endTime": 1735776000000,
        },
    },
)

candles = response.json()
```

## Response

An array of candle objects, oldest first.

```json
[
  {
    "t": 1735689600000,
    "T": 1735693199999,
    "s": "BTC",
    "i": "1h",
    "o": "62739.0",
    "c": "62960.0",
    "h": "63118.0",
    "l": "62711.0",
    "v": "921.9829",
    "n": 16396
  }
]
```

### Field descriptions

> **Note:** The price and volume fields (`o`, `c`, `h`, `l`, `v`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats.

| Field | Type | Description |
| --- | --- | --- |
| `t` | `int` | Candle open time, Unix milliseconds. |
| `T` | `int` | Candle close time, Unix milliseconds. |
| `s` | `string` | Coin symbol. |
| `i` | `string` | Candle interval - echoes the request `interval`. |
| `o` | `string` | Open price. |
| `c` | `string` | Close price. |
| `h` | `string` | High price. |
| `l` | `string` | Low price. |
| `v` | `string` | Base-asset volume over the candle. |
| `n` | `int` | Number of trades in the candle. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 26. clearinghouseState | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/clearinghouse-state

**Metadata:**
```yaml
title: clearinghouseState | Hyperliquid Info API
keywords: ["clearinghouseState","Hyperliquid clearinghouseState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: clearinghouseState
description: Hyperliquid clearinghouseState: fetch a single user's perpetuals account state by wallet address.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "clearinghouseState"` is used to fetch a single user's perpetuals account state by wallet address.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fclearinghouse-state).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "clearinghouseState", "user": "..."}`.
- For real-time push instead of polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/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. Pass `"*"` or `"ALL_DEXES"` to return state across the native dex and every HIP-3 dex in one call.
- Wildcard (`"*"` / `"ALL_DEXES"`) requests are billed at a flat `10 credits` vs. `1 credit` for a single-dex call.
- The `perpDexs` list used for wildcard fan-out is cached ~2 minutes, so a newly-deployed dex may take up to that long to appear in wildcard results.

**Note:** Wildcard (`"*"` / `"ALL_DEXES"`) requests are **billed at a flat 10 credits per call.**

## 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. |

{/* generated:hl-footer-start */}

## Related endpoints


### batchClearinghouseState

fetch perpetuals account state for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-clearinghouse-state)


### batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state)


### spotClearinghouseState

fetch a single user's spot account balances by wallet address.

[Read more](/api-reference/hyperliquid-info/spot-clearinghouse-state)

_Last reviewed: 2026-07-07_

{/* generated:hl-footer-end */}

---

## 27. delegatorHistory | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/delegator-history

**Metadata:**
```yaml
title: delegatorHistory | Hyperliquid Info API
keywords: ["delegatorHistory","Hyperliquid delegatorHistory","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: delegatorHistory
description: Hyperliquid delegatorHistory: reconstruct the sequence of HYPE staking events behind the totals shown in delegatorSummary.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "delegatorHistory"` is used to reconstruct the sequence of HYPE staking events behind the totals shown in delegatorSummary.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fdelegator-history).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorHistory", "user": "..."}`.
- For totals (delegated, undelegated, pending withdrawal sums), use [`delegatorSummary`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-summary).
- For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards).
- For real-time push of staking events, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreDelegationEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-delegation-event) entries.

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](https://goldrush.dev/docs/api-reference/hyperliquid/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. |

{/* generated:hl-footer-start */}

## Related endpoints


### delegatorRewards

fetch a user’s current HYPE staking position.

[Read more](/api-reference/hyperliquid-info/delegator-rewards)


### delegatorSummary

get a one-shot snapshot of a user's HYPE staking position for dashboards and portfolio overviews.

[Read more](/api-reference/hyperliquid-info/delegator-summary)


### fundingHistory

fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis…

[Read more](/api-reference/hyperliquid-info/funding-history)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 28. delegatorRewards | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/delegator-rewards

**Metadata:**
```yaml
title: delegatorRewards | Hyperliquid Info API
keywords: ["delegatorRewards","Hyperliquid delegatorRewards","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: delegatorRewards
description: Hyperliquid delegatorRewards: fetch a user’s current HYPE staking position.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "delegatorRewards"` is used to fetch a user’s current HYPE staking position.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fdelegator-rewards).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorSummary", "user": "..."}`.
- For the sequence of delegation events behind these totals, use [`delegatorHistory`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history).
- For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards).

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](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history) for the underlying delegate / undelegate events and [delegatorSummary](https://goldrush.dev/docs/api-reference/hyperliquid/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. |

{/* generated:hl-footer-start */}

## Related endpoints


### delegatorHistory

reconstruct the sequence of HYPE staking events behind the totals shown in delegatorSummary.

[Read more](/api-reference/hyperliquid-info/delegator-history)


### delegatorSummary

get a one-shot snapshot of a user's HYPE staking position for dashboards and portfolio overviews.

[Read more](/api-reference/hyperliquid-info/delegator-summary)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 29. delegatorSummary | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/delegator-summary

**Metadata:**
```yaml
title: delegatorSummary | Hyperliquid Info API
keywords: ["delegatorSummary","Hyperliquid delegatorSummary","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: delegatorSummary
description: Hyperliquid delegatorSummary: get a one-shot snapshot of a user's HYPE staking position for dashboards and portfolio overviews.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "delegatorSummary"` is used to get a one-shot snapshot of a user's HYPE staking position for dashboards and portfolio overviews.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fdelegator-summary).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorSummary", "user": "..."}`.
- For the sequence of delegation events behind these totals, use [`delegatorHistory`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history).
- For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards).

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](https://goldrush.dev/docs/api-reference/hyperliquid/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. |

{/* generated:hl-footer-start */}

## Related endpoints


### delegatorHistory

reconstruct the sequence of HYPE staking events behind the totals shown in delegatorSummary.

[Read more](/api-reference/hyperliquid-info/delegator-history)


### delegatorRewards

fetch a user’s current HYPE staking position.

[Read more](/api-reference/hyperliquid-info/delegator-rewards)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 30. frontendOpenOrders | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/frontend-open-orders

**Metadata:**
```yaml
title: frontendOpenOrders | Hyperliquid Info API
keywords: ["frontendOpenOrders","Hyperliquid frontendOpenOrders","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: frontendOpenOrders
description: Hyperliquid frontendOpenOrders: fetch a user's currently open orders enriched with frontend metadata.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "frontendOpenOrders"` is used to fetch a user's currently open orders enriched with frontend metadata.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Ffrontend-open-orders).

> **Note:** - 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`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream).

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). |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 31. fundingHistory | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/funding-history

**Metadata:**
```yaml
title: fundingHistory | Hyperliquid Info API
keywords: ["fundingHistory","Hyperliquid fundingHistory","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: fundingHistory
description: Hyperliquid fundingHistory: fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis strategies.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "fundingHistory"` is used to fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis strategies.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Ffunding-history).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "fundingHistory", "coin": "..."}`.
- Each response contains at most 500 entries per call.
- This is market-wide funding history for a coin. For a single wallet’s actual funding payments, use [userFunding](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-funding) instead.
- For the current funding rate alongside live market context, use [metaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs).

Returns the sequence of applied funding intervals for a single coin within a `[startTime, endTime]` window. Each entry carries the funding rate that was applied and the mark-vs-oracle premium at that time. Use it for funding-rate charts, basis/carry analytics, and historical funding P&L modeling.

This is a global, non-user-keyed type. Page through time by advancing `startTime`.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"fundingHistory"`. |
| `coin` | `string` | Yes | The asset symbol, e.g. `"BTC"`. HIP-3 markets use the deployer-prefixed form. |
| `startTime` | `int` | Yes | 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": "fundingHistory",
    "coin": "BTC",
    "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: "fundingHistory",
    coin: "BTC",
    startTime: 1735689600000,
    endTime: 1735776000000,
  }),
});

const history = 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": "fundingHistory",
        "coin": "BTC",
        "startTime": 1735689600000,
        "endTime": 1735776000000,
    },
)

history = response.json()
```

## Response

An array of funding-interval objects, oldest first.

```json
[
  {
    "coin": "BTC",
    "fundingRate": "0.0000054021",
    "premium": "-0.0004567829",
    "time": 1735693200000
  }
]
```

### Field descriptions

> **Note:** `fundingRate` and `premium` are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats.

| Field | Type | Description |
| --- | --- | --- |
| `coin` | `string` | The asset the funding interval is for - echoes the request `coin`. |
| `fundingRate` | `string` | The funding rate applied for this interval (decimal string, e.g. `"0.0000125"`). |
| `premium` | `string` | Mark-vs-oracle premium at the time the funding was computed (decimal string). |
| `time` | `int` | Unix timestamp in milliseconds when the funding interval was applied. |

{/* generated:hl-footer-start */}

## Related endpoints


### delegatorHistory

reconstruct the sequence of HYPE staking events behind the totals shown in delegatorSummary.

[Read more](/api-reference/hyperliquid-info/delegator-history)


### userFunding

fetch a user's per-coin funding payment history within a time window for funding-only P&L attribution.

[Read more](/api-reference/hyperliquid-info/user-funding)


### userNonFundingLedgerUpdates

fetch a user's non-funding USDC ledger history (deposits, withdrawals, transfers, vault flows) within a time…

[Read more](/api-reference/hyperliquid-info/user-non-funding-ledger-updates)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 32. l2Book | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/l2-book

**Metadata:**
```yaml
title: l2Book | Hyperliquid Info API
keywords: ["l2Book","Hyperliquid l2Book","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: l2Book
description: Hyperliquid l2Book: fetch an aggregated Level-2 order book snapshot for a single coin - bids and asks as price, size, and order-count levels.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "l2Book"` is used to fetch an aggregated Level-2 order book snapshot for a single coin - bids and asks as price, size, and order-count levels.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fl2-book).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "l2Book", "coin": "..."}`.
- Returns at most 20 levels per side.
- For a continuous push stream instead of polling snapshots, subscribe to the [WebSocket API `l2Book`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l2-book) channel (optional wildcard `coin`) or the GoldRush-native [`l2BookDiff`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l2-book-diff) for incremental updates.

Returns a point-in-time aggregated order book for one `coin`: two arrays of price levels (bids first, then asks), each level carrying the price, the total resting size at that price, and the number of orders comprising it. Use it for a one-shot depth snapshot, spread checks, or seeding a book before switching to a diff stream.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"l2Book"`. |
| `coin` | `string` | Yes | The asset symbol, e.g. `"BTC"`. For HIP-3 markets use the deployer-prefixed form (e.g. `"xyz:GOLD"`); for spot use the pair symbol or `@`. |
| `nSigFigs` | `int` | No | Number of significant figures to aggregate price levels to (`2`-`5`). Omit or pass `null` for full precision. |
| `mantissa` | `int` | No | Optional mantissa for price-level bucketing. Only valid when `nSigFigs` is `5`. Omit or pass `null` for the default. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "l2Book",
    "coin": "BTC"
  }'
```

```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: "l2Book",
    coin: "BTC",
  }),
});

const book = await response.json();
const [bids, asks] = book.levels;
```

```python Python
import os, requests

response = requests.post(
    "https://hypercore.goldrushdata.com/info",
    headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
    json={"type": "l2Book", "coin": "BTC"},
)

book = response.json()
bids, asks = book["levels"]
```

## Response

A single JSON object. `levels` is a two-element array: element 0 is the bid side (descending price), element 1 is the ask side (ascending price). Each level is a `{px, sz, n}` object.

```json
{
  "coin": "BTC",
  "time": 1780940795265,
  "levels": [
    [
      { "px": "63405.0", "sz": "4.43382", "n": 36 },
      { "px": "63404.0", "sz": "3.38588", "n": 44 }
    ],
    [
      { "px": "63406.0", "sz": "0.00347", "n": 3 },
      { "px": "63407.0", "sz": "0.00017", "n": 1 }
    ]
  ]
}
```

### Field descriptions

> **Note:** `px` and `sz` are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats.

| Field | Type | Description |
| --- | --- | --- |
| `coin` | `string` | The asset the book is for - echoes the request `coin`. |
| `time` | `int` | Snapshot timestamp in milliseconds since Unix epoch. |
| `levels` | `array>` | Two-element array: `levels[0]` are bids (sorted highest price first), `levels[1]` are asks (sorted lowest price first). Each side defaults to up to 20 aggregated levels. |
| `levels.px` | `string` | Price of the level. |
| `levels.sz` | `string` | Total resting size at this price. |
| `levels.n` | `int` | Number of individual orders aggregated into this level. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 33. metaAndAssetCtxs | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/meta-and-asset-ctxs

**Metadata:**
```yaml
title: metaAndAssetCtxs | Hyperliquid Info API
keywords: ["metaAndAssetCtxs","Hyperliquid metaAndAssetCtxs","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: metaAndAssetCtxs
description: Hyperliquid metaAndAssetCtxs: fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "metaAndAssetCtxs"` is used to fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fmeta-and-asset-ctxs).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "metaAndAssetCtxs"}`.
- For real-time mark-price updates, use the [Streaming API OHLCV streams](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) instead of polling.

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. |

{/* generated:hl-footer-start */}

## Related endpoints


### spotMetaAndAssetCtxs

fetch the spot universe metadata, token configuration, and live market data in a single call.

[Read more](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs)


### activeAssetData

fetch a user's active trading limits, leverage setting, available size, and mark price for a single…

[Read more](/api-reference/hyperliquid-info/active-asset-data)


### meta

fetch the perpetuals universe metadata without live market context.

[Read more](/api-reference/hyperliquid-info/meta)


### outcomeMeta

enumerate all active HIP-4 binary outcome markets on HyperCore.

[Read more](/api-reference/hyperliquid-info/outcome-meta)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 34. meta | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/meta

**Metadata:**
```yaml
title: meta | Hyperliquid Info API
keywords: ["meta","Hyperliquid meta","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: meta
description: Hyperliquid meta: fetch the perpetuals universe metadata without live market context.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "meta"` is used to fetch the perpetuals universe metadata without live market context.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fmeta).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "meta"}`.
- Use [metaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs) when you also need live per-asset mark price, funding, open interest, and day volume.
- The optional `dex` field takes a perp DEX name. It defaults to the empty string which represents the first perp DEX.
- For the spot equivalent, use [spotMeta](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-meta).

Returns the static metadata for the entire Hyperliquid perpetuals universe: every coin’s symbol, size-decimal precision, maximum leverage, and the margin-tier table it references. Unlike `metaAndAssetCtxs`, this payload carries no live market data, so it is cheap to cache and changes only when listings or margin parameters change.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"meta"`. |
| `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": "meta",
    "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: "meta",
    dex: "",
  }),
});

const meta = 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": "meta", "dex": ""},
)

meta = response.json()
```

## Response

A single JSON object describing the perp universe, the margin-tier tables it references, and the collateral token.

```json
{
  "universe": [
    { "name": "BTC", "szDecimals": 5, "maxLeverage": 40, "marginTableId": 56 },
    { "name": "ETH", "szDecimals": 4, "maxLeverage": 25, "marginTableId": 55 },
    { "name": "MATIC", "szDecimals": 1, "maxLeverage": 20, "marginTableId": 20, "isDelisted": true }
  ],
  "marginTables": [
    [
      50,
      {
        "description": "",
        "marginTiers": [
          { "lowerBound": "0.0", "maxLeverage": 50 }
        ]
      }
    ]
  ],
  "collateralToken": 0
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `universe` | `array` | Array of perp asset metadata. |
| `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.marginTableId` | `int` | Identifier of the margin-tier table in `marginTables` that governs this asset. |
| `universe.onlyIsolated` | `boolean` | If true, the asset only supports isolated margin. Omitted when false. |
| `universe.isDelisted` | `boolean` | If true, the asset has been delisted and is no longer tradeable. Omitted when false. |
| `marginTables` | `array` | Margin-tier tables, each a `[id, table]` tuple. `id` matches a `universe[].marginTableId`; `table` holds a `description` and a `marginTiers` array of `{lowerBound, maxLeverage}` steps describing how max leverage decreases as position notional grows. |
| `collateralToken` | `int` | Token index of the collateral asset backing the perp universe (USDC is `0`). |

{/* generated:hl-footer-start */}

## Related endpoints


### metaAndAssetCtxs

fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

[Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs)


### outcomeMeta

enumerate all active HIP-4 binary outcome markets on HyperCore.

[Read more](/api-reference/hyperliquid-info/outcome-meta)


### spotMeta

fetch the spot universe metadata and full token configuration without live market context.

[Read more](/api-reference/hyperliquid-info/spot-meta)


### spotMetaAndAssetCtxs

fetch the spot universe metadata, token configuration, and live market data in a single call.

[Read more](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 35. outcomeMeta | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/outcome-meta

**Metadata:**
```yaml
title: outcomeMeta | Hyperliquid Info API
keywords: ["outcomeMeta","Hyperliquid outcomeMeta","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: outcomeMeta
description: Hyperliquid outcomeMeta: enumerate all active HIP-4 binary outcome markets on HyperCore.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "outcomeMeta"` is used to enumerate all active HIP-4 binary outcome markets on HyperCore.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Foutcome-meta).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "outcomeMeta"}`.
- For real-time price updates on a discovered outcome, subscribe to [`ohlcvCandlesForPair`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) using the per-side encoding. See the [HIP-4 markets recipe](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip4-markets) for end-to-end discovery and streaming patterns.
- HIP-4 launched on Hyperliquid mainnet on May 2, 2026. Read the canonical spec: [HIP-4: Outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets).

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`, 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.  |

{/* generated:hl-footer-start */}

## Related endpoints


### meta

fetch the perpetuals universe metadata without live market context.

[Read more](/api-reference/hyperliquid-info/meta)


### metaAndAssetCtxs

fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

[Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs)


### settledOutcome

retrieve resolution details for a settled HIP-4 binary outcome market on HyperCore.

[Read more](/api-reference/hyperliquid-info/settled-outcome)


### spotMeta

fetch the spot universe metadata and full token configuration without live market context.

[Read more](/api-reference/hyperliquid-info/spot-meta)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 36. perpDexs | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/perp-dexs

**Metadata:**
```yaml
title: perpDexs | Hyperliquid Info API
keywords: ["perpDexs","Hyperliquid perpDexs","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: perpDexs
description: Hyperliquid perpDexs: enumerate every HIP-3 builder-deployed perpetual DEX on HyperCore.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "perpDexs"` is used to enumerate every HIP-3 builder-deployed perpetual DEX on HyperCore.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fperp-dexs).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "perpDexs"}`.
- The `null` at index `0` represents the canonical Hyperliquid perp DEX; use [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta) or [metaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs) with the default `dex: ""` to query its universe.
- Pass a builder DEX `name` from this list as the `dex` field on [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta) or [metaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs) to fetch a specific HIP-3 perp universe.
- `assetToStreamingOiCap` and `assetToFundingMultiplier` are `[coin, value]` tuple arrays scoped to that DEX.

Returns the full list of perpetual DEXes on HyperCore. Index `0` is `null` and represents the canonical Hyperliquid perp universe; each subsequent entry is a HIP-3 builder-deployed perp DEX, exposing its short name, full name, deployer address, oracle updater, fee recipient, per-asset streaming open-interest caps, and per-asset funding-rate multipliers.

This is a global, non-user-keyed type. A single cache entry is shared across all callers and is refreshed as new HIP-3 DEXes are deployed or their parameters change.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"perpDexs"`. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "perpDexs"
  }'
```

```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: "perpDexs",
  }),
});

const perpDexs = 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": "perpDexs"},
)

perp_dexs = response.json()
```

## Response

An array of perpetual DEX entries. Index `0` is `null` and represents the canonical Hyperliquid perp universe (query it via `meta` / `metaAndAssetCtxs` with the default empty `dex` field). Each subsequent element is a HIP-3 builder-deployed perp DEX.

```json
[
  null,
  {
    "name": "test",
    "fullName": "test dex",
    "deployer": "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152",
    "oracleUpdater": null,
    "feeRecipient": null,
    "assetToStreamingOiCap": [["COIN1", "100000.0"], ["COIN2", "200000.0"]],
    "assetToFundingMultiplier": [["COIN1", "1.0"], ["COIN2", "2.0"]]
  }
]
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `[0]` | `null` | The canonical Hyperliquid perp DEX is always represented by `null` at index 0. Use `meta` or `metaAndAssetCtxs` with the default `dex: ""` to query its universe. |
| `[1..]` | `object` | HIP-3 builder-deployed perpetual DEX. |
| `[1..].name` | `string` | Short identifier for the perp DEX. Pass this value as the `dex` field to `meta` or `metaAndAssetCtxs` to query this DEX's universe. |
| `[1..].fullName` | `string` | Human-readable name for the perp DEX. |
| `[1..].deployer` | `string` | Address of the builder that deployed the HIP-3 perp DEX. |
| `[1..].oracleUpdater` | `string | null` | Address authorized to push oracle updates for this DEX. `null` when the DEX does not delegate oracle updates. |
| `[1..].feeRecipient` | `string | null` | Address that collects fees generated by this DEX. `null` when unset. |
| `[1..].assetToStreamingOiCap` | `array` | Per-asset streaming open-interest caps, encoded as `[coin, cap]` tuples. Values are decimal strings. |
| `[1..].assetToFundingMultiplier` | `array` | Per-asset funding-rate multipliers, encoded as `[coin, multiplier]` tuples. Values are decimal strings. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-07-07_

{/* generated:hl-footer-end */}

---

## 37. settledOutcome | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/settled-outcome

**Metadata:**
```yaml
title: settledOutcome | Hyperliquid Info API
keywords: ["settledOutcome","Hyperliquid settledOutcome","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: settledOutcome
description: Hyperliquid settledOutcome: retrieve resolution details for a settled HIP-4 binary outcome market on HyperCore.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "settledOutcome"` is used to retrieve resolution details for a settled HIP-4 binary outcome market on HyperCore.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fsettled-outcome).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "settledOutcome", "outcome": }`.

Returns the on-chain settlement data for a single settled HIP-4 outcome: the integer outcome ID, the resolved side, the resolution price, and the settlement timestamp.

Use this once an outcome has resolved to confirm which side paid out and reconcile against your own books.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"settledOutcome"`. |
| `outcome` | `int` | Yes | Integer outcome ID for the settled HIP-4 market. Outcome IDs are stable across the market's lifecycle - the same ID returned by `outcomeMeta` while live is queried here once the outcome has resolved. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "settledOutcome",
    "outcome": 1
  }'
```

```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: "settledOutcome",
    outcome: 1,
  }),
});

const settlement = 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": "settledOutcome",
        "outcome": 1,
    },
)

settlement = response.json()
```

## Response

```json
{
  "spec": {
    "outcome": 1,
    "name": "Recurring",
    "description": "class:priceBinary|underlying:BTC|expiry:20260504-0600|targetPrice:78213|period:1d",
    "sideSpecs": [
      { "name": "Yes" },
      { "name": "No" }
    ],
    "quoteToken": "USDH"
  },
  "settleFraction": "1.0",
  "details": "price:79980"
}
```

For question-class outcomes (free-form markets resolved by an oracle question), the response also includes a `question` object:

```json
{
  "spec": {
    "outcome": 100,
    "name": "Fallback",
    "description": "",
    "sideSpecs": [{ "name": "Yes" }, { "name": "No" }],
    "quoteToken": "USDC"
  },
  "settleFraction": "0.0",
  "details": "",
  "question": {
    "question": {
      "settled": 19,
      "name": "May CPI year-over-year",
      "description": "The question resolves by assigning Yes to exactly one of …"
    }
  }
}
```

### Field descriptions

> **Note:** `settleFraction` is returned as a **decimal string** with full upstream precision. Do not parse it as a float - keep it as a string or use a fixed-precision decimal type.

| Field | Type | Description |
| --- | --- | --- |
| `spec` | `object` | Original market specification for the outcome - the same shape `outcomeMeta` returns while the market is live. |
| `spec.outcome` | `int` | Integer outcome ID. Echoes the request parameter. |
| `spec.name` | `string` | Human-readable label for the market - for example, `"Recurring"` for repeating price-binary markets. |
| `spec.description` | `string` | For `priceBinary` markets, a pipe-delimited spec (`class:…\|underlying:…\|expiry:…\|targetPrice:…\|period:…`). Empty string for `question`-class outcomes. |
| `spec.sideSpecs` | `array` | Tradeable sides of the outcome. For binary outcomes, index 0 is `Yes` and index 1 is `No`.  __RESPONSE_ROW__name	string	Side label - typically `"Yes"` or `"No"`. Symbol of the token the market quotes against - typically `"USDC"` or `"USDH"`. |



| Field | Type | Description |
| --- | --- | --- |
| `settleFraction` | `string` | The fraction the `Yes` side (index 0) paid out at resolution, as a decimal string. `"1.0"` means `Yes` won outright, `"0.0"` means `No` won, fractional values indicate a partial settlement. |
| `details` | `string` | Free-form resolution detail. For `priceBinary` markets, contains the resolved underlying value (e.g. `"price:79980"`). Empty string when settlement detail is carried in the `question` object instead. |
| `question` | `object` | Optional. Present only for question-class outcomes. Wraps the structured oracle question that produced the resolution. |
| `question.question` | `object` |  __RESPONSE_ROW__settled	int	Encoded settlement side (`19` is observed for `No`-resolved questions in current data). __RESPONSE_ROW__question.name	string	Short label for the question. __RESPONSE_ROW__question.description	string	Full question description, including resolution criteria and fallback rules.  |

{/* generated:hl-footer-start */}

## Related endpoints


### outcomeMeta

enumerate all active HIP-4 binary outcome markets on HyperCore.

[Read more](/api-reference/hyperliquid-info/outcome-meta)

_Last reviewed: 2026-06-19_

{/* generated:hl-footer-end */}

---

## 38. spotClearinghouseState | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/spot-clearinghouse-state

**Metadata:**
```yaml
title: spotClearinghouseState | Hyperliquid Info API
keywords: ["spotClearinghouseState","Hyperliquid spotClearinghouseState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: spotClearinghouseState
description: Hyperliquid spotClearinghouseState: fetch a single user's spot account balances by wallet address.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "spotClearinghouseState"` is used to fetch a single user's spot account balances by wallet address.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fspot-clearinghouse-state).

> **Note:** - 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`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerSpotTransfer` events.

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. |

{/* generated:hl-footer-start */}

## Related endpoints


### batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state)


### batchClearinghouseState

fetch perpetuals account state for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-clearinghouse-state)


### clearinghouseState

fetch a single user's perpetuals account state by wallet address.

[Read more](/api-reference/hyperliquid-info/clearinghouse-state)


### spotMeta

fetch the spot universe metadata and full token configuration without live market context.

[Read more](/api-reference/hyperliquid-info/spot-meta)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 39. spotMetaAndAssetCtxs | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/spot-meta-and-asset-ctxs

**Metadata:**
```yaml
title: spotMetaAndAssetCtxs | Hyperliquid Info API
keywords: ["spotMetaAndAssetCtxs","Hyperliquid spotMetaAndAssetCtxs","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: spotMetaAndAssetCtxs
description: Hyperliquid spotMetaAndAssetCtxs: fetch the spot universe metadata, token configuration, and live market data in a single call.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "spotMetaAndAssetCtxs"` is used to fetch the spot universe metadata, token configuration, and live market data in a single call.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fspot-meta-and-asset-ctxs).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotMetaAndAssetCtxs"}`.
- For perp universe + live contexts, use [`metaAndAssetCtxs`](https://goldrush.dev/docs/api-reference/hyperliquid/meta-and-asset-ctxs) instead.
- For real-time mark-price updates on a discovered spot pair, use the [Streaming API OHLCV pair stream](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream).

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`. 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. |

{/* generated:hl-footer-start */}

## Related endpoints


### metaAndAssetCtxs

fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

[Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs)


### spotMeta

fetch the spot universe metadata and full token configuration without live market context.

[Read more](/api-reference/hyperliquid-info/spot-meta)


### activeAssetData

fetch a user's active trading limits, leverage setting, available size, and mark price for a single…

[Read more](/api-reference/hyperliquid-info/active-asset-data)


### batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 40. spotMeta | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/spot-meta

**Metadata:**
```yaml
title: spotMeta | Hyperliquid Info API
keywords: ["spotMeta","Hyperliquid spotMeta","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: spotMeta
description: Hyperliquid spotMeta: fetch the spot universe metadata and full token configuration without live market context.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "spotMeta"` is used to fetch the spot universe metadata and full token configuration without live market context.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fspot-meta).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotMeta"}`.
- Use [spotMetaAndAssetCtxs](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs) when you also need live per-pair mark price, mid, and day volume.
- For the perpetuals equivalent, use [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta).

Returns the static metadata for the entire Hyperliquid spot market: the list of trading pairs (`universe`) and the full token registry (`tokens`) with each token’s decimals, on-chain identifier, and linked HyperEVM contract. Carries no live market data, so it is cheap to cache and changes only when new tokens or pairs are listed.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"spotMeta"`. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "spotMeta"
  }'
```

```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: "spotMeta",
  }),
});

const spotMeta = 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": "spotMeta"},
)

spot_meta = response.json()
```

## Response

A single JSON object with two arrays: `tokens` (the token registry) and `universe` (the tradeable pairs that reference those tokens by index).

```json
{
  "tokens": [
    {
      "name": "USDC",
      "szDecimals": 8,
      "weiDecimals": 8,
      "index": 0,
      "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054",
      "isCanonical": true,
      "evmContract": {
        "address": "0x6b9e773128f453f5c2c60935ee2de2cbc5390a24",
        "evm_extra_wei_decimals": -2
      },
      "fullName": null,
      "deployerTradingFeeShare": "0.0"
    },
    {
      "name": "PURR",
      "szDecimals": 0,
      "weiDecimals": 5,
      "index": 1,
      "tokenId": "0xc1fb593aeffbeb02f85e0308e9956a90",
      "isCanonical": true,
      "evmContract": null,
      "fullName": null,
      "deployerTradingFeeShare": "0.0"
    }
  ],
  "universe": [
    { "tokens": [1, 0], "name": "PURR/USDC", "index": 0, "isCanonical": true }
  ]
}
```

### `tokens[]`

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Token symbol - e.g. `"USDC"`, `"PURR"`. |
| `szDecimals` | `int` | Number of decimals used for order size precision. |
| `weiDecimals` | `int` | Number of decimals in the token's native wei representation. |
| `index` | `int` | Token index. `universe[].tokens` references tokens by this value. |
| `tokenId` | `string` | Hyperliquid on-chain token identifier. |
| `isCanonical` | `boolean` | Whether the token is a canonical (core) Hyperliquid token. |
| `evmContract` | `object | null` | Linked HyperEVM contract, or `null` if the token is not bridged. Carries `address` and `evm_extra_wei_decimals` (the wei-decimal offset between the spot token and its EVM representation). |
| `fullName` | `string | null` | Human-readable token name, or `null` when not set. |
| `deployerTradingFeeShare` | `string` | Share of trading fees routed to the token deployer (decimal string). |

### `universe[]`

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pair symbol - e.g. `"PURR/USDC"`. Non-canonical pairs use the `@` form (e.g. `"@1"`). |
| `tokens` | `array` | Two-element `[base, quote]` array of token indices into `tokens`. |
| `index` | `int` | Pair index. Used as the spot asset identifier in other endpoints and streams. |
| `isCanonical` | `boolean` | Whether the pair is a canonical Hyperliquid market. |

{/* generated:hl-footer-start */}

## Related endpoints


### spotMetaAndAssetCtxs

fetch the spot universe metadata, token configuration, and live market data in a single call.

[Read more](/api-reference/hyperliquid-info/spot-meta-and-asset-ctxs)


### batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

[Read more](/api-reference/hyperliquid-info/batch-spot-clearinghouse-state)


### meta

fetch the perpetuals universe metadata without live market context.

[Read more](/api-reference/hyperliquid-info/meta)


### metaAndAssetCtxs

fetch the full Hyperliquid perpetuals market universe with live per-asset trading context.

[Read more](/api-reference/hyperliquid-info/meta-and-asset-ctxs)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 41. subAccounts | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/sub-accounts

**Metadata:**
```yaml
title: subAccounts | Hyperliquid Info API
keywords: ["subAccounts","Hyperliquid subAccounts","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: subAccounts
description: Hyperliquid subAccounts: fetch a master wallet's sub-accounts along with their full perp and spot state in a single call.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "subAccounts"` is used to fetch a master wallet's sub-accounts along with their full perp and spot state in a single call.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fsub-accounts).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "subAccounts", "user": "..."}`.
- For per-sub-account real-time updates, subscribe to [`walletTxs`](https://goldrush.dev/docs/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`](https://goldrush.dev/docs/api-reference/hyperliquid/batch-clearinghouse-state) and [`batchSpotClearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid/batch-spot-clearinghouse-state).

Returns the sub-accounts owned by a master wallet, with each sub-account’s perp [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid/clearinghouse-state) and spot [spotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid/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. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 42. userFillsByTime | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-fills-by-time

**Metadata:**
```yaml
title: userFillsByTime | Hyperliquid Info API
keywords: ["userFillsByTime","Hyperliquid userFillsByTime","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userFillsByTime
description: Hyperliquid userFillsByTime: fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userFillsByTime"` is used to fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-fills-by-time).

> **Note:** - 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 or page by advancing `startTime` if you need more.
- GoldRush serves this `type` from a dedicated HyperCore historical store, so windows older than upstream Hyperliquid’s 10,000-fill retention are still fulfilled.
- For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/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.

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**; page by advancing `startTime`. **NOT LIMITED TO THE 10,000 MOST RECENT FILLS.** GoldRush serves this `type` from a dedicated HyperCore historical store so windows extending past the upstream retention limit are fulfilled from GoldRush data rather than 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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userTwapSliceFillsByTime

fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic…

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills-by-time)


### builderFillsByTime

fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.

[Read more](/api-reference/hyperliquid-info/builder-fills-by-time)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userTwapSliceFills

fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 43. userFills | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-fills

**Metadata:**
```yaml
title: userFills | Hyperliquid Info API
keywords: ["userFills","Hyperliquid userFills","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userFills
description: Hyperliquid userFills: fetch a user's most recent trade fills without specifying a time window.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userFills"` is used to fetch a user's most recent trade fills without specifying a time window.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-fills).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFills", "user": "..."}`.
- Each response contains at most 2,000 fills.
- For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events.

Returns the most recent fills for a user, up to 2,000. Use this when you need the latest trade activity without specifying a time window.

User-keyed. The upstream Hyperliquid API caps each response at **2,000 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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### userTwapSliceFills

fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills)


### userTwapSliceFillsByTime

fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic…

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills-by-time)


### builderFills

fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.

[Read more](/api-reference/hyperliquid-info/builder-fills)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 44. userFunding | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-funding

**Metadata:**
```yaml
title: userFunding | Hyperliquid Info API
keywords: ["userFunding","Hyperliquid userFunding","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userFunding
description: Hyperliquid userFunding: fetch a user's per-coin funding payment history within a time window for funding-only P&L attribution.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userFunding"` is used to fetch a user's per-coin funding payment history within a time window for funding-only P&L attribution.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-funding).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFunding", "user": "..."}`.
- For real-time push, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreFundingEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-funding-event) entries.
- Use [`userNonFundingLedgerUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid/user-non-funding-ledger-updates) for deposits, withdrawals, transfers, vault flows, liquidations, and other balance-moving events.

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](https://goldrush.dev/docs/api-reference/hyperliquid/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`. |

{/* generated:hl-footer-start */}

## Related endpoints


### userNonFundingLedgerUpdates

fetch a user's non-funding USDC ledger history (deposits, withdrawals, transfers, vault flows) within a time…

[Read more](/api-reference/hyperliquid-info/user-non-funding-ledger-updates)


### fundingHistory

fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis…

[Read more](/api-reference/hyperliquid-info/funding-history)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 45. userNonFundingLedgerUpdates | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-non-funding-ledger-updates

**Metadata:**
```yaml
title: userNonFundingLedgerUpdates | Hyperliquid Info API
keywords: ["userNonFundingLedgerUpdates","Hyperliquid userNonFundingLedgerUpdates","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userNonFundingLedgerUpdates
description: Hyperliquid userNonFundingLedgerUpdates: fetch a user's non-funding USDC ledger history (deposits, withdrawals, transfers, vault flows) within a time window.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userNonFundingLedgerUpdates"` is used to fetch a user's non-funding USDC ledger history (deposits, withdrawals, transfers, vault flows) within a time window.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-non-funding-ledger-updates).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userNonFundingLedgerUpdates", "user": "..."}`.
- Funding payments are not included here - use [`userFunding`](https://goldrush.dev/docs/api-reference/hyperliquid/user-funding).
- For real-time push of the same events, subscribe to [`walletTxs`](https://goldrush.dev/docs/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.

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, 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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userFunding

fetch a user's per-coin funding payment history within a time window for funding-only P&L attribution.

[Read more](/api-reference/hyperliquid-info/user-funding)


### fundingHistory

fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis…

[Read more](/api-reference/hyperliquid-info/funding-history)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)

_Last reviewed: 2026-06-17_

{/* generated:hl-footer-end */}

---

## 46. userTwapSliceFillsByTime | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-twap-slice-fills-by-time

**Metadata:**
```yaml
title: userTwapSliceFillsByTime | Hyperliquid Info API
keywords: ["userTwapSliceFillsByTime","Hyperliquid userTwapSliceFillsByTime","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userTwapSliceFillsByTime
description: Hyperliquid userTwapSliceFillsByTime: fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic orders.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userTwapSliceFillsByTime"` is used to fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic orders.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-twap-slice-fills-by-time).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userTwapSliceFillsByTime", "user": "...", "startTime": ...}`.
- Each response contains at most 2,000 slice fills; widen the window in chunks or page by advancing `startTime` if you need more.
- GoldRush serves this `type` from a dedicated HyperCore historical store, so windows older than upstream Hyperliquid’s 10,000-fill retention are still fulfilled.
- TWAP slice fills have a `hash` of all zeros - use that, or the presence of `twapId`, to distinguish them from regular fills.
- Use [`userTwapSliceFills`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-twap-slice-fills) (no `ByTime` suffix) when you only need the most recent N slice fills without specifying a window.

Returns a single user's TWAP slice fills bounded by a `[startTime, endTime)` window in milliseconds. Each entry is a `{fill, twapId}` pair, where `twapId` ties the slice back to its parent TWAP order. Use this when you want execution-quality data for TWAP orders within a specific window - daily slice recaps, post-deploy backfills, or reconciling realized TWAP execution against benchmarks.

User-keyed. The upstream Hyperliquid API caps each response at **2,000 slice fills**; page by advancing `startTime`. **NOT LIMITED TO THE 10,000 MOST RECENT FILLS.** GoldRush serves this `type` from a dedicated HyperCore historical store so windows extending past the upstream retention limit are fulfilled from GoldRush data rather than truncated.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"userTwapSliceFillsByTime"`. |
| `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. Exclusive 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": "userTwapSliceFillsByTime",
    "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: "userTwapSliceFillsByTime",
    user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    startTime: 1735689600000,
  }),
});

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": "userTwapSliceFillsByTime",
        "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "startTime": 1735689600000,
    },
)

slices = response.json()
```

## Response

An array of TWAP slice fill objects ordered by `time`.

```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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userTwapSliceFills

fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### builderFillsByTime

fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.

[Read more](/api-reference/hyperliquid-info/builder-fills-by-time)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)

_Last reviewed: 2026-06-19_

{/* generated:hl-footer-end */}

---

## 47. userTwapSliceFills | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-twap-slice-fills

**Metadata:**
```yaml
title: userTwapSliceFills | Hyperliquid Info API
keywords: ["userTwapSliceFills","Hyperliquid userTwapSliceFills","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userTwapSliceFills
description: Hyperliquid userTwapSliceFills: fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userTwapSliceFills"` is used to fetch a user's most recent TWAP slice fills for execution-quality analytics on algorithmic orders.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-twap-slice-fills).

> **Note:** - 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`](https://goldrush.dev/docs/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.

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](https://goldrush.dev/docs/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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userTwapSliceFillsByTime

fetch a user's TWAP slice fills within a time window for execution-quality reconciliation on algorithmic…

[Read more](/api-reference/hyperliquid-info/user-twap-slice-fills-by-time)


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### builderFills

fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.

[Read more](/api-reference/hyperliquid-info/builder-fills)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 48. userVaultEquities | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-vault-equities

**Metadata:**
```yaml
title: userVaultEquities | Hyperliquid Info API
keywords: ["userVaultEquities","Hyperliquid userVaultEquities","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userVaultEquities
description: Hyperliquid userVaultEquities: fetch a user's locked vault equity positions across all vaults they have deposited into.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userVaultEquities"` is used to fetch a user's locked vault equity positions across all vaults they have deposited into.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fuser-vault-equities).

> **Note:** - 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`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and `LedgerVaultDistribution` entries.

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. |

{/* generated:hl-footer-start */}

## Related endpoints


### userFills

fetch a user's most recent trade fills without specifying a time window.

[Read more](/api-reference/hyperliquid-info/user-fills)


### userFillsByTime

fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.

[Read more](/api-reference/hyperliquid-info/user-fills-by-time)


### userFunding

fetch a user's per-coin funding payment history within a time window for funding-only P&L attribution.

[Read more](/api-reference/hyperliquid-info/user-funding)


### userNonFundingLedgerUpdates

fetch a user's non-funding USDC ledger history (deposits, withdrawals, transfers, vault flows) within a time…

[Read more](/api-reference/hyperliquid-info/user-non-funding-ledger-updates)

_Last reviewed: 2026-06-13_

{/* generated:hl-footer-end */}

---

## 49. webData2 | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/web-data2

**Metadata:**
```yaml
title: webData2 | Hyperliquid Info API
keywords: ["webData2","Hyperliquid webData2","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: webData2
description: Hyperliquid webData2: fetch the composite snapshot the Hyperliquid web app uses for a wallet in a single call.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "webData2"` is used to fetch the composite snapshot the Hyperliquid web app uses for a wallet in a single call.

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fweb-data2).

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "webData2", "user": "0x..."}`.

Returns the same composite payload the Hyperliquid web frontend pulls on page load for a given wallet: perp clearinghouse state, spot balances, open orders with trigger metadata, recent fills, and assorted UI-side context.

User-keyed. Use this when you want a single round-trip to populate a dashboard for a wallet.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"webData2"`. |
| `user` | `string` | Yes | Wallet address (lowercase `0x`-prefixed 42-character hex). The payload is keyed to this user. |

### Example

```bash cURL
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webData2",
    "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: "webData2",
    user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  }),
});

const dashboard = 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": "webData2",
        "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    },
)

dashboard = response.json()
```

## Response

The response is a single composite object. The example below shows one representative element of each array; in practice `meta.universe`, `assetCtxs`, `spotAssetCtxs`, and `openOrders` each contain many entries.

```json
{
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "isVault": true,
  "agentAddress": null,
  "agentValidUntil": null,
  "serverTime": 1781881474980,
  "cumLedger": "6332392.6399999997",
  "totalVaultEquity": "0.0",
  "perpsAtOpenInterestCap": ["CANTO", "FTM", "JELLY"],
  "twapStates": [],
  "leadingVaults": [],
  "clearinghouseState": {
    "marginSummary": {
      "accountValue": "3007919.6080829999",
      "totalNtlPos": "3459573.844978",
      "totalRawUsd": "3271201.7188229999",
      "totalMarginUsed": "172978.692196"
    },
    "crossMarginSummary": { "...": "same shape as marginSummary" },
    "crossMaintenanceMarginUsed": "...",
    "withdrawable": "...",
    "time": 1781881474980,
    "assetPositions": [
      {
        "type": "oneWay",
        "position": {
          "coin": "BTC",
          "szi": "-0.67076",
          "leverage": { "type": "cross", "value": 20 },
          "entryPx": "62884.6",
          "positionValue": "42329.65132",
          "unrealizedPnl": "-149.163124",
          "returnOnEquity": "-0.070726125",
          "liquidationPx": "4451986.8072480513",
          "marginUsed": "2116.482566",
          "maxLeverage": 50,
          "cumFunding": {
            "allTime": "167037.152562",
            "sinceOpen": "-63.255648",
            "sinceChange": "0.0"
          }
        }
      }
    ]
  },
  "meta": {
    "collateralToken": 0,
    "marginTables": [],
    "universe": [
      { "szDecimals": 5, "name": "BTC", "maxLeverage": 40, "marginTableId": 56 }
    ]
  },
  "assetCtxs": [
    {
      "funding": "0.0000125",
      "openInterest": "30871.17824",
      "prevDayPx": "63776.0",
      "dayNtlVlm": "2564601901.510225296",
      "premium": "-0.000633553",
      "oraclePx": "63136.0",
      "markPx": "63107.0",
      "midPx": "63095.5",
      "impactPxs": ["63095.0", "63096.0"],
      "dayBaseVlm": "40824.8194300001"
    }
  ],
  "spotAssetCtxs": [
    {
      "coin": "PURR/USDC",
      "prevDayPx": "0.094397",
      "dayNtlVlm": "1940712.1805890012",
      "markPx": "0.10119",
      "midPx": "0.101275",
      "circulatingSupply": "595243631.3874200583",
      "totalSupply": "595243637.9101999998",
      "dayBaseVlm": "20336991.0"
    }
  ],
  "openOrders": [
    {
      "coin": "APE",
      "side": "A",
      "limitPx": "0.13155",
      "sz": "5187.6",
      "oid": 473960008142,
      "timestamp": 1781881474980,
      "triggerCondition": "N/A",
      "isTrigger": false,
      "triggerPx": "0.0",
      "children": [],
      "isPositionTpsl": false,
      "reduceOnly": false,
      "orderType": "Limit",
      "origSz": "5187.6",
      "tif": "Alo",
      "cloid": null
    }
  ]
}
```

### Field descriptions

> **Note:** All numeric balances, prices, and sizes are returned as **decimal strings** with full upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. Timestamps (`serverTime`, `time`, `timestamp`) are integer Unix milliseconds.

| Field | Type | Description |
| --- | --- | --- |
| `user` | `string` | Echo of the wallet address requested. |
| `isVault` | `boolean` | `true` when the wallet is a Hyperliquid vault address. |
| `agentAddress` | `string | null` | Active API agent address if one is registered for the wallet, otherwise `null`. |
| `agentValidUntil` | `int | null` | Expiry of the API agent in Unix milliseconds, or `null` when no agent is registered. |
| `serverTime` | `int` | HyperCore server time (Unix milliseconds) at the moment the snapshot was assembled. |
| `cumLedger` | `string` | Cumulative non-funding ledger total for the wallet, in USDC. Tracks net deposits/withdrawals/transfers across time. |
| `totalVaultEquity` | `string` | Sum of all vault equity the wallet leads (when `isVault` or a vault leader). `"0.0"` when the wallet leads no vaults. |
| `perpsAtOpenInterestCap` | `array` | List of perp `coin` symbols currently at their open-interest cap. Useful for surfacing "no new shorts/longs" UI states. |
| `twapStates` | `array` | Active TWAP orders for the wallet. Empty array when no TWAPs are in flight. |
| `leadingVaults` | `array` | Vaults the wallet leads, each with vault address and current equity. Empty array when the wallet leads no vaults. |
| `clearinghouseState` | `object` | Perpetuals account state - identical to the response shape of [`clearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state). Contains `marginSummary`, `crossMarginSummary`, `crossMaintenanceMarginUsed`, `withdrawable`, `time`, and `assetPositions[]`. |
| `meta` | `object` | Perp universe metadata - identical to the response shape of [`meta`](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta). Contains `universe[]` (`{name, szDecimals, maxLeverage, marginTableId}`), `marginTables[]`, and `collateralToken`. |
| `assetCtxs` | `array` | Live per-perp market context, ordered to align with `meta.universe`. Each entry carries `funding`, `openInterest`, `markPx`, `oraclePx`, `midPx`, `impactPxs`, `premium`, `prevDayPx`, `dayNtlVlm`, and `dayBaseVlm`. |
| `spotAssetCtxs` | `array` | Live per-spot-pair market context. Each entry carries `coin` (the spot pair symbol), `markPx`, `midPx`, `prevDayPx`, `dayNtlVlm`, `dayBaseVlm`, `circulatingSupply`, and `totalSupply`. |
| `openOrders` | `array` | The wallet's open orders with full trigger metadata - identical to the response shape of [`frontendOpenOrders`](https://goldrush.dev/docs/api-reference/hyperliquid-info/frontend-open-orders). Each entry includes `coin`, `side`, `limitPx`, `sz`, `oid`, `timestamp`, `triggerCondition`, `isTrigger`, `triggerPx`, `children`, `isPositionTpsl`, `reduceOnly`, `orderType`, `origSz`, `tif`, and `cloid`. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-19_

{/* generated:hl-footer-end */}

---

## 50. allFills | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/all-fills

**Metadata:**
```yaml
title: allFills | Hyperliquid WebSocket API
keywords: ["allFills","Hyperliquid allFills","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: allFills
description: Hyperliquid allFills: stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow monitoring.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fall-fills).

> **Note:** - GoldRush-native: No `wss://api.hyperliquid.xyz/ws` equivalent.
- Filters `coin` and `aggregateByTime` are both optional. Omit `coin` to stream every market.
- Live-only: No historical snapshot on subscribe. For windowed history, use the Info API [`userFillsByTime`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-fills-by-time).
- Same per-fill shape as `userFills`; channel name in messages is `allFills`.

Subscribe once and receive every fill on HyperCore as it executes, batched per block as `[address, fill]` tuples. Optional `coin` filter narrows the stream to a single market; `aggregateByTime` merges partial fills of the same order in a block.

## 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 `"allFills"`. __RESPONSE_ROW__coin	string	Restrict the stream to a single market (e.g. `"BTC"`, `"ETH"`, or spot `@N` form). Omit to receive every market on one subscription. __RESPONSE_ROW__aggregateByTime	boolean	When `true`, partial fills of the same order within the same block are merged into one. Default `false`.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"allFills"}}
```

```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: "allFills",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "allFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px);
    }
  }
});
```

```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": "allFills"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "allFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "allFills"
  }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `{"type": "allFills", "coin": "BTC"}` is a different subscription from a wildcard `{"type": "allFills"}` - they must be unsubscribed independently.

## Streamed message

Each push has `channel: "allFills"` and a `fills` array of `[address, fill]` tuples - every fill from the same HyperCore block that matches the optional `coin` filter, with the executing wallet as the first element of each tuple.

```json
{
  "channel": "allFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"allFills"`. |
| `fills` | `array` | Tuples of `[address, fill]`. The `address` is the wallet that executed the fill; the `fill` object carries the trade details. |
| `fills.coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). |
| `fills.px` | `string` | Fill execution price (decimal string). |
| `fills.sz` | `string` | Fill size (decimal string). |
| `fills.side` | `string` | `"B"` for buy/long, `"A"` for ask/short. |
| `fills.time` | `int` | Unix timestamp in milliseconds when the fill executed. |
| `fills.startPosition` | `string` | Signed position size on the same coin immediately before this fill. |
| `fills.dir` | `string` | Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`. |
| `fills.closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). |
| `fills.hash` | `string` | L1 transaction hash that included this fill. |
| `fills.oid` | `int` | Parent order ID. |
| `fills.crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. |
| `fills.fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. |
| `fills.tid` | `int` | Unique trade ID. |
| `fills.feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. |
| `fills.twapId` | `int | null` | Parent TWAP order ID if this fill is a slice of a TWAP, otherwise `null`. |
| `fills.cloid` | `string` | Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement. |
| `fills.builder` | `string` | Optional. Builder address the order was routed through. |
| `fills.builderFee` | `string` | Optional. Builder fee paid for this fill, denominated in `feeToken`. |
| `fills.liquidation` | `object` | Optional. Present only when this fill closed a position as part of a liquidation event.  __RESPONSE_ROW__liquidatedUser	string	The wallet whose position was liquidated. __RESPONSE_ROW__fills.markPx	string	Mark price at the time of liquidation. __RESPONSE_ROW__fills.method	string	Liquidation method - `"market"` or `"backstop"`.  |

{/* generated:hl-footer-start */}

## Related endpoints


### builderFills

stream live attributed fills for one or more builder addresses in real time.

[Read more](/api-reference/hyperliquid-websocket/builder-fills)


### liquidationFills

stream a global, market-wide feed of every liquidation fill on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/liquidation-fills)


### userFills

stream real-time trade fills for one or more wallets as they execute on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/user-fills)

_Last reviewed: 2026-06-19_

{/* generated:hl-footer-end */}

---

## 51. builderFills | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/builder-fills

**Metadata:**
```yaml
title: builderFills | Hyperliquid WebSocket API
keywords: ["builderFills","Hyperliquid builderFills","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: builderFills
description: Hyperliquid builderFills: stream live attributed fills for one or more builder addresses in real time.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fbuilder-fills).

> **Note:** - GoldRush-native: No `wss://api.hyperliquid.xyz/ws` equivalent.
- Pass `builder` (string) for a single builder or `addresses` (string[]) for many. `aggregateByTime` optional.
- Live-only: No historical snapshot on subscribe. For windowed history, use the Info API [`builderFillsByTime`](https://goldrush.dev/docs/api-reference/hyperliquid-info/builder-fills-by-time).
- Same per-fill shape as `userFills`, plus `builder` and `builderFee` on every entry; channel name in messages is `builderFills`.

Subscribe to one builder address (`builder`) or many (`addresses`) and receive every fill routed through those builders as they execute, batched per block as `[address, fill]` tuples. Each fill carries the matched `builder` address and the corresponding `builderFee`.

## 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. Provide either `builder` (single address) or `addresses` (array of addresses).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | `string` | Yes | Always `"subscribe"`. |
| `subscription` | `object` | Yes |  __RESPONSE_ROW__type	string	Always `"builderFills"`. __RESPONSE_ROW__builder	string	Single builder address (lowercase `0x`-prefixed 42-character hex) to stream fills for. Mutually exclusive with `addresses`. __RESPONSE_ROW__addresses	string[]	Array of builder addresses to stream fills for - the multi-builder form of `builder`. Mutually exclusive with `builder`. __RESPONSE_ROW__aggregateByTime	boolean	When `true`, partial fills of the same order within the same block are merged into one. Default `false`.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"builderFills","builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}
```

```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: "builderFills",
      builder: "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "builderFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px, "builderFee:", fill.builderFee);
    }
  }
});
```

```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": "builderFills",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "builderFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"], "builderFee:", fill.get("builderFee"))

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderFills",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `builder: "0xAAA"` is a different subscription from one created with `addresses: ["0xAAA"]`, even if they target the same builder. To narrow a multi-builder set, unsubscribe the original list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "builderFills"` and a `fills` array of `[address, fill]` tuples. The first element of each tuple is the trader who executed the fill; the `fill` object carries the trade details, including the `builder` it was routed through and the `builderFee` earned.

```json
{
  "channel": "builderFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null,
        "builderFee": "0.1",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
      }
    ]
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"builderFills"`. |
| `fills` | `array` | Tuples of `[address, fill]`. The `address` is the trader who placed the order; the `fill` object carries the trade details plus builder-attribution fields. |
| `fills.coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). |
| `fills.px` | `string` | Fill execution price (decimal string). |
| `fills.sz` | `string` | Fill size (decimal string). |
| `fills.side` | `string` | `"B"` for buy/long, `"A"` for ask/short. |
| `fills.time` | `int` | Unix timestamp in milliseconds when the fill executed. |
| `fills.startPosition` | `string` | Signed position size the trader held on this coin immediately before this fill. |
| `fills.dir` | `string` | Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`. |
| `fills.closedPnl` | `string` | Realized PnL in USDC attributable to this fill for the trader (zero when the fill opens or extends a position). |
| `fills.hash` | `string` | L1 transaction hash that included this fill. |
| `fills.oid` | `int` | Parent order ID. |
| `fills.crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. |
| `fills.fee` | `string` | Trading fee paid by the trader for this fill, denominated in `feeToken`. |
| `fills.tid` | `int` | Unique trade ID. |
| `fills.feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. |
| `fills.twapId` | `int | null` | Parent TWAP order ID if this fill is a slice of a TWAP, otherwise `null`. |
| `fills.builder` | `string` | Builder address the order was routed through - matches one of the subscribed builders. |
| `fills.builderFee` | `string` | Builder fee earned for this fill, denominated in `feeToken`. |
| `fills.cloid` | `string` | Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement. |
| `fills.liquidation` | `object` | Optional. Present only when this fill closed a position as part of a liquidation event.  __RESPONSE_ROW__liquidatedUser	string	The wallet whose position was liquidated. __RESPONSE_ROW__fills.markPx	string	Mark price at the time of liquidation. __RESPONSE_ROW__fills.method	string	Liquidation method - `"market"` or `"backstop"`.  |

## Errors

A missing or malformed `builder`/`addresses` field returns an error message on the same channel:

```json
{ "channel": "error", "data": "subscription builderFills requires a 'builder' field" }
```

{/* generated:hl-footer-start */}

## Related endpoints


### allFills

stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…

[Read more](/api-reference/hyperliquid-websocket/all-fills)


### liquidationFills

stream a global, market-wide feed of every liquidation fill on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/liquidation-fills)


### userFills

stream real-time trade fills for one or more wallets as they execute on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/user-fills)

_Last reviewed: 2026-06-19_

{/* generated:hl-footer-end */}

---

## 52. l2BookDiff | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/l2-book-diff

**Metadata:**
```yaml
title: l2BookDiff | Hyperliquid WebSocket API
keywords: ["l2BookDiff","Hyperliquid l2BookDiff","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: l2BookDiff
description: Hyperliquid l2BookDiff: subscribe to real-time L2 order book (initial snapshot + diffs) for all Hyperliquid assets over WebSocket.
```

**Content:**

**Credit Cost:** 0.1 per coin per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fl2-book-diff).

> **Note:** - GoldRush-native. `l2BookDiff` is not exposed on `wss://api.hyperliquid.xyz/ws`. Pointing a client at the public endpoint with this subscription type will fail.
- 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.
- `coin` is optional. Omit it to stream the entire L2 order book across every asset on a single subscription.
- When `coin` is omitted, the optional `marketTypes` filter selects which market families to include. It defaults to `["perp"]` only.
- Pass `"marketTypes": ["spot"]`, or `"marketTypes":["outcome"]`, or a mix (e.g. `"marketTypes": ["perp","spot"]`), or use the wildcard `"marketTypes": ["*"]` to opt into spot, perps, outcome, and any future market types.
- No 1000-subscription-per-IP cap - multiplex hundreds of `l2BookDiff` subscriptions on a single connection.
- For OHLCV candles instead of raw book state, use the [Streaming API OHLCV streams](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream).

**Note:** When `coin` is omitted, a credit rate of `10` **credits per minute subscribed** is applied.

## 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 `"l2BookDiff"`. __RESPONSE_ROW__coin	string \| string[]	Asset filter. Accepts three shapes: - **String** - a single asset symbol (e.g. `"HYPE"`, `"BTC"`, `"@107"` for spot pairs). For HIP-3 markets, include the deployer prefix. - **Array of strings** - a fixed list of asset symbols (e.g. `["HYPE", "BTC", "ETH"]`). Each listed coin gets its own initial `Snapshot`; subsequent `Updates` may bundle diffs for any subset of the list per block. - **Omitted** - wildcard. Streams the full L2 book across **every perp asset** by default on one subscription (see `marketTypes` to include spot or outcome markets). The server emits one `Snapshot` per live coin, then per-block `Updates` covering only the coins that changed. __RESPONSE_ROW__marketTypes	string[]	Optional. Selects which market families a wildcard subscription includes. **Only valid when `coin` is omitted.** **Defaults to `["perp"]`** - when omitted, only perp markets stream. Spot and outcome markets require explicit opt-in. Accepted values: - `"perp"` *(default)* - vanilla perps and HIP-3 deployer-perps (e.g. `BTC`, `ETH`, `HYPE`, `SOL`, `cash`, `abcd`, `USA500`). - `"spot"` - `@` spot markets and legacy spot pairs (e.g. `@1`, `@107` for HYPE spot, `PURR/USDC`). Not included by default. - `"outcome"` - HIP-4 prediction-market outcomes (e.g. `#700`, `#710`, `#741`). Not included by default. - `"*"` - every current type (`"perp"` + `"spot"` + `"outcome"`) and auto-opt-in to any future types the server adds. Mix and match in one subscription, e.g. `["perp", "outcome"]`. A second `subscribe` with a different `marketTypes` value **replaces** the previous filter rather than coexisting with it.  |

### Example

Pick the subscription shape that matches the coverage you want. Every subscription starts with one `Snapshot` per coin in scope, then per-block `Updates` carrying only changed levels:

| Subscribe with | What you receive |
|---|---|
| `{"type":"l2BookDiff","coin":"HYPE"}` | Snapshot + diffs for **HYPE only** |
| `{"type":"l2BookDiff","coin":["HYPE","BTC","ETH"]}` | Snapshot + diffs for **a fixed list of coins** |
| `{"type":"l2BookDiff"}` | Snapshot + diffs for **every perp coin** (default: `marketTypes: ["perp"]`) |
| `{"type":"l2BookDiff","marketTypes":["spot"]}` | Snapshot + diffs for **every spot coin** |
| `{"type":"l2BookDiff","marketTypes":["outcome"]}` | Snapshot + diffs for **every HIP-4 outcome market** |
| `{"type":"l2BookDiff","marketTypes":["perp","spot"]}` | Snapshot + diffs for **perps + spot** |
| `{"type":"l2BookDiff","marketTypes":["*"]}` | Snapshot + diffs for **every coin** (perp + spot + outcome, plus future types) |

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"l2BookDiff","coin":"HYPE"}}
```

```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: "l2BookDiff", coin: "HYPE" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "l2BookDiff") 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, book_diffs } = msg.data.Updates;
    console.log("updates", time, block_height, "coins:", 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": "l2BookDiff", "coin": "HYPE"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l2BookDiff":
                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"], "coins:", len(upd["book_diffs"]))

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": { "type": "l2BookDiff", "coin": "HYPE" }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `coin: ["BTC", "ETH"]` is a different subscription from one created with `coin: "BTC"` or `coin: "ETH"`.

**You cannot unsubscribe a partial set of coins from an existing multi-coin subscription.** To narrow the set, unsubscribe the original `coin` array in full, then resubscribe with the smaller list:

  ```json
  // Drop ETH from a ["BTC","ETH"] subscription:
  { "method": "unsubscribe", "subscription": { "type": "l2BookDiff", "coin": ["BTC", "ETH"] } }
  { "method": "subscribe",   "subscription": { "type": "l2BookDiff", "coin": ["BTC"] } }
  ```

## Streamed messages

Every message has `channel: "l2BookDiff"`. The `data` payload contains **exactly one** of two variants: a `Snapshot` (emitted once per subscribed coin, immediately after subscribe) or an `Updates` (emitted on each subsequent HyperCore block where the book for at least one subscribed coin changed).

### Initial snapshot

After subscribe, the server emits one `Snapshot` message per coin currently in scope. For a single-coin subscription that is one message; for a list or wildcard subscription that is one message per asset. Each entry in `levels[0]` (bids) and `levels[1]` (asks) is an aggregated price level, sorted best-first.

```json
{
  "channel": "l2BookDiff",
  "data": {
    "Snapshot": {
      "coin": "HYPE",
      "time": 1779220051027,
      "block_height": 1002862373,
      "levels": [
        [
          { "px": "48.601", "sz": "51.26", "n": 1 }
        ],
        [
          { "px": "48.614", "sz": "12.34", "n": 1 }
        ]
      ]
    }
  }
}
```

### Incremental updates

Subsequent messages carry only the levels that changed since the previous block, grouped by coin. A level entry with `sz: "0"` and `n: 0` means **the level at that price has been removed**; any other entry replaces the current state at that `px` with the new `{sz, n}`.

```json
{
  "channel": "l2BookDiff",
  "data": {
    "Updates": {
      "time": 1779220051224,
      "block_height": 1002862374,
      "book_diffs": [
        {
          "coin": "HYPE",
          "levels": [
            [
              { "px": "48.601", "sz": "60.00", "n": 2 }
            ],
            [
              { "px": "48.614", "sz": "0", "n": 0 }
            ]
          ]
        }
      ]
    }
  }
}
```

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"l2BookDiff"`. |
| `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 aggregated **Level** objects 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.   HyperCore block timestamp in milliseconds. |
| `block_height` | `int` | HyperCore block height. |
| `book_diffs` | `array` | Per-coin lists of changed price levels. One entry per coin that had changes at this block. |
| `book_diffs.coin` | `string` | Asset symbol the diff applies to. |
| `book_diffs.levels` | `array>` | Tuple `[changed_bids, changed_asks]`. Each entry replaces the current state at its `px`. An entry with `sz: "0"` and `n: 0` removes the level at that price.  __RESPONSE_ROW__px	string	Price for this level (decimal string). __RESPONSE_ROW__book_diffs.sz	string	New aggregate size at this level (decimal string). `"0"` means the level is removed. __RESPONSE_ROW__book_diffs.n	int	New number of orders aggregated into this level. `0` means the level is removed.  |



{/* generated:hl-footer-start */}

## Related endpoints


### l2Book

Subscribe to real-time L2 order book snapshots for all Hyperliquid assets over WebSocket.

[Read more](/api-reference/hyperliquid-websocket/l2-book)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 53. l2Book | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/l2-book

**Metadata:**
```yaml
title: l2Book | Hyperliquid WebSocket API
keywords: ["l2Book","Hyperliquid l2Book","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: l2Book
description: Hyperliquid l2Book: subscribe to real-time L2 order book snapshots for all Hyperliquid assets over WebSocket.
```

**Content:**

**Credit Cost:** 0.5 per coin per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fl2-book).

> **Note:** - 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.
- When `coin` is omitted, the optional `marketTypes` filter selects which market families to include. It defaults to `["perp"]` only.
- Pass `"marketTypes": ["spot"]`, or `"marketTypes":["outcome"]`, or a mix (e.g. `"marketTypes": ["perp","spot"]`), or use the wildcard `"marketTypes": ["*"]` to opt into spot, perps, outcome, and any future market types.
- 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](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream).

**Note:** When `coin` is omitted, a credit rate of `50` **credits per minute subscribed** is applied.

## 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 perp assets** (the default; see `marketTypes` to include spot or outcome markets). __RESPONSE_ROW__marketTypes	string[]	Optional. Selects which market families a wildcard subscription includes. **Only valid when `coin` is omitted.** **Defaults to `["perp"]`** - when omitted, only perp markets stream. Spot and outcome markets require explicit opt-in. Accepted values: - `"perp"` *(default)* - vanilla perps and HIP-3 deployer-perps (e.g. `BTC`, `ETH`, `HYPE`, `SOL`, `cash`, `abcd`, `USA500`). - `"spot"` - `@` spot markets and legacy spot pairs (e.g. `@1`, `@107` for HYPE spot, `PURR/USDC`). Not included by default. - `"outcome"` - HIP-4 prediction-market outcomes (e.g. `#700`, `#710`, `#741`). Not included by default. - `"*"` - every current type (`"perp"` + `"spot"` + `"outcome"`) and auto-opt-in to any future types the server adds. Mix and match in one subscription, e.g. `["perp", "outcome"]`. A second `subscribe` with a different `marketTypes` value **replaces** the previous filter rather than coexisting with it. __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

Pick the subscription shape that matches the coverage you want:

| Subscribe with | What you receive |
|---|---|
| `{"type":"l2Book","coin":"BTC"}` | L2 snapshots for **BTC only** |
| `{"type":"l2Book"}` | L2 snapshots for **every perp coin** (default: `marketTypes: ["perp"]`) |
| `{"type":"l2Book","marketTypes":["spot"]}` | L2 snapshots for **every spot coin** |
| `{"type":"l2Book","marketTypes":["outcome"]}` | L2 snapshots for **every HIP-4 outcome market** |
| `{"type":"l2Book","marketTypes":["perp","spot"]}` | L2 snapshots for **perps + spot** |
| `{"type":"l2Book","marketTypes":["*"]}` | L2 snapshots for **every coin** (perp + spot + outcome, plus future types) |

```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" }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `coin: ["BTC", "ETH"]` is a different subscription from one created with `coin: "BTC"` or `coin: "ETH"`.

**You cannot unsubscribe a partial set of coins from an existing multi-coin subscription.** To narrow the set, unsubscribe the original `coin` array in full, then resubscribe with the smaller list:

  ```json
  // Drop ETH from a ["BTC","ETH"] subscription:
  { "method": "unsubscribe", "subscription": { "type": "l2Book", "coin": ["BTC", "ETH"] } }
  { "method": "subscribe",   "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.  |

{/* generated:hl-footer-start */}

## Related endpoints


### l2BookDiff

Subscribe to real-time L2 order book (initial snapshot + diffs) for all Hyperliquid assets over WebSocket.

[Read more](/api-reference/hyperliquid-websocket/l2-book-diff)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 54. l4Book | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/l4-book

**Metadata:**
```yaml
title: l4Book | Hyperliquid WebSocket API
keywords: ["l4Book","Hyperliquid l4Book","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: l4Book
description: Hyperliquid l4Book: subscribe to GoldRush's order-level Hyperliquid book - initial snapshot of every resting order plus per-block diffs with full metadata.
```

**Content:**

**Credit Cost:** 2 per coin per minute (except BTC which is 20 per minute)


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fl4-book).

> **Note:** - 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.
- Perps only. No spot assets.
- `coin` is required. Unlike `l2Book` and `l2BookDiff`, 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](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/l4-book) for patterns to maintain book state, attribute flow by `user`, or reconstruct aggregated price levels.

**Note:** When `"coin":"BTC"` is used, a credit rate of `20` **credits per minute subscribed** is applied.

## 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. |

{/* generated:hl-footer-start */}

_Last reviewed: 2026-06-24_

{/* generated:hl-footer-end */}

---

## 55. liquidationFills | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/liquidation-fills

**Metadata:**
```yaml
title: liquidationFills | Hyperliquid WebSocket API
keywords: ["liquidationFills","Hyperliquid liquidationFills","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: liquidationFills
description: Hyperliquid liquidationFills: stream a global, market-wide feed of every liquidation fill on HyperCore.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fliquidation-fills).

> **Note:** - GoldRush-native:  No `wss://api.hyperliquid.xyz/ws` equivalent. The public WebSocket exposes per-wallet fills only; detecting liquidations there would require subscribing to every wallet and filtering.
- Global stream: Every liquidation fill on HyperCore, across every wallet, on a single subscription. No `addresses` filter is accepted.
- Every fill in this stream carries a non-null `liquidation` object. The rest of the payload mirrors `userFills`.
- Live-only: No historical snapshot on subscribe. For historical liquidations, query the Streaming API [`HypercoreLedgerEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-ledger-event) type.

Subscribe with no addresses filter to receive every liquidation fill on HyperCore across every wallet, in real time. Same payload shape as `userFills`, with the `liquidation` object populated (with `liquidatedUser`, `markPx`, `method`) on every entry.

## 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 `"liquidationFills"`. __RESPONSE_ROW__aggregateByTime	boolean	When `true`, partial fills of the same liquidation within the same block are merged into one. Default `false`.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"liquidationFills"}}
```

```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: "liquidationFills" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "liquidationFills") {
    for (const [address, fill] of msg.fills) {
      console.log(
        "liquidated:", fill.liquidation.liquidatedUser,
        "via", fill.liquidation.method,
        "—", fill.coin, fill.sz, "@", fill.px,
      );
    }
  }
});
```

```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": "liquidationFills"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "liquidationFills":
                for address, fill in msg["fills"]:
                    liq = fill["liquidation"]
                    print("liquidated:", liq["liquidatedUser"],
                          "via", liq["method"], "—",
                          fill["coin"], fill["sz"], "@", fill["px"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": { "type": "liquidationFills" }
}
```

## Streamed message

Each push has `channel: "liquidationFills"` and a `fills` array of `[address, fill]` tuples. The `address` is the wallet whose order was filled (i.e. the liquidator's counterparty); `liquidation.liquidatedUser` is the wallet whose position was liquidated.

```json
{
  "channel": "liquidationFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "liquidation": {
          "liquidatedUser": "0x...",
          "markPx": "2148.75",
          "method": "market"
        },
        "twapId": null
      }
    ]
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"liquidationFills"`. |
| `fills` | `array` | Tuples of `[address, fill]`. Same `fill` shape as [`userFills`](/api-reference/hyperliquid-websocket/user-fills), with `liquidation` always populated. |
| `fills.liquidation` | `object` | Always present on this stream.  __RESPONSE_ROW__liquidatedUser	string	The wallet whose position was liquidated. __RESPONSE_ROW__fills.markPx	string	Mark price at the time of liquidation. __RESPONSE_ROW__fills.method	string	Liquidation method - `"market"` or `"backstop"`.  All other fields (`coin`, `px`, `sz`, `side`, `time`, `startPosition`, `dir`, `closedPnl`, `hash`, `oid`, `crossed`, `fee`, `tid`, `feeToken`, `twapId`, and optional `cloid` / `builderFee` / `builder`) match the [`userFills`](/api-reference/hyperliquid-websocket/user-fills) shape. |

{/* generated:hl-footer-start */}

## Related endpoints


### allFills

stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…

[Read more](/api-reference/hyperliquid-websocket/all-fills)


### builderFills

stream live attributed fills for one or more builder addresses in real time.

[Read more](/api-reference/hyperliquid-websocket/builder-fills)


### userFills

stream real-time trade fills for one or more wallets as they execute on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/user-fills)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 56. orderUpdates | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/order-updates

**Metadata:**
```yaml
title: orderUpdates | Hyperliquid WebSocket API
keywords: ["orderUpdates","Hyperliquid orderUpdates","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: orderUpdates
description: Hyperliquid orderUpdates: stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or more wallets on HyperCore.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Forder-updates).

> **Note:** - Wire-compatible with `wss://api.hyperliquid.xyz/ws` `orderUpdates` subscription - same channel name, same per-update shape.
- Up to 1,000 wallet addresses per subscription. Use `addresses` (string[]); aliases `user`(string) and `users` (string[]) are also accepted.
- Messages are batched per HyperCore block; each push carries one or more `updates` entries, each with its own `user` field. Subscribe many wallets and receive one push per block containing every matching wallet’s events.
- Live-only — no historical snapshot of resting orders on subscribe. For the current resting-order set, use the Info API  [`frontendOpenOrders`](https://goldrush.dev/docs/api-reference/hyperliquid-info/frontend-open-orders). For historical fills, use [`userFillsByTime`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-fills-by-time).
- No 1,000-subscription-per-IP cap. Multiplex many `orderUpdates` subscriptions on a single connection.

Subscribe to one or more wallets and receive their live order status updates the moment they change when an order is placed, filled, canceled, or rejected. The server batches one push per HyperCore block, carrying every matching update as an `updates` array of objects, each tagged with the originating `user`.

**Supports up to 1,000 wallet addresses per subscription.**

## 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 `"orderUpdates"`. __RESPONSE_ROW__addresses	string[]	One or more wallet addresses (lowercase `0x`-prefixed hex) to stream order updates for. Aliases `user` (string) and `users` (string[]) are also accepted.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"orderUpdates","addresses":["0x010461c14e146ac35fe42271bdc1134ee31c703a"]}}
```

```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: "orderUpdates",
      addresses: ["0x010461c14e146ac35fe42271bdc1134ee31c703a"],
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "orderUpdates") {
    for (const update of msg.updates) {
      console.log(
        update.user,
        update.order.coin,
        update.order.side,
        update.order.sz,
        "@",
        update.order.limitPx,
        "->",
        update.status,
      );
    }
  }
});
```

```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": "orderUpdates",
                "addresses": ["0x010461c14e146ac35fe42271bdc1134ee31c703a"],
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "orderUpdates":
                for update in msg["updates"]:
                    print(
                        update["user"],
                        update["order"]["coin"],
                        update["order"]["side"],
                        update["order"]["sz"],
                        "@",
                        update["order"]["limitPx"],
                        "->",
                        update["status"],
                    )

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "orderUpdates",
    "addresses": ["0x010461c14e146ac35fe42271bdc1134ee31c703a"]
  }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `addresses: ["0xAAA", "0xBBB"]` is a different subscription from two single-address subscriptions. To narrow the set, unsubscribe the original list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "orderUpdates"` and an `updates` array of objects - every order lifecycle event from the same HyperCore block that matches any subscribed wallet. Each entry is self-tagged with the originating `user`.

```json
{
  "channel": "orderUpdates",
  "updates": [
    {
      "time": "2026-06-18T04:21:19.321641904",
      "user": "0x010461c14e146ac35fe42271bdc1134ee31c703a",
      "hash": "0xc2e340827d8e0749c45c043df991d1019b0058681881261b66abebd53c81e134",
      "status": "open",
      "builder": null,
      "order": {
        "coin": "W",
        "side": "B",
        "oid": 472501605004,
        "limitPx": "0.00963",
        "sz": "77502.4",
        "origSz": "77502.4",
        "timestamp": 1781756479321,
        "orderType": "Limit",
        "tif": "Alo",
        "reduceOnly": false,
        "isTrigger": false,
        "isPositionTpsl": false,
        "triggerCondition": "N/A",
        "triggerPx": "0.0",
        "cloid": null,
        "children": []
      }
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"orderUpdates"`. |
| `updates` | `object[]` | Array of order lifecycle events from the same HyperCore block. Each entry carries its own `user` field, so a single push can contain events for multiple subscribed wallets. |
| `updates.time` | `string` | ISO 8601 timestamp (nanosecond precision) of the HyperCore block in which the status transition occurred. |
| `updates.user` | `string` | Wallet the update belongs to (lowercase `0x`-prefixed hex). |
| `updates.hash` | `string` | Optional. L1 transaction hash for the action that produced this update. Present on placements (`"open"`); typically absent on terminal transitions like `"filled"` and `"canceled"`. |
| `updates.status` | `string` | Order lifecycle state. Common values: `"open"`, `"filled"`, `"canceled"`, `"triggered"`, plus rejection codes (`"iocCancelRejected"`, `"selfTradeCanceled"`, `"badAloPxRejected"`, `"tickRejected"`, `"minTradeNtlRejected"`, `"reduceOnlyRejected"`, `"marginCanceled"`, `"vaultWithdrawalCanceled"`, `"openInsufficientMargin"`, `"perpMarginRejected"`, `"badTriggerPxRejected"`, `"marketOrderNoLiquidityRejected"`, `"positionIncreaseAtOpenInterestCapRejected"`, `"positionFlipAtOpenInterestCapRejected"`, `"tooAggressiveAtOpenInterestCapRejected"`, `"openInterestIncreaseRejected"`, `"insufficientSpotBalanceRejected"`, `"oracleNotFoundRejected"`, `"perpMaxPositionRejected"`). |
| `updates.builder` | `string | null` | Builder address the order was routed through, or `null` if the order was not routed through a builder code. |
| `updates.order` | `object` | Order snapshot at the moment of the status change.  __RESPONSE_ROW__coin	string	Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). __RESPONSE_ROW__updates.side	string	`"B"` for buy/long, `"A"` for ask/short. __RESPONSE_ROW__updates.oid	int	Order ID. __RESPONSE_ROW__updates.limitPx	string	Limit price (decimal string). __RESPONSE_ROW__updates.sz	string	Current remaining size (decimal string). `"0.0"` after a full fill. __RESPONSE_ROW__updates.origSz	string	Original size at placement. __RESPONSE_ROW__updates.timestamp	int	Unix timestamp in milliseconds when the order was placed. __RESPONSE_ROW__updates.orderType	string	`"Limit"` or trigger variants (e.g. `"Stop Market"`, `"Stop Limit"`, `"Take Profit Market"`, `"Take Profit Limit"`). __RESPONSE_ROW__updates.tif	string	Time-in-force - `"Alo"` (add-liquidity-only / post-only), `"Ioc"` (immediate-or-cancel), or `"Gtc"` (good-til-cancel). __RESPONSE_ROW__updates.reduceOnly	boolean	`true` if the order is constrained to reduce an existing position. __RESPONSE_ROW__updates.isTrigger	boolean	`true` if this is a trigger (stop / take-profit) order. __RESPONSE_ROW__updates.isPositionTpsl	boolean	`true` for position-level take-profit / stop-loss orders. __RESPONSE_ROW__updates.triggerCondition	string	Human-readable trigger condition; `"N/A"` for plain limit orders. __RESPONSE_ROW__updates.triggerPx	string	Trigger price (decimal string); `"0.0"` for plain limit orders. __RESPONSE_ROW__updates.cloid	string \| null	Optional client order ID (`0x`-prefixed 32-character hex) if one was set at placement, otherwise `null`. __RESPONSE_ROW__updates.children	object[]	Child orders (e.g. TP/SL attached at placement); empty array if none.  |

{/* generated:hl-footer-start */}

## Related endpoints


### userNonFundingLedgerUpdates

stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or…

[Read more](/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates)

_Last reviewed: 2026-06-18_

{/* generated:hl-footer-end */}

---

## 57. userFills | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/user-fills

**Metadata:**
```yaml
title: userFills | Hyperliquid WebSocket API
keywords: ["userFills","Hyperliquid userFills","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: userFills
description: Hyperliquid userFills: stream real-time trade fills for one or more wallets as they execute on HyperCore.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-fills).

> **Note:** - Wire-compatible with `wss://api.hyperliquid.xyz/ws` `userFills` subscription - same channel name, same per-fill shape.
- Up to 1,000 wallet addresses per subscription. Use `addresses` (string[]); aliases `user`(string) and `users` (string[]) are also accepted.
- Messages are batched per HyperCore block as `[address, fill]` tuples; subscribe many wallets, receive one push per block per wallet that had activity.
- Live-only - no historical snapshot on subscribe. For windowed history, use the Info API `userFillsByTime`.
- No 1,000-subscription-per-IP cap. Multiplex many `userFills` subscriptions on a single connection.

Subscribe to one or more wallets and receive their live trade fills the moment they execute. The server batches one push per HyperCore block, carrying every matching fill as `[address, fill]` tuples.

**Supports up to 1,000 wallet addresses per subscription.**

## 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 `"userFills"`. __RESPONSE_ROW__addresses	string[]	One or more wallet addresses (lowercase `0x`-prefixed hex) to stream fills for. Aliases `user` (string) and `users` (string[]) are also accepted. __RESPONSE_ROW__aggregateByTime	boolean	When `true`, partial fills of the same order within the same block are merged into one. Default `false`.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"userFills","addresses":["0x31ca8395cf837de08b24da3f660e77761dfb974b"]}}
```

```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: "userFills",
      addresses: ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "userFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px);
    }
  }
});
```

```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": "userFills",
                "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "userFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "userFills",
    "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"]
  }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. A subscription created with `addresses: ["0xAAA", "0xBBB"]` is a different subscription from two single-address subscriptions. To narrow the set, unsubscribe the original list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "userFills"` and a `fills` array of `[address, fill]` tuples - all fills from the same HyperCore block that match any subscribed wallet.

```json
{
  "channel": "userFills",
  "fills": [
    [
      "0x31ca8395cf837de08b24da3f660e77761dfb974b",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"userFills"`. |
| `fills` | `array` | Tuples of `[address, fill]`. The `address` is the subscribed wallet the fill belongs to; the `fill` object carries the trade details. |
| `fills.coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). |
| `fills.px` | `string` | Fill execution price (decimal string). |
| `fills.sz` | `string` | Fill size (decimal string). |
| `fills.side` | `string` | `"B"` for buy/long, `"A"` for ask/short. |
| `fills.time` | `int` | Unix timestamp in milliseconds when the fill executed. |
| `fills.startPosition` | `string` | Signed position size on the same coin immediately before this fill. |
| `fills.dir` | `string` | Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`. |
| `fills.closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). |
| `fills.hash` | `string` | L1 transaction hash that included this fill. |
| `fills.oid` | `int` | Parent order ID. |
| `fills.crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. |
| `fills.fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. |
| `fills.tid` | `int` | Unique trade ID. |
| `fills.feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. |
| `fills.twapId` | `int | null` | Parent TWAP order ID if this fill is a slice of a TWAP, otherwise `null`. |
| `fills.cloid` | `string` | Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement. |
| `fills.builderFee` | `string` | Optional. Builder fee paid for this fill, denominated in `feeToken`. Present only on fills routed through a builder code. |
| `fills.builder` | `string` | Optional. Builder address the order was routed through. |
| `fills.liquidation` | `object` | Optional. Present only when this fill closed a position as part of a liquidation event.  __RESPONSE_ROW__liquidatedUser	string	The wallet whose position was liquidated. __RESPONSE_ROW__fills.markPx	string	Mark price at the time of liquidation. __RESPONSE_ROW__fills.method	string	Liquidation method - `"market"` or `"backstop"`.  |

{/* generated:hl-footer-start */}

## Related endpoints


### allFills

stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…

[Read more](/api-reference/hyperliquid-websocket/all-fills)


### builderFills

stream live attributed fills for one or more builder addresses in real time.

[Read more](/api-reference/hyperliquid-websocket/builder-fills)


### liquidationFills

stream a global, market-wide feed of every liquidation fill on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/liquidation-fills)


### userNonFundingLedgerUpdates

stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or…

[Read more](/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates)

_Last reviewed: 2026-06-16_

{/* generated:hl-footer-end */}

---

## 58. userNonFundingLedgerUpdates | Hyperliquid WebSocket API

**Path:** api-reference/hyperliquid-websocket/user-non-funding-ledger-updates

**Metadata:**
```yaml
title: userNonFundingLedgerUpdates | Hyperliquid WebSocket API
keywords: ["userNonFundingLedgerUpdates","Hyperliquid userNonFundingLedgerUpdates","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket"]
sidebarTitle: userNonFundingLedgerUpdates
description: Hyperliquid userNonFundingLedgerUpdates: stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or more wallets.
```

**Content:**

**Credit Cost:** 1 per minute


**Processing:** Realtime

> **Tip:** Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-non-funding-ledger-updates).

> **Note:** - Wire-compatible with `wss://api.hyperliquid.xyz/ws` `userNonFundingLedgerUpdates`subscription - same channel name, same `delta` shape per event.
- Up to 1,000 wallet addresses per subscription. Use `addresses` (string[]); aliases `user`(string) and `users` (string[]) are also accepted.
- Covers everything that moves USDC or token balances except funding payments - deposits, withdrawals, transfers, liquidations, vault actions, staking, rewards.
- Live-only: `isSnapshot` is always `false` on this transport. For windowed history, use the Info API [`userNonFundingLedgerUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-non-funding-ledger-updates).

Subscribe to one or more wallets and receive every non-funding ledger event in real time: deposits, withdrawals, transfers, liquidations, vault deposits/withdrawals, staking, rewards, and more. Each push carries a list of `{time, hash, delta}` entries where `delta.type` identifies the event class and the remaining `delta` fields are type-specific.

**Supports up to 1,000 wallet addresses per subscription.**

## 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 `"userNonFundingLedgerUpdates"`. __RESPONSE_ROW__addresses	string[]	One or more wallet addresses (lowercase `0x`-prefixed hex) to stream events for. Aliases `user` (string) and `users` (string[]) are also accepted.  |

### Example

```bash wscat
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"userNonFundingLedgerUpdates","addresses":["0x31ca8395cf837de08b24da3f660e77761dfb974b"]}}
```

```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: "userNonFundingLedgerUpdates",
      addresses: ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "userNonFundingLedgerUpdates") {
    const { user, nonFundingLedgerUpdates } = msg.data;
    for (const update of nonFundingLedgerUpdates) {
      console.log(user, update.delta.type, update.delta);
    }
  }
});
```

```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": "userNonFundingLedgerUpdates",
                "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "userNonFundingLedgerUpdates":
                data = msg["data"]
                for update in data["nonFundingLedgerUpdates"]:
                    print(data["user"], update["delta"]["type"], update["delta"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "userNonFundingLedgerUpdates",
    "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"]
  }
}
```

> **Note:** Unsubscribe matches subscriptions by **exact body**. To narrow the wallet set, unsubscribe the original `addresses` list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "userNonFundingLedgerUpdates"` and a `data` object keyed to a single wallet. Multi-wallet subscriptions receive one push per affected wallet.

```json
{
  "channel": "userNonFundingLedgerUpdates",
  "data": {
    "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "isSnapshot": false,
    "nonFundingLedgerUpdates": [
      {
        "time": 1781560864370,
        "hash": "0xd49c1a45a99fa0b4d615043dce4a050000d7322b4492bf867864c59868937a9f",
        "delta": {
          "type": "send",
          "amount": "0.012417",
          "destination": "0x6043daf4fbd6bd60601d277312a0664551302e70",
          "usdcValue": "0.012417",
          "nativeTokenFee": "0.0"
        }
      }
    ]
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `channel` | `string` | Always `"userNonFundingLedgerUpdates"`. |
| `data` | `object` |  |
| `data.user` | `string` | The wallet address this batch of updates belongs to. |
| `data.isSnapshot` | `boolean` | Always `false` on this live stream. The field is preserved for parity with the public Hyperliquid WebSocket contract. |
| `data.nonFundingLedgerUpdates` | `array` | One entry per ledger event in the current block.  __RESPONSE_ROW__time	int	Unix timestamp in milliseconds when the event was recorded. __RESPONSE_ROW__data.hash	string	L1 transaction hash that produced the event. __RESPONSE_ROW__data.delta	object	Event payload. `delta.type` identifies the event class; remaining `delta` fields are type-specific - see [Delta types](#delta-types) below.  |

### Delta types

`delta.type` is one of:

| Value | Description |
|---|---|
| `deposit` | USDC deposit into the perp account from an external chain. |
| `withdraw` | USDC withdrawal to an external chain. |
| `internalTransfer` | USDC transfer between Hyperliquid accounts. |
| `subAccountTransfer` | Transfer between a master account and one of its sub-accounts. |
| `accountClassTransfer` | Transfer between perp and spot accounts on the same wallet. |
| `spotTransfer` | Spot token transfer between wallets. |
| `liquidation` | Position closed by liquidation. |
| `vaultCreate` | Vault was created. |
| `vaultDeposit` | Deposit into a vault. |
| `vaultWithdraw` | Withdrawal from a vault. |
| `vaultDistribution` | Vault PnL distribution to depositors. |
| `vaultLeaderCommission` | Commission paid to a vault leader. |
| `spotGenesis` | Initial token allocation at spot deployment. |
| `rewardsClaim` | Claim of accrued rewards. |
| `accountActivationGas` | Gas fee paid to activate a new account. |
| `perpDexClassTransfer` | Transfer between different perp DEXes on the same wallet. |
| `deployGasAuction` | Gas-auction settlement for HIP-3 / HIP-4 deployments. |
| `send` | Native HYPE / token send. |
| `cStakingTransfer` | Transfer of staked HYPE between wallets. |
| `borrowLend` | Borrow or lend operation in the spot borrow-lend market. |

The remaining keys on `delta` vary by `type` and follow the public Hyperliquid `info` API `userNonFundingLedgerUpdates` payload. Common fields include `amount` (decimal string), `usdcValue` (decimal string), `coin` (string), `destination` / `source` (address strings), and `nativeTokenFee` (decimal string).

{/* generated:hl-footer-start */}

## Related endpoints


### orderUpdates

stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or more wallets…

[Read more](/api-reference/hyperliquid-websocket/order-updates)


### userFills

stream real-time trade fills for one or more wallets as they execute on HyperCore.

[Read more](/api-reference/hyperliquid-websocket/user-fills)

_Last reviewed: 2026-06-17_

{/* generated:hl-footer-end */}

---

# Solana API Documentation

GoldRush API for Solana is the complete data layer for Solana: REST endpoints for SPL token balances, transactions by signature, NFTs (Metaplex + Bubblegum cNFTs), pricing, and Solana-native primitives; real-time GraphQL streams for the DEX firehose (Raydium, Orca, Meteora, Jupiter, PumpFun), OHLCV, and wallet activity on `SOLANA_MAINNET`; and Pipeline warehouse delivery for decoded `swaps`, `transfers`, and PumpFun lifecycle (`sol_pf_*`) tables.

## 1. Foundational API on Solana

**Path:** goldrush-solana/foundational/overview

**Metadata:**
```yaml
title: Foundational API on Solana
sidebarTitle: Overview
description: REST endpoint on Solana for SPL token balances.
```

**Content:**

The GoldRush Foundational API on Solana is the same REST surface that serves other chains, adapted for Solana addressing. Wallets and mints are base58.

## Endpoint

```
GET https://api.covalenthq.com/v1/solana-mainnet/...
Authorization: Bearer
```

`solana-mainnet` slots into the same `{chainName}` path parameter as `eth-mainnet`, `base-mainnet`, or other supported chains.

## Solana addressing conventions

| Topic | Convention |
|---|---|
| **Wallet address** | Base58, 32-44 chars, **case-preserved** (unlike EVM 0x-hex which is lowercased). Example: `4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY`. |
| **Token mint** | Base58 mint pubkey - takes the same path slot as `contract_address` on EVM. SOL is represented as `So11111111111111111111111111111111111111112` (wrapped SOL mint), USDC as `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`. |
| **Native unit** | Lamports - 1 SOL = 10⁹ lamports. |

## Supported endpoint

| Endpoint | What it returns |
|---|---|
| [Get token balances for address](/api-reference/foundational-api/balances/get-token-balances-for-address) | SPL token balances plus native SOL with USD quote where pricing exists. |

Walkthrough: [Wallet](/goldrush-solana/foundational/wallet).

## Not supported today

The following are **not** part of Foundational REST coverage on Solana today:

- SPL token transfer history (REST). Available in the warehouse via the [`transfers` normalizer](/goldrush-solana/warehouse/spl-transfers).
- Solana transactions (signature lookup, paginated history, summary)
- NFTs (Metaplex and Bubblegum compressed)
- Token pricing REST endpoints (historical or pool spot). Real-time OHLCV is available via the [streaming OHLCV recipe](/goldrush-solana/streaming/ohlcv-markets).
- Solana-native primitives (stake, IDL, validators, Token-2022 extensions, SPL delegations)

## Error handling

Follows the standard GoldRush envelope and error taxonomy - see [Error handling](/error-handling).

---

## 2. Wallet endpoints on Solana

**Path:** goldrush-solana/foundational/wallet

**Metadata:**
```yaml
title: Wallet endpoints on Solana
sidebarTitle: Wallet
description: REST endpoint on Solana for SPL token balances.
```

**Content:**

This page walks through the wallet-centric Foundational endpoint currently supported on `solana-mainnet`: SPL token balances.

## Balances (SPL + native SOL)

Returns SPL token holdings plus native SOL with USD pricing where available.

```bash cURL
curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/" \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY"
```

```typescript TypeScript
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
  chainName: "solana-mainnet",
  walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY",
});

for (const item of resp.data.items) {
  console.log(item.contract_ticker_symbol, item.balance, item.pretty_quote);
}
```

```python Python
import os, requests

resp = requests.get(
    "https://api.covalenthq.com/v1/solana-mainnet/address/"
    "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/",
    headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
)
print(resp.json()["data"]["items"][:3])
```

Each item carries the SPL mint as `contract_address`, decimals from the Mint account, and `quote` in USD where pricing exists. The wrapped-SOL row (`So111…`) is the native balance.

Reference: [`get-token-balances-for-address`](/api-reference/foundational-api/balances/get-token-balances-for-address).

## SPL transfer history

SPL transfer history is **not** available on the Foundational REST API for Solana today. For decoded SPL transfers, use the [warehouse `transfers` normalizer](/goldrush-solana/warehouse/spl-transfers).

## Related

- [DEX firehose](/goldrush-solana/streaming/dex-firehose) - new DEX pair events on `SOLANA_MAINNET`.
- [Wallet activity](/goldrush-solana/streaming/wallet-activity) - real-time push of decoded swaps and transfers for a list of wallets.
- [OHLCV markets](/goldrush-solana/streaming/ohlcv-markets) - real-time candles by pool or token mint.
- [SPL Transfers warehouse recipe](/goldrush-solana/warehouse/spl-transfers) - decoded SPL transfers landed in your warehouse.
- [DEX Swaps warehouse recipe](/goldrush-solana/warehouse/dex-swaps) - decoded DEX swaps landed in your warehouse.

---

## 3. Solana API Overview

**Path:** goldrush-solana/overview

**Metadata:**
```yaml
title: Solana API Overview
sidebarTitle: Overview
description: GoldRush on Solana: SPL token balances (REST); new DEX pairs, wallet activity, and OHLCV candles (streaming); decoded DEX swaps and SPL transfers (warehouse).
```

**Content:**

GoldRush's coverage on Solana today spans these primitives:

- **SPL token balances** for any wallet - Foundational REST.
- **New DEX pairs** decoded in real time - Streaming `newPairs`.
- **Wallet activity** for arbitrary wallets in real time - Streaming `walletTxs`.
- **OHLCV candles** for pools and tokens in real time - Streaming `ohlcvCandlesForPair` and `ohlcvCandlesForToken`.
- **DEX swaps** decoded, landed in your warehouse - Pipeline `swaps` normalizer.
- **SPL token transfers** decoded, landed in your warehouse - Pipeline `transfers` normalizer.


### Foundational API

REST endpoint for SPL token balances on `solana-mainnet`. Base58 addresses.

[Read more](/goldrush-solana/foundational/overview)


### Real-time Streaming

`newPairs`, `walletTxs`, and OHLCV subscriptions on `SOLANA_MAINNET`.

[Read more](/goldrush-solana/streaming/dex-firehose)


### Pipeline to your warehouse

Decoded `swaps` and `transfers` to ClickHouse, BigQuery, Postgres, Kafka, S3, or webhooks.

[Read more](/goldrush-solana/warehouse/dex-swaps)


### GoldRush vs Solana RPC

What GoldRush adds on top of plain Solana RPC.

[Read more](/resources/differentiate-your-solana-app)

## What's included

## Quickstart


### Look up a Solana wallet

SPL token balances and native SOL for any base58 address.

[Read more](/goldrush-solana/quickstart#1-look-up-spl-token-balances)


### Stream new DEX pairs

New pool events via the `newPairs` subscription on `SOLANA_MAINNET`.

[Read more](/goldrush-solana/quickstart#2-stream-new-dex-pairs)


### Pipe SPL transfers to a warehouse

Land decoded SPL transfers in ClickHouse, BigQuery, or Postgres.

[Read more](/goldrush-solana/quickstart#3-pipe-spl-transfers-to-your-warehouse)

---

## 4. Solana API Quickstart

**Path:** goldrush-solana/quickstart

**Metadata:**
```yaml
title: Solana API Quickstart
sidebarTitle: Quickstart
description: Three quickstarts for Solana on GoldRush: SPL token balances (REST), new DEX pair stream, and DEX swaps to a warehouse.
```

**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. Look up SPL token balances

Get SPL token balances and native SOL for any base58 wallet address.

```bash cURL
curl -X GET "https://api.covalenthq.com/v1/solana-mainnet/address/4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/" \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY"
```

```typescript TypeScript
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
  chainName: "solana-mainnet",
  walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY",
});

for (const token of resp.data.items) {
  console.log(`${token.contract_ticker_symbol}: ${token.balance} (${token.pretty_quote})`);
}
```

```python Python
import os
import requests

resp = requests.get(
    "https://api.covalenthq.com/v1/solana-mainnet/address/"
    "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY/balances_v2/",
    headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
)

for item in resp.json()["data"]["items"]:
    print(item["contract_ticker_symbol"], item["balance"], item.get("pretty_quote"))
```

Balances are returned with `contract_address` as the base58 mint pubkey, `contract_decimals` from the Mint account, and USD `quote` where pricing is available.

### Foundational on Solana walkthrough

SPL token balance details and request shape.

[Read more](/goldrush-solana/foundational/wallet)

---

## 2. Stream new DEX pairs

Subscribe to new DEX pairs on Solana over a WebSocket.

```graphql GraphQL Subscription
subscription {
  newPairs(chain_name: SOLANA_MAINNET) {
    block_signed_at
    protocol
    pair_address
    base_token { contract_address contract_ticker_symbol contract_decimals }
    quote_token { contract_address contract_ticker_symbol contract_decimals }
    liquidity
  }
}
```

Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key. See [DEX firehose](/goldrush-solana/streaming/dex-firehose) for the full pattern.

---

## 3. Pipe SPL transfers to your warehouse

Stream decoded SPL token transfers into ClickHouse, BigQuery, Postgres, Kafka, or S3.


**Create a pipeline**

In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**.


**Pick Solana + Transfers**

Choose **Solana** as the chain and **Transfers** as the data type. The companion `Swaps` data type for decoded DEX trades is also available.


**Choose your destination**

Connect ClickHouse, BigQuery, Postgres, Kafka, S3/GCS/R2, SQS, or a Webhook.


**Deploy**

Decoded transfers begin flowing within seconds.

Full walkthrough with sample SQL: [SPL Transfers warehouse recipe](/goldrush-solana/warehouse/spl-transfers) and [DEX Swaps warehouse recipe](/goldrush-solana/warehouse/dex-swaps).

---

## What's next


### Foundational endpoints

SPL token balances on `solana-mainnet`.

[Read more](/goldrush-solana/foundational/overview)


### DEX firehose

`newPairs` subscription on `SOLANA_MAINNET`.

[Read more](/goldrush-solana/streaming/dex-firehose)


### Wallet activity

`walletTxs` subscription on `SOLANA_MAINNET`.

[Read more](/goldrush-solana/streaming/wallet-activity)


### OHLCV markets

Real-time OHLCV candles by pool or token.

[Read more](/goldrush-solana/streaming/ohlcv-markets)


### DEX swaps to your warehouse

Decoded swaps via the Pipeline API.

[Read more](/goldrush-solana/warehouse/dex-swaps)


### SPL transfers to your warehouse

Decoded SPL transfers via the Pipeline API.

[Read more](/goldrush-solana/warehouse/spl-transfers)


### GoldRush vs Solana RPC

What GoldRush adds on top of plain Solana RPC.

[Read more](/resources/differentiate-your-solana-app)

---

## 5. DEX Firehose on Solana

**Path:** goldrush-solana/streaming/dex-firehose

**Metadata:**
```yaml
title: DEX Firehose on Solana
sidebarTitle: DEX Firehose
description: Subscribe to new DEX pairs on Solana in real time over a WebSocket connection using the newPairs subscription.
```

**Content:**

GoldRush's `newPairs` subscription on `SOLANA_MAINNET` delivers new DEX pairs as they appear.

## Subscribe

```graphql GraphQL Subscription
subscription {
  newPairs(chain_name: SOLANA_MAINNET) {
    block_signed_at
    protocol
    pair_address
    base_token { contract_address contract_ticker_symbol contract_decimals }
    quote_token { contract_address contract_ticker_symbol contract_decimals }
    liquidity
  }
}
```

```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 {
  newPairs(chain_name: SOLANA_MAINNET) {
    block_signed_at
    protocol
    pair_address
    base_token { contract_address contract_ticker_symbol contract_decimals }
    quote_token { contract_address contract_ticker_symbol contract_decimals }
    liquidity
  }
}
""")

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["newPairs"])

asyncio.run(main())
```

Connect via WebSocket at `wss://streaming.goldrushdata.com/graphql` with your API key in the connection parameters.

The `protocol` field carries the DEX protocol name. Filter client-side to scope to a particular venue.

## Patterns

### "New pools" tab

Stream the firehose, dedupe by `pair_address`, drop pools below a `liquidity` threshold to filter spam, and display chronologically.

### Cross-DEX arbitrage discovery

The same base/quote pair can launch on multiple venues within minutes. Group new pools by base/quote token addresses to discover routes for arb.

## Production considerations

- **Reconnect on close or error.** Wrap the subscribe call in a function and re-invoke on `error` / `complete` with a 1-2s backoff.
- **Dedupe by `pair_address`.** During brief reconnects you may see a recently-emitted pool twice; deduplicate on `pair_address`.
- **No backfill on reconnect.** The subscription delivers events from the moment it opens. For historical pairs and swaps, use the [warehouse `swaps` recipe](/goldrush-solana/warehouse/dex-swaps).

## Related

- [DEX Swaps warehouse recipe](/goldrush-solana/warehouse/dex-swaps) - decoded swaps landed in your warehouse.
- [New DEX Pairs Stream reference](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream) - full subscription schema.

---

## 6. OHLCV Markets on Solana

**Path:** goldrush-solana/streaming/ohlcv-markets

**Metadata:**
```yaml
title: OHLCV Markets on Solana
sidebarTitle: OHLCV Markets
description: Real-time OHLCV candles on Solana. Subscribe by pair address or by token mint.
```

**Content:**

GoldRush exposes two OHLCV streams on `SOLANA_MAINNET`:

- **`ohlcvCandlesForPair`** - candles for a specific pool address.
- **`ohlcvCandlesForToken`** - candles aggregated across pools carrying that SPL mint.

Both deliver candles in real time over WebSocket as new swaps land in the pool.

## Stream candles for a specific pool

Best for charting one pool.

```graphql GraphQL Subscription
subscription {
  ohlcvCandlesForPair(
    chain_name: SOLANA_MAINNET
    pair_addresses: ["58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2"]
    interval: ONE_MINUTE
    timeframe: ONE_HOUR
  ) {
    pair_address
    timestamp
    open
    high
    low
    close
    volume_usd
  }
}
```

`pair_addresses` is an array of base58 pool addresses. You can subscribe to multiple pools on one subscription.

## Stream candles for a token (across all pools)

`ohlcvCandlesForToken` aggregates across pools carrying that mint.

```graphql
subscription {
  ohlcvCandlesForToken(
    chain_name: SOLANA_MAINNET
    token_addresses: ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]
    interval: ONE_MINUTE
    timeframe: ONE_HOUR
  ) {
    timestamp
    open
    high
    low
    close
    volume_usd
  }
}
```

## When to use pairs vs tokens

| Use case | Stream |
|---|---|
| Chart a single pool | `ohlcvCandlesForPair` with the pool address |
| Track arbitrage between two venues for the same pair | `ohlcvCandlesForPair` with both pool addresses |
| Get the USD price of a token aggregated across pools | `ohlcvCandlesForToken` |

## Patterns

### TradingView chart

Subscribe to `ohlcvCandlesForPair` at the user's selected interval; push candles into TradingView's UDF datafeed adapter. The `timestamp / open / high / low / close / volume_usd` fields map 1:1 to UDF.

### Discovery → chart

Pair this stream with the [DEX firehose](/goldrush-solana/streaming/dex-firehose): when a new pool appears in `newPairs`, automatically subscribe to its OHLCV. Limit to pools above a `liquidity` threshold to avoid spam.

### Pricing service

Use [`ohlcvCandlesForToken`](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) on `1d` candles for an aggregated USD price.

## Related

- [DEX firehose](/goldrush-solana/streaming/dex-firehose) - discover new pools to subscribe to.
- [OHLCV Pairs Stream reference](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) - full subscription schema.
- [OHLCV Tokens Stream reference](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) - full subscription schema.

---

## 7. Wallet Activity on Solana

**Path:** goldrush-solana/streaming/wallet-activity

**Metadata:**
```yaml
title: Wallet Activity on Solana
sidebarTitle: Wallet Activity
description: Subscribe to real-time activity for Solana wallets over `walletTxs` on SOLANA_MAINNET.
```

**Content:**

The `walletTxs` subscription delivers transactions for the wallets you subscribe to, with `decoded_details` typed as a `SwapTransaction` or `TransferTransaction` union member.

## Subscribe

```graphql GraphQL Subscription
subscription {
  walletTxs(
    wallet_addresses: [
      "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY"
    ]
    chain_name: SOLANA_MAINNET
  ) {
    tx_hash
    block_signed_at
    from_address
    to_address
    successful
    decoded_type
    decoded_details {
      typeString
      ... on SwapTransaction {
        amount_in
        amount_out
        token_in { contract_address contract_ticker_symbol contract_decimals }
        token_out { contract_address contract_ticker_symbol contract_decimals }
      }
      ... on TransferTransaction {
        amount
        from
        to
        quote_usd
        quote_rate_usd
        contract_metadata { contract_address contract_ticker_symbol contract_decimals }
      }
    }
  }
}
```

The chain enum is `SOLANA_MAINNET` (SCREAMING_SNAKE_CASE), not `solana-mainnet`. The Streaming API uses the enum; the Foundational REST API uses the kebab-case form.

## Patterns

### Copy-trading

Subscribe to a curated list of high-performing wallets. Filter the stream on `SwapTransaction` and mirror to your own execution layer.

### Whale watch

Subscribe to a curated list of high-balance wallets and surface every fill and large transfer in a live tape.

### Compliance / AML alerts

Subscribe to flagged addresses. Filter on `TransferTransaction` events and alert when `amount` exceeds a threshold.

### Push vs pull

For long-range transfer history, use the warehouse [`transfers` normalizer](/goldrush-solana/warehouse/spl-transfers); use `walletTxs` here for the live tip.

## Production considerations

- **Reconnect on close or error.** Wrap subscribe in a function; re-invoke with 1-2s backoff on `error` / `complete`.
- **Validate addresses up front.** Pre-filter with a base58 validator before passing in.
- **No gap-fill on reconnect.** Events that occurred during a disconnect are not replayed. For continuity across a gap, query the warehouse [`transfers`](/goldrush-solana/warehouse/spl-transfers) or [`swaps`](/goldrush-solana/warehouse/dex-swaps) table over the disconnect window.

## Related

- [Wallet endpoints](/goldrush-solana/foundational/wallet) - REST companion for SPL token balances.
- [SPL Transfers warehouse recipe](/goldrush-solana/warehouse/spl-transfers) - decoded SPL transfers landed in your warehouse.
- [DEX Swaps warehouse recipe](/goldrush-solana/warehouse/dex-swaps) - decoded DEX swaps landed in your warehouse.
- [Wallet Activity Stream reference](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - full subscription schema.

---

## 8. Solana DEX Swaps to your warehouse

**Path:** goldrush-solana/warehouse/dex-swaps

**Metadata:**
```yaml
title: Solana DEX Swaps to your warehouse
sidebarTitle: DEX Swaps
description: Land decoded Solana DEX trades into ClickHouse, BigQuery, Postgres, Kafka, or S3 via the `swaps` normalizer.
```

**Content:**

The `swaps` normalizer streams decoded Solana DEX trades into your warehouse as one unified table. See the [Solana normalizers page](/goldrush-pipeline-api/normalizers/solana) for the full per-column schema and supported protocols.

## Why warehouse delivery

Streaming and REST are great for live execution and lookups, but every retention cohort, churn model, token analytics dashboard, and tax export lives in your data warehouse - not in HTTP responses. The Pipeline API streams Solana data continuously into customer-managed destinations with no ETL on your side.

## Pipeline configuration


**Create a pipeline**

In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `solana-swaps`.


**Pick Solana + Swaps**

Choose **Solana** as the chain and **Swaps** as the data type.


**Configure your destination**

Connect ClickHouse, BigQuery, Postgres, Kafka, S3/GCS/R2, SQS, or a Webhook. ClickHouse is recommended for high-volume analytical queries over swaps.

    ```yaml
    destination:
      type: "clickhouse"
      url: "https://your-cluster.clickhouse.cloud:8443"
      user: "${CH_USER}"
      password: "${CH_PASSWORD}"
      database: "solana_swaps"
      batch_size: 5000
    ```


**Optional: SQL transform**

Filter or reshape rows before they land. Example: keep only swaps over $100 of volume.

    ```yaml
    transforms:
      swaps: >
        SELECT *
        FROM swaps
        WHERE volume_usd >= 100
    ```


**Deploy**

Decoded swaps begin flowing within seconds.

## Schema

The `swaps` table is documented in full on the [Solana Normalizers page](/goldrush-pipeline-api/normalizers/solana). Key columns include `block_slot`, `block_time`, `tx_id`, `signer`, `pool_address`, `base_mint`, `quote_mint`, `base_amount`, `quote_amount`, `price_usd`, `volume_usd`, `protocol_name`, and CPI attribution fields (`outer_program`, `inner_program`, `instruction_type`).

## Sample analytical queries

### Top tokens by 24h volume

```sql
SELECT
  base_mint,
  SUM(volume_usd) AS volume_24h
FROM swaps
WHERE block_time >= now() - INTERVAL 1 DAY
GROUP BY base_mint
ORDER BY volume_24h DESC
LIMIT 50;
```

### Per-protocol market share by token

```sql
SELECT
  protocol_name,
  SUM(volume_usd) AS volume_24h,
  COUNT(*) AS swap_count
FROM swaps
WHERE base_mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
  AND block_time >= now() - INTERVAL 1 DAY
GROUP BY protocol_name
ORDER BY volume_24h DESC;
```

### Whale activity

```sql
SELECT
  signer,
  SUM(volume_usd) AS volume_24h,
  COUNT(*) AS swap_count
FROM swaps
WHERE block_time >= now() - INTERVAL 1 DAY
GROUP BY signer
HAVING volume_24h > 1000000
ORDER BY volume_24h DESC;
```

### Jupiter routing through Raydium and Orca

```sql
SELECT
  tx_id,
  protocol_name,
  outer_program,
  inner_program,
  base_mint,
  quote_mint,
  volume_usd
FROM swaps
WHERE outer_program = 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4' -- Jupiter v6
  AND block_time >= now() - INTERVAL 1 HOUR
ORDER BY tx_id, instruction_index;
```

## Production tips

- **ClickHouse for high-volume analytics.** Solana swap volume is significant; analytical queries over millions of rows are much faster on ClickHouse than Postgres.
- **Partition by `block_date`.** Most analytical queries are time-bounded.
- **Materialized views for per-token metrics.** Build hourly / daily roll-ups in ClickHouse materialized views to keep dashboards snappy.

## Related

- [Solana Normalizers (full schema)](/goldrush-pipeline-api/normalizers/solana) - column-level reference for `swaps` and other Solana entities.
- [SPL Transfers warehouse recipe](/goldrush-solana/warehouse/spl-transfers) - companion table for transfer-side analytics.
- [DEX firehose (streaming)](/goldrush-solana/streaming/dex-firehose) - real-time push for new pair events.

---

## 9. Solana SPL Transfers to your warehouse

**Path:** goldrush-solana/warehouse/spl-transfers

**Metadata:**
```yaml
title: Solana SPL Transfers to your warehouse
sidebarTitle: SPL Transfers
description: Land decoded SPL token transfers on Solana into ClickHouse, BigQuery, Postgres, Kafka, or S3 via the `transfers` normalizer.
```

**Content:**

The `transfers` normalizer streams decoded SPL token transfers on Solana into your warehouse. Each row carries source/destination account context (owner, balance pre/post, UI amount). See the [Solana normalizers page](/goldrush-pipeline-api/normalizers/solana) for the full schema.

## Pipeline configuration


**Create a pipeline**

In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. Name it `solana-spl-transfers`.


**Pick Solana + Transfers**

Choose **Solana** as the chain and **Transfers** as the data type.


**Configure your destination**

Connect ClickHouse, BigQuery, Postgres, Kafka, S3/GCS/R2, SQS, or a Webhook.

    ```yaml
    destination:
      type: "postgres"
      url: "postgresql://your-host:5432/solana_data"
      user: "${PG_USER}"
      password: "${PG_PASSWORD}"
      batch_size: 1000
    ```


**Optional: SQL transform**

Filter rows before they land. Example: keep only stablecoin transfers.

    ```yaml
    transforms:
      transfers: >
        SELECT *
        FROM transfers
        WHERE mint IN (
          'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',  -- USDC
          'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'   -- USDT
        )
    ```


**Deploy**

Decoded transfers begin flowing within seconds.

## Schema

The `transfers` table is documented in full on the [Solana Normalizers page](/goldrush-pipeline-api/normalizers/solana). Key columns:

- `block_slot`, `slot`, `block_time`, `tx_hash` (signature).
- `mint`, `amount` (raw uint64), `token_decimals`, `is_raw_amount`.
- `source_address` (token account), `source_owner` (wallet pubkey).
- `destination_address`, `destination_owner`.
- Pre/post balances on both sides (`*_pre_balance`, `*_post_balance`) plus UI-amount variants.
- `transfer_index` for ordering within a transaction.

## Sample analytical queries

### Daily stablecoin volume by mint

```sql
SELECT
  date_trunc('day', to_timestamp(block_time)) AS day,
  mint,
  SUM(amount::numeric / power(10, token_decimals)) AS volume_tokens
FROM transfers
WHERE mint IN (
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'
)
  AND block_time >= extract(epoch from now() - interval '30 days')
GROUP BY day, mint
ORDER BY day DESC, volume_tokens DESC;
```

### Net flow per wallet for a token

```sql
WITH inflow AS (
  SELECT destination_owner AS wallet, mint, SUM(amount::numeric) AS in_amount
  FROM transfers
  WHERE mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
  GROUP BY destination_owner, mint
),
outflow AS (
  SELECT source_owner AS wallet, mint, SUM(amount::numeric) AS out_amount
  FROM transfers
  WHERE mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
  GROUP BY source_owner, mint
)
SELECT
  COALESCE(i.wallet, o.wallet) AS wallet,
  COALESCE(i.in_amount, 0) - COALESCE(o.out_amount, 0) AS net
FROM inflow i
FULL OUTER JOIN outflow o ON i.wallet = o.wallet AND i.mint = o.mint
ORDER BY net DESC
LIMIT 100;
```

### Exchange deposit attribution

Maintain a table of known exchange wallets; join against `destination_owner` to attribute deposits.

```sql
SELECT
  ex.exchange_name,
  t.mint,
  date_trunc('day', to_timestamp(t.block_time)) AS day,
  SUM(t.amount::numeric / power(10, t.token_decimals)) AS deposits
FROM transfers t
JOIN known_exchanges ex ON t.destination_owner = ex.wallet
WHERE t.block_time >= extract(epoch from now() - interval '7 days')
GROUP BY ex.exchange_name, t.mint, day
ORDER BY day DESC, deposits DESC;
```

## Production tips

- **`source_owner` and `destination_owner`** are the *wallet* pubkeys, not the SPL token-account pubkeys. Index on these for wallet-centric queries.
- **`amount` is raw uint64.** Always divide by `power(10, token_decimals)` (or use the `*_ui` balance columns) for human-readable amounts.
- **High-volume mints (USDC, USDT, WSOL).** Partition by date and consider materialized views per top-N mint for fast dashboarding.

## Related

- [Solana Normalizers (full schema)](/goldrush-pipeline-api/normalizers/solana) - column-level reference for `transfers` and other Solana entities.
- [DEX Swaps warehouse recipe](/goldrush-solana/warehouse/dex-swaps) - companion table for DEX-trade analytics.
- [Wallet endpoints (REST)](/goldrush-solana/foundational/wallet) - REST lookups for the same transfer history.

---

# 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="
```

```bash Chain Name (ADI Testnet)
curl -X GET "https://api.covalenthq.com/v1/adi-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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 on ADI Chain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on ADI Chain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on ADI Chain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on ADI Chain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on ADI Chain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on ADI Chain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on ADI Chain](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on ADI Chain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on ADI Chain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on ADI Chain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on ADI Chain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on ADI Chain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on ADI Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on ADI Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on ADI Chain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on ADI Chain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on ADI Chain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on ADI Chain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on ADI Chain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on ADI Chain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on ADI Chain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on ADI Chain](/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. 24 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "apechain-mainnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **24**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on ApeChain](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on ApeChain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on ApeChain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on ApeChain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on ApeChain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on ApeChain](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on ApeChain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on ApeChain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on ApeChain](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on ApeChain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on ApeChain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on ApeChain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on ApeChain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on ApeChain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on ApeChain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on ApeChain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on ApeChain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on ApeChain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on ApeChain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on ApeChain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on ApeChain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on ApeChain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on ApeChain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on ApeChain](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Arbitrum Nova](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Arbitrum Nova](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Arbitrum Nova](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Arbitrum Nova](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Arbitrum Nova](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Arbitrum Nova](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Arbitrum Nova](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Arbitrum Nova](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Arbitrum Nova](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Arbitrum Nova](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Arbitrum Nova](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Arbitrum Nova](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Arbitrum Nova](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Arbitrum Nova](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Arbitrum Nova](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Arbitrum Nova](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Arbitrum Nova](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Arbitrum Nova](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Arbitrum Nova](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Arbitrum Nova](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Arbitrum Nova](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Arbitrum Nova](/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. 24 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="
```

```bash Chain Name (Arbitrum Sepolia Testnet)
curl -X GET "https://api.covalenthq.com/v1/arbitrum-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "arbitrum-sepolia",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **24**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Arbitrum](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Arbitrum](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Arbitrum](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Arbitrum](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Arbitrum](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Arbitrum](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on Arbitrum](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Arbitrum](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Arbitrum](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Arbitrum](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Arbitrum](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Arbitrum](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Arbitrum](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Arbitrum](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Arbitrum](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Arbitrum](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Arbitrum](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Arbitrum](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Arbitrum](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Arbitrum](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Arbitrum](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Arbitrum](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Arbitrum](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Arbitrum](/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="
```

#### SDK Usage

```typescript TypeScript SDK
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Arc Testnet](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Arc Testnet](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Arc Testnet](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Arc Testnet](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Arc Testnet](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Arc Testnet](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Arc Testnet](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Arc Testnet](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Arc Testnet](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Arc Testnet](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Arc Testnet](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Arc Testnet](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Arc Testnet](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Arc Testnet](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Arc Testnet](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Arc Testnet](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Arc Testnet](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Arc Testnet](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Arc Testnet](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Arc Testnet](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Arc Testnet](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Arc Testnet](/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. 23 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="
```

```bash Chain Name (Avalanche Fuji Testnet)
curl -X GET "https://api.covalenthq.com/v1/avalanche-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "avalanche-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Avalanche C-Chain](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Avalanche C-Chain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Avalanche C-Chain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Avalanche C-Chain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Avalanche C-Chain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Avalanche C-Chain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Avalanche C-Chain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Avalanche C-Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Avalanche C-Chain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Avalanche C-Chain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Avalanche C-Chain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Avalanche C-Chain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Avalanche C-Chain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Avalanche C-Chain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Avalanche C-Chain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Avalanche C-Chain](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Axie/Ronin](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Axie/Ronin](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Axie/Ronin](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Axie/Ronin](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Axie/Ronin](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Axie/Ronin](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Axie/Ronin](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Axie/Ronin](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Axie/Ronin](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Axie/Ronin](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Axie/Ronin](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Axie/Ronin](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Axie/Ronin](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Axie/Ronin](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Axie/Ronin](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Axie/Ronin](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Axie/Ronin](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Axie/Ronin](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Axie/Ronin](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Axie/Ronin](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Axie/Ronin](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Axie/Ronin](/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. 39 endpoints 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 |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `base-mainnet` / `BASE_MAINNET` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/base-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "base-mainnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **28**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Base](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on Base](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on Base](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Base](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Base](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Base](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Base](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on Base](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on Base](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on Base](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on Base](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Base](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Base](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Base](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Base](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Base](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Base](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Base](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Base](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Base](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Base](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Base](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Base](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Base](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Base](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Base](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Base](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Base](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Base](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Base](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Base](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Base](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Base](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on Base](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on Base](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Base](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Base](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on Base](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Base](/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. 23 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="
```

```bash Chain Name (Berachain Testnet)
curl -X GET "https://api.covalenthq.com/v1/berachain-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "berachain-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Berachain](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Berachain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Berachain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Berachain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Berachain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Berachain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Berachain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Berachain](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Berachain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Berachain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Berachain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Berachain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Berachain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Berachain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Berachain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Berachain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Berachain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Berachain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Berachain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Berachain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Berachain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Berachain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Berachain](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Blast](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Blast](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Blast](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Blast](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Blast](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Blast](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Blast](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Blast](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Blast](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Blast](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Blast](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Blast](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Blast](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Blast](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Blast](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Blast](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Blast](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Blast](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Blast](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Blast](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Blast](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Blast](/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). 39 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="
```

```bash Chain Name (BNB Smart Chain (BSC) Testnet)
curl -X GET "https://api.covalenthq.com/v1/bsc-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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) on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on BNB Smart Chain (BSC)](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on BNB Smart Chain (BSC)](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on BNB Smart Chain (BSC)](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on BNB Smart Chain (BSC)](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on BNB Smart Chain (BSC)](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on BNB Smart Chain (BSC)](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on BNB Smart Chain (BSC)](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on BNB Smart Chain (BSC)](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on BNB Smart Chain (BSC)](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on BNB Smart Chain (BSC)](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Canto](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Canto](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Canto](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Canto](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Canto](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Canto](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Canto](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Canto](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Canto](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Canto](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Canto](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Canto](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Canto](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Canto](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Canto](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Canto](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Canto](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Canto](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Canto](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Canto](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Canto](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Canto](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Celo](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Celo](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Celo](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Celo](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Celo](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Celo](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Celo](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Celo](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Celo](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Celo](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Celo](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Celo](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Celo](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Celo](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Celo](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Celo](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Celo](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Celo](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Celo](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Celo](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Celo](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Celo](/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 Streaming Subscription

```graphql GraphQL Subscription
subscription {
  walletTxs(
    chain_name: COVALENT_INTERNAL_NETWORK_V1,
    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("");

client.StreamingService.subscribeToWalletTxs(
  {
    chain_name: StreamingChain.COVALENT_INTERNAL_NETWORK_V1,
    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/)

---

## 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Cronos zkEVM](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Cronos zkEVM](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Cronos zkEVM](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Cronos zkEVM](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Cronos zkEVM](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Cronos zkEVM](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Cronos zkEVM](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Cronos zkEVM](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Cronos zkEVM](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Cronos zkEVM](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Cronos zkEVM](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Cronos zkEVM](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Cronos zkEVM](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Cronos zkEVM](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Cronos zkEVM](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Cronos zkEVM](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Cronos zkEVM](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Cronos zkEVM](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Cronos zkEVM](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Cronos zkEVM](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Cronos zkEVM](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Cronos zkEVM](/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("");

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. 39 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="
```

```bash Chain Name (Holesky Testnet)
curl -X GET "https://api.covalenthq.com/v1/eth-holesky/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

```bash Chain Name (Ethereum Sepolia Testnet)
curl -X GET "https://api.covalenthq.com/v1/eth-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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("");
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) on Ethereum](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on Ethereum](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on Ethereum](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Ethereum](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Ethereum](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Ethereum](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Ethereum](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on Ethereum](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on Ethereum](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on Ethereum](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on Ethereum](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Ethereum](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Ethereum](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Ethereum](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Ethereum](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Ethereum](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Ethereum](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Ethereum](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Ethereum](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Ethereum](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Ethereum](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Ethereum](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Ethereum](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Ethereum](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Ethereum](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Ethereum](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Ethereum](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Ethereum](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Ethereum](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Ethereum](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Ethereum](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Ethereum](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Ethereum](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on Ethereum](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on Ethereum](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Ethereum](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Ethereum](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on Ethereum](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Ethereum](/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="
```

```bash Chain Name (Fantom Testnet)
curl -X GET "https://api.covalenthq.com/v1/fantom-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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 on Fantom](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Fantom](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Fantom](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Fantom](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Fantom](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Fantom](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Fantom](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Fantom](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Fantom](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Fantom](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Fantom](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Fantom](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Fantom](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Fantom](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Fantom](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Fantom](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Fantom](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Fantom](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Fantom](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Fantom](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Fantom](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Fantom](/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="
```

```bash Chain Name (Chiado Testnet)
curl -X GET "https://api.covalenthq.com/v1/gnosis-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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) on Gnosis](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on Gnosis](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on Gnosis](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Gnosis](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Gnosis](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Gnosis](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Gnosis](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on Gnosis](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on Gnosis](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on Gnosis](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on Gnosis](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Gnosis](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Gnosis](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Gnosis](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Gnosis](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Gnosis](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Gnosis](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Gnosis](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Gnosis](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Gnosis](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Gnosis](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Gnosis](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Gnosis](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Gnosis](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Gnosis](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Gnosis](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Gnosis](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Gnosis](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **2** GoldRush Streaming APIs:
- [Top Trader Wallets for Token Query on Gnosis](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Gnosis](/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("");

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:**

## 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("");

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 **5** GoldRush Streaming APIs:
- [OHLCV Pairs Stream on HyperCore](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on HyperCore](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Wallet Activity Stream on HyperCore](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on HyperCore](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on HyperCore](/api-reference/streaming-api/queries/ohlcv-tokens-query/)

## 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. 30 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on HyperEVM](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on HyperEVM](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on HyperEVM](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on HyperEVM](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on HyperEVM](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on HyperEVM](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on HyperEVM](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on HyperEVM](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on HyperEVM](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on HyperEVM](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on HyperEVM](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on HyperEVM](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on HyperEVM](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on HyperEVM](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on HyperEVM](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on HyperEVM](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on HyperEVM](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on HyperEVM](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on HyperEVM](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on HyperEVM](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on HyperEVM](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on HyperEVM](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **8** GoldRush Streaming APIs:
- [New DEX Pairs Stream on HyperEVM](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on HyperEVM](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on HyperEVM](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on HyperEVM](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on HyperEVM](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on HyperEVM](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on HyperEVM](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on HyperEVM](/api-reference/streaming-api/queries/ohlcv-tokens-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#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="
```

```bash Chain Name (Ink Testnet)
curl -X GET "https://api.covalenthq.com/v1/ink-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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 on Ink](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Ink](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Ink](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Ink](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Ink](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Ink](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Ink](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Ink](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Ink](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Ink](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Ink](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Ink](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Ink](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Ink](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Ink](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Ink](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Ink](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Ink](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Ink](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Ink](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Ink](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Ink](/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. 24 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="
```

```bash Chain Name (Linea Sepolia Testnet)
curl -X GET "https://api.covalenthq.com/v1/linea-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "linea-sepolia-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **24**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Linea](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Linea](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Linea](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Linea](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Linea](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Linea](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on Linea](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Linea](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Linea](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Linea](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Linea](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Linea](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Linea](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Linea](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Linea](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Linea](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Linea](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Linea](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Linea](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Linea](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Linea](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Linea](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Linea](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Linea](/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="
```

```bash Chain Name (Lisk Sepolia Testnet)
curl -X GET "https://api.covalenthq.com/v1/lisk-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash  
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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="
```

#### SDK Usage

```typescript TypeScript SDK
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Manta Pacific Testnet](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Manta Pacific Testnet](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Manta Pacific Testnet](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Manta Pacific Testnet](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Manta Pacific Testnet](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Manta Pacific Testnet](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Manta Pacific Testnet](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Manta Pacific Testnet](/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. 24 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "mantle-mainnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **24**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Mantle](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Mantle](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Mantle](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Mantle](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Mantle](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Mantle](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on Mantle](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Mantle](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Mantle](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Mantle](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Mantle](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Mantle](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Mantle](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Mantle](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Mantle](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Mantle](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Mantle](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Mantle](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Mantle](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Mantle](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Mantle](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Mantle](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Mantle](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Mantle](/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. 33 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on MegaETH](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on MegaETH](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on MegaETH](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on MegaETH](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on MegaETH](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on MegaETH](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on MegaETH](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on MegaETH](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on MegaETH](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on MegaETH](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on MegaETH](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on MegaETH](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on MegaETH](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on MegaETH](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on MegaETH](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on MegaETH](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on MegaETH](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on MegaETH](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on MegaETH](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on MegaETH](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on MegaETH](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on MegaETH](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on MegaETH](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on MegaETH](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on MegaETH](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on MegaETH](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on MegaETH](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on MegaETH](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on MegaETH](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on MegaETH](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on MegaETH](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on MegaETH](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on MegaETH](/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. 31 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="
```

```bash Chain Name (Monad Testnet)
curl -X GET "https://api.covalenthq.com/v1/monad-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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 on Monad](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Monad](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Monad](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Monad](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Monad](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Monad](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Monad](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Monad](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Monad](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Monad](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Monad](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Monad](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Monad](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Monad](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Monad](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Monad](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Monad](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Monad](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Monad](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Monad](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Monad](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Monad](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **9** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Monad](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Monad](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Monad](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Monad](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Monad](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on Monad](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on Monad](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Monad](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Monad](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Moonbeam](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Moonbeam](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Moonbeam](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Moonbeam](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Moonbeam](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Moonbeam](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Moonbeam](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Moonbeam](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Moonbeam](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Moonbeam](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Moonbeam](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Moonbeam](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Moonbeam](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Moonbeam](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Moonbeam](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Moonbeam](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Moonbeam](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Moonbeam](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Moonbeam](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Moonbeam](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Moonbeam](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Moonbeam](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Moonriver](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Moonriver](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Moonriver](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Moonriver](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Moonriver](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Moonriver](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Moonriver](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Moonriver](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Moonriver](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Moonriver](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Moonriver](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Moonriver](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Moonriver](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Moonriver](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Moonriver](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Moonriver](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Moonriver](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Moonriver](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Moonriver](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Moonriver](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Moonriver](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Moonriver](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Oasis Sapphire](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Oasis Sapphire](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Oasis Sapphire](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Oasis Sapphire](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Oasis Sapphire](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Oasis Sapphire](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Oasis Sapphire](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Oasis Sapphire](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Oasis Sapphire](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Oasis Sapphire](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Oasis Sapphire](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Oasis Sapphire](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Oasis Sapphire](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Oasis Sapphire](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Oasis Sapphire](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Oasis Sapphire](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Oasis Sapphire](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Oasis Sapphire](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Oasis Sapphire](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Oasis Sapphire](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Oasis Sapphire](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Oasis Sapphire](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Oasis](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Oasis](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Oasis](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Oasis](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Oasis](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Oasis](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Oasis](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Oasis](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Oasis](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Oasis](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Oasis](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Oasis](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Oasis](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Oasis](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Oasis](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Oasis](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Oasis](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Oasis](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Oasis](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Oasis](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Oasis](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Oasis](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on opBNB](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on opBNB](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on opBNB](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on opBNB](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on opBNB](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on opBNB](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on opBNB](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on opBNB](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on opBNB](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on opBNB](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on opBNB](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on opBNB](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on opBNB](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on opBNB](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on opBNB](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on opBNB](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on opBNB](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on opBNB](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on opBNB](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on opBNB](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on opBNB](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on opBNB](/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="
```

```bash Chain Name (Optimism Sepolia Testnet)
curl -X GET "https://api.covalenthq.com/v1/optimism-sepolia/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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) on Optimism](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on Optimism](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on Optimism](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Optimism](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Optimism](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Optimism](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Optimism](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on Optimism](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on Optimism](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on Optimism](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on Optimism](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Optimism](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Optimism](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Optimism](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Optimism](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Optimism](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Optimism](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Optimism](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Optimism](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Optimism](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Optimism](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Optimism](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Optimism](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Optimism](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Optimism](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Optimism](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Optimism](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Optimism](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **2** GoldRush Streaming APIs:
- [Top Trader Wallets for Token Query on Optimism](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Optimism](/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. 23 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="
```

```bash Chain Name (Plasma Testnet)
curl -X GET "https://api.covalenthq.com/v1/plasma-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "plasma-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Plasma](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Plasma](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Plasma](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Plasma](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Plasma](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Plasma](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Plasma](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Plasma](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Plasma](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Plasma](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Plasma](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Plasma](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Plasma](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Plasma](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Plasma](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Plasma](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Plasma](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Plasma](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Plasma](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Plasma](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Plasma](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Plasma](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Plasma](/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. 39 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="
```

```bash Chain Name (Polygon Amoy Testnet)
curl -X GET "https://api.covalenthq.com/v1/polygon-amoy-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
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) on Polygon](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get historical token balances for address on Polygon](/api-reference/foundational-api/balances/get-historical-token-balances-for-address/)**
- **[Get token balances for address on Polygon](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Polygon](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Polygon](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Polygon](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Polygon](/api-reference/foundational-api/nft/get-nfts-for-address/)**
- **[Check ownership in NFT collection on Polygon](/api-reference/foundational-api/nft/check-ownership-in-nft-collection/)**
- **[Check ownership in NFT collection for specific token on Polygon](/api-reference/foundational-api/nft/check-ownership-in-nft-collection-token/)**

#### Pricing API

- **[Get pool spot prices on Polygon](/api-reference/foundational-api/utility/get-pool-spot-prices/)**
- **[Get historical token prices on Polygon](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Polygon](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Polygon](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Polygon](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Polygon](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Polygon](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Polygon](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Polygon](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Polygon](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Polygon](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Polygon](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Polygon](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Polygon](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Polygon](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Polygon](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Polygon](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Polygon](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Polygon](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Polygon](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Polygon](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Polygon](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Polygon](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Polygon](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on Polygon](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on Polygon](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Polygon](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Polygon](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on Polygon](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Polygon](/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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Redstone](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Redstone](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Redstone](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Redstone](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Redstone](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Redstone](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Redstone](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Redstone](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Redstone](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Redstone](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Redstone](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Redstone](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Redstone](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Redstone](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Redstone](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Redstone](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Redstone](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Redstone](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Redstone](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Redstone](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Redstone](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Redstone](/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. Robinhood Chain Onchain Data API

**Path:** chains/robinhood-chain

**Metadata:**
```yaml
title: Robinhood Chain Onchain Data API
sidebarTitle: Robinhood Chain
description: Get token balances, transactions, and OHLCV pricing data for Robinhood Chain. 33 endpoints supported.
```

**Content:**

## Overview

> **Tip:** Robinhood Chain is a permissionless, AI-native Layer 2 blockchain built for financial services and real-world assets.

GoldRush offers the most comprehensive Robinhood 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 Robinhood 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)

### 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** | `robinhood-mainnet` (Foundational API) / `ROBINHOOD_MAINNET` (Streaming API) |
| **Chain ID** | `4663` |
| **Network Type** | Frontier Chain |
| **Support Level** | frontier |
| **Block Explorer** | [Robinhood Chain explorer](https://robinhoodchain.blockscout.com/) |
| **Official Website** | [Robinhood Chain Website](https://robinhood.com/ca/en/chain/) |
| **Native Gas Token** | ETH |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `robinhood-mainnet` / `ROBINHOOD_MAINNET` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/robinhood-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "robinhood-mainnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **22**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token balances for address on Robinhood Chain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Robinhood Chain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Robinhood Chain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Robinhood Chain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Robinhood Chain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Robinhood Chain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Robinhood Chain](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Robinhood Chain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Robinhood Chain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Robinhood Chain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Robinhood Chain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Robinhood Chain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Robinhood Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Robinhood Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Robinhood Chain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Robinhood Chain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Robinhood Chain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Robinhood Chain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Robinhood Chain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Robinhood Chain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Robinhood Chain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Robinhood Chain](/api-reference/foundational-api/utility/get-logs/)**

## Streaming API Support

This chain supports **11** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [Wallet Activity Stream on Robinhood Chain](/api-reference/streaming-api/subscriptions/wallet-activity-stream/)
- [OHLCV Pairs Query on Robinhood Chain](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Robinhood Chain](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Robinhood Chain](/api-reference/streaming-api/queries/token-search-query/)
- [Top Trader Wallets for Token Query on Robinhood Chain](/api-reference/streaming-api/queries/upnl-for-token-query/)
- [Wallet PnL by Token Query on Robinhood Chain](/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/)

---

## 41. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Scroll](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Scroll](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Scroll](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Scroll](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on Scroll](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on Scroll](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Scroll](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Scroll](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Scroll](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Scroll](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Scroll](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Scroll](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Scroll](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Scroll](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Scroll](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Scroll](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Scroll](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Scroll](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Scroll](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Scroll](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Scroll](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Scroll](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Scroll](/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/)

---

## 42. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Sei](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Sei](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Sei](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Sei](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Sei](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Sei](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Sei](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Sei](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Sei](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Sei](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Sei](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Sei](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Sei](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Sei](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Sei](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Sei](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Sei](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Sei](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Sei](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Sei](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Sei](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Sei](/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/)

---

## 43. Solana

**Path:** chains/solana

**Metadata:**
```yaml
title: Solana
sidebarTitle: Solana
description: Solana data API - indexed SPL token balances (REST), a real-time DEX firehose (Raydium / Orca / Meteora / Jupiter / PumpFun) with OHLCV candles, plus historical decoded swaps and SPL transfers delivered to your warehouse.
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, PumpFun memecoin discovery, and consumer applications at scale.

## 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "solana-mainnet",
    walletAddress: "4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY"
});
```

## Foundational API Support

## Streaming API Support

This chain supports **8** GoldRush Streaming APIs:
- [New DEX Pairs Stream on Solana](/api-reference/streaming-api/subscriptions/new-dex-pairs-stream/)
- [OHLCV Pairs Stream on Solana](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream/)
- [OHLCV Tokens Stream on Solana](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream/)
- [Update Pairs Stream on Solana](/api-reference/streaming-api/subscriptions/update-pairs-stream/)
- [Update Tokens Stream on Solana](/api-reference/streaming-api/subscriptions/update-tokens-stream/)
- [OHLCV Pairs Query on Solana](/api-reference/streaming-api/queries/ohlcv-pairs-query/)
- [OHLCV Tokens Query on Solana](/api-reference/streaming-api/queries/ohlcv-tokens-query/)
- [Token Search Query on Solana](/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

---

## 44. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Sonic](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Sonic](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Sonic](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Sonic](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Sonic](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Sonic](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Sonic](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Sonic](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Sonic](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Sonic](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Sonic](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Sonic](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Sonic](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Sonic](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Sonic](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Sonic](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Sonic](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Sonic](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Sonic](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Sonic](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Sonic](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Sonic](/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. Taiko

**Path:** chains/taiko

**Metadata:**
```yaml
title: Taiko
sidebarTitle: Taiko
description: Get token balances and transactions for Taiko. 23 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "taiko-mainnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Taiko](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Taiko](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Taiko](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Taiko](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Taiko](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Taiko](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Taiko](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Taiko](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Taiko](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Taiko](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Taiko](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Taiko](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Taiko](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Taiko](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Taiko](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Taiko](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Taiko](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Taiko](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Taiko](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Taiko](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Taiko](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Taiko](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Taiko](/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/)

---

## 46. 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("");

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/)

---

## 47. Unichain

**Path:** chains/unichain

**Metadata:**
```yaml
title: Unichain
sidebarTitle: Unichain
description: Get token balances and transactions for Unichain. 23 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="
```

```bash Chain Name (Unichain Testnet)
curl -X GET "https://api.covalenthq.com/v1/unichain-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "unichain-sepolia-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on Unichain](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on Unichain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Unichain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Unichain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Unichain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Unichain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Unichain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Unichain](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on Unichain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Unichain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on Unichain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on Unichain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on Unichain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Unichain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Unichain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Unichain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Unichain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Unichain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Unichain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Unichain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Unichain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Unichain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Unichain](/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. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on Viction](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on Viction](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on Viction](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on Viction](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on Viction](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on Viction](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on Viction](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on Viction](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on Viction](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on Viction](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on Viction](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on Viction](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on Viction](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on Viction](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on Viction](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on Viction](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on Viction](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on Viction](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on Viction](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on Viction](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on Viction](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on Viction](/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. World Chain

**Path:** chains/world-chain

**Metadata:**
```yaml
title: World Chain
sidebarTitle: World Chain
description: Get token balances and transactions for World Chain. 23 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="
```

```bash Chain Name (World Chain  Testnet)
curl -X GET "https://api.covalenthq.com/v1/world-sepolia-testnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

```bash
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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("");
const resp = await client.BalanceService.getTokenBalancesForWalletAddress({
    chainName: "world-sepolia-testnet",
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
});
```

## Foundational API Support
 
This chain supports **23**  GoldRush Foundational APIs:

#### Wallet API

- **[Get token holders as of any block height (v2) on World Chain](/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2/)**
- **[Get token balances for address on World Chain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on World Chain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on World Chain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on World Chain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on World Chain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on World Chain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on World Chain](/api-reference/foundational-api/transactions/get-a-transaction/)** `with-traces`
- **[Get transaction summary for address on World Chain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on World Chain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)** `with-traces`
- **[Get recent transactions for address (v3) on World Chain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)** `with-traces`
- **[Get paginated transactions for address (v3) on World Chain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)** `with-traces`
- **[Get bulk time bucket transactions for address (v3) on World Chain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on World Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on World Chain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on World Chain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on World Chain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on World Chain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on World Chain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on World Chain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on World Chain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on World Chain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on World Chain](/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. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on ZetaChain](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on ZetaChain](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on ZetaChain](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on ZetaChain](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### Pricing API

- **[Get historical token prices on ZetaChain](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on ZetaChain](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on ZetaChain](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on ZetaChain](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on ZetaChain](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on ZetaChain](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on ZetaChain](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on ZetaChain](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on ZetaChain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on ZetaChain](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on ZetaChain](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on ZetaChain](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on ZetaChain](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on ZetaChain](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on ZetaChain](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on ZetaChain](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on ZetaChain](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on ZetaChain](/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/)

---

## 51. 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="
```

#### SDK Usage

```typescript TypeScript SDK (Mainnet)
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("");
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 on zkSync Era](/api-reference/foundational-api/balances/get-token-balances-for-address/)**
- **[Get native token balance for address on zkSync Era](/api-reference/foundational-api/balances/get-native-token-balance/)**
- **[Get historical portfolio value over time on zkSync Era](/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time/)**
- **[Get ERC20 token transfers for address on zkSync Era](/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address/)**

#### NFT API

- **[Get NFTs for address on zkSync Era](/api-reference/foundational-api/nft/get-nfts-for-address/)**

#### Pricing API

- **[Get historical token prices on zkSync Era](/api-reference/foundational-api/utility/get-historical-token-prices/)**

#### Security API

- **[Get token approvals for address on zkSync Era](/api-reference/foundational-api/security/get-token-approvals-for-address/)**

#### Transactions API

- **[Get a transaction on zkSync Era](/api-reference/foundational-api/transactions/get-a-transaction/)**
- **[Get transaction summary for address on zkSync Era](/api-reference/foundational-api/transactions/get-transaction-summary-for-address/)**
- **[Get earliest transactions for address (v3)  on zkSync Era](/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3/)**
- **[Get recent transactions for address (v3) on zkSync Era](/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3/)**
- **[Get paginated transactions for address (v3) on zkSync Era](/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3/)**
- **[Get bulk time bucket transactions for address (v3) on zkSync Era](/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3/)**
- **[Get all transactions in a block (v3) on zkSync Era](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block/)**
- **[Get all transactions in a block by page (v3)  on zkSync Era](/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page/)**

#### Block Explorer API

- **[Get a block on zkSync Era](/api-reference/foundational-api/utility/get-a-block/)**
- **[Get all chain statuses on zkSync Era](/api-reference/foundational-api/utility/get-all-chain-statuses/)**
- **[Get all chains on zkSync Era](/api-reference/foundational-api/utility/get-all-chains/)**
- **[Get block heights on zkSync Era](/api-reference/foundational-api/utility/get-block-heights/)**
- **[Get gas prices on zkSync Era](/api-reference/foundational-api/utility/get-gas-prices/)**
- **[Get log events by contract address on zkSync Era](/api-reference/foundational-api/utility/get-log-events-by-contract-address/)**
- **[Get log events by topic hash(es) on zkSync Era](/api-reference/foundational-api/utility/get-log-events-by-topic-hash/)**
- **[Get logs on zkSync Era](/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/)

---