### Clone and Run HyperSync Quickstart Project

Source: https://github.com/enviodev/docs/blob/main/blog/2026-04-30-what-is-hypersync.md

These shell commands guide you through cloning the hypersync-quickstart repository, installing dependencies, and running a simple example script to get started with HyperSync.

```shell
git clone https://github.com/enviodev/hypersync-quickstart.git
cd hypersync-quickstart
pnpm install
node run-simple.js

```

--------------------------------

### Install Go HyperSync Client

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-clients.md

Use the go get command to install the Go HyperSync client.

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

--------------------------------

### Setup Bun Project and Install HyperSync Client

Source: https://github.com/enviodev/docs/blob/main/blog/2026-04-24-native-transfers.md

Initialize a new Bun project and install the necessary HyperSync client library. Ensure your API token is added to a `.env` file.

```sh
bun init -y && bun install @envio-dev/hypersync-client
```

--------------------------------

### Example config.yaml Structure

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Guides/configuration-file.mdx

This example demonstrates the basic structure of a `config.yaml` file, including name, description, contract definitions with ABIs, and network configurations with contract addresses and start blocks.

```yaml
# yaml-language: $schema=./node_modules/envio/evm.schema.json
name: Greeter
description: Greeter Indexer Example

contracts:
  - name: Greeter
    abi:
      - event: "NewGreeting(address user, string greeting)"
      - event: "ClearGreeting(address user)"

networks:
  - id: 1 # ethereum-mainnet
    start_block: 12345678
    contracts:
      - name: Greeter
        address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c

```

--------------------------------

### Full Configuration File Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Guides/configuration-file.mdx

This example demonstrates indexing events from multiple contracts across different networks. It includes settings for indexer name, multi-chain mode, contract definitions with event subscriptions, and network-specific configurations including contract addresses and start blocks.

```yaml
name: envio-indexer
unordered_multichain_mode: true
preload_handlers: true
contracts:
  - name: PoolManager
    handler: src/EventHandlers.ts
    events:
      - event: Swap(bytes32 indexed id, address indexed sender, int128 amount0, int128 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick, uint24 fee)
  - name: PositionManager
    handler: src/EventHandlers.ts
    events:
      - event: Transfer(address indexed from, address indexed to, uint256 indexed id)
networks:
  - id: 1
    # Keep it 0 and HyperSync will automatically find the first block for your contracts
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e
        start_block: 18500000 # OPTIONAL: Override for contract deployed later
      - name: PoolManager
        address:
          - "0x000000000004444c5dc75cB358380D2e3dE08A90"
  - id: 10
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0x3C3Ea4B57a46241e54610e5f022e5c45859A1017
      - name: PoolManager
        address:
          - 0x9a13F98Cb987694C9F086b1F5eB990EeA8264Ec3
  - id: 42161
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0xd88f38f930b7952f2db2432cb002e7abbf3dd869
      - name: PoolManager
        address:
          - 0x360e68faccca8ca495c1b759fd9eee466db9fb32

```

--------------------------------

### Clone HyperSync Quickstart Repository

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/quickstart.md

Clone the minimal example repository to quickly set up a project for streaming blockchain data with HyperSync.

```bash
git clone https://github.com/enviodev/hypersync-quickstart.git
cd hypersync-quickstart
```

--------------------------------

### Envio CLI: Project Initialization

Source: https://context7.com/enviodev/docs/llms.txt

Initialize a new Envio indexer project. This command is interactive and guides you through the setup process.

```bash
# Initialize a new indexer (interactive)
pnpx envio init
```

--------------------------------

### Initialize Indexer from Template

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Guides/cli-commands.md

Quickly start an indexer using a predefined template, such as the ERC20 template. This simplifies setup for common use cases.

```bash
pnpx envio init template -n erc20-example -t erc20 -l typescript -d erc20-indexer --api-token "your-api-token" && cd erc20-indexer && pnpm dev
```

--------------------------------

### Run HyperSync Quickstart Scripts

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/quickstart.md

