# 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 the right API for your use case
- [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
- [Hyperliquid API](#hyperliquid-api-documentation) - 84 pages (Info API, streaming recipes, and API reference)
- [Solana API](#solana-api-documentation) - 6 pages (Foundational walkthroughs, warehouse recipes)
- [x402 API](#x402-api-documentation) - Pay-per-request access for AI agents (60+ endpoints)
- [Chain Documentation](#chain-documentation) - 50 supported chains

---

# API Selection Guide

## Choosing the Right API

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

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

## 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
- HB = Historical Balances, NFT = NFT Assets & Metadata

#### Foundational Chains

| Chain Name | APIs | Advanced Features | Block Time | Network |
|------------|------|-------------------|------------|---------|
| Base (`base-mainnet`) | F | HB | 2s | Mainnet |
| BNB Smart Chain (BSC) (`bsc-mainnet`) | F | HB | 5s | Mainnet |
| Ethereum (`eth-mainnet`) | F | HB | 12s | Mainnet |
| Gnosis (`gnosis-mainnet`) | F | - | 5s | Mainnet |
| Optimism (`optimism-mainnet`) | F | - | 2s | Mainnet |
| Polygon (`matic-mainnet`) | F | 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`) | - | - | 1s | Mainnet |
| HyperEVM (`hyperevm-mainnet`) | F | - | 1s | Mainnet |
| Ink (`ink-mainnet`) | F | - | 1s | Mainnet |
| Linea (`linea-mainnet`) | F | - | 10s | Mainnet |
| Mantle (`mantle-mainnet`) | F | - | 15s | Mainnet |
| MegaETH (`megaeth-mainnet`) | F | - | 1s | Mainnet |
| Monad (`monad-mainnet`) | F | - | 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 | - | 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
- **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)

### NFT & Token Queries
- Get NFT holdings → `getNftsForAddress` (primary, REST, 1 per call)
- 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
- Get token price history → `getTokenPrices` (primary, REST, 1 per call)
- Get DEX pool prices → `getPoolSpotPrices` (specialized, REST, Foundational only)

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

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

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

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

---

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

### 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 Backtesting (Foundational)
```
1. getTokenPrices → Get historical price data for backtesting
2. getHistoricalPortfolioForWalletAddress → Analyze historical performance
```
**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
```
Historical Records (Foundational API):
1. getHistoricalTokenBalancesForWalletAddress → Ownership history at specific blocks
2. getTransactionsForAddressV3 → Complete transfer history
3. getTokenHoldersV2ForTokenAddress → Token holder snapshots
```
**Use case:** RWA registries, compliance platforms, 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

---

# 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, 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` + [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` + 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) |

---

## 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 and 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 [`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. |
| `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). 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 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.

Forty-nine wire-compatible `type` values are supported today across market metadata, user state, user history, vaults, and staking - plus six GoldRush-native types (two batched state lookups, two builder-keyed fill feeds, a portfolio composite, and an all-DEX metadata fan-out) 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. Six GoldRush-native types (`batchClearinghouseState`, `batchSpotClearinghouseState`, `builderFills`, `builderFillsByTime`, `portfolioState`, `allPerpMetas`) 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`). |
| [`allPerpMetas`](/api-reference/hyperliquid-info/all-perp-metas) | `{"type": "allPerpMetas"}` | Universe + margin tables for **every** perp DEX in one array (index `0` = native, then HIP-3 DEXes in `perpDexs` order). **GoldRush-native**. |
| [`allMids`](/api-reference/hyperliquid-info/all-mids) | `{"type": "allMids", "dex": ""}` | Current mid price for every actively traded coin, as a `coin → price` map (spot pairs keyed `@index`). |
| [`perpDexLimits`](/api-reference/hyperliquid-info/perp-dex-limits) | `{"type": "perpDexLimits", "dex": "xyz"}` | Per-DEX open-interest, position-size, and transfer limits for a HIP-3 perp DEX. |
| [`marginTable`](/api-reference/hyperliquid-info/margin-table) | `{"type": "marginTable", "id": 56}` | Margin-tier (leverage-bracket) table for a `marginTableId`. |
| [`maxMarketOrderNtls`](/api-reference/hyperliquid-info/max-market-order-ntls) | `{"type": "maxMarketOrderNtls"}` | Maximum market-order notional for each leverage bucket. |
| [`perpsAtOpenInterestCap`](/api-reference/hyperliquid-info/perps-at-open-interest-cap) | `{"type": "perpsAtOpenInterestCap"}` | List of perp coins currently at their open-interest cap. |
| [`exchangeStatus`](/api-reference/hyperliquid-info/exchange-status) | `{"type": "exchangeStatus"}` | Current exchange operational status and server time. |
| [`validatorL1Votes`](/api-reference/hyperliquid-info/validator-l1-votes) | `{"type": "validatorL1Votes"}` | Pending validator L1 governance votes/actions. |
| [`spotDeployState`](/api-reference/hyperliquid-info/spot-deploy-state) | `{"type": "spotDeployState", "user": "0x…"}` | Spot-token deployment state and gas auction for a deployer. |
| [`perpDeployAuctionStatus`](/api-reference/hyperliquid-info/perp-deploy-auction-status) | `{"type": "perpDeployAuctionStatus"}` | Current perp-deploy Dutch-auction status. |
| [`liquidatable`](/api-reference/hyperliquid-info/liquidatable) | `{"type": "liquidatable"}` | Accounts currently eligible for liquidation. |

### 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. |
| [`openOrders`](/api-reference/hyperliquid-info/open-orders) | `{"type": "openOrders", "user": "0x…", "dex": ""}` | A wallet's resting open orders (coin, side, `limitPx`, `sz`, `oid`). |
| [`userRole`](/api-reference/hyperliquid-info/user-role) | `{"type": "userRole", "user": "0x…"}` | Account role - `user`, `agent`, `vault`, or `subAccount` (with its master). |
| [`userFees`](/api-reference/hyperliquid-info/user-fees) | `{"type": "userFees", "user": "0x…"}` | Fee schedule and recent daily trading volume for a wallet. |
| [`userRateLimit`](/api-reference/hyperliquid-info/user-rate-limit) | `{"type": "userRateLimit", "user": "0x…"}` | API rate-limit usage, cap, and cumulative volume. |
| [`userAbstraction`](/api-reference/hyperliquid-info/user-abstraction) | `{"type": "userAbstraction", "user": "0x…"}` | Account-abstraction mode (`"disabled"` or `"unifiedAccount"`). |
| [`extraAgents`](/api-reference/hyperliquid-info/extra-agents) | `{"type": "extraAgents", "user": "0x…"}` | Approved API-agent wallets, each with `name` and `validUntil`. |
| [`userToMultiSigSigners`](/api-reference/hyperliquid-info/user-to-multi-sig-signers) | `{"type": "userToMultiSigSigners", "user": "0x…"}` | Authorized signers and threshold for a multi-sig account (`null` if not multi-sig). |
| [`maxBuilderFee`](/api-reference/hyperliquid-info/max-builder-fee) | `{"type": "maxBuilderFee", "user": "0x…", "builder": "0x…"}` | Maximum builder fee (tenths of a bp) a user has approved for a builder. |
| [`portfolioState`](/api-reference/hyperliquid-info/portfolio-state) | `{"type": "portfolioState", "user": "0x…", "dex": ""}` | Perp `clearinghouseState` + `spotClearinghouseState` + `userAbstraction` in one call (`dex: "ALL_DEXES"` for all DEXes). **GoldRush-native**. |

### 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). |
| [`delegations`](/api-reference/hyperliquid-info/delegations) | `{"type": "delegations", "user": "0x…"}` | Active HYPE staking delegations, per validator. |
| [`userBorrowLendInterest`](/api-reference/hyperliquid-info/user-borrow-lend-interest) | `{"type": "userBorrowLendInterest", "user": "0x…", "startTime": …}` | Borrow/lend interest accrual history over a time window. |
| [`vaultSummaries`](/api-reference/hyperliquid-info/vault-summaries) | `{"type": "vaultSummaries"}` | Summary information for every vault on the platform. |
| [`vaultDetails`](/api-reference/hyperliquid-info/vault-details) | `{"type": "vaultDetails", "vaultAddress": "0x…"}` | Full detail for one vault - leader, portfolio history, APR, followers. |
| [`leadingVaults`](/api-reference/hyperliquid-info/leading-vaults) | `{"type": "leadingVaults", "user": "0x…"}` | Vaults that a user leads. |

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

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


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

---

## 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` with periodic listing logic to surface new markets in a "trending" tab.

### Deployer-scoped leaderboards

Group `HypercoreFillTransaction` events from `walletTxs` 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.

### 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` table. Add a SQL transform 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
- 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`, `ohlcvCandlesForToken`, and `walletTxs` - 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` 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` 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.

### 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` table. Add a SQL transform 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` - full type reference.
- OHLCV Pairs Stream / OHLCV Tokens Stream
- Wallet Activity Stream
- [HIP-3 markets recipe](/goldrush-hyperliquid/streaming/hip3-markets) - identical address syntax, useful for builder-deployer prefixes.

## 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` for the full type with all fields.

### Funding, deposits, withdrawals, delegations

Each gets its own typed event:

- `HypercoreFundingEvent` - funding rate payment with coin, rate, and amount.
- `HypercoreDepositEvent` - cross-chain deposit into HyperCore.
- `HypercoreWithdrawalEvent` - finalized cross-chain withdrawal.
- `HypercoreDelegationEvent` - 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).

## Reference

- `HypercoreFillTransaction`
- `HypercoreLedgerEvent`
- `HypercoreFundingEvent`
- `HypercoreDepositEvent`
- `HypercoreWithdrawalEvent`
- `HypercoreDelegationEvent`
- Decoded Events Guide - 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.

## 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` - full type reference.
- `HypercoreLedgerEvent` - vault, staking, borrow/lend, rewards subtypes.
- [Liquidations and vault events](/goldrush-hyperliquid/streaming/liquidations-vaults) - full decoded-event walkthrough.
- 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.
- [HIP-3 markets OHLCV recipe](/goldrush-hyperliquid/streaming/hip3-markets) - 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) 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 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. |
| [`builderLiquidations`](/api-reference/hyperliquid-websocket/builder-liquidations) | `{"type": "builderLiquidations", "builder": "0x…"}` | Liquidation fills whose closing order was routed through your builder code - the intersection of `liquidationFills` and `builderFills`. Requires `builder`; carries both the `liquidation` object and `builder` attribution on every entry. **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 real-time [HIP-3](/goldrush-hyperliquid/streaming/hip3-markets) and [HIP-4](/goldrush-hyperliquid/streaming/hip4-markets) OHLCV recipes for 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.

---

## 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. allMids | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/all-mids

**Metadata:**
```yaml
title: allMids | Hyperliquid Info API
keywords: ["allMids","Hyperliquid allMids","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: allMids
description: Hyperliquid allMids: fetch the current mid price for every actively traded asset 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: "allMids"` is used to fetch the current mid price for every actively traded asset in a single call.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "allMids"}`.
- The response is a flat map keyed by asset. Perp assets use their symbol (e.g. `BTC`); spot pairs are keyed as `@` using the spot pair index from [spotMeta](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-meta).
- The optional `dex` field takes a perp DEX name. It defaults to the empty string, which represents the first (native) perp DEX; pass a HIP-3 dex name to scope mids to that dex.
- Mid prices are returned as decimal strings - keep them as strings or use a fixed-precision decimal type rather than parsing as floats.

Returns the current mid price for every actively traded asset in one call. The mid price is the midpoint between the best bid and the best ask. The payload is a single JSON object mapping each asset key to its mid price as a decimal string.

This is a global, non-user-keyed type. Perp assets are keyed by their symbol (for example `BTC`); spot pairs are keyed as `@`, using the spot pair index from `spotMeta`.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"allMids"`. |
| `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) returns mids for the first (native) perp DEX. Pass a builder code (e.g. `"xyz"`) to scope mids to 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": "allMids",
    "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: "allMids",
    dex: "",
  }),
});

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

mids = response.json()
```

## Response

A JSON object mapping each asset key to its mid price as a decimal string.

```json
{
  "BTC": "64000.0",
  "ETH": "3000.0",
  "@1": "1.0002"
}
```

### Field descriptions

> **Note:** All mid prices 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` | Mid price for the asset, as a decimal string. Perp assets are keyed by symbol (e.g. `BTC`, `ETH`); spot pairs are keyed as `@` using the spot pair index from `spotMeta`. |

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

_Last reviewed: 2026-07-24_

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

---

## 22. allPerpMetas | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/all-perp-metas

**Metadata:**
```yaml
title: allPerpMetas | Hyperliquid Info API
keywords: ["allPerpMetas","Hyperliquid allPerpMetas","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: allPerpMetas
description: Hyperliquid allPerpMetas: perpetuals universe and margin tables for every perp DEX in one request.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "allPerpMetas"` is used to fetch the perpetuals metadata — universe definitions and margin tables — for every perp DEX in a single request.

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

> **Note:** - GoldRush-native — not part of the original Hyperliquid API. It fans [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta) out across every perp DEX so you get the whole map in one call.
- The response is an array: index `0` is the native Hyperliquid perp DEX; each later entry is a HIP-3 builder-deployed perp DEX, in the same order as [perpDexs](https://goldrush.dev/docs/api-reference/hyperliquid-info/perp-dexs).
- For a single DEX's metadata, use [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta) with the `dex` field — this endpoint is the heavier, all-DEX equivalent.

Returns the full universe and margin tables across every perp DEX on HyperCore. Each element carries a DEX's `universe` (its perp asset definitions), its `marginTables` (leverage-bracket tiers), and the `collateralToken` index.

## Endpoint

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

## Request

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

### Example

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

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

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

all_perp_metas = response.json()
```

## Response

An array with one entry per perp DEX. Index `0` is the native Hyperliquid perp DEX; later entries are the HIP-3 builder-deployed perp DEXes in `perpDexs` order.

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

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `[n]` | `object` | Perpetuals metadata for one perp DEX (index `0` = native Hyperliquid; later = HIP-3 DEXes). |
| `[n].universe` | `array` | The DEX's perp asset definitions.  __RESPONSE_ROW__name	string	Asset name (with the DEX prefix for builder-deployed perps, e.g. `xyz:TSLA`). __RESPONSE_ROW__[n].szDecimals	int	Number of decimals for the size field. __RESPONSE_ROW__[n].maxLeverage	int	Maximum leverage for the asset. __RESPONSE_ROW__[n].marginTableId	int	Margin table id referenced in `marginTables`. __RESPONSE_ROW__[n].isDelisted	bool	Present and `true` if the asset is delisted. "> List of `[marginTableId, marginTable]` pairs for this DEX. Each `marginTable` has a `description` and a `marginTiers` array of `{ lowerBound, maxLeverage }` tiers (decimal-string bounds). |
| `collateralToken` | `int` | Token index used as collateral for this DEX. |



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

_Last reviewed: 2026-07-30_

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

---

## 23. 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 */}

---

## 24. 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 */}

---

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

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 */}

---

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

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 */}

---

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

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

## Paginating a large backfill

Each response returns at most **5,000 candles** - a per-response cap, not a limit on how far back history goes. To backfill a range wider than 5,000 candles, page forward through time: start at your window's `startTime`, then set the next request's `startTime` to the last candle's close time (`T`) plus one millisecond. Repeat until a response returns fewer than 5,000 candles.

Because `T` is the inclusive close of a candle and the next candle opens at `T + 1`, advancing to `T + 1` lands exactly on the following candle - no overlap to de-duplicate and no gaps.

```typescript TypeScript
async function backfillCandles(
  coin: string,
  interval: string,
  startTime: number,
  endTime: number,
) {
  const all: any[] = [];
  let cursor = startTime;

  while (cursor  **Tip:** Pick the coarsest `interval` that satisfies your use case - larger intervals cover more calendar time per 5,000-candle page, so a multi-year `1d` backfill is a single request while the same range at `1m` pages many times.

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

_Last reviewed: 2026-06-16_

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

---

## 28. 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": "..."}`.
- 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 */}

