For AI agents: the documentation index is at /llms.txt. Markdown versions of pages are available by appending .md to the URL.
Skip to main content

HyperSync Client Libraries

HyperSync provides powerful client libraries that enable you to integrate high-performance blockchain data access into your applications. These libraries handle the communication with HyperSync servers, data serialization/deserialization, and provide convenient APIs for querying blockchain data.

ClientResources
Node.js📝 API Docs · 📦 NPM · 💻 GitHub · 🧪 Examples
Python📦 PyPI · 💻 GitHub · 🧪 Examples
Rust📦 Crates.io · 📝 API Docs · 💻 GitHub · 🧪 Examples
Go (community)💻 GitHub · 🧪 Examples
Solana (Rust)📖 Guide · 📦 Crates.io · 📝 API Docs · 💻 GitHub
API Tokens🔑 Get Tokens

Client Overview​

The Node.js and Python clients are bindings over the Rust client, so the three share one engine and the same defaults. The Go client is a separate, community-maintained implementation. This page describes Node.js 1.4.1, Python 1.2.1 and Rust 1.4.1.

The Node.js, Python and Rust clients share these key features:

  • Optimized Transport: Responses arrive in Apache Arrow, a binary columnar format, rather than JSON
  • Automatic Pagination: stream and collect cover a whole block range for you
  • Retries: Failed requests are retried with backoff, 12 times by default
  • Event Decoding: Decoder parses raw logs into typed values

Choose the client that best matches your application's technology stack:

FeatureNode.jsPythonRustGo
TypingTypeScriptType HintsNativeNative
OutputJS objects, ParquetPython objects, Arrow (pyarrow), ParquetRust structs, Arrow, ParquetGo structs
Installationnpmpipcargogo get

API at a Glance​

Exact names in each official client. Each one takes a query built as described in the Query Reference.

TaskNode.jsPythonRust
Create a clientnew HypersyncClient({ url, apiToken })HypersyncClient(ClientConfig(url=..., api_token=...))Client::builder().url(..).api_token(..).build()?
One requestget(query)get(query)get(&query)
Stream a rangestream(query, {}), then recv() until nullstream(query, StreamConfig()), then recv() until Nonestream(query, StreamConfig::default()), then recv() until None
Collect a range in memorycollect(query, config)collect(query, config)collect(query, config)
Logs joined with their block and transactiongetEvents, streamEvents, collectEventsget_events, stream_events, collect_eventsget_events, stream_events, collect_events
Arrow tablesnot availableget_arrow, stream_arrow, collect_arrowget_arrow, stream_arrow, collect_arrow
Write Parquet to a directorycollectParquet(dir, query, config)collect_parquet(dir, query, config)collect_parquet(dir, query, config)
Chain height and chain IDgetHeight(), getChainId()get_height(), get_chain_id()get_height(), get_chain_id()
Follow new blocksstreamHeight()not availablestream_height()
Rate limit infogetWithRateLimit, rateLimitInfo, waitForRateLimitget_with_rate_limit, rate_limit_info, wait_for_rate_limitget_with_rate_limit, rate_limit_info, wait_for_rate_limit
Decode logsDecoder.fromSignatures([...]), decodeLogsDecoder([...]), decode_logsDecoder::from_signatures(&[...]), decode_log
Decode call inputCallDecoder.fromSignatures, decodeTransactionsInput, decodeTracesInputCallDecoder([...]), decode_transactions_input, decode_traces_inputCallDecoder::from_signatures, decode_input
Query keyscamelCase: fromBlock, fieldSelectionsnake_case: from_block, field_selectionbuilder: Query::new().from_block(..)
Field names"BlockNumber""block_number"LogField::BlockNumber