Execute the provided Node.js scripts to start streaming Uniswap V3 events from Ethereum mainnet. Options include a minimal version, a version with a progress bar, and a version with a terminal UI.

```bash
# Run minimal version (recommended for beginners)
node run-simple.js

# Run full version with progress bar
node run.js

# Run version with terminal UI
node run-tui.js
```

--------------------------------

### Install HyperSync Client and Viem

Source: https://github.com/enviodev/docs/blob/main/blog/2026-03-24-track-polymarket-trades-hypersync.md

Use these commands to create a Bun project and install the HyperSync client and Viem for event decoding.

```bash
mkdir track-trades && cd track-trades
bun init -y
bun add @envio-dev/hypersync-client viem
```

--------------------------------

### Multichain Indexing Configuration Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Advanced/multichain-indexing.mdx

This YAML configuration demonstrates how to set up contracts and networks for multichain indexing. It defines global contract details and then specifies network-specific addresses and starting blocks.

```yaml
contracts:
  - name: ExampleContract
    abi_file_path: ./abis/example-abi.json
    handler: ./src/EventHandlers.js
    events:
      - event: ExampleEvent

networks:
  - id: 1 # Ethereum Mainnet
    start_block: 0
    contracts:
      - name: ExampleContract
        address: "0x1234..."
  - id: 137 # Polygon
    start_block: 0
    contracts:
      - name: ExampleContract
        address: "0x5678..."
```

--------------------------------

### eRPC Configuration File Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Advanced/rpc-sync.md

Define your eRPC setup in a `erpc.yaml` file, specifying project IDs, upstream RPC endpoints (including HyperRPC as primary), and fallback providers. This configuration enables features like caching, auto failover, and re-org awareness.

```yaml
logLevel: debug
projects:
  - id: main
    upstreams:
      # Add HyperRPC as primary source
      - endpoint: evm+envio://rpc.hypersync.xyz
      # Add fallback RPC endpoints
      - endpoint: https://eth-mainnet-provider1.com
      - endpoint: https://eth-mainnet-provider2.com
      - endpoint: https://eth-mainnet-provider3.com
```

--------------------------------

### Start Envio Indexer

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Tutorials/tutorial-scaffold-eth-2.md

Navigate to the Envio package directory within your project and start the indexer to begin processing contract events.

```bash
cd packages/envio
pnpm dev
```

--------------------------------

### Start Local Blockchain

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Tutorials/tutorial-scaffold-eth-2.md

Navigate to your project directory and run this command to start a local blockchain node for development.

```bash
cd your-project-name
yarn chain
```

--------------------------------

### Node.js Client Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/HyperFuel/hyperfuel.md

Example demonstrating how to use the HyperfuelClient in Node.js to query for specific asset inputs within a block range.

```APIDOC
## Node Js

```js
import { HyperfuelClient, Query } from "@envio-dev/hyperfuel-client";

async function main() {
  const client = HyperfuelClient.new({
    url: "https://fuel-testnet.hypersync.xyz",
  });

  const query: Query = {
    // start query from block 0
    fromBlock: 0,
    // if to_block is not set, query runs to the end of the chain
    toBlock: 1300000,
    // load inputs that have `asset_id` = 0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea
    inputs: [
      {
        assetId: [
          "0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea",
        ],
      },
    ],
    // fields we want returned from loaded inputs
    fieldSelection: {
      input: [
        "tx_id",
        "block_height",
        "input_type",
        "utxo_id",
        "owner",
        "amount",
        "asset_id",
      ],
    },
  };

  const res = await client.getSelectedData(query);

  console.log(`inputs: ${JSON.stringify(res.data.inputs)}`);
}

main();
```
```

--------------------------------

### Envio HyperIndex config.yaml Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/migration-guide.md

This is an example of a `config.yaml` file for Envio's HyperIndex, specifying the indexer name, networks, start block, contract details, and event handlers.