---

## 29. delegations | Hyperliquid Info API

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

**Metadata:**
```yaml
title: delegations | Hyperliquid Info API
keywords: ["delegations","Hyperliquid delegations","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: delegations
description: Hyperliquid delegations: list a user's active HYPE staking delegations.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "delegations"` is used to list a user's active HYPE staking delegations.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegations", "user": "..."}`.
- Returns an empty array when the user has no active delegations.
- For staking totals use [`delegatorSummary`](https://goldrush.dev/docs/api-reference/hyperliquid-info/delegator-summary); for the delegate / undelegate event history behind them, use [`delegatorHistory`](https://goldrush.dev/docs/api-reference/hyperliquid-info/delegator-history).

Returns a user's active HYPE staking delegations - one entry per validator - with the delegated amount and the timestamp until which each delegation is locked. Use [delegatorSummary](https://goldrush.dev/docs/api-reference/hyperliquid-info/delegator-summary) for aggregate totals and [delegatorHistory](https://goldrush.dev/docs/api-reference/hyperliquid-info/delegator-history) for the underlying event sequence.

User-keyed.

## Endpoint

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

## Request

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

const delegations = 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": "delegations",
        "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036",
    },
)

delegations = response.json()
```

## Response

An array of delegation objects, one per validator. Empty when the user has no active delegations.

```json
[
  {
    "validator": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66",
    "amount": "305.27602401",
    "lockedUntilTimestamp": 1768061059908
  },
  {
    "validator": "0x497beec89958848126c2ea65934ce430e1410ad2",
    "amount": "217.26663138",
    "lockedUntilTimestamp": 1753148985995
  }
]
```

### Field descriptions

> **Note:** `amount` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float.

| Field | Type | Description |
| --- | --- | --- |
| `validator` | `string` | Validator address the stake is delegated to. |
| `amount` | `string` | Delegated HYPE amount. |
| `lockedUntilTimestamp` | `int` | Millisecond timestamp until which the delegation is locked (undelegation is subject to this lock). |

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

_Last reviewed: 2026-07-24_

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

---

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

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 */}

---

## 31. 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 */}

---

## 32. 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 */}

---

## 33. exchangeStatus | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/exchange-status

**Metadata:**
```yaml
title: exchangeStatus | Hyperliquid Info API
keywords: ["exchangeStatus","Hyperliquid exchangeStatus","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: exchangeStatus
description: Hyperliquid exchangeStatus: fetch the current exchange operational status.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "exchangeStatus"` is used to fetch the current exchange operational status.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "exchangeStatus"}`.
- `specialStatuses` is `null` under normal operation and carries status flags only when the exchange is in a special state.
- This is a global, non-user-keyed type; `time` reflects the exchange's current clock.

Returns the current operational status of the exchange. Under normal operation `specialStatuses` is `null`; a non-null value signals that the exchange is in a special state. The `time` field is the exchange's current timestamp, useful for detecting clock skew or a stalled feed.

## Endpoint

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

## Request

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

### Example

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

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

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

status = response.json()
```

## Response

A single object describing the exchange status.

```json
{
  "specialStatuses": null,
  "time": 1784799315619
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `specialStatuses` | `object | null` | Special status flags. `null` under normal operation; a non-null object is present only when the exchange is in a special state. |
| `time` | `int` | Current exchange timestamp in milliseconds since Unix epoch. |

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

_Last reviewed: 2026-07-24_

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

---

## 34. extraAgents | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/extra-agents

**Metadata:**
```yaml
title: extraAgents | Hyperliquid Info API
keywords: ["extraAgents","Hyperliquid extraAgents","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: extraAgents
description: Hyperliquid extraAgents: list a user's approved API-agent wallets.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "extraAgents"` is used to list a user's approved API-agent wallets.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "extraAgents", "user": "..."}`.
- Returns an empty array when the user has approved no agent wallets.
- Each agent's `validUntil` is a millisecond timestamp after which the API wallet's approval expires.

Returns the extra API-agent wallets (also called API wallets) that a master account has approved. Agent wallets can sign actions on behalf of the master without holding funds themselves; each entry carries the agent's name, address, and approval expiry.

User-keyed.

## Endpoint

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

## Request

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

const agents = 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": "extraAgents",
        "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036",
    },
)

agents = response.json()
```

## Response

An array of agent-wallet objects. Empty when the user has approved no agents.

```json
[
  {
    "name": "Agent 1",
    "address": "0x77deafccbb9ddbc5da3e8f5d066624265bdb2a74",
    "validUntil": 1775216111330
  },
  {
    "name": "Agent 2",
    "address": "0xfff6471954ad1bbe70f18e2fea9928fd7aba31ad",
    "validUntil": 1782653334723
  }
]
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Human-readable label assigned to the agent (API) wallet. |
| `address` | `string` | The agent wallet address (0x-prefixed hex). |
| `validUntil` | `int` | Millisecond timestamp after which the agent's approval expires. |

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

_Last reviewed: 2026-07-24_

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

---

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

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 */}

---

## 36. 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 */}

---

## 37. 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 */}

---

## 38. leadingVaults | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/leading-vaults

**Metadata:**
```yaml
title: leadingVaults | Hyperliquid Info API
keywords: ["leadingVaults","Hyperliquid leadingVaults","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: leadingVaults
description: Hyperliquid leadingVaults: list the vaults a user leads.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "leadingVaults"` is used to list the vaults a user leads.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "leadingVaults", "user": "..."}`.
- Returns one entry per vault the user leads (manages); the array is empty when the user leads none.
- Each entry gives the vault's address and name; use [vaultDetails](https://goldrush.dev/docs/api-reference/hyperliquid-info/vault-details) for the full breakdown.
- User-keyed by the leader address.

Returns the vaults that a user leads (manages), as an array of `{vaultAddress, name}` entries. The array is empty when the user does not lead any vault.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"leadingVaults"`. |
| `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": "leadingVaults",
    "user": "0x677d831aef5328190852e24f13c46cac05f984e7"
  }'
```

```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: "leadingVaults",
    user: "0x677d831aef5328190852e24f13c46cac05f984e7",
  }),
});

const vaults = 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": "leadingVaults",
        "user": "0x677d831aef5328190852e24f13c46cac05f984e7",
    },
)

vaults = response.json()
```

## Response

An array of vaults the user leads. Empty when the user leads none.

