Crate hypersync_client

Expand description

§hypersync-client

Rust crate for Envio’s HyperSync client. The most performant way to access HyperSync, with direct access to the underlying Rust implementation and no FFI overhead.

Full API documentation on docs.rs

§What is HyperSync?

HyperSync is Envio’s high-performance blockchain data retrieval layer. It is a purpose-built alternative to JSON-RPC endpoints, offering up to 2000x faster data access across 70+ EVM-compatible networks and Fuel.

HyperSync lets you query logs, transactions, blocks, and traces with flexible filtering and field selection, returning only the data you need in binary formats for maximum throughput.

If you need a full indexing framework on top of HyperSync with GraphQL APIs and schema management, see HyperIndex.

§Features

Maximum performance: Direct Rust implementation with no FFI overhead
Arrow and Parquet format support: Stream blockchain data as Apache Arrow record batches for in-memory analytics, or write directly to Parquet files
Binary transport: Uses CapnProto serialization to minimize bandwidth and maximize throughput
Flexible queries: Filter logs, transactions, blocks, and traces with granular control
Field selection: Choose exactly which fields to return, reducing unnecessary data transfer
Automatic pagination: Handles large datasets with built-in pagination
Event decoding: Decode ABI-encoded event data directly in the stream
Real-time updates: Live height streaming via Server-Sent Events
Production ready: Built-in rate limiting, automatic retries, and error handling
Async/await: Built on Tokio for fully asynchronous operation
70+ networks: Access any HyperSync-supported network

§Installation

Add to your Cargo.toml:

[dependencies]
hypersync-client = "1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

§API Token

An API token is required to use HyperSync. Get your token here, then set it as an environment variable:

export ENVIO_API_TOKEN="your-token-here"

§Quick Start

Query ERC-20 Transfer events from USDC on Ethereum mainnet:

use hypersync_client::{Client, net_types::{Query, LogFilter, LogField}, StreamConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a client for Ethereum mainnet
    let client = Client::builder()
        .chain_id(1)
        .api_token(std::env::var("ENVIO_API_TOKEN")?)
        .build()?;

    // Query ERC-20 Transfer events from USDC contract
    let query = Query::new()
        .from_block(0)
        .where_logs(
            LogFilter::all()
                // USDC contract address
                .and_address(["0xA0b86a33E6411b87Fd9D3DF822C8698FC06BBe4c"])?
                // ERC-20 Transfer event signature
                .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?
        )
        .select_log_fields([
            LogField::Data,
            LogField::Topic0,
            LogField::Topic1,
            LogField::Topic2,
        ]);

    // Get all data in one response
    let response = client.get(&query).await?;
    println!("Retrieved {} blocks", response.data.blocks.len());

    // Or stream data for large ranges
    let mut receiver = client.stream(query, StreamConfig::default()).await?;
    while let Some(response) = receiver.recv().await {
        let response = response?;
        println!("Streaming: got blocks up to {}", response.next_block);
    }

    Ok(())
}

See the examples directory for more usage patterns including wallet transactions, block streaming, and decoded event output.

§Main Types

Client - Main client for interacting with HyperSync servers
net_types::Query - Query builder for specifying what data to fetch
StreamConfig - Configuration for streaming operations
QueryResponse - Response containing blocks, transactions, logs, and traces
ArrowResponse - Response in Apache Arrow format for high-performance processing

§Connecting to Different Networks

Change the chain_id (or use url) to connect to any supported network:

use hypersync_client::Client;

let api_token = std::env::var("ENVIO_API_TOKEN")?;

// Arbitrum
Client::builder().chain_id(42161).api_token(&api_token).build()?;

// Base
Client::builder().chain_id(8453).api_token(&api_token).build()?;

// Or use the URL directly
Client::builder().url("https://eth.hypersync.xyz").api_token(&api_token).build()?;

See the full list of supported networks and URLs.

§What you can build

The Rust client is well suited for performance-critical applications that need direct, low-latency access to blockchain data:

Blockchain indexers: Build custom data pipelines without the overhead of JSON-RPC
Data analytics: Scan entire chain histories in seconds, not hours
Block explorers: Power responsive, real-time interfaces with comprehensive data access
ETL pipelines: Extract and transform on-chain data at scale using Apache Arrow output
Monitoring tools: Track wallet activity, token transfers, and contract events in near real-time
Security tooling: Scan token approvals and transaction history across 70+ chains. See Snubb, a CLI tool built with HyperSync that scans outstanding token approvals across 70 chains simultaneously

§Documentation

API Reference (docs.rs)
HyperSync Documentation
Query Reference
All Client Libraries (Node.js, Python, Go)

§FAQ

How does this compare to using JSON-RPC? HyperSync retrieves data up to 2000x faster than traditional JSON-RPC. Scanning the entire Arbitrum chain for sparse log data takes seconds instead of hours.

Do I need an API token? Yes. Get one here.

Which networks are supported? 70+ EVM-compatible networks and Fuel. See the full list.

What serialization formats are supported? CapnProto (recommended for performance) and JSON. Both are available via SerializationFormat.

Is there an Arrow output format? Yes. Use stream_arrow to receive data as Apache Arrow record batches, which integrates directly with analytics and DataFrame libraries.

What is the difference between this and the other HyperSync clients? This is the native Rust implementation. The Python and Node.js clients are built on top of this crate via FFI bindings. If you don’t need Rust specifically, those clients give you the same HyperSync performance in your preferred language.

What is the difference between HyperSync and HyperIndex? HyperSync is the raw data access layer. Use it when you need direct, low-level access to blockchain data in your own pipeline. HyperIndex is the full indexing framework built on top of HyperSync, with schema management, event handlers, and a GraphQL API.

§Support

Re-exports§

pub use hypersync_format as format;
pub use hypersync_net_types as net_types;
pub use hypersync_schema as schema;

Modules§

arrow_reader: Reader types for reading Arrow record batch data as native Rust types.
preset_query: Preset queries for common use cases.
simple_types: Base object types for the Hypersync client.

Structs§

ArrowResponseData: Query response in Arrow format
CallDecoder: Decode input data parsing input data.
Client: Client to handle http requests and retries.
ClientBuilder: Builder for creating a hypersync client with configuration options.
ClientConfig: Configuration for the hypersync client.
ColumnMapping: Column mapping for stream function output. It lets you map columns you want into the DataTypes you want.
Decoder: Decode logs parsing topics and log data.
QueryResponse: Query response from hypersync instance. Contain next_block field in case query didn’t process all the block range
QueryResponseWithRateLimit: Response that includes rate limit information from the server.
RateLimitInfo: Rate limit information extracted from response headers.
StreamConfig: Config for hypersync event streaming.

Enums§

DataType: DataType is an enumeration representing the different data types that can be used in the column mapping. Each variant corresponds to a specific data type.
HeightStreamEvent: Events emitted by the height stream.
HexOutput: Determines format of Binary column
HyperSyncResponseError: Used to indicate whether or not a retry should be attempted.
SerializationFormat: Determines query serialization format for HTTP requests.

Type Aliases§

ArrowResponse: Alias for Arrow Query response
EventResponse: Alias for Event oriented, vectorized QueryResponse