```yaml
# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: uni-v4-indexer
networks:
  - id: 1
    start_block: 21689089
    contracts:      
      - name: PositionManager
        address: 0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e
        handler: src/EventHandlers.ts
        events:        
        - event: Subscription(uint256 indexed tokenId, address indexed subscriber)
        - event: Unsubscription(uint256 indexed tokenId, address indexed subscriber)          
        - event: Transfer(address indexed from, address indexed to, uint256 indexed id)
          
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Tutorials/tutorial-indexing-fuel.md

After initialization, change into the newly created project directory to continue.

```bash
Please run `cd sway-farm-indexer` to run the rest of the envio commands
```

--------------------------------

### Get Successful or Failed Transactions

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-curl-examples.md

Query recent transactions, filtering by status (successful or failed). First, get the current chain height and calculate a starting block. Then, make a POST request to the query endpoint with the desired transaction status.

```bash
# Get current height and calculate starting block
height=$((`curl https://eth.hypersync.xyz/height | jq .height` - 10))

# Query successful transactions (change status to 0 for failed transactions)
curl --request POST \
  --url https://eth.hypersync.xyz/query \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data "{
    \"from_block\": ${height},
    \"transactions\": [
        {
            \"status\": 1
        }
    ],
    \"field_selection\": {
        \"block\": [
            \"number\",
            \"timestamp\",
            \"hash\"
        ],
        \"transaction\": [
            \"block_number\",
            \"transaction_index\",
            \"hash\",
            \"from\",
            \"to\"
        ]
    }
  }"
```

--------------------------------

### Example Configuration for Multiple Networks

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Advanced/reorgs-support.md

This example demonstrates configuring reorg handling with different confirmation thresholds for Ethereum and Polygon, while using the default for Arbitrum One.

```yaml
rollback_on_reorg: true
networks:
  - id: 1 # Ethereum Mainnet
    confirmed_block_threshold: 250 # Higher threshold for Ethereum
    # other network config...

  - id: 137 # Polygon
    confirmed_block_threshold: 150 # Lower threshold for Polygon
    # other network config...

  - id: 42161 # Arbitrum One
    # Using default threshold (200)
    # other network config...
```

--------------------------------

### Get All Transactions for an Address

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-curl-examples.md

Retrieves all transactions where a specific address is either the sender or receiver. It starts from a specified block and uses OR logic for filters.

```APIDOC
## POST /query

### Description
Retrieves all transactions where a specific address is either the sender or receiver.

### Method
POST

### Endpoint
https://eth.hypersync.xyz/query

### Parameters
#### Request Body
- **from_block** (integer) - Required - The starting block number to scan from.
- **transactions** (array) - Required - An array of transaction filter objects. Multiple objects are combined with an OR relationship.
  - **from** (array of strings) - Optional - Filter transactions by sender address.
  - **to** (array of strings) - Optional - Filter transactions by receiver address.
- **field_selection** (object) - Optional - Specifies which fields to include in the response.
  - **block** (array of strings) - Optional - Fields to include from the block object.
  - **transaction** (array of strings) - Optional - Fields to include from the transaction object.

### Request Example
```json
{
  "from_block": 15362000,
  "transactions": [
    {
      "from": ["0xdb255746609baadd67ef44fc15b5e1d04befbca7"]
    },
    {
      "to": ["0xdb255746609baadd67ef44fc15b5e1d04befbca7"]
    }
  ],
  "field_selection": {
    "block": [
      "number",
      "timestamp",
      "hash"
    ],
    "transaction": [
      "block_number",
      "transaction_index",
      "hash",
      "from",
      "to"
    ]
  }
}
```

### Response
#### Success Response (200)
- **next_block** (integer) - The next block number to query for pagination.
- **blocks** (array) - An array of block objects.
- **transactions** (array) - An array of transaction objects.
```

--------------------------------

### Select Initialization Option

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Tutorials/tutorial-indexing-fuel.md

Choose how to initialize your indexer. 'Contract Import' is suitable for existing contracts.

```bash
? Choose an initialization option
  Template