```json
[
  {
    "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
    "name": "Hyperliquidity Provider (HLP)"
  }
]
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `[n]` | `object` | A vault the user leads. |
| `[n].vaultAddress` | `string` | Vault contract address (0x-prefixed hex). |
| `[n].name` | `string` | Vault name. |

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

_Last reviewed: 2026-07-24_

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

---

## 39. liquidatable | Hyperliquid Info API

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

**Metadata:**
```yaml
title: liquidatable | Hyperliquid Info API
keywords: ["liquidatable","Hyperliquid liquidatable","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: liquidatable
description: Hyperliquid liquidatable: list accounts currently eligible for liquidation.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "liquidatable"` is used to list accounts currently eligible for liquidation.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "liquidatable"}`.
- Global, non-user-keyed: it takes no `user` field and returns the accounts that are liquidatable at the instant of the call.
- The array is frequently empty - eligible accounts are typically liquidated the moment they cross the threshold, so a point-in-time snapshot rarely catches an open candidate.

Returns the set of accounts currently eligible for liquidation across HyperCore. This is a global, non-user-keyed type: a single snapshot shared across all callers. Because eligible accounts are liquidated almost immediately, the result is usually an empty array.

## Endpoint

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

## Request

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

### Example

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

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

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

liquidatable = response.json()
```

## Response

An array of liquidatable-account entries. The array is empty when no account is currently eligible for liquidation, which is the common case.

```json
[]
```

### Field descriptions

> **Note:** Upstream Hyperliquid does not publish a stable, fully-specified per-entry schema for `liquidatable`, and the result is empty in the vast majority of calls. When the array is non-empty, each entry identifies an at-risk account by its wallet address; treat any additional per-entry fields defensively.

| Field | Type | Description |
| --- | --- | --- |
| `[n].user` | `string` | Wallet address (0x-prefixed hex) of an account currently eligible for liquidation. |

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

_Last reviewed: 2026-07-24_

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

---

## 40. marginTable | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/margin-table

**Metadata:**
```yaml
title: marginTable | Hyperliquid Info API
keywords: ["marginTable","Hyperliquid marginTable","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: marginTable
description: Hyperliquid marginTable: fetch the margin-tier (leverage-bracket) table for a given margin table id.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "marginTable"` is used to fetch the margin-tier (leverage-bracket) table for a given margin table id.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "marginTable", "id": ...}`.
- `id` is the `marginTableId` referenced by a [meta](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta) universe entry (`universe[].marginTableId`), also listed inline in `meta.marginTables`.
- `marginTiers` describes how the maximum leverage steps down as a position's notional grows.

Returns a single margin-tier table by id. Each tier gives the lower notional bound at which it applies and the maximum leverage allowed within that tier, so maximum leverage decreases as a position's notional grows. This is the standalone lookup for the same tables embedded in `meta.marginTables`.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"marginTable"`. |
| `id` | `int` | Yes | The margin table id - the `marginTableId` from a `meta` universe entry (or an id listed in `meta.marginTables`). |

### Example

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

```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: "marginTable",
    id: 56,
  }),
});

const marginTable = 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": "marginTable", "id": 56},
)

margin_table = response.json()
```

## Response

A single object describing the table's description and its ordered leverage tiers.

```json
{
  "description": "tiered 40x",
  "marginTiers": [
    { "lowerBound": "0.0", "maxLeverage": 40 },
    { "lowerBound": "150000000.0", "maxLeverage": 20 }
  ]
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `description` | `string` | Human-readable label for the table (for example `"tiered 40x"`). May be an empty string. |
| `marginTiers` | `array` | Ordered leverage tiers. Each tier applies once a position's notional reaches its `lowerBound`; the highest applicable tier's `maxLeverage` caps leverage for the position. |
| `marginTiers.lowerBound` | `string` | Lower bound of position notional (USD) at which this tier begins, as a decimal string. |
| `marginTiers.maxLeverage` | `int` | Maximum leverage allowed while the position's notional is within this tier. |

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

_Last reviewed: 2026-07-24_

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

---

## 41. maxBuilderFee | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/max-builder-fee

**Metadata:**
```yaml
title: maxBuilderFee | Hyperliquid Info API
keywords: ["maxBuilderFee","Hyperliquid maxBuilderFee","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: maxBuilderFee
description: Hyperliquid maxBuilderFee: fetch the maximum builder fee a user has approved for a given builder.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "maxBuilderFee"` is used to fetch the maximum builder fee a user has approved for a given builder.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "maxBuilderFee", "user": "...", "builder": "..."}`.
- The response is a **bare integer** in tenths of a basis point (e.g. `10` = 1 basis point = 0.01%).
- Returns `0` when the user has not approved any builder fee for that builder.

Returns the maximum builder fee that a user has authorized a specific builder to charge, expressed as an integer in tenths of a basis point. Builders route order flow on behalf of users and may attach a fee up to this approved ceiling; `0` means no approval is in place for that builder.

User-keyed (and scoped to a single `builder`).

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"maxBuilderFee"`. |
| `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). |
| `builder` | `string` | Yes | The builder address the approval is scoped to (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": "maxBuilderFee",
    "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "builder": "0x1924b8561eef20e70d8f8f8f6a9c0e7f3c2f9c11"
  }'
```

```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: "maxBuilderFee",
    user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    builder: "0x1924b8561eef20e70d8f8f8f6a9c0e7f3c2f9c11",
  }),
});

const maxFee = 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": "maxBuilderFee",
        "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "builder": "0x1924b8561eef20e70d8f8f8f6a9c0e7f3c2f9c11",
    },
)

max_fee = response.json()
```

## Response

The body is a **bare integer** - the approved ceiling in tenths of a basis point.

```json
0
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `(response body)` | `int` | Maximum approved builder fee, in tenths of a basis point (e.g. `10` = 1 bp = 0.01%). `0` when no builder fee is approved for this builder. |

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

_Last reviewed: 2026-07-24_

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

---

## 42. maxMarketOrderNtls | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/max-market-order-ntls

**Metadata:**
```yaml
title: maxMarketOrderNtls | Hyperliquid Info API
keywords: ["maxMarketOrderNtls","Hyperliquid maxMarketOrderNtls","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: maxMarketOrderNtls
description: Hyperliquid maxMarketOrderNtls: fetch the maximum market-order notional for each leverage bucket.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "maxMarketOrderNtls"` is used to fetch the maximum market-order notional for each leverage bucket.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "maxMarketOrderNtls"}`.
- Each entry is a `[leverage, maxNotionalUsd]` tuple; the notional is a decimal string.
- This is a global, non-user-keyed type. Buckets are ordered from highest leverage to lowest.

Returns the maximum market-order notional permitted at each leverage bucket. Each element is a `[maxLeverage, maxNotional]` tuple: a position running at up to `maxLeverage` may place a single market order of at most `maxNotional` USD. The cap tightens as leverage rises, bounding slippage on aggressive market orders.

## Endpoint

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

## Request

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

### Example

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

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

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

max_ntls = response.json()
```

## Response

An array of `[maxLeverage, maxNotional]` tuples, ordered from highest leverage to lowest.

```json
[
  [25, "30000000.0"],
  [20, "5000000.0"],
  [10, "2000000.0"],
  [1, "500000.0"]
]
```

### Field descriptions

> **Note:** The notional value in each tuple 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 |
| --- | --- | --- |
| `[n]` | `[int, string]` | A `[maxLeverage, maxNotional]` tuple. Index `0` is the maximum leverage (int) that the bucket applies to; index `1` is the maximum market-order notional in USD for that bucket, as a decimal string. |

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

_Last reviewed: 2026-07-24_

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

---

## 43. 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"}`.

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 */}

---

## 44. 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 */}

---

## 45. openOrders | Hyperliquid Info API

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

**Metadata:**
```yaml
title: openOrders | Hyperliquid Info API
keywords: ["openOrders","Hyperliquid openOrders","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: openOrders
description: Hyperliquid openOrders: list a user's resting open orders by wallet address.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "openOrders"` is used to list a user's resting open orders.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "openOrders", "user": "..."}`.
- For orders enriched with trigger metadata, TP/SL flags, and the human-readable order type shown in the Hyperliquid web UI, use [`frontendOpenOrders`](https://goldrush.dev/docs/api-reference/hyperliquid-info/frontend-open-orders) instead.
- The optional `dex` field scopes the query to a HIP-3 builder DEX; the empty string (default) returns orders on the canonical Hyperliquid perp DEX.
- For a real-time stream of order placement and cancellation events, subscribe to [`walletTxs`](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/wallet-firehose).

Returns a single user's currently resting open orders as compact rows: coin, side, limit price, remaining size, order id, placement timestamp, original size, and client order id. This is the lightweight variant - reach for [frontendOpenOrders](https://goldrush.dev/docs/api-reference/hyperliquid-info/frontend-open-orders) when you also need trigger conditions, reduce-only / position-TP-SL flags, 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 `"openOrders"`. |
| `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). |
| `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) 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": "openOrders",
    "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
  }'
```

```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: "openOrders",
    user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
  }),
});

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": "openOrders",
        "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
    },
)

orders = response.json()
```

## Response

An array of open-order objects. Empty when the user has no resting orders.

```json
[
  {
    "coin": "UNI",
    "side": "B",
    "limitPx": "3.8558",
    "sz": "104.2",
    "oid": 501169923808,
    "timestamp": 1784799315550,
    "origSz": "104.2",
    "cloid": "0x00000000000000000000019f8ad9b4b4"
  }
]
```

### Field descriptions

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

| Field | Type | Description |
| --- | --- | --- |
| `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"UNI"` for perps; spot pairs use the `@N` form. |
| `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. |
| `limitPx` | `string` | Limit price. |
| `sz` | `string` | Remaining (unfilled) order size. |
| `oid` | `int` | Numeric order ID. |
| `timestamp` | `int` | Order placement time in milliseconds since Unix epoch. |
| `origSz` | `string` | Original order size before any partial fills. |
| `cloid` | `string | null` | Client order ID set at placement, or `null` when none was provided. |

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

_Last reviewed: 2026-07-24_

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

---

## 46. 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 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 */}

---

## 47. perpDeployAuctionStatus | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/perp-deploy-auction-status

**Metadata:**
```yaml
title: perpDeployAuctionStatus | Hyperliquid Info API
keywords: ["perpDeployAuctionStatus","Hyperliquid perpDeployAuctionStatus","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: perpDeployAuctionStatus
description: Hyperliquid perpDeployAuctionStatus: fetch the current perp-deploy Dutch-auction status.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "perpDeployAuctionStatus"` is used to fetch the current perp-deploy Dutch-auction status.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "perpDeployAuctionStatus"}`.
- Describes the current perp-deploy (HIP-3) Dutch auction: the gas price decays over `durationSeconds` from `startGas`, and `currentGas` is the live price a deployer would pay now.
- `currentGas` is `null` once the auction has ended; `endGas` is `null` while the auction is still active.
- Gas prices are decimal strings. This is a global, non-user-keyed type.

Returns the status of the current perp-deploy Dutch auction. To deploy a new HIP-3 perp DEX, a deployer pays the auction's gas price, which decays over time from `startGas`. `currentGas` is the live price; it becomes `null` after the auction ends, at which point `endGas` records the final price.

## Endpoint

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

## Request

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

### Example

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

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

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

auction = response.json()
```

## Response

A single object describing the current perp-deploy gas auction.

```json
{
  "startTimeSeconds": 1784707200,
  "durationSeconds": 111600,
  "startGas": "1079.90632916",
  "currentGas": "601.24549785",
  "endGas": null
}
```

### Field descriptions

> **Note:** Gas prices 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 |
| --- | --- | --- |
| `startTimeSeconds` | `int` | Auction start time (Unix seconds). |
| `durationSeconds` | `int` | Auction duration, in seconds. |
| `startGas` | `string` | Starting gas price, as a decimal string. |
| `currentGas` | `string | null` | Current gas price, as a decimal string; `null` when the auction has ended. |
| `endGas` | `string | null` | Ending gas price, as a decimal string; `null` while the auction is still active. |

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

_Last reviewed: 2026-07-24_

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

---

## 48. perpDexLimits | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/perp-dex-limits

**Metadata:**
```yaml
title: perpDexLimits | Hyperliquid Info API
keywords: ["perpDexLimits","Hyperliquid perpDexLimits","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: perpDexLimits
description: Hyperliquid perpDexLimits: fetch the open-interest, position-size, and transfer limits for a HIP-3 perp DEX.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "perpDexLimits"` is used to fetch the open-interest, position-size, and transfer limits for a HIP-3 perp DEX.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "perpDexLimits", "dex": "..."}`.
- The `dex` field names the HIP-3 builder-deployed perp DEX to inspect. Enumerate deployed DEX names with [perpDexs](https://goldrush.dev/docs/api-reference/hyperliquid-info/perp-dexs).
- Returns `null` for a DEX that has no configured limits (including the empty-string native perp DEX).
- `coinToOiCap` is an array of `[coin, cap]` tuples; all limit values are decimal strings.

Returns the risk limits configured for a HIP-3 builder-deployed perpetual DEX: the total open-interest cap, the per-perp open-interest size cap, the maximum transfer notional, and the per-asset open-interest caps.

This is a per-DEX type. Pass a builder DEX `name` from `perpDexs` as the `dex` field to inspect that DEX's limits.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"perpDexLimits"`. |
| `dex` | `string` | Yes | The HIP-3 builder DEX name (e.g. `"xyz"`). Enumerate deployed DEX names with `perpDexs`. An empty string selects the native Hyperliquid perp DEX, which has no configured limits and returns `null`. |

### Example

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

```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: "perpDexLimits",
    dex: "xyz",
  }),
});

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

limits = response.json()
```

## Response

A single object describing the DEX's limits, or `null` when the DEX has no configured limits.

```json
{
  "totalOiCap": "10000000000.0",
  "oiSzCapPerPerp": "20000000000.0",
  "maxTransferNtl": "3000000000.0",
  "coinToOiCap": [
    ["xyz:AAPL", "100000000.0"],
    ["xyz:AMD", "100000000.0"]
  ]
}
```

