Envio

Skill is based on Envio docs (enviodev/docs), generated at 2026-02-09.

Envio provides high-performance blockchain data access and indexing: HyperSync (raw data API), HyperIndex (indexer + GraphQL), and HyperRPC (read-only JSON-RPC). This skill covers product choice, client usage, queries, API tokens, and supported networks.

Core References

Features

Best Practices

Generation Info

• Source: sources/envio
• Git SHA: 0039f5499a84745bda248da25a7fa2f800f1b69b
• Generated: 2026-02-09

HyperSync Query Best Practices

Field Selection

Request only the fields you need in fieldSelection for block, transaction, log, and trace. This reduces payload size and improves speed.

fieldSelection: {
  block: ["number", "timestamp"],
  log: ["address", "topic0", "data"],
  transaction: ["from", "to", "value"],
}

Use snake_case for field names (e.g. block_number, not blockNumber).

Join Mode

• JoinNothing: Only rows matching your selection (logs/transactions/traces). Smallest responses.
• Default: Matched items plus their related transaction and block. Good balance.
• JoinAll: Matched item plus all related logs, traces, and block. Use when you need full context (e.g. all logs for a tx).

Choose JoinNothing when you only need the selected entity and no related data.

Limits and Pagination

• max_num_blocks, max_num_logs, max_num_transactions, max_num_traces: Approximate caps; server may slightly exceed to finish a block group.
• Use stream for large ranges instead of a single huge query; loop on recv() and set from_block to next_block.
• to_block: Set when you need a fixed upper bound (exclusive).

Chain Tip and Rollbacks

Stream/collect are not intended for real-time use at the chain tip where reorgs occur. For tip data, use one-off get-style requests and implement rollback handling (e.g. using rollback_guard in the response).

Resource Management

• Call close() on stream handles when done to avoid leaks, especially with multiple streams.
• For very large or analytical workloads, consider collect_parquet (or equivalent) instead of holding full JSON in memory.

<!-- Source references:

• https://docs.envio.dev/docs/HyperSync/hypersync-query
• https://docs.envio.dev/docs/HyperSync/quickstart

-->

HyperIndex Indexer

HyperIndex turns on-chain events into a queryable GraphQL API. Core pieces: config, schema, and event handlers.

Prerequisites and Init

• Node.js 22+, pnpm 8+, Docker (for local run).
• Init: pnpx envio init (templates) or use contract import for quickstart.
• Essential files: config.yaml, schema.graphql, src/EventHandlers.* (TS/JS/ReScript).

config.yaml

Defines contracts (name, ABI/events), networks (id, start_block), and which contract addresses to index per network.

name: MyIndexer
contracts:
  - name: Greeter
    abi:
      - event: "NewGreeting(address user, string greeting)"
networks:
  - id: 1
    start_block: 12345678
    contracts:
      - name: Greeter
        address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c

After config or schema changes, run pnpm codegen to regenerate types and handler bindings.

schema.graphql

Defines entities and fields that event handlers write. These become the GraphQL API (via Hasura when running locally or on hosted).

Event Handlers

Handlers are registered in src/EventHandlers.* and receive event + context (DB/entity access). Use the generated API from generated (from codegen).

import { Greeter, User } from "generated";

Greeter.NewGreeting.handler(async ({ event, context }) => {
  const userId = event.params.user;
  const latestGreeting = event.params.greeting;
  const current = await context.User.get(userId);

  await context.User.set({
    id: userId,
    latestGreeting,
    numberOfGreetings: current ? current.numberOfGreetings + 1 : 1,
    greetings: current ? [...current.greetings, latestGreeting] : [latestGreeting],
  });
});

Running

• Local: pnpm dev (Docker + Hasura). Stop with pnpm envio stop.
• Hosted: Deploy via Envio Hosted Service; no custom API token needed for HyperSync in that case.
• Self-hosted: Set ENVIO_API_TOKEN for HyperSync access.

Key Points

• Use proxy address, not implementation, when indexing proxy contracts.
• API token required for HyperSync from Nov 2025 for local/self-hosted; see API Tokens doc.
• Supported: EVM, Solana, Fuel; multichain and dynamic/factory contracts are supported (see docs).

