HyperSync Preset Queries

HyperSync's client libraries include helper functions that build common queries. These presets are useful when you need raw blockchain objects without crafting a query manually.

Each preset returns a Query object so you can pass it directly to client.get, client.stream, or client.collect.

The names below are the Python ones. Node.js and TypeScript expose the same four presets in camelCase, and Rust uses a different naming scheme again. See Other client libraries.

Available Presets

preset_query_blocks_and_transactions(from_block, to_block=None)

Returns every block and all associated transactions within the supplied block range. Leave to_block unset to query up to the current chain head.

import hypersync
import asyncio

async def main():
    client = hypersync.HypersyncClient(
        hypersync.ClientConfig(
            url="https://eth.hypersync.xyz",
            bearer_token="your-token-here",  # Get from https://docs.envio.dev/docs/HyperSync/api-tokens
        )
    )

    query = hypersync.preset_query_blocks_and_transactions(17_000_000, 17_000_050)
    result = await client.get(query)
    print(f"Query returned {len(result.data.blocks)} blocks and {len(result.data.transactions)} transactions")

asyncio.run(main())

preset_query_blocks_and_transaction_hashes(from_block, to_block=None)

Returns each block in the range along with only the transaction hashes.

preset_query_logs(address, from_block, to_block=None)

Fetches all logs emitted by a single contract address in the given block range. The address is the first argument.

logs_res = await client.get(
    hypersync.preset_query_logs("0xdAC17F958D2ee523a2206206994597C13D831ec7", 17_000_000, 17_000_050)
)

preset_query_logs_of_event(address, topic0, from_block, to_block=None)

Fetches logs emitted by a contract address that match a single event topic. topic0 is the hashed event signature, not the human-readable one.

# keccak256("Transfer(address,address,uint256)")
transfer_topic0 = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

logs_res = await client.get(
    hypersync.preset_query_logs_of_event(
        "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        transfer_topic0,
        17_000_000,
        17_000_050,
    )
)

Other client libraries

Node.js and TypeScript

@envio-dev/hypersync-client exports the same four presets in camelCase, with the same argument order. The Python snake_case names are not defined in the Node client.

import {
  presetQueryBlocksAndTransactions,
  presetQueryBlocksAndTransactionHashes,
  presetQueryLogs,
  presetQueryLogsOfEvent,
} from "@envio-dev/hypersync-client";

const query = presetQueryLogs(
  "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  17_000_000,
  17_000_050
);

Rust

The Rust client groups these in a preset_query module, drops the preset_query_ prefix, and takes the block range first rather than last.

use hypersync_client::preset_query;

let query = preset_query::logs(17_000_000, Some(17_000_050), contract_address);

The module provides blocks_and_transactions, blocks_and_transaction_hashes, logs, logs_of_event, transactions, and transactions_from_address. The last two have no Python or Node.js equivalent.

For runnable examples, see the Python and Node.js client repositories.

Use these helpers whenever you need a quick query without specifying field selections or joins manually.