### Field descriptions

> **Note:** All limit values 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 |
| --- | --- | --- |
| `totalOiCap` | `string` | Total open-interest cap across the DEX, in USD notional. |
| `oiSzCapPerPerp` | `string` | Open-interest size cap applied per perp on this DEX. |
| `maxTransferNtl` | `string` | Maximum transfer notional allowed on this DEX. |
| `coinToOiCap` | `array` | Per-asset open-interest caps, encoded as `[coin, cap]` tuples. Values are decimal strings. |

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

_Last reviewed: 2026-07-24_

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

---

## 49. 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 */}

---

## 50. perpsAtOpenInterestCap | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/perps-at-open-interest-cap

**Metadata:**
```yaml
title: perpsAtOpenInterestCap | Hyperliquid Info API
keywords: ["perpsAtOpenInterestCap","Hyperliquid perpsAtOpenInterestCap","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: perpsAtOpenInterestCap
description: Hyperliquid perpsAtOpenInterestCap: list the perp assets currently at their open-interest cap.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "perpsAtOpenInterestCap"` is used to list the perp assets currently at their open-interest cap.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "perpsAtOpenInterestCap"}`.
- While an asset is in this list it has reached its open-interest cap; orders that would increase aggregate open interest are rejected (see the `openInterestCap*` order-rejection reasons) until open interest falls back below the cap.
- This is a global, non-user-keyed type refreshed continuously from upstream Hyperliquid.

Returns the list of perpetual assets that are currently at their open-interest cap, as an array of coin symbol strings. Use it to detect which markets are constrained before placing orders that would add open interest.

## Endpoint

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

## Request

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

### Example

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

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

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

capped_perps = response.json()
```

## Response

An array of coin symbol strings for the perp assets currently at their open-interest cap. Empty when no market is capped.

```json
["CANTO", "FTM", "JELLY", "LOOM", "RLB", "ZEREBRO"]
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `[n]` | `string` | Coin symbol of a perp asset currently at its open-interest cap. |

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

_Last reviewed: 2026-07-24_

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

---

## 51. portfolioState | Hyperliquid Info API

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

**Metadata:**
```yaml
title: portfolioState | Hyperliquid Info API
keywords: ["portfolioState","Hyperliquid portfolioState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: portfolioState
description: Hyperliquid portfolioState: fetch a wallet's perp state, spot balances, and account-abstraction mode in one request.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "portfolioState"` is used to fetch a wallet's perp clearinghouse state, spot balances, and account-abstraction mode in a single request.

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

> **Note:** - GoldRush-native composite — not part of the original Hyperliquid API. It bundles three upstream calls into one round-trip: [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state), [spotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-clearinghouse-state), and `userAbstraction`.
- Pass `dex` to scope the perp `clearinghouseState` to a single HIP-3 DEX. Pass `dex: "ALL_DEXES"` to return the perp state across the native DEX plus every HIP-3 DEX in one call, keyed by DEX name.
- `spotClearinghouseState` and `userAbstraction` are DEX-independent and always returned once.

Returns a single object bundling a wallet's perp account state (`clearinghouseState`), spot balances (`spotClearinghouseState`), and account-abstraction mode (`userAbstraction`) — the three calls a portfolio view typically needs, in one round-trip.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"portfolioState"`. |
| `user` | `string` | Yes | Ethereum address (0x-prefixed, 42 characters). |
| `dex` | `string` | No | Perp DEX name. Omit for the native DEX (default). Use `"ALL_DEXES"` to fetch the perp `clearinghouseState` across the native DEX plus every HIP-3 DEX in one call. |

### Example

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

const portfolio = 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": "portfolioState",
        "user": "0x0000000000000000000000000000000000000000",
    },
)

portfolio = response.json()
```

## Response

An object with three keys — the perp clearinghouse state, spot clearinghouse state, and the account-abstraction mode.

```json
{
  "clearinghouseState": {
    "marginSummary": { "accountValue": "…", "totalNtlPos": "…", "totalRawUsd": "…", "totalMarginUsed": "…" },
    "crossMarginSummary": { "…": "…" },
    "assetPositions": [],
    "time": 1234567890123
  },
  "spotClearinghouseState": {
    "balances": [
      { "coin": "USDC", "token": 0, "total": "0.02221591", "hold": "0.0", "entryNtl": "0.0" }
    ]
  },
  "userAbstraction": "unifiedAccount"
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `clearinghouseState` | `object` | The wallet's perp account state — identical to the standalone `clearinghouseState` response (`marginSummary`, `crossMarginSummary`, `assetPositions`, `time`). Scoped to `dex` when supplied; a per-DEX object when `dex: "ALL_DEXES"` (see below). |
| `spotClearinghouseState` | `object` | The wallet's spot balances. |
| `spotClearinghouseState.balances` | `array` | One entry per held spot token.  __RESPONSE_ROW__coin	string	Coin symbol. __RESPONSE_ROW__spotClearinghouseState.token	int	Token index. __RESPONSE_ROW__spotClearinghouseState.total	string	Total balance (decimal string). __RESPONSE_ROW__spotClearinghouseState.hold	string	Amount on hold (decimal string). __RESPONSE_ROW__spotClearinghouseState.entryNtl	string	Entry notional (decimal string).  |
| `userAbstraction` | `string` | The wallet's account-abstraction mode. One of: |
| `userAbstraction.unifiedAccount` | `string` | Single balance per asset across all DEXes; all cross-margin positions share collateral. |
| `userAbstraction.portfolioMargin` | `string` | Portfolio margin — a single portfolio unifying eligible assets with borrowing / LTV. |
| `userAbstraction.disabled` | `string` | Abstraction disabled — separate perp and spot balances. |
| `userAbstraction.default` | `string` | Default mode. |
| `userAbstraction.dexAbstraction` | `string` | DEX abstraction mode (legacy, being discontinued). |

### `ALL_DEXES` response

When `dex: "ALL_DEXES"` is passed, `clearinghouseState` becomes an object keyed by DEX name — the native DEX under `"native"` plus one key per HIP-3 DEX. `spotClearinghouseState` and `userAbstraction` are unchanged.

```json
{
  "clearinghouseState": {
    "native": { "marginSummary": {}, "crossMarginSummary": {}, "assetPositions": [], "time": 1234567890123 },
    "xyz": { "marginSummary": {}, "crossMarginSummary": {}, "assetPositions": [], "time": 1234567890123 }
  },
  "spotClearinghouseState": { "balances": [] },
  "userAbstraction": "unifiedAccount"
}
```

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

_Last reviewed: 2026-07-30_

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

---

## 52. 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 */}

---

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

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 */}

---

## 54. spotDeployState | Hyperliquid Info API

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

**Metadata:**
```yaml
title: spotDeployState | Hyperliquid Info API
keywords: ["spotDeployState","Hyperliquid spotDeployState","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: spotDeployState
description: Hyperliquid spotDeployState: fetch the spot-token deployment state and gas auction for a deployer.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "spotDeployState"` is used to fetch the spot-token deployment state and gas auction for a deployer.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotDeployState", "user": "..."}`.
- `states` lists the deployer's in-progress spot-token deployments; it is empty for a `user` with no active deployment.
- `gasAuction` describes the current spot-deploy Dutch gas auction, with gas prices returned as decimal strings.
- User-keyed by the deployer address.

Returns the spot-token deployment state for a deployer: any in-progress token deployments (`states`) plus the current spot-deploy gas auction (`gasAuction`). Use it to track a deployer's genesis configuration and the live gas price required to deploy a spot token.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"spotDeployState"`. |
| `user` | `string` | Yes | The deployer 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": "spotDeployState",
    "user": "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152"
  }'
```

```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: "spotDeployState",
    user: "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152",
  }),
});

const deployState = 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": "spotDeployState",
        "user": "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152",
    },
)

deploy_state = response.json()
```

## Response

A single object with the deployer's in-progress deployments and the current gas auction. `states` is empty when the deployer has no active spot deployment.

```json
{
  "states": [],
  "gasAuction": {
    "startTimeSeconds": 1784707200,
    "durationSeconds": 111600,
    "startGas": "1009.8417473",
    "currentGas": "589.01327066",
    "endGas": null
  }
}
```

### Field descriptions

> **Note:** Gas prices and genesis balances 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 |
| --- | --- | --- |
| `states` | `array` | In-progress spot-token deployments for this deployer. Empty when the deployer has no active deployment. |
| `states.token` | `int` | Token index. |
| `states.spec` | `object` | Token specification.  __RESPONSE_ROW__name	string	Token name. __RESPONSE_ROW__states.szDecimals	int	Number of decimals for size precision. __RESPONSE_ROW__states.weiDecimals	int	Number of decimals for the wei-denominated amount. Full (human-readable) token name. |
| `spots` | `array` | Spot pair indices the token participates in. |
| `maxSupply` | `int` | Maximum token supply. |
| `hyperliquidityGenesisBalance` | `string` | Hyperliquidity genesis balance allocated at deployment. |
| `totalGenesisBalanceWei` | `string` | Total genesis balance, in wei. |
| `userGenesisBalances` | `array` | `[address, balance]` pairs for genesis balances allocated to users. |
| `existingTokenGenesisBalances` | `array` | `[tokenIndex, balance]` pairs for genesis balances denominated in existing tokens. |



| Field | Type | Description |
| --- | --- | --- |
| `gasAuction` | `object` | Current spot-deploy gas auction. |
| `gasAuction.startTimeSeconds` | `int` | Auction start time (Unix seconds). |
| `gasAuction.durationSeconds` | `int` | Auction duration, in seconds. |
| `gasAuction.startGas` | `string` | Starting gas price, as a decimal string. |
| `gasAuction.currentGas` | `string | null` | Current gas price, as a decimal string; `null` when the auction has ended. |
| `gasAuction.endGas` | `string | null` | Ending gas price, as a decimal string; `null` while the auction is still active. |

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

_Last reviewed: 2026-07-24_

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

---

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

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 */}

---

## 56. 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 */}

---

## 57. 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 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 */}

---

## 58. userAbstraction | Hyperliquid Info API

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

**Metadata:**
```yaml
title: userAbstraction | Hyperliquid Info API
keywords: ["userAbstraction","Hyperliquid userAbstraction","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userAbstraction
description: Hyperliquid userAbstraction: fetch a user's account-abstraction mode.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userAbstraction"` is used to fetch a user's account-abstraction mode.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userAbstraction", "user": "..."}`.
- The response body is a **bare JSON string** (for example `"disabled"`), not an object - parse it as a scalar.
- Values seen in production are `disabled` and `unifiedAccount`; the wider native enum also includes `portfolioMargin`, `default`, and the legacy `dexAbstraction`.

Returns the account-abstraction mode configured for a wallet. The response is a single JSON string rather than an object: `disabled` means the account keeps separate perp and spot balances, while `unifiedAccount` means a single balance per asset is shared across all DEXes with cross-margin positions sharing collateral.

User-keyed.

## Endpoint

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

## Request

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

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

mode = response.json()
```

## Response

The body is a **bare JSON string** - not an object - naming the account-abstraction mode.

```json
"unifiedAccount"
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `(response body)` | `string` | Account-abstraction mode. One of: - `disabled` - abstraction disabled; separate perp and spot balances. - `unifiedAccount` - single balance per asset across all DEXes; cross-margin positions share collateral. - `portfolioMargin` - single portfolio unifying eligible assets with borrowing / LTV. - `default` - default mode. - `dexAbstraction` - DEX abstraction mode (legacy, being discontinued). |

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

_Last reviewed: 2026-07-24_

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

---

## 59. userBorrowLendInterest | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-borrow-lend-interest

**Metadata:**
```yaml
title: userBorrowLendInterest | Hyperliquid Info API
keywords: ["userBorrowLendInterest","Hyperliquid userBorrowLendInterest","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userBorrowLendInterest
description: Hyperliquid userBorrowLendInterest: fetch a user's borrow/lend interest accrual history.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userBorrowLendInterest"` is used to fetch a user's borrow/lend interest accrual history.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userBorrowLendInterest", "user": "...", "startTime": ...}`.
- Bounded by a `[startTime, endTime)` window in milliseconds; `endTime` defaults to the current server time when omitted.
- Amounts are decimal strings, one row per token per accrual point.

Returns a user's borrow/lend interest accrual over a time window - the interest charged on borrowed balances and earned on supplied (lent) balances, per token. Use it for P&L attribution and accounting on Hyperliquid borrow/lend positions.

User-keyed.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"userBorrowLendInterest"`. |
| `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). |
| `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": "userBorrowLendInterest",
    "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: "userBorrowLendInterest",
    user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    startTime: 1735689600000,
  }),
});

const interest = 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": "userBorrowLendInterest",
        "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "startTime": 1735689600000,
    },
)

interest = response.json()
```

## Response

An array of per-token interest accrual points within the window. Empty when the user accrued no borrow/lend interest over the range.

```json
[
  {
    "time": 1735689600000,
    "token": "USDC",
    "borrow": "0.0",
    "supply": "1.2345"
  }
]
```

### Field descriptions

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

| Field | Type | Description |
| --- | --- | --- |
| `time` | `int` | Millisecond timestamp of the accrual point. |
| `token` | `string` | Token symbol the interest applies to - e.g. `"USDC"`. |
| `borrow` | `string` | Borrow interest charged on the borrowed balance of this token. |
| `supply` | `string` | Supply (lend) interest earned on the supplied balance of this token. |

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

_Last reviewed: 2026-07-24_

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

---

## 60. userFees | Hyperliquid Info API

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

**Metadata:**
```yaml
title: userFees | Hyperliquid Info API
keywords: ["userFees","Hyperliquid userFees","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userFees
description: Hyperliquid userFees: fetch a user's fee schedule and recent daily trading volume.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userFees"` is used to fetch a user's fee schedule and recent daily volume.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFees", "user": "..."}`.
- `feeSchedule` is the exchange-wide tier table; `userCrossRate` / `userAddRate` are the effective rates *this* user pays after VIP-tier, referral, and staking discounts.
- All rate and volume fields are decimal strings; a rate of `"0.00045"` means 4.5 basis points.

Returns a user's effective trading fees together with the exchange-wide fee schedule and the user's recent per-day traded volume. Use it to display the taker (`cross`) and maker (`add`) rates a wallet actually pays, and to reconstruct the tier table and discounts that produce them.

User-keyed.

## Endpoint

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

## Request

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

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

fees = response.json()
```

## Response

A single object with the user's recent daily volume, the exchange-wide `feeSchedule`, the user's effective rates, and any active discounts / trial state.

```json
{
  "dailyUserVlm": [
    {
      "date": "2026-07-09",
      "userCross": "587333.02",
      "userAdd": "1041946.77",
      "exchange": "3832824759.19"
    }
  ],
  "feeSchedule": {
    "cross": "0.00045",
    "add": "0.00015",
    "spotCross": "0.0007",
    "spotAdd": "0.0004",
    "referralDiscount": "0.04",
    "tiers": {
      "vip": [
        {
          "ntlCutoff": "5000000",
          "cross": "0.0004",
          "add": "0.00012",
          "spotCross": "0.0006",
          "spotAdd": "0.0003"
        }
      ],
      "mm": [
        {
          "makerFractionCutoff": "0.005",
          "add": "-0.00001"
        }
      ]
    },
    "stakingDiscountTiers": [
      { "bpsOfMaxSupply": "0.0", "discount": "0.0" },
      { "bpsOfMaxSupply": "0.1", "discount": "0.05" }
    ]
  },
  "userCrossRate": "0.000405",
  "userAddRate": "0.00015",
  "activeReferralDiscount": "0.0",
  "trial": null,
  "feeTrialReward": "0.0",
  "nextTrialAvailableTimestamp": null
}
```

### Field descriptions

> **Note:** All rate and volume fields (`userCross`, `userAdd`, `exchange`, `cross`, `add`, `userCrossRate`, `userAddRate`, and the tier / discount values) are returned as **decimal strings**. Do not parse them as floats. Rates are expressed as fractions of notional - `"0.00045"` = 4.5 bps.

| Field | Type | Description |
| --- | --- | --- |
| `dailyUserVlm` | `array` | Recent per-day traded volume, one entry per day. |
| `dailyUserVlm.date` | `string` | Calendar day in `YYYY-MM-DD` (UTC). |
| `dailyUserVlm.userCross` | `string` | The user's taker (cross) volume that day, in USDC. |
| `dailyUserVlm.userAdd` | `string` | The user's maker (add) volume that day, in USDC. |
| `dailyUserVlm.exchange` | `string` | Total exchange-wide volume that day, in USDC. |
| `feeSchedule` | `object` | Exchange-wide fee schedule - the base rates and the tier tables that discounts are applied against. |
| `feeSchedule.cross` | `string` | Base taker (cross) fee rate for perps. |
| `feeSchedule.add` | `string` | Base maker (add) fee rate for perps. |
| `feeSchedule.spotCross` | `string` | Base taker fee rate for spot. |
| `feeSchedule.spotAdd` | `string` | Base maker fee rate for spot. |
| `feeSchedule.referralDiscount` | `string` | Base referral discount, as a fraction of fees. |
| `feeSchedule.tiers` | `object` | Volume- and maker-based tier tables.  __RESPONSE_ROW__vip	array	VIP tiers keyed by notional-volume cutoff. Each entry: `ntlCutoff` (volume threshold) plus the `cross`, `add`, `spotCross`, and `spotAdd` rates at that tier. __RESPONSE_ROW__feeSchedule.mm	array	Market-maker tiers. Each entry: `makerFractionCutoff` (share-of-maker-volume threshold) and the reduced `add` (maker) rate at that tier. ">Staking-based discount tiers. Each entry: `bpsOfMaxSupply` (staked HYPE as basis points of max supply) and the `discount` (fraction of fees) at that tier. |



| Field | Type | Description |
| --- | --- | --- |
| `userCrossRate` | `string` | Effective taker (cross) rate this user pays, after all applicable discounts. |
| `userAddRate` | `string` | Effective maker (add) rate this user pays, after all applicable discounts. |
| `activeReferralDiscount` | `string` | Referral discount currently applied to the user, as a fraction of fees. |
| `trial` | `object | null` | Active fee-trial details, or `null` when the user has no active trial. |
| `feeTrialReward` | `string` | Reward accrued from the user's fee trial. |
| `nextTrialAvailableTimestamp` | `int | null` | Millisecond timestamp when the next fee trial becomes available, or `null` when not applicable. |

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

_Last reviewed: 2026-07-24_

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

---

## 61. 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.
- 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 */}

---

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

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 */}

---

## 63. 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": "..."}`.
- 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 */}

---

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

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 */}

---

## 65. userRateLimit | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-rate-limit

**Metadata:**
```yaml
title: userRateLimit | Hyperliquid Info API
keywords: ["userRateLimit","Hyperliquid userRateLimit","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userRateLimit
description: Hyperliquid userRateLimit: fetch a user's API rate-limit usage and cap.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userRateLimit"` is used to fetch a user's API rate-limit usage and cap.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userRateLimit", "user": "..."}`.
- This reports Hyperliquid's own address-based L1 request allowance; it is unrelated to your GoldRush credit budget.
- The request cap (`nRequestsCap`) is a function of the account's cumulative traded volume (`cumVlm`), so higher-volume accounts are granted more requests.

Returns the address-based API rate-limit accounting Hyperliquid maintains for a wallet: cumulative traded volume, how many requests have been used, the current cap, and any surplus beyond it. Use it to monitor how much of an account's request allowance remains.

User-keyed.

## Endpoint

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

## Request

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

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

rate_limit = response.json()
```

## Response

```json
{
  "cumVlm": "471728188.87",
  "nRequestsUsed": 370317503,
  "nRequestsCap": 471738188,
  "nRequestsSurplus": 0
}
```

### Field descriptions

> **Note:** `cumVlm` is returned as a **decimal string**. Do not parse it as a float.

| Field | Type | Description |
| --- | --- | --- |
| `cumVlm` | `string` | Cumulative traded volume for the account, in USDC. |
| `nRequestsUsed` | `int` | Number of requests consumed so far against the address allowance. |
| `nRequestsCap` | `int` | Current maximum number of requests allowed for the account. |
| `nRequestsSurplus` | `int` | Requests made beyond the cap; `0` when the account is within its limit. |

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

_Last reviewed: 2026-07-24_

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

---

## 66. userRole | Hyperliquid Info API

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

**Metadata:**
```yaml
title: userRole | Hyperliquid Info API
keywords: ["userRole","Hyperliquid userRole","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userRole
description: Hyperliquid userRole: fetch a user's account role.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userRole"` is used to fetch a user's account role.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userRole", "user": "..."}`.
- The `role` value is one of `missing`, `user`, `agent`, `vault`, or `subAccount`.
- The `subAccount` and `agent` roles additionally carry a `data` object identifying the controlling master account.

Returns the role a wallet plays on HyperCore. Most trading wallets are plain `user` accounts; this type also distinguishes API `agent` wallets, `vault` addresses, and `subAccount`s. For a `subAccount` (and for an `agent`), a nested `data` object carries the `master` account address that controls the wallet.

User-keyed.

## Endpoint

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

## Request

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

const role = 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": "userRole",
        "user": "0x2b804617c6f63c040377e95bb276811747006f4b",
    },
)

role = response.json()
```

## Response

A single object with a `role` discriminator. A plain trading wallet returns `{"role": "user"}`; a sub-account additionally returns its controlling master under `data`.

```json
{
  "role": "subAccount",
  "data": {
    "master": "0x399965e15d4e61ec3529cc98b7f7ebb93b733336"
  }
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `role` | `string` | Account role. One of: - `missing` - the address has never interacted with HyperCore. - `user` - an ordinary trading account. - `agent` - an API agent (API wallet) that signs on behalf of a master. - `vault` - a vault address. - `subAccount` - a sub-account owned by a master account. |
| `data` | `object` | Present only for the `subAccount` and `agent` roles. |
| `data.master` | `string` | Address of the master account that controls this sub-account / agent. |

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

_Last reviewed: 2026-07-24_

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

---

## 67. userToMultiSigSigners | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/user-to-multi-sig-signers

**Metadata:**
```yaml
title: userToMultiSigSigners | Hyperliquid Info API
keywords: ["userToMultiSigSigners","Hyperliquid userToMultiSigSigners","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: userToMultiSigSigners
description: Hyperliquid userToMultiSigSigners: fetch the authorized signers for a multi-sig user.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "userToMultiSigSigners"` is used to fetch the authorized signers for a multi-sig user.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userToMultiSigSigners", "user": "..."}`.
- Returns `null` when the queried wallet is not a multi-sig account.
- A multi-sig account has at most 10 authorized signers; `threshold` is the minimum number that must sign to authorize an action.

Returns the authorized-signer configuration for a wallet that has been converted to a multi-sig account: the set of addresses allowed to sign for it, and the minimum number of signatures (`threshold`) required to authorize an action. Returns `null` for ordinary (non-multi-sig) wallets.

User-keyed.

## Endpoint

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

## Request

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

const signers = 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": "userToMultiSigSigners",
        "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036",
    },
)

signers = response.json()
```

## Response

An object describing the multi-sig signer set, or `null` when the queried wallet is not a multi-sig account.

```json
{
  "authorizedUsers": [
    "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036",
    "0x399965e15d4e61ec3529cc98b7f7ebb93b733336"
  ],
  "threshold": 2
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `authorizedUsers` | `array` | Addresses authorized to sign for the multi-sig account. |
| `threshold` | `int` | Minimum number of authorized signatures required to execute an action. |

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

_Last reviewed: 2026-07-24_

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

---

## 68. 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 */}

---

## 69. 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 */}

---

## 70. 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": "..."}`.

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 */}

---

## 71. validatorL1Votes | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/validator-l1-votes