<!-- Source references:

• https://docs.envio.dev/docs/HyperIndex/getting-started
• https://docs.envio.dev/docs/HyperIndex/configuration-file
• https://docs.envio.dev/docs/HyperIndex/event-handlers

-->

HyperRPC

HyperRPC is a read-only, JSON-RPC–compatible endpoint optimized for data-heavy reads. Prefer HyperSync for new code when you need maximum speed and flexibility.

When to Use

• HyperRPC: Drop-in RPC replacement; existing code or tools that call eth_getLogs, eth_getBlockByNumber, etc. Minimal integration.
• HyperSync: New integrations; need filtering, field selection, or best performance.

Supported Methods

• Chain: eth_chainId, eth_blockNumber
• Blocks: eth_getBlockByNumber, eth_getBlockByHash, eth_getBlockReceipts
• Transactions: eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex, eth_getTransactionReceipt
• Logs: eth_getLogs
• Traces: trace_block (only on select chains; see supported networks).

Endpoint and Token

• Base URL per network, e.g. https://100.rpc.hypersync.xyz or https://arbitrum.rpc.hypersync.xyz. See supported networks doc for full list.
• Append API token to path: https://<network>.rpc.hypersync.xyz/<api-token>.
• Example request:

const response = await fetch("https://100.rpc.hypersync.xyz/<api-token>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_getLogs",
    params: [{ fromBlock: "0x1000000", toBlock: "0x1000100", address: "0x..." }],
  }),
});

Key Points

• Read-only; no sending transactions.
• Under active development; not all RPC methods supported. Check docs for latest method list and tier/network support.

<!-- Source references:

• https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc
• https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks

-->

HyperSync Usage

HyperSync is a high-performance blockchain data API. Use it for raw logs, transactions, traces, and blocks with filtering and field selection.

Client Setup (Node.js)

import { HypersyncClient } from "@envio-dev/hypersync-client";

const client = new HypersyncClient({
  url: "https://eth.hypersync.xyz",  // or https://arbitrum.hypersync.xyz, etc.
  apiToken: process.env.ENVIO_API_TOKEN,
});

Other clients: Python (hypersync on PyPI), Rust (hypersync-client), Go (community). All use the same query model.

Query Shape

• from_block / to_block: Block range (to_block exclusive).
• logs / transactions / traces: Array of selection criteria (OR between array items).
• field_selection: Which fields to return for block, transaction, log, trace (reduces payload).
• max_num_blocks, max_num_logs, etc.: Approximate limits; server may slightly exceed to finish a block group.
• join_mode: JoinNothing (only matched rows), default (related tx/block), JoinAll (full context).

Log Selection Example

import { keccak256, toHex } from "viem";

const topic0_list = ["PoolCreated(address,address,uint24,int24,address)"].map((sig) =>
  keccak256(toHex(sig))
);

const query = {
  fromBlock: 0,
  logs: [{ address: ["0x..."], topics: [topic0_list] }],
  fieldSelection: {
    log: ["Data", "Address", "Topic0", "Topic1", "Topic2", "Topic3"],
  },
};

Stream and Pagination

• Use stream for large ranges: const stream = await client.stream(query, {}); then await stream.recv() in a loop. Each response has data and next_block; set query.fromBlock = res.next_block for the next batch.
• Use reverse: true in stream options to start from chain head and go backwards.
• Near chain tip: stream/collect are not designed for rollbacks; use one-off get + custom rollback handling for real-time tip.

Key Points

• Always request only needed fields in fieldSelection for better performance.
• Pagination is time-based (~5s execution window); one response can cover many blocks.
• Topic0 = event signature hash; topics[1–3] = indexed args. Use snake_case for field names in queries.

<!-- Source references:

• https://docs.envio.dev/docs/HyperSync/quickstart
• https://docs.envio.dev/docs/HyperSync/hypersync-query
• https://docs.envio.dev/docs/HyperSync/hypersync-clients

-->

Envio Overview

Envio provides high-performance blockchain data access and indexing. Three main products:

