> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

# 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.

## Quick Links

| Client | Resources |
| --- | --- |
| **Node.js** | [📝 API Docs](https://enviodev.github.io/hypersync-client-node/) · [📦 NPM](https://www.npmjs.com/package/@envio-dev/hypersync-client) · [💻 GitHub](https://github.com/enviodev/hypersync-client-node) · [🧪 Examples](https://github.com/enviodev/hypersync-client-node/tree/main/examples) |
| **Python** | [📦 PyPI](https://pypi.org/project/hypersync/) · [💻 GitHub](https://github.com/enviodev/hypersync-client-python) · [🧪 Examples](https://github.com/enviodev/hypersync-client-python/tree/main/examples) |
| **Rust** | [📦 Crates.io](https://crates.io/crates/hypersync-client) · [📝 API Docs](https://docs.rs/hypersync-client/latest/hypersync_client/) · [💻 GitHub](https://github.com/enviodev/hypersync-client-rust) · [🧪 Examples](https://github.com/enviodev/hypersync-client-rust/tree/main/examples) |
| **Go** _(community)_ | [💻 GitHub](https://github.com/enviodev/hypersync-client-go) · [🧪 Examples](https://github.com/enviodev/hypersync-client-go/tree/main/examples) |
| **Solana** _(Rust)_ | [📖 Guide](https://docs.envio.dev/docs/HyperSync/solana-client.md) · [📦 Crates.io](https://crates.io/crates/hypersync-client-solana) · [📝 API Docs](https://docs.rs/hypersync-client-solana) · [💻 GitHub](https://github.com/enviodev/hypersync-client-solana) |
| **API Tokens** | [🔑 Get Tokens](https://docs.envio.dev/docs/HyperSync/api-tokens.md) |

## 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:

| Feature | Node.js | Python | Rust | Go |
| --- | --- | --- | --- | --- |
| Typing | TypeScript | Type Hints | Native | Native |
| Output | JS objects, Parquet | Python objects, Arrow (pyarrow), Parquet | Rust structs, Arrow, Parquet | Go structs |
| Installation | npm | pip | cargo | go get |

## API at a Glance

Exact names in each official client. Each one takes a `query` built as described in the [Query Reference](https://docs.envio.dev/docs/HyperSync/hypersync-query.md).

| Task | Node.js | Python | Rust |
| --- | --- | --- | --- |
| Create a client | `new HypersyncClient({ url, apiToken })` | `HypersyncClient(ClientConfig(url=..., api_token=...))` | `Client::builder().url(..).api_token(..).build()?` |
| One request | `get(query)` | `get(query)` | `get(&query)` |
| Stream a range | `stream(query, {})`, then `recv()` until `null` | `stream(query, StreamConfig())`, then `recv()` until `None` | `stream(query, StreamConfig::default())`, then `recv()` until `None` |
| Collect a range in memory | `collect(query, config)` | `collect(query, config)` | `collect(query, config)` |
| Logs joined with their block and transaction | `getEvents`, `streamEvents`, `collectEvents` | `get_events`, `stream_events`, `collect_events` | `get_events`, `stream_events`, `collect_events` |
| Arrow tables | not available | `get_arrow`, `stream_arrow`, `collect_arrow` | `get_arrow`, `stream_arrow`, `collect_arrow` |
| Write Parquet to a directory | `collectParquet(dir, query, config)` | `collect_parquet(dir, query, config)` | `collect_parquet(dir, query, config)` |
| Chain height and chain ID | `getHeight()`, `getChainId()` | `get_height()`, `get_chain_id()` | `get_height()`, `get_chain_id()` |
| Follow new blocks | `streamHeight()` | not available | `stream_height()` |
| Rate limit info | `getWithRateLimit`, `rateLimitInfo`, `waitForRateLimit` | `get_with_rate_limit`, `rate_limit_info`, `wait_for_rate_limit` | `get_with_rate_limit`, `rate_limit_info`, `wait_for_rate_limit` |
| Decode logs | `Decoder.fromSignatures([...])`, `decodeLogs` | `Decoder([...])`, `decode_logs` | `Decoder::from_signatures(&[...])`, `decode_log` |
| Decode call input | `CallDecoder.fromSignatures`, `decodeTransactionsInput`, `decodeTracesInput` | `CallDecoder([...])`, `decode_transactions_input`, `decode_traces_input` | `CallDecoder::from_signatures`, `decode_input` |
| Query keys | camelCase: `fromBlock`, `fieldSelection` | snake_case: `from_block`, `field_selection` | builder: `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](https://docs.envio.dev/docs/HyperSync/stream-config-tuning.md).

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

```typescript
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

:::info Resources

- [📝 API Documentation](https://enviodev.github.io/hypersync-client-node/)
- [📦 NPM Package](https://www.npmjs.com/package/@envio-dev/hypersync-client)
- [💻 GitHub Repository](https://github.com/enviodev/hypersync-client-node)
- [🧪 Example Projects](https://github.com/enviodev/hypersync-client-node/tree/main/examples)
  :::

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

### Installation

```bash
# 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

:::info Resources

- [📦 PyPI Package](https://pypi.org/project/hypersync/)
- [💻 GitHub Repository](https://github.com/enviodev/hypersync-client-python)
- [🧪 Example Projects](https://github.com/enviodev/hypersync-client-python/tree/main/examples)
  :::

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

### Installation

```bash
pip install hypersync
```

## Rust Client

:::info Resources

- [📦 Crates.io Package](https://crates.io/crates/hypersync-client)
- [📝 API Documentation](https://docs.rs/hypersync-client/latest/hypersync_client/)
- [💻 GitHub Repository](https://github.com/enviodev/hypersync-client-rust)
- [🧪 Example Projects](https://github.com/enviodev/hypersync-client-rust/tree/main/examples)
  :::

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`:

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

## Solana Client

:::info Resources

- [📖 Solana Client Guide](https://docs.envio.dev/docs/HyperSync/solana-client.md)
- [📦 Crates.io Package](https://crates.io/crates/hypersync-client-solana)
- [📝 API Documentation](https://docs.rs/hypersync-client-solana)
- [💻 GitHub Repository](https://github.com/enviodev/hypersync-client-solana)
  :::

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](https://docs.envio.dev/docs/HyperSync/solana-client.md).

```toml
[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

:::info Resources

- [💻 GitHub Repository](https://github.com/enviodev/hypersync-client-go)
- [🧪 Example Projects](https://github.com/enviodev/hypersync-client-go/tree/main/examples)
  :::

:::caution 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

```bash
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`:

```go
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

:::info Get Your API Token
You'll need an API token to use any HyperSync client. [Get your token here](https://docs.envio.dev/docs/HyperSync/api-tokens.md).
:::

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](https://envio.dev)
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](https://docs.envio.dev/docs/HyperSync/api-tokens.md) guide.

## Client Selection Guide

Choose the client that best fits your use case:

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

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

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

:::tip 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

- [📚 HyperSync Usage Guide](https://docs.envio.dev/docs/HyperSync/hypersync-usage.md)
- [📝 Query Reference](https://docs.envio.dev/docs/HyperSync/hypersync-query.md)
- [🧪 cURL Examples](https://docs.envio.dev/docs/HyperSync/hypersync-curl-examples.md)
- [📊 Supported Networks](https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks.md)
- [🧱 HyperIndex blockchain indexer](/docs/HyperIndex/overview), the full framework with schema, handlers, and a hosted GraphQL API, powered by HyperSync

## Support

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

- [Discord Community](https://discord.gg/envio)
- [GitHub Issues](https://github.com/enviodev)