**Metadata:**
```yaml
title: validatorL1Votes | Hyperliquid Info API
keywords: ["validatorL1Votes","Hyperliquid validatorL1Votes","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: validatorL1Votes
description: Hyperliquid validatorL1Votes: fetch the pending validator L1 governance votes/actions.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "validatorL1Votes"` is used to fetch the pending validator L1 governance votes/actions.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "validatorL1Votes"}`.
- Each entry is an L1 governance action currently awaiting validator votes, with an `expireTime` (ms) after which the pending vote lapses.
- The `action` object is a tagged variant; its inner shape depends on the specific L1 action being voted on (the example below shows a `settleOutcome` action).
- This is a global, non-user-keyed type.

Returns the pending validator L1 governance votes - the L1 actions currently awaiting validator approval. Each entry pairs an `expireTime` with the `action` under vote.

The `action` is a tagged variant whose inner structure depends on the action type, so treat it as an opaque object keyed by action tag unless you are decoding a specific action you recognize.

## Endpoint

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

## Request

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

### Example

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

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

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

votes = response.json()
```

## Response

An array of pending L1 action votes. Empty when no L1 action is awaiting votes.

```json
[
  {
    "expireTime": 1785021897017,
    "action": {
      "O": {
        "settleOutcome": {
          "outcome": 855,
          "settleFraction": "0",
          "details": "...",
          "nameAndDescription": ["...", "..."]
        }
      }
    }
  }
]
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `[n]` | `object` | A pending L1 governance action awaiting validator votes. |
| `[n].expireTime` | `int` | Unix timestamp in milliseconds at which this pending vote expires. |
| `[n].action` | `object` | The L1 governance action under vote. A tagged variant whose inner shape depends on the action type - treat it as an opaque object unless you are decoding a known action. The example shows a `settleOutcome` action carrying the target `outcome` id, a `settleFraction`, and descriptive metadata. |

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

_Last reviewed: 2026-07-24_

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

---

## 72. vaultDetails | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/vault-details

**Metadata:**
```yaml
title: vaultDetails | Hyperliquid Info API
keywords: ["vaultDetails","Hyperliquid vaultDetails","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: vaultDetails
description: Hyperliquid vaultDetails: fetch detailed information for a specific vault.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "vaultDetails"` is used to fetch detailed information for a specific vault.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "vaultDetails", "vaultAddress": "..."}`.
- `vaultAddress` is required; the optional `user` field populates `followerState` with that wallet's position in the vault.
- `portfolio` is an array of `[period, series]` pairs bucketed by `day`, `week`, `month`, `allTime`, and their `perp*` variants.
- Aggregate stats (`apr`, `leaderFraction`, `leaderCommission`, `maxDistributable`, `maxWithdrawable`) are JSON numbers, while position, equity, and history values are decimal strings.
- For a lightweight list across all vaults, use [vaultSummaries](https://goldrush.dev/docs/api-reference/hyperliquid-info/vault-summaries).

Returns the full detail for a single vault: identity (name, address, leader, description), time-bucketed performance history (`portfolio`), headline stats (`apr`, distributable and withdrawable amounts), the follower roster, and the vault's relationship to any parent or child vaults.

Pass the optional `user` field to have `followerState` reflect that wallet's position in the vault.

## Endpoint

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

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Yes | Always `"vaultDetails"`. |
| `vaultAddress` | `string` | Yes | The vault contract address (lowercase 0x-prefixed hex). |
| `user` | `string` | No | Optional wallet address (lowercase 0x-prefixed hex). When supplied, `followerState` is populated with that wallet's position in the vault. |

### Example

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

```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: "vaultDetails",
    vaultAddress: "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
  }),
});

const vault = 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": "vaultDetails",
        "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
    },
)

vault = response.json()
```

## Response

A single object describing the vault.

```json
{
  "name": "Hyperliquidity Provider (HLP)",
  "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
  "leader": "0x677d831aef5328190852e24f13c46cac05f984e7",
  "description": "This community-owned vault provides liquidity to Hyperliquid through multiple market making strategies, performs liquidations, and accrues platform fees.",
  "portfolio": [
    [
      "day",
      {
        "accountValueHistory": [[1784713601558, "248732255.46"]],
        "pnlHistory": [[1784713601558, "0.0"]],
        "vlm": "0.0"
      }
    ],
    ["week", { "accountValueHistory": [], "pnlHistory": [], "vlm": "0.0" }],
    ["allTime", { "accountValueHistory": [], "pnlHistory": [], "vlm": "0.0" }]
  ],
  "apr": 0.36387129259090006,
  "followerState": null,
  "leaderFraction": 0.0007904828725729887,
  "leaderCommission": 0,
  "followers": [
    {
      "user": "0x005844b2ffb2e122cf4244be7dbcb4f84924907c",
      "vaultEquity": "714491.71026243",
      "pnl": "3203.43026143",
      "allTimePnl": "79843.74476743",
      "daysFollowing": 388,
      "vaultEntryTime": 1700926145201,
      "lockupUntil": 1734824439201
    }
  ],
  "maxDistributable": 94856870.164485,
  "maxWithdrawable": 742557.680863,
  "isClosed": false,
  "relationship": {
    "type": "parent",
    "data": {
      "childAddresses": [
        "0x010461c14e146ac35fe42271bdc1134ee31c703a",
        "0x2e3d94f0562703b25c83308a05046ddaf9a8dd14"
      ]
    }
  },
  "allowDeposits": true,
  "alwaysCloseOnWithdraw": false
}
```

### Field descriptions

> **Note:** Position, equity, and history values (`portfolio` account-value/PnL samples, `vlm`, and follower `vaultEquity`/`pnl`/`allTimePnl`) are returned as **decimal strings**. The aggregate stats `apr`, `leaderFraction`, `leaderCommission`, `maxDistributable`, and `maxWithdrawable` are returned as JSON **numbers**.

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Vault name. |
| `vaultAddress` | `string` | Vault contract address (0x-prefixed hex). |
| `leader` | `string` | Vault leader (manager) address. |
| `description` | `string` | Free-text description of the vault's strategy. |
| `portfolio` | `array` | Time-bucketed performance history. Each element is a `[period, series]` pair, where `period` is one of `day`, `week`, `month`, `allTime`, `perpDay`, `perpWeek`, `perpMonth`, or `perpAllTime`, and `series` holds the account-value and PnL time series for that period. |
| `portfolio.accountValueHistory` | `array` | `[timestampMs, accountValue]` samples. Account value is a decimal string. |
| `portfolio.pnlHistory` | `array` | `[timestampMs, pnl]` samples. PnL is a decimal string. |
| `portfolio.vlm` | `string` | Traded volume over the period, as a decimal string. |
| `apr` | `number` | Annualized return as a raw fraction (e.g. `0.3639` = 36.39%). |
| `followerState` | `object | null` | The requesting `user`'s follower state in this vault when the optional `user` field is supplied; `null` otherwise. |
| `leaderFraction` | `number` | Fraction of the vault's equity held by the leader. |
| `leaderCommission` | `number` | Leader's commission rate (fraction of follower profits). |
| `followers` | `array` | Per-follower positions in the vault. |
| `followers.user` | `string` | Follower wallet address (0x-prefixed hex). |
| `followers.vaultEquity` | `string` | Follower's current equity in the vault, in USD (decimal string). |
| `followers.pnl` | `string` | Follower's current-period PnL (decimal string). |
| `followers.allTimePnl` | `string` | Follower's all-time PnL in the vault (decimal string). |
| `followers.daysFollowing` | `int` | Number of days the follower has been in the vault. |
| `followers.vaultEntryTime` | `int` | Unix timestamp (ms) at which the follower entered the vault. |
| `followers.lockupUntil` | `int` | Unix timestamp (ms) until which the follower's equity is locked. |
| `maxDistributable` | `number` | Maximum amount currently distributable from the vault, in USD. |
| `maxWithdrawable` | `number` | Maximum amount the leader can currently withdraw, in USD. |
| `isClosed` | `boolean` | Whether the vault is closed. |
| `relationship` | `object` | Relationship metadata for the vault. |
| `relationship.type` | `string` | Relationship type - `"normal"` for a standalone vault, or `"parent"` / `"child"` for linked vaults. |
| `relationship.data` | `object` | Present for parent/child relationships. For a `parent`, contains `childAddresses` (an array of child vault addresses); for a `child`, identifies the parent vault. |
| `allowDeposits` | `boolean` | Whether the vault currently accepts new deposits. |
| `alwaysCloseOnWithdraw` | `boolean` | Whether a withdrawal always fully closes the follower's position. |

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

_Last reviewed: 2026-07-24_

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

---

## 73. vaultSummaries | Hyperliquid Info API

**Path:** api-reference/hyperliquid-info/vault-summaries

**Metadata:**
```yaml
title: vaultSummaries | Hyperliquid Info API
keywords: ["vaultSummaries","Hyperliquid vaultSummaries","Hyperliquid Info API","Hyperliquid","Hyperliquid info endpoint"]
sidebarTitle: vaultSummaries
description: Hyperliquid vaultSummaries: list summary information for every vault on the platform.
api: POST https://hypercore.goldrushdata.com/info
```

**Content:**

**Credit Cost:** 1 per call


**Processing:** Realtime

The Hyperliquid info endpoint with `type: "vaultSummaries"` is used to list summary information for every vault on the platform.

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

> **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "vaultSummaries"}`.
- Returns one entry per vault on the platform. The array may be empty depending on platform state.
- `relationship.type` distinguishes standalone vaults (`"normal"`) from parent/child vault relationships.
- This is a global, non-user-keyed type; `tvl` is a decimal string.
- For a single vault's full breakdown (portfolio history, followers, APR), use [vaultDetails](https://goldrush.dev/docs/api-reference/hyperliquid-info/vault-details).

Returns summary information for every vault on the platform, one entry per vault: its name, address, leader, total value locked, closed flag, relationship type, and creation time. Use `vaultDetails` for a single vault's full breakdown.

## Endpoint

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

## Request

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

### Example

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

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

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

vaults = response.json()
```

## Response

An array of vault-summary objects, one per vault. May be empty depending on platform state.

```json
[
  {
    "name": "BlockChain OG",
    "vaultAddress": "0xb9612144b6783f43191c09a7e56333f805ae12dd",
    "leader": "0xc7c6cf1f1a5c5ccb025416b24bbfa678dc5922e7",
    "tvl": "101.0",
    "isClosed": false,
    "relationship": {
      "type": "normal"
    },
    "createTimeMillis": 1773644731666
  }
]
```

### Field descriptions

> **Note:** `tvl` 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 |
| --- | --- | --- |
| `name` | `string` | Vault name. |
| `vaultAddress` | `string` | Vault contract address (0x-prefixed hex). |
| `leader` | `string` | Vault leader (manager) address. |
| `tvl` | `string` | Total value locked in the vault, in USD, as a decimal string. |
| `isClosed` | `boolean` | Whether the vault is closed. |
| `relationship` | `object` | Relationship metadata for the vault. |
| `relationship.type` | `string` | Relationship type (e.g. `"normal"` for a standalone vault, or `"parent"` / `"child"` for linked vaults). |
| `createTimeMillis` | `int` | Vault creation timestamp (Unix ms). |

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

_Last reviewed: 2026-07-24_

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

---

## 74. 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 */}

---

## 75. 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 */}

---

## 76. 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 */}

---

## 77. builderLiquidations | Hyperliquid WebSocket API

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

**Metadata:**
```yaml
title: builderLiquidations | Hyperliquid WebSocket API
keywords: ["builderLiquidations","Hyperliquid builderLiquidations","Hyperliquid WebSocket API","Hyperliquid","Hyperliquid WebSocket","builder liquidations"]
sidebarTitle: builderLiquidations
description: Hyperliquid builderLiquidations: stream liquidation fills attributed to your builder code 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-liquidations).

> **Note:** - GoldRush-native: No `wss://api.hyperliquid.xyz/ws` equivalent. The public WebSocket exposes per-wallet fills only; attributing a liquidation to a builder there would require subscribing to every wallet and filtering.
- Builder-scoped: `builder` is required. The stream returns only liquidation fills whose closing order was routed through your builder code - it is the intersection of `liquidationFills` and `builderFills`.
- Every entry carries a non-null `liquidation` object plus the attributed `builder`; the rest of the payload mirrors `userFills`.
- TWAP caveat: TWAP fills do not carry builder codes. If a user's last fill before liquidation was a TWAP fill, no builder liquidation is emitted for it.

Subscribe with your `builder` address to receive every liquidation fill attributed to your builder code, in real time. This is the builder-attributed slice of the global [`liquidationFills`](/api-reference/hyperliquid-websocket/liquidation-fills) stream: same per-fill shape as [`userFills`](/api-reference/hyperliquid-websocket/user-fills), with both the `liquidation` object and the `builder` attribution populated 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. `builder` is required.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | `string` | Yes | Always `"subscribe"` - GoldRush house style, matching the sibling channels. This is the only accepted form; a bare `type: "subscribe"` envelope is not recognized and is relayed upstream unchanged. |
| `subscription` | `object` | Yes |  __RESPONSE_ROW__type	string	Always `"builderLiquidations"`. __RESPONSE_ROW__builder	string	Your builder address (lowercase `0x`-prefixed 42-character hex). Only liquidations whose closing order was routed through this builder are streamed. __RESPONSE_ROW__aggregateByTime	boolean	When `true`, partial fills of the same liquidation within the same block are merged by `(user, time, order_id)` into one entry. **Defaults to `false`** on this channel. __RESPONSE_ROW__dex	string	Optional DEX filter - `"xyz"` or `"main"` (first-DEX fills only). Omit to stream across all DEXs.  |

### Example

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

> {"method":"subscribe","subscription":{"type":"builderLiquidations","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: "builderLiquidations",
      builder: "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === "builderLiquidations") {
    for (const [address, fill] of msg.liquidations) {
      console.log(
        "liquidated:", fill.liquidation.liquidatedUser,
        "via", fill.liquidation.method,
        "—", fill.coin, fill.sz, "@", fill.px,
        "builder:", fill.builder,
      );
    }
  }
});
```

```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": "builderLiquidations",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") == "builderLiquidations":
                for address, fill in msg["liquidations"]:
                    liq = fill["liquidation"]
                    print("liquidated:", liq["liquidatedUser"],
                          "via", liq["method"], "—",
                          fill["coin"], fill["sz"], "@", fill["px"],
                          "builder:", fill["builder"])