> Contract Import
[↑↓ to move, enter to select, type to filter]
```

--------------------------------

### TypeScript WebSocket Subscription Example

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Advanced/websockets.md

Use the `graphql-ws` library in TypeScript to subscribe to real-time updates from your HyperIndex GraphQL endpoint. Ensure you have installed `graphql-ws` and `ws`.

```typescript
import { createClient } from 'graphql-ws';

// Define the entity you are subscribing to (must match your schema definition)
interface Swap {
  id: string;
}

interface SubscriptionData {
  data?: {
    Swap?: Swap[];
  };
}

const client = createClient({
  url: 'ws://localhost:8080/v1/graphql',
});

console.log('Connecting to WebSocket...');

client.subscribe<SubscriptionData>(
  {
    query: `
      subscription {
        Swap(order_by: { id: desc }, limit: 10) {
          id
        }
      }
    `,
  },
  {
    next: (data) => {
      console.log('\n📥 New event received:');
      console.log(JSON.stringify(data, null, 2));
    },
    error: (err) => {
      console.error('❌ Error:', err);
    },
    complete: () => {
      console.log('✅ Subscription completed');
    },
  }
);

```

--------------------------------

### Initialize Solana Project with Envio

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/solana/solana.md

Use this command to initialize a new project with Solana support using Envio CLI.

```bash
pnpx envio@3.0.0-alpha.14 init svm
```

--------------------------------

### Initialize HyperIndex Project (Template)

Source: https://context7.com/enviodev/docs/llms.txt

Create a new indexer project using a pre-built template, such as 'greeter' or 'erc20'. Specify the template name and desired language.

```bash
pnpx envio init template -n erc20-example -t erc20 -l typescript -d erc20-indexer
```

--------------------------------

### Get All Logs for a Smart Contract

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-curl-examples.md

Retrieves all event logs for a specified contract address, starting from block 0. Use the 'next_block' field in the response for pagination.

```bash
curl --request POST \
  --url https://eth.hypersync.xyz/query \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{ \
    "from_block": 0, \
    "logs": [ \
        { \
            "address": ["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"] \
        } \
    ], \
    "field_selection": { \
        "block": [ \
            "number", \
            "timestamp", \
            "hash" \
        ], \
        "log": [ \
            "block_number", \
            "log_index", \
            "transaction_index", \
            "data", \
            "address", \
            "topic0", \
            "topic1", \
            "topic2", \
            "topic3" \
        ], \
        "transaction": [ \
            "block_number", \
            "transaction_index", \
            "hash", \
            "from", \
            "to", \
            "value", \
            "input" \
        ] \
    } \
}'
```

--------------------------------

### Build LLM Documentation Commands

Source: https://github.com/enviodev/docs/blob/main/LLM_DOCS_README.md

Commands to build, start the development server, and consolidate documentation files for LLM consumption.

```bash
# Build the LLM documentation
yarn build-llm

# Start the LLM documentation server
yarn start-llm

# Consolidate documentation files
yarn consolidate-docs
```

--------------------------------

### Example Environment Variables for Envio

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Guides/environment-variables.md

Commonly used environment variables for configuring an Envio indexer, including API tokens, RPC URLs, and indexing start blocks.

```bash
# Envio API Token (required for continued HyperSync access)
ENVIO_API_TOKEN=your-secret-token

# Blockchain RPC URL
ENVIO_RPC_URL=https://arbitrum.direct.dev/your-api-key

# Starting block number for indexing
ENVIO_START_BLOCK=12345678

# Coingecko API key
ENVIO_COINGECKO_API_KEY=api-key

# In-memory batch size (default 5000)
MAX_BATCH_SIZE=1
```

--------------------------------

### Select Indexer Initialization Option

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/contract-import.md

During initialization, choose between 'Template' and 'Contract Import'. 'Contract Import' is recommended for existing smart contracts.

```bash
? Choose an initialization option
  Template
