Query

A request to retrieve the current or historical token holdings of a specific wallet address. This is the most fundamental query type.

• Example: "What is the ETH balance of address 0x...?"
• Key Data: Native token (ETH, MATIC) and ERC-20/ERC-721 token balances.
• Use Case: Wallet dashboards, airdrop eligibility checks, and portfolio tracking.

A request to fetch details about a specific on-chain transaction or a filtered list of transactions.

• Filters: By transaction hash, block number, sender/recipient address, or timestamp.
• Data Returned: Status (success/failed), gas used, input data, and event logs.
• Use Case: Investigating a specific transfer, auditing contract interactions, or building transaction explorers.

A request to extract specific smart contract events emitted during transactions. This is crucial for decoding complex contract activity.

• Example: Querying all Transfer or Swap events from a DEX contract.
• Key Filters: Contract address, event signature, and indexed topic parameters.
• Use Case: Tracking NFT sales, monitoring liquidity pool activity, or analyzing governance proposals.

A request that performs calculations across multiple data points to produce summarized metrics.

• Common Operations: SUM, AVG, COUNT, MIN/MAX.
• Examples: "Total volume traded on Uniswap V3 in the last 24 hours," "Average transaction fee on Ethereum this week."
• Use Case: Generating dashboards, calculating TVL, and producing analytical reports.

A request to read the current value of a specific variable or data structure stored within a smart contract.

• Mechanism: Executes a call to a contract's view or pure function without sending a transaction.
• Examples: Querying a token's total supply, a user's staking rewards, or a DAO's proposal count.
• Use Case: Displaying real-time protocol metrics, checking user entitlements, or verifying contract state.

An advanced query that reconstructs the full execution path and internal state changes of a transaction.

• Data Sources: Uses debug_traceTransaction or similar RPC methods to access opcode-level traces.
• Reveals: Internal calls between contracts, precise gas consumption per step, and state changes that didn't emit events.
• Use Case: Security auditing, complex bug investigation, and understanding intricate DeFi arbitrage transactions.

Efficient querying is critical for application performance and cost management.

• Batching: Combining multiple RPC requests (e.g., eth_getBalance for 100 addresses) into a single call.
• Caching: Storing frequently accessed data (like token prices) to reduce redundant on-chain queries.
• Choosing the Right Layer: Using an indexer for complex historical analysis instead of raw log queries on a full node.
• Rate Limits & Costs: Being aware of provider tiers, request limits, and associated costs for high-volume querying.

Games require fast, complex data that cannot be stored efficiently on-chain. Hybrid queries combine on-chain verification with off-chain performance.

• Examples: Fetching a player's leaderboard rank, real-time match statistics, or the metadata for an NFT (image, 3D model) stored on IPFS or a centralized server.
• Architecture: Often served by dedicated game servers or decentralized oracle networks that bridge on-chain triggers with off-chain data.

Queries power the financial dashboards and analytics tools central to GameFi, providing visibility into the game's economy.

• Key Metrics: Total Value Locked (TVL) in game pools, token inflation/deflation rates, marketplace trading volume, and yield farming APYs.
• Use Case: Players and analysts run these queries to assess investment opportunities, game sustainability, and asset liquidity before participating.

A specific type of on-chain query that reads the current variables and storage of a game's smart contracts without executing a transaction (a call).

• Purpose: Checking live in-game variables like a character's health, a land parcel's cooldown timer, or the available supply of a consumable item.
• Importance: Enables real-time game logic and UI updates that reflect the true, verifiable state of the game world on the blockchain.

Queries that resolve a player's decentralized identity and aggregated asset portfolio across chains and games.

• Function: Answering questions like "What games does this wallet address play?" or "What is the total value of this player's cross-game assets?"
• Technology: Often relies on decentralized identifiers (DIDs) and unified profile protocols that abstract away wallet addresses, creating a portable gamer identity.

A specialized service that pre-processes and organizes raw blockchain data into queryable databases. Indexers eliminate the need to scan the entire chain for each request, enabling fast retrieval of specific events, transactions, or state changes. They are a core component of The Graph protocol and other query stacks.

• Function: Listens to blocks, extracts data based on schemas, and stores it in optimized formats.
• Example: An indexer for an NFT marketplace would track all Transfer events and maintain a real-time ledger of token ownership.

A direct, low-level interface for submitting transactions and querying the current state of a blockchain node. RPC calls (e.g., eth_getBalance) are fundamental but limited to simple, real-time data.

• Function: Provides access to node-level data like account balances, transaction receipts, and block headers.
• Limitation: Cannot answer historical or aggregated questions (e.g., "total DEX volume last month") without extensive client-side processing.

An open API built by a developer that defines how to index and query data from a specific smart contract or protocol. It consists of a manifest (subgraph.yaml), a schema, and mapping scripts.

• Function: Instructs indexers on which data to extract and how to transform it.
• Query Access: Once deployed, the subgraph exposes a GraphQL endpoint for applications to fetch the indexed data with complex, nested queries.

A query language for APIs that allows clients to request exactly the data they need in a single request. It is the standard interface for querying indexed data from services like The Graph.

• Advantage: Prevents over-fetching (getting unnecessary data) and under-fetching (requiring multiple round trips).
• Example Query: A single GraphQL query can fetch a user's swap history, associated token details, and pool statistics simultaneously.

A service that provides external, off-chain data to smart contracts on-chain. While both provide data, oracles are for blockchain input, whereas queries are typically for off-chain read access to blockchain data.

• Primary Use: Supplies real-world information (price feeds, weather data) to trigger or settle on-chain contracts.
• Key Difference: Queries pull data from the chain for analysis; oracles push data onto the chain for contract execution.

A type of blockchain node that retains the full historical state for every block, unlike standard nodes which prune old data. It is essential for executing complex queries that require historical context.

• Capability: Can answer questions about the state of an address or contract at any past block height.
• Resource Intensive: Requires significant storage but is the gold standard for reliable historical data querying without an indexer.