asyncio.run(main())
```

## Unsubscribe

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

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}
```

## Streamed message

Each push keeps the upstream wire shape: `type: "builderLiquidations"` and a `liquidations` array of `[address, fill]` tuples - it is **not** normalized to the `channel`/`fills` shape used by the sibling channels. The `address` (and mirrored `user` field) is the wallet whose position was liquidated; `liquidation.liquidatedUser` repeats it, and `builder` is the attributed builder code.

```json
{
  "type": "builderLiquidations",
  "liquidations": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",
        "sz": "1.5",
        "side": "A",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Close Long",
        "closedPnl": "-125.50",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": true,
        "fee": "2.50",
        "tid": 87654321,
        "cloid": null,
        "builderFee": null,
        "deployerFee": null,
        "feeToken": "USDC",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
        "twapId": null,
        "liquidation": {
          "liquidatedUser": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
          "markPx": "2148.00",
          "method": "market"
        },
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"
      }
    ]
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` | Always `"builderLiquidations"`. |
| `liquidations` | `array` | Tuples of `[address, fill]`. The `address` is the liquidated wallet. Same `fill` shape as [`userFills`](/api-reference/hyperliquid-websocket/user-fills), with `liquidation` and `builder` always populated. |
| `liquidations.builder` | `string` | The builder code the closing order was routed through - matches the subscribed `builder`. |
| `liquidations.builderFee` | `string | null` | Builder fee earned on this fill, denominated in `feeToken`; `null` when none applies. |
| `liquidations.deployerFee` | `string | null` | Deployer fee attributed to this fill, denominated in `feeToken`; `null` when none applies. |
| `liquidations.user` | `string` | The liquidated wallet - mirrors the tuple `address`. |
| `liquidations.liquidation` | `object` | Always present on this stream.  __RESPONSE_ROW__liquidatedUser	string	The wallet whose position was liquidated. __RESPONSE_ROW__liquidations.markPx	string	Mark price at the time of liquidation. __RESPONSE_ROW__liquidations.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`) match the [`userFills`](/api-reference/hyperliquid-websocket/user-fills) shape. |

> **Note:** **TWAP-preceded liquidations are omitted.** TWAP fills do not carry builder codes, so if a user's last fill before liquidation was a TWAP slice, GoldRush cannot attribute the liquidation to a builder and no entry is emitted on this stream. Use the global [`liquidationFills`](/api-reference/hyperliquid-websocket/liquidation-fills) stream if you need every liquidation regardless of builder attribution.

## Errors

A missing or malformed `builder` field returns an error message:

```json
{ "channel": "error", "data": "subscription builderLiquidations requires a 'builder' field" }
```

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

## Related endpoints


### liquidationFills

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

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


### builderFills

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

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


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


### 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-07-28_

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

---

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

**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 */}

---

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

**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 */}

---

## 80. 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 */}

---

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

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 */}

---

## 82. 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 */}

---

## 83. 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 */}

---

## 84. 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; and warehouse delivery for decoded `swaps` and `transfers`.

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

- [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); 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.
- **DEX swaps** decoded, landed in your warehouse - `swaps` normalizer.
- **SPL token transfers** decoded, landed in your warehouse - `transfers` normalizer.


### Foundational API

REST endpoint for SPL token balances on `solana-mainnet`. Base58 addresses.

[Read more](/goldrush-solana/foundational/overview)


### Warehouse delivery

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)


### Pipe SPL transfers to a warehouse

Land decoded SPL transfers in ClickHouse, BigQuery, or Postgres.

[Read more](/goldrush-solana/quickstart#2-pipe-spl-transfers-to-your-warehouse)

---

## 4. Solana API Quickstart

**Path:** goldrush-solana/quickstart

**Metadata:**
```yaml
title: Solana API Quickstart
sidebarTitle: Quickstart
description: Two quickstarts for Solana on GoldRush: SPL token balances (REST) and DEX swaps to a warehouse.
```

**Content:**

Pick the path that matches what you're building. Both 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. 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 swaps to your warehouse

Decoded DEX swaps landed in your warehouse.

[Read more](/goldrush-solana/warehouse/dex-swaps)


### SPL transfers to your warehouse

Decoded SPL transfers landed in your warehouse.

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

## Why warehouse delivery

REST is great for live lookups, but every retention cohort, churn model, token analytics dashboard, and tax export lives in your data warehouse - not in HTTP responses. GoldRush 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

Key columns of the `swaps` table 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

- [SPL Transfers warehouse recipe](/goldrush-solana/warehouse/spl-transfers) - companion table for transfer-side analytics.

---

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

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

Key columns of the `transfers` table:

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

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

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

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

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

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

## JSON-RPC

Arbitrum is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/arbitrum-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/arbitrum-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/arbitrum-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Arbitrum](/api-reference/json-rpc/arbitrum/eth-blocknumber)**
- **[eth_getBalance on Arbitrum](/api-reference/json-rpc/arbitrum/eth-getbalance)**
- **[eth_call on Arbitrum](/api-reference/json-rpc/arbitrum/eth-call)**
- **[eth_getLogs on Arbitrum](/api-reference/json-rpc/arbitrum/eth-getlogs)**
- **[eth_getTransactionReceipt on Arbitrum](/api-reference/json-rpc/arbitrum/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Arbitrum](/api-reference/json-rpc/chains/arbitrum).

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

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

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

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

## 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 and transactions for Base. 28 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `base-mainnet` |
| **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` (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/)**

## JSON-RPC

Base is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/base-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/base-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/base-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Base](/api-reference/json-rpc/base/eth-blocknumber)**
- **[eth_getBalance on Base](/api-reference/json-rpc/base/eth-getbalance)**
- **[eth_call on Base](/api-reference/json-rpc/base/eth-call)**
- **[eth_getLogs on Base](/api-reference/json-rpc/base/eth-getlogs)**
- **[eth_getTransactionReceipt on Base](/api-reference/json-rpc/base/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Base](/api-reference/json-rpc/chains/base).

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

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

## 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 and transactions for BNB Smart Chain (BSC). 28 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `bsc-mainnet` |
| **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` (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/)**

## JSON-RPC

BNB Smart Chain (BSC) is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/bsc-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/bsc-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/bsc-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on BNB Smart Chain (BSC)](/api-reference/json-rpc/bsc/eth-blocknumber)**
- **[eth_getBalance on BNB Smart Chain (BSC)](/api-reference/json-rpc/bsc/eth-getbalance)**
- **[eth_call on BNB Smart Chain (BSC)](/api-reference/json-rpc/bsc/eth-call)**
- **[eth_getLogs on BNB Smart Chain (BSC)](/api-reference/json-rpc/bsc/eth-getlogs)**
- **[eth_getTransactionReceipt on BNB Smart Chain (BSC)](/api-reference/json-rpc/bsc/eth-gettransactionreceipt)**

See the [full method list and per-method examples for BNB Smart Chain (BSC)](/api-reference/json-rpc/chains/bsc).

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

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

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

---

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

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

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

**Path:** chains/ethereum

**Metadata:**
```yaml
title: Ethereum
sidebarTitle: Ethereum
description: Get token balances and transactions for Ethereum. 28 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `eth-mainnet` |
| **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` (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/)**

## JSON-RPC

Ethereum is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/eth-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/eth-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/eth-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Ethereum](/api-reference/json-rpc/ethereum/eth-blocknumber)**
- **[eth_getBalance on Ethereum](/api-reference/json-rpc/ethereum/eth-getbalance)**
- **[eth_call on Ethereum](/api-reference/json-rpc/ethereum/eth-call)**
- **[eth_getLogs on Ethereum](/api-reference/json-rpc/ethereum/eth-getlogs)**
- **[eth_getTransactionReceipt on Ethereum](/api-reference/json-rpc/ethereum/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Ethereum](/api-reference/json-rpc/chains/ethereum).

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

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

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

**Path:** chains/gnosis

**Metadata:**
```yaml
title: Gnosis
sidebarTitle: Gnosis
description: Get token balances and transactions for Gnosis. 28 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/)**

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

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

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

**Path:** chains/hypercore

**Metadata:**
```yaml
title: HyperCore
sidebarTitle: HyperCore
description: Get token balances and transactions 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)

## Additional Resources

---

## 22. HyperEVM

**Path:** chains/hyperevm

**Metadata:**
```yaml
title: HyperEVM
sidebarTitle: HyperEVM
description: Get token balances and transactions for HyperEVM. 22 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `hyperevm-mainnet` |
| **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` (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/)**

## JSON-RPC

HyperEVM is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/hyperevm-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/hyperevm-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/hyperevm-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on HyperEVM](/api-reference/json-rpc/hyperevm/eth-blocknumber)**
- **[eth_getBalance on HyperEVM](/api-reference/json-rpc/hyperevm/eth-getbalance)**
- **[eth_call on HyperEVM](/api-reference/json-rpc/hyperevm/eth-call)**
- **[eth_getLogs on HyperEVM](/api-reference/json-rpc/hyperevm/eth-getlogs)**
- **[eth_getTransactionReceipt on HyperEVM](/api-reference/json-rpc/hyperevm/eth-gettransactionreceipt)**

See the [full method list and per-method examples for HyperEVM](/api-reference/json-rpc/chains/hyperevm).

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---

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

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

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

---

## 25. 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/)

---

## 26. 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/)

---

## 27. 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/)

---

## 28. MegaETH

**Path:** chains/megaeth

**Metadata:**
```yaml
title: MegaETH
sidebarTitle: MegaETH
description: Get token balances and transactions for MegaETH. 22 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.

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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `megaeth-mainnet` |
| **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` (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/)**

## JSON-RPC

MegaETH is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/megaeth-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/megaeth-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/megaeth-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on MegaETH](/api-reference/json-rpc/megaeth/eth-blocknumber)**
- **[eth_getBalance on MegaETH](/api-reference/json-rpc/megaeth/eth-getbalance)**
- **[eth_call on MegaETH](/api-reference/json-rpc/megaeth/eth-call)**
- **[eth_getLogs on MegaETH](/api-reference/json-rpc/megaeth/eth-getlogs)**
- **[eth_getTransactionReceipt on MegaETH](/api-reference/json-rpc/megaeth/eth-gettransactionreceipt)**

See the [full method list and per-method examples for MegaETH](/api-reference/json-rpc/chains/megaeth).

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

**Path:** chains/monad

**Metadata:**
```yaml
title: Monad
sidebarTitle: Monad
description: Get token balances and transactions for Monad. 22 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `monad-mainnet` |
| **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` (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/)**

## JSON-RPC

Monad is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/monad-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/monad-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/monad-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Monad](/api-reference/json-rpc/monad/eth-blocknumber)**
- **[eth_getBalance on Monad](/api-reference/json-rpc/monad/eth-getbalance)**
- **[eth_call on Monad](/api-reference/json-rpc/monad/eth-call)**
- **[eth_getLogs on Monad](/api-reference/json-rpc/monad/eth-getlogs)**
- **[eth_getTransactionReceipt on Monad](/api-reference/json-rpc/monad/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Monad](/api-reference/json-rpc/chains/monad).

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

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

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

---

## 32. 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/)

---

## 33. 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/)

---

## 34. 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/)

---

## 35. Optimism

**Path:** chains/optimism

**Metadata:**
```yaml
title: Optimism
sidebarTitle: Optimism
description: Get token balances and transactions for Optimism. 28 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)

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

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---