Products

• HyperSync: Raw blockchain data API (Rust, 70+ EVM + Fuel). Direct replacement for JSON-RPC; up to ~2000x faster. Use when you need raw data at max speed or custom pipelines.
• HyperIndex: Full indexing framework built on HyperSync. Schema, event handlers, GraphQL API. Use when you need structured, queryable data and an indexer.
• HyperRPC: Read-only JSON-RPC–compatible endpoint. Drop-in for existing RPC code; ~5x faster for read-heavy workloads. Use when you need minimal integration change.

Choosing

• HyperSync: New data layer, advanced filtering, field selection, maximum performance.
• HyperIndex: End-to-end indexer (config, schema, handlers, Hasura GraphQL).
• HyperRPC: Simple RPC replacement; tools that expect standard eth_* methods.

Key Points

• HyperIndex is powered by HyperSync; HyperRPC uses HyperSync under the hood.
• API tokens (ENVIO_API_TOKEN) are required for HyperSync/HyperRPC (and for HyperIndex when using HyperSync); get them at https://envio.dev/app/api-tokens.
• Supported: 80+ EVM chains and Fuel; URLs by network at docs (e.g. https://eth.hypersync.xyz, https://arbitrum.hypersync.xyz).

<!-- Source references:

• https://docs.envio.dev/docs/HyperSync/overview
• https://docs.envio.dev/docs/HyperIndex/overview
• https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc

-->

Envio API Tokens

API tokens authenticate access to HyperSync and HyperRPC. Required from 3 November 2025 (rate limits apply without tokens). Hosted Service indexers do not need a custom token for HyperSync.

Obtaining a Token

1. Go to https://envio.dev/app/api-tokens 2. Sign in (e.g. GitHub) 3. Create a token and store it securely

Using in Clients

Node.js (HyperSync):

const client = new HypersyncClient({
  url: "https://eth.hypersync.xyz",
  apiToken: process.env.ENVIO_API_TOKEN,
});

Python: Pass bearer_token=os.environ.get("ENVIO_API_TOKEN") in ClientConfig. Rust: api_token: std::env::var("ENVIO_API_TOKEN") in ClientConfig.

HyperRPC: Append token to URL path: https://<network>.rpc.hypersync.xyz/<api-token>.

HyperIndex (self-hosted): Set ENVIO_API_TOKEN in the indexer environment (e.g. .env); config reads it for HyperSync.

Security

• Do not commit tokens; use env vars and add .env to .gitignore.
• Rotate tokens periodically; limit sharing.

Usage and Credits

Usage (requests and credits) for the current month: https://envio.dev/app/api-tokens. Credits reflect bandwidth, disk reads, and other usage.

<!-- Source references:

• https://docs.envio.dev/docs/HyperSync/api-tokens

-->

Envio Supported Networks

HyperSync and HyperRPC support 80+ EVM networks and Fuel. Each network has a tier (service level); see the docs table for the full list and tiers.

URL Patterns

• HyperSync: https://<network>.hypersync.xyz or https://<chainId>.hypersync.xyz

Examples: https://eth.hypersync.xyz, https://arbitrum.hypersync.xyz, https://base.hypersync.xyz, https://42161.hypersync.xyz

• HyperRPC: https://<network>.rpc.hypersync.xyz or https://<chainId>.rpc.hypersync.xyz

Examples: https://eth.rpc.hypersync.xyz, https://arbitrum.rpc.hypersync.xyz

Usage

• In HyperSync clients, set url to the desired network’s HyperSync URL.
• For HyperRPC, use the network’s HyperRPC URL and append /<api-token>.
• Supported networks list (with tiers and optional trace support): HyperSync Supported Networks. HyperIndex supported networks are documented separately (EVM, Solana, Fuel).

Key Points

• Use the same network identifier (name or chain ID) for both HyperSync and HyperRPC.
• Some chains have a separate “traces” endpoint (e.g. Base Traces). Check the docs table when using trace selection.

<!-- Source references:

• https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks
• https://docs.envio.dev/docs/HyperRPC/hyperrpc-supported-networks

-->