> Contract Import
[↑↓ to move, enter to select]
```

--------------------------------

### Get All Transactions for an Address

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-curl-examples.md

Retrieves all transactions where a specified address is either the sender or receiver, starting from a given block. Multiple queries might be necessary for a complete history.

```bash
curl --request POST \
  --url https://eth.hypersync.xyz/query \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{ \
    "from_block": 15362000, \
    "transactions": [ \
        { \
            "from": ["0xdb255746609baadd67ef44fc15b5e1d04befbca7"] \
        }, \
        { \
            "to": ["0xdb255746609baadd67ef44fc15b5e1d04befbca7"] \
        } \
    ], \
    "field_selection": { \
        "block": [ \
            "number", \
            "timestamp", \
            "hash" \
        ], \
        "transaction": [ \
            "block_number", \
            "transaction_index", \
            "hash", \
            "from", \
            "to" \
        ] \
    } \
}'
```

--------------------------------

### Complete or Add More Contracts

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/contract-import.md

After selecting events, you can choose to finish the setup or add more contracts. Options include adding another contract on the same network, a different network for the same contract, or a completely new contract.

```bash
? Would you like to add another contract?
> I'm finished
  Add a new address for same contract on same network
  Add a new network for same contract
  Add a new contract (with a different ABI)
```

--------------------------------

### Configure Canto Testnet RPC Indexing

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/supported-networks/canto-testnet.md

Define the network configuration for Canto Testnet indexing. Adjust the RPC URL, start block, and contract details as needed for your specific setup.

```yaml
name: IndexerName # Specify indexer name
description: Indexer Description # Include indexer description
networks:
  - id: 7701 # Canto Testnet
    rpc_config:
      url: https://testnet-archive.plexnode.wtf 
    start_block: START_BLOCK_NUMBER # Specify the starting block
    contracts:
      - name: ContractName
        address:
          - "0xYourContractAddress1"
          - "0xYourContractAddress2"
        handler: ./src/EventHandlers.ts
        events:
          - event: Event # Specify event
          - event: Event
```

--------------------------------

### Start Indexer with Benchmarking Enabled

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Advanced/performance/benchmarking.md

Run your indexer with the '--bench' flag to capture performance metrics. Note that this adds overhead and should not be used in production.

```bash
pnpm envio start --bench
```

--------------------------------

### Configure Neo X Testnet RPC Indexing

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/supported-networks/neo-x-testnet.md

Define the network configuration for Neo X Testnet in your indexer setup. Adjust RPC URL, start block, and contract details as needed.

```yaml
name: IndexerName
description: Indexer Description
networks:
  - id: 12227332 # Neo X Testnet
    rpc_config:
      url: https://testnet.rpc.banelabs.org 
    start_block: START_BLOCK_NUMBER # Specify the starting block
    contracts:
      - name: ContractName
        address:
          - "0xYourContractAddress1"
          - "0xYourContractAddress2"
        handler: ./src/EventHandlers.ts
        events:
          - event: Event # Specify event
          - event: Event
```

--------------------------------

### Initialize a New Indexer Project

Source: https://github.com/enviodev/docs/blob/main/blog/2023-11-09-powers-of-dedicated-hosting-for-web3-apps.md

Use this command to quickly set up a new indexer project by importing data from a contract address. This command generates a working indexer that can be run locally or deployed.

```bash
pnpx envio init
```

--------------------------------

### Keep Mocha with tsx for V3

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/migrate-to-v3.md

If you prefer to keep using Mocha, remove `ts-mocha` and `ts-node`, then install and configure `tsx` for your test script. This setup allows Mocha to run with ESM modules.

```bash
pnpm remove ts-mocha ts-node
pnpm add -D tsx@4.21.0
```

```json
{
  "scripts": {
    "mocha": "tsc --noEmit && NODE_OPTIONS='--no-warnings --import tsx' mocha --exit test/**/*.ts"
  }
}
```

--------------------------------

### Query Inputs by Asset ID in Python

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/HyperFuel/hyperfuel.md

This Python example shows how to use the `hyperfuel` library to query for input objects based on a specific asset ID and block range. Ensure the `hyperfuel` library is installed.

```python
import hyperfuel
from hyperfuel import InputField
import asyncio