The request and stream methods are async: await them in Node.js and Python, and .await them in Rust (Rust's stream_height returns its receiver directly). In Rust, Client::builder().chain_id(1) sets the URL to https://1.hypersync.xyz.

The main client options are the same in every official client (camelCase in Node.js): url, api_token, http_req_timeout_millis (default 30000), max_num_retries (default 12), retry_backoff_ms (500), retry_base_ms (200), retry_ceiling_ms (5000) and proactive_rate_limit_sleep (true). Node.js also has enableChecksumAddresses. The stream options are in Stream Config & Tuning.

To react to new blocks without polling, stream the chain height. It works the same way in Rust with stream_height():

const heights = await client.streamHeight();
while (true) {
  const event = await heights.recv(); // { type: "Connected" | "Height" | "Reconnecting", ... }
  if (event === null) break;
  if (event.type === "Height") console.log("new block", event.height);
}

Node.js Client​

Resources

The Node.js client provides a TypeScript-first experience for JavaScript developers.

Installation​

# Using npm
npm install @envio-dev/hypersync-client

# Using yarn
yarn add @envio-dev/hypersync-client

# Using pnpm
pnpm add @envio-dev/hypersync-client

Python Client​

Resources

The Python client provides a Pythonic interface with full type hinting support.

Installation​

pip install hypersync

Rust Client​

Resources

The Rust client provides the most efficient and direct access to HyperSync, with all the safety and performance benefits of Rust.

Installation​

Add the following to your Cargo.toml:

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

Solana Client​

Resources

Solana HyperSync has its own client, because the query and table model is Solana-shaped (slots, instruction calls, account activity) rather than EVM-shaped. It is Rust today, with unpublished Node bindings in the same repository. Everything client-side is covered in the Solana client guide.

[dependencies]
hypersync-client-solana = "0.2"
hypersync-solana-net-types = "0.2" # SolanaQuery and the selection types
tokio = { version = "1", features = ["full"] }
anyhow = "1"

The query types live in the separate hypersync-solana-net-types crate. The client doesn't re-export them, so add both.

Go Client​

Resources
Community Maintained

The Go client is community maintained and marked as work-in-progress. For production use, you may want to test thoroughly or consider the officially supported clients.

The Go client provides a native Go interface for accessing HyperSync, with support for streaming and decoding blockchain data. It is written in Go rather than built on the Rust client, so the API, defaults and the stream tuning on this site don't apply to it. It has Get, Stream, GetHeight and range helpers such as StreamLogsInRange, and can call HyperRPC, but has no Parquet output.

Installation​

go get github.com/enviodev/hypersync-client-go

The repository has no tagged releases, so this installs the latest commit on main. Set RpcEndpoint as well as Endpoint when you create a client. Without it, NewClient fails with failed to connect to RPC client: dial unix: missing address:

client, err := hypersyncgo.NewClient(ctx, options.Node{
    Endpoint:    "https://eth.hypersync.xyz",
    RpcEndpoint: "https://eth.rpc.hypersync.xyz",
    ApiToken:    os.Getenv("ENVIO_API_TOKEN"),
})

Using API Tokens​

Get Your API Token

You'll need an API token to use any HyperSync client. Get your token here.

All HyperSync clients require an API token for authentication. Tokens are used to manage access and usage limits.

To get an API token:

  1. Visit Envio
  2. Register or sign in with your github account
  3. Navigate to the API Tokens section
  4. Create a new token

For detailed instructions, see our API Tokens guide.

Client Selection Guide​

Choose the client that best fits your use case:

Node.js Client

Choose when: You're building JavaScript/TypeScript applications or if your team is most comfortable with the JavaScript ecosystem.

Python Client

Choose when: You're doing data science work, need integration with pandas/numpy, or if your team prefers Python's simplicity.

Rust Client

Choose when: You need maximum performance, are doing systems programming, or building performance-critical applications.

Go Client

Choose when: You're working in a Go ecosystem and want native integration with Go applications. Note that this client is community maintained.

Additional Resources​

Support​

Need help getting started or have questions about our clients? Connect with our community: