Queries Overview

Queries provide on-demand access to Guardian-attested on-chain data. They allow smart contracts to fetch real-time, verifiable data from across the multichain ecosystem, such as prices, rates, and liquidity.

Key Features

• On-demand data access: Fetch price feeds, interest rates, and other data in real-time.
• Guardian attested: All data is signed by Guardians for trustless validation.
• Cross-chain ready: Request data on one chain, use it on another.
• Smart contract integration: Results are delivered as Verified Action Approvals (VAAs), readable by smart contracts.
• Chain agnostic: works across supported EVM chains, Solana, Sui, and more.

How It Works

A query request follows a simple but robust lifecycle. The off-chain service responsible for handling requests is called the CCQ Server (Cross-Chain Query Server), also referred to as the Query Server throughout this documentation.

1. An off-chain app sends a query to the CCQ Server via HTTPS
2. The CCQ Server checks the request and shares it with Guardians
3. Guardians independently fetch the data, verify it, and sign the result
4. Once enough Guardians (2/3 quorum) return matching results, the CCQ Server aggregates and sends the final response
5. The off-chain app submits this result to a smart contract, which verifies the Guardian signatures and uses the data

The CCQ Server is permissioned but trustless. Most queries resolve in under one second, and Guardians retry failed requests for up to one minute. Up to 255 queries can be batched together to optimize performance, supporting efficient multichain workflows.

Use Cases

Queries enable a wide range of cross-chain applications. Below are common use cases and the Wormhole stack components you can use to build them.

• Borrowing and Lending Across Chains (e.g., Folks Finance)

  • Queries: Fetch rates and prices in real-time.
  • Messaging: Sync actions between chains.
  • Native Token Transfer: Transfer collateral as native assets.

• Cross-Chain Swaps and Liquidity Aggregation (e.g., StellaSwap)

  • Queries: Fetch live prices optimal trade execution.
  • Connect: Handle user-friendly asset transfers.
  • Native Token Transfer: Moves native tokens.

• Real-Time Price Feeds and Trading Strategies (e.g., Infinex)

  • Queries: Fetch price feeds.
  • Messaging: Trigger trades.

• Multichain Prediction Markets

  • Queries: Fetch market data and odds.
  • Settlement: Automates token execution.

• Oracle Networks (e.g., Pyth)

  • Queries: Source data from chains.
  • Messaging: Ensures tamper-proof data relay across networks.

Next Steps

Follow these steps to get started with Queries:

Get Started with Queries

Install the SDK, request an API key, and run your first verifiable query.

Construct a Query

Set up the query configuration.

Make a Query Request

Send your query to the Query Server using HTTPS.

Submit a Query Response

Post the Guardian-signed VAA to your smart contract.