async def main():
    client = hyperfuel.HyperfuelClient()

    query = hyperfuel.Query(
        # start query from block 0
        from_block=0,
        # if to_block is not set, query runs to the end of the chain
        to_block = 1300000,
        # load inputs that have `asset_id` = 0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea
        inputs=[
            hyperfuel.InputSelection(
                asset_id=["0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea"]
            )
        ],
        # what data we want returned from the inputs we loaded
        field_selection=hyperfuel.FieldSelection(
            input=[
                InputField.TX_ID,
                InputField.BLOCK_HEIGHT,
                InputField.INPUT_TYPE,
                InputField.UTXO_ID,
                InputField.OWNER,
                InputField.AMOUNT,
                InputField.ASSET_ID,
            ]
        )
    )

    res = await client.get_selected_data(query)

    print("inputs: " + str(res.data.inputs))

asyncio.run(main())

```

--------------------------------

### Envio CLI: Performance Benchmarking

Source: https://context7.com/enviodev/docs/llms.txt

Benchmark the performance of your indexer. Use 'start --bench' to run benchmarks and 'benchmark-summary' to view results.

```bash
# Performance benchmarking
pnpm envio start --bench
pnpm envio benchmark-summary
```

--------------------------------

### Initialize HyperIndex Project

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/migrate-from-alchemy.md

Use this command to create a basic HyperIndex project. Replace 'YOUR_ENVIO_API_KEY' with your actual API key.

```bash
pnpx envio init template --name alchemy-migration --directory alchemy-migration --template  greeter --api-token "YOUR_ENVIO_API_KEY"
```

--------------------------------

### Get All ERC-20 Transfers for an Address

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-curl-examples.md

This example filters for all ERC-20 transfer events involving a specific address, either as sender or recipient. It matches the Transfer event signature and includes direct transactions to/from the address.

```APIDOC
## Get All ERC-20 Transfers for an Address

### Description
This example filters for all ERC-20 transfer events involving a specific address, either as sender or recipient. Feel free to swap your address into the example.

### Method
POST

### Endpoint
https://eth.hypersync.xyz/query

### Request Body
```json
{
    "from_block": 0,
    "logs": [
        {
            "topics": [
                [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
                ],
                [],
                [
                    "0x0000000000000000000000001e037f97d730Cc881e77F01E409D828b0bb14de0"
                ]
            ]
        },
        {
            "topics": [
                [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
                ],
                [
                    "0x0000000000000000000000001e037f97d730Cc881e77F01E409D828b0bb14de0"
                ],
                []
            ]
        }
    ],
    "transactions": [
        {
            "from": [
                "0x1e037f97d730Cc881e77F01E409D828b0bb14de0"
            ]
        },
        {
            "to": [
                "0x1e037f97d730Cc881e77F01E409D828b0bb14de0"
            ]
        }
    ],
    "field_selection": {
        "block": [
            "number",
            "timestamp",
            "hash"
        ],
        "log": [
            "block_number",
            "log_index",
            "transaction_index",
            "data",
            "address",
            "topic0",
            "topic1",
            "topic2",
            "topic3"
        ],
        "transaction": [
            "block_number",
            "transaction_index",
            "hash",
            "from",
            "to",
            "value",
            "input"
        ]
    }
}
```

### Request Example
```bash
curl --request POST \
  --url https://eth.hypersync.xyz/query \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data 
```
```

--------------------------------

### Configure Flow Network for RPC Indexing

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/supported-networks/flow.md

Define the network configuration for Flow (network ID 747) in your indexer setup. Specify the RPC URL, starting block, and contract details including event handlers.

```yaml
name: IndexerName
description: Indexer Description
networks:
  - id: 747 # Flow
    rpc_config:
      url: https://mainnet.evm.nodes.onflow.org 
    start_block: START_BLOCK_NUMBER # Specify the starting block
    contracts:
      - name: ContractName
        address:
          - "0xYourContractAddress1"
          - "0xYourContractAddress2"
        handler: ./src/EventHandlers.ts
        events:
          - event: Event # Specify event
          - event: Event