## 36. 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/)

---

## 37. Polygon

**Path:** chains/polygon

**Metadata:**
```yaml
title: Polygon
sidebarTitle: Polygon
description: Get token balances and transactions for Polygon. 28 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `matic-mainnet` |
| **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` (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/)**

## JSON-RPC

Polygon is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/matic-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/matic-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/matic-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Polygon](/api-reference/json-rpc/polygon/eth-blocknumber)**
- **[eth_getBalance on Polygon](/api-reference/json-rpc/polygon/eth-getbalance)**
- **[eth_call on Polygon](/api-reference/json-rpc/polygon/eth-call)**
- **[eth_getLogs on Polygon](/api-reference/json-rpc/polygon/eth-getlogs)**
- **[eth_getTransactionReceipt on Polygon](/api-reference/json-rpc/polygon/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Polygon](/api-reference/json-rpc/chains/polygon).

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

---

## 39. Robinhood Chain Onchain Data API

**Path:** chains/robinhood-chain

**Metadata:**
```yaml
title: Robinhood Chain Onchain Data API
sidebarTitle: Robinhood Chain
description: Get token balances and transactions for Robinhood Chain. 22 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)

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `robinhood-mainnet` |
| **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` (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/)**

## JSON-RPC

Robinhood Chain is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/robinhood-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/robinhood-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/robinhood-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Robinhood Chain](/api-reference/json-rpc/robinhood/eth-blocknumber)**
- **[eth_getBalance on Robinhood Chain](/api-reference/json-rpc/robinhood/eth-getbalance)**
- **[eth_call on Robinhood Chain](/api-reference/json-rpc/robinhood/eth-call)**
- **[eth_getLogs on Robinhood Chain](/api-reference/json-rpc/robinhood/eth-getlogs)**
- **[eth_getTransactionReceipt on Robinhood Chain](/api-reference/json-rpc/robinhood/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Robinhood Chain](/api-reference/json-rpc/chains/robinhood).

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---

## 40. Scroll

**Path:** chains/scroll

**Metadata:**
```yaml
title: Scroll
sidebarTitle: Scroll
description: Get token balances and transactions for Scroll. 23 endpoints supported.
chain_name: scroll-mainnet
chain_id: 534352
support_level: frontier
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** Discover Scroll, an L2 solution extending Ethereum with zero knowledge tech and EVM equivalence. Sign up for a free Covalent API key and start building today!

GoldRush offers the most comprehensive Scroll Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our Scroll Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

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

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---

## 41. Sei

**Path:** chains/sei

**Metadata:**
```yaml
title: Sei
sidebarTitle: Sei
description: Get token balances and transactions for Sei. 22 endpoints supported.
chain_name: sei-mainnet
chain_id: 1329
support_level: frontier
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** Sei is the first parallelized EVM, known for being extremely fast and processing multiple transactions at the same time.

GoldRush offers the most comprehensive Sei Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our Sei Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `sei-mainnet` |
| **Chain ID** | `1329` |
| **Network Type** | Frontier Chain |
| **Support Level** | frontier |
| **Block Explorer** | [Explorer](https://seistream.app/) |
| **Official Website** | [Sei Website](https://www.sei.io/) |
| **Native Gas Token** | SEI |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `sei-mainnet` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/sei-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

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

---

## 42. Solana

**Path:** chains/solana

**Metadata:**
```yaml
title: Solana
sidebarTitle: Solana
description: Solana data API - indexed SPL token balances (REST), 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` |
| **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` (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

## JSON-RPC

Solana is available on the GoldRush JSON-RPC service. Point your existing Solana tooling (`@solana/web3.js` or raw HTTP) at the GoldRush endpoint — the standard Solana JSON-RPC method set is supported over HTTP, with live subscriptions over WebSocket.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/solana-mainnet
```

WebSocket subscriptions are available at `wss://rpc.goldrushdata.com/v1/solana-mainnet`.

#### Example JSON-RPC Calls

```bash getSlot
curl https://rpc.goldrushdata.com/v1/solana-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'
```

```bash getBalance
curl https://rpc.goldrushdata.com/v1/solana-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["4ZJhPQAgUseCsWhKvJLTmmRRUV74fdoTpQLNfKoekbPY"]}'
```

#### Sample Methods

- **[getSlot on Solana](/api-reference/json-rpc/solana/getslot)**
- **[getBalance on Solana](/api-reference/json-rpc/solana/getbalance)**
- **[getBlock on Solana](/api-reference/json-rpc/solana/getblock)**
- **[getTransaction on Solana](/api-reference/json-rpc/solana/gettransaction)**
- **[getSignaturesForAddress on Solana](/api-reference/json-rpc/solana/getsignaturesforaddress)**

See the [full method list and per-method examples for Solana](/api-reference/json-rpc/chains/solana).

## Additional Resources

---

## 43. Sonic

**Path:** chains/sonic

**Metadata:**
```yaml
title: Sonic
sidebarTitle: Sonic
description: Get token balances and transactions for Sonic. 22 endpoints supported.
chain_name: sonic-mainnet
chain_id: 146
support_level: frontier
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** Sonic is the highest-performing EVM L1, combining speed, incentives, and world-class infrastructure for DeFi.

GoldRush offers the most comprehensive Sonic Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our Sonic Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `sonic-mainnet` |
| **Chain ID** | `146` |
| **Network Type** | Frontier Chain |
| **Support Level** | frontier |
| **Block Explorer** | [Sonic Explorer](https://sonicscan.org/) |
| **Official Website** | [Sonic Website](https://www.soniclabs.com/) |
| **Native Gas Token** | S |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `sonic-mainnet` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/sonic-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

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

---

## 44. 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/)

---

## 45. Tempo Onchain Data API

**Path:** chains/tempo

**Metadata:**
```yaml
title: Tempo Onchain Data API
sidebarTitle: Tempo
description: Get token balances and transactions 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

### JSON-RPC

Low-latency EVM JSON-RPC with global failover and archive depth.
    Point your existing tooling at the GoldRush endpoint — no code changes required.

    **Use cases: dApps, wallets, indexers, bots, and trading infrastructure.**

[Read more](/goldrush-json-rpc/overview)

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

## JSON-RPC

Tempo is available on the GoldRush JSON-RPC service. Point your existing EVM tooling (ethers.js, viem, web3.js, or raw HTTP) at the GoldRush endpoint — the standard `eth_*`, `net_*`, `web3_*`, `debug_*`, and `trace_*` methods are supported.

#### Endpoint

```
https://rpc.goldrushdata.com/v1/tempo-mainnet
```

#### Example JSON-RPC Calls

```bash eth_blockNumber
curl https://rpc.goldrushdata.com/v1/tempo-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

```bash eth_getBalance
curl https://rpc.goldrushdata.com/v1/tempo-mainnet \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"]}'
```

#### Sample Methods

- **[eth_blockNumber on Tempo](/api-reference/json-rpc/tempo/eth-blocknumber)**
- **[eth_getBalance on Tempo](/api-reference/json-rpc/tempo/eth-getbalance)**
- **[eth_call on Tempo](/api-reference/json-rpc/tempo/eth-call)**
- **[eth_getLogs on Tempo](/api-reference/json-rpc/tempo/eth-getlogs)**
- **[eth_getTransactionReceipt on Tempo](/api-reference/json-rpc/tempo/eth-gettransactionreceipt)**

See the [full method list and per-method examples for Tempo](/api-reference/json-rpc/chains/tempo).

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---

## 46. Unichain

**Path:** chains/unichain

**Metadata:**
```yaml
title: Unichain
sidebarTitle: Unichain
description: Get token balances and transactions for Unichain. 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/)

---

## 47. Viction

**Path:** chains/viction

**Metadata:**
```yaml
title: Viction
sidebarTitle: Viction
description: Get token balances and transactions for Viction. 22 endpoints supported.
chain_name: viction-mainnet
chain_id: 88
support_level: frontier
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** Viction, previously known as TomoChain, is a scalable, highly decentralized blockchain network that takes a community-driven approach to development and adoption.

GoldRush offers the most comprehensive Viction Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our Viction Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `viction-mainnet` |
| **Chain ID** | `88` |
| **Network Type** | Frontier Chain |
| **Support Level** | frontier |
| **Block Explorer** | [Explorer](https://www.vicscan.xyz/) |
| **Official Website** | [Viction Website](https://viction.xyz/) |
| **Native Gas Token** | TOMO |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `viction-mainnet` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/viction-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

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

---

## 48. 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/)

---

## 49. ZetaChain

**Path:** chains/zetachain

**Metadata:**
```yaml
title: ZetaChain
sidebarTitle: ZetaChain
description: Get token balances and transactions for ZetaChain. 22 endpoints supported.
chain_name: zetachain-mainnet
chain_id: 7000
support_level: community
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** ZetaChain is an EVM-compatible L1 blockchain for cross-chain apps.

GoldRush offers the most comprehensive ZetaChain Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our ZetaChain Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

## Mainnet

| Property | Value |
|----------|-------|
| **Chain Name** | `zetachain-mainnet` |
| **Chain ID** | `7000` |
| **Network Type** | Community Chain |
| **Support Level** | community |
| **Block Explorer** | [Explorer](https://explorer.zetachain.com/) |
| **Official Website** | [ZetaChain Website](https://www.zetachain.com/) |
| **Native Gas Token** | ZETA |

## API Usage

To use this blockchain network in GoldRush API calls, use:

#### Chain Name
- `zetachain-mainnet` (mainnet)

#### Example API Calls

```bash Chain Name (Mainnet)
curl -X GET "https://api.covalenthq.com/v1/zetachain-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key="
```

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

---

## 50. zkSync Era

**Path:** chains/zksync-era

**Metadata:**
```yaml
title: zkSync Era
sidebarTitle: zkSync Era
description: Get token balances and transactions for zkSync Era. 23 endpoints supported.
chain_name: zksync-mainnet
chain_id: 324
support_level: frontier
network_type: mainnet
apis: {"foundational":true,"streaming":false}
capabilities: {}
```

**Content:**

## Overview

> **Tip:** zkSync Era is a Layer-2 protocol that scales Ethereum with cutting-edge ZK tech.

GoldRush offers the most comprehensive zkSync Era Data API suite for developers, analysts, and enterprises. Whether you're
building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform,
our zkSync Era Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need.

 ### Supported APIs

### Foundational API

Access structured historical blockchain data across 100+ chains using REST APIs.
    Get token balances, transaction histories, decoded event logs, NFT assets, token holders and more.

    **Use cases: Wallets, portfolio trackers, crypto accounting & tax tools, and DeFi dashboards.**

[Read more](/goldrush-foundational-api)

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

## Additional Resources

- [GoldRush API Documentation](https://goldrush.dev/docs/)
- [Supported Chains List](https://goldrush.dev/chains/)
- [API Reference](https://goldrush.dev/docs/api-reference/)

---