```

--------------------------------

### Complete Example: Fetch USDC Transfer Events

Source: https://github.com/enviodev/docs/blob/main/docs/HyperSync/hypersync-usage.md

A comprehensive Python example demonstrating how to initialize the HyperSync client, define field selections, construct a query for USDC transfers, configure output, and collect data to a Parquet file.

```python
import hypersync
from hypersync import (
    LogSelection,
    LogField,
    BlockField,
    FieldSelection,
    TransactionField,
    HexOutput
)
import asyncio

async def collect_usdc_transfers():
    # Initialize client
    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
        )
    )

    # Define field selection
    field_selection = hypersync.FieldSelection(
        block=[BlockField.NUMBER, BlockField.TIMESTAMP],
        transaction=[TransactionField.HASH],
        log=[
            LogField.ADDRESS,
            LogField.TOPIC0,
            LogField.TOPIC1,
            LogField.TOPIC2,
            LogField.DATA,
        ]
    )

    # Define query for USDC transfers
    query = hypersync.Query(
        from_block=12000000,
        to_block=12100000,
        field_selection=field_selection,
        logs=[
            LogSelection(
                address=["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],  # USDC contract
                topics=[
                    ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]  # Transfer signature
                ]
            )
        ]
    )

    # Configure output
    config = hypersync.StreamConfig(
        hex_output=HexOutput.PREFIXED,
        event_signature="Transfer(address indexed from, address indexed to, uint256 value)"
    )

    # Collect data to a Parquet file
    result = await client.collect_parquet("usdc_transfers", query, config)
    print(f"Processed blocks {query.from_block} to {result.end_block}")

asyncio.run(collect_usdc_transfers())
```

--------------------------------

### Configure ZkSync Sepolia Testnet RPC Network

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/supported-networks/zksync-sepolia-testnet.md

Define the network configuration for ZkSync Sepolia Testnet in your indexer setup. Specify the network ID, RPC URL, starting block, and contract details for event handling.

```yaml
name: IndexerName # Specify indexer name
description: Indexer Description # Include indexer description
networks:
  - id: 300 # ZkSync Sepolia Testnet
    rpc_config:
      url: https://zksync-era-sepolia.blockpi.network/v1/rpc/private 
    # url: https://zksync-sepolia.drpc.org # alternative,
    # url: https://sepolia.era.zksync.dev # alternative
    start_block: START_BLOCK_NUMBER # Specify the starting block
    contracts:
      - name: ContractName
        address:
          - "0xYourContractAddress1"
          - "0xYourContractAddress2"
        handler: ./src/EventHandlers.ts
        events:
          - event: Event # Specify event
          - event: Event
```

--------------------------------

### Select Blockchain Ecosystem

Source: https://github.com/enviodev/docs/blob/main/docs/HyperIndex/Tutorials/tutorial-indexing-fuel.md

Choose the blockchain ecosystem for your indexer. This tutorial focuses on Fuel.

```bash
? Choose blockchain ecosystem
  Evm
> Fuel
[↑↓ to move, enter to select, type to filter]
```

--------------------------------

### Launch LogTUI for Real-time Blockchain Event Viewing

Source: https://github.com/enviodev/docs/blob/main/blog/2026-04-30-what-is-hypersync.md

This shell command launches LogTUI, a terminal-based blockchain event viewer built on HyperSync. It starts streaming Aave events on Arbitrum in real time without requiring any installation.

```shell
pnpx logtui aave arbitrum

```

--------------------------------

### Initialize HyperIndex Project (Local ABI)

Source: https://context7.com/enviodev/docs/llms.txt

Initialize an indexer from a local ABI file for unverified or custom contracts. Specify the ABI path, contract address, and network.

```bash
pnpx envio init contract-import local \
  -n my-indexer \
  -a ./abis/MyContract.json \
  -c 0xYourContractAddress \
  -b ethereum-mainnet \
  --contract-name MyContract \
  --single-contract --all-events \
  -l typescript -d my-indexer && cd my-indexer && pnpm dev
```