HyperFuel

HyperSync is a high-performance data node and accelerated data query layer that powers Envio’s Indexing framework, HyperIndex, for up to 2000x faster data retrieval than standard RPC methods.

HyperFuel is HyperSync adapted for the Fuel Network and is exposed as a low-level API for developers and data analysts to create flexible, high-speed queries for all fuel data.

Users can interact with the HyperFuel in Rust, Python, NodeJS clients, or directly via the JSON API to extract data into parquet files, arrow format, or as typed data. Client examples are listed further below.

Using HyperFuel, application developers can easily sync and search large datasets in a few minutes. HyperFuel is an ideal solution for indexers, block explorers, data analysts, bridges, and other applications or use cases focused on performance.

You can integrate with HyperFuel using any of our clients:

Client	Install	Repository
Rust	cargo add hyperfuel-client	https://github.com/enviodev/hyperfuel-client-rust
Python	pip install hyperfuel	https://github.com/enviodev/hyperfuel-client-python
Node.js	npm install @envio-dev/hyperfuel-client	https://github.com/enviodev/hyperfuel-client-node
JSON API	any HTTP client	https://github.com/enviodev/hyperfuel-json-api

info

HyperFuel supports Fuel mainnet and testnet:
Mainnet: https://fuel.hypersync.xyz
Testnet: https://fuel-testnet.hypersync.xyz

note

HyperFuel requires an API token. Generate one from the Envio Dashboard and pass it to the client when you initialize it: api_token in Rust, bearer_token in Python, bearerToken in Node.js, or an Authorization: Bearer <token> header on the JSON API. The examples below read it from the ENVIO_API_TOKEN environment variable. The Rust client refuses to start without one (api_token is required). See API Tokens for more details.

Example usage

Below is an example of a Hyperfuel query in each of our clients searching the first 1,300,000 blocks for all input objects of a specific asset-id. This example returns 10,543 inputs in around 100ms - not including latency.

Rust (repo)

[dependencies]
hyperfuel-client = "4"
tokio = { version = "1", features = ["full"] }
serde_json = "1"
url = "2"

use hyperfuel_client::{net_types::Query, Client, ClientConfig};
use url::Url;

#[tokio::main]
async fn main() {
    let client_config = ClientConfig {
        url: Some(Url::parse("https://fuel-testnet.hypersync.xyz").unwrap()),
        api_token: std::env::var("ENVIO_API_TOKEN")
            .expect("ENVIO_API_TOKEN env var is required, get a token from https://envio.dev/app/api-tokens"),
        ..Default::default()
    };
    let client = Client::new(client_config).unwrap();

    // Construct query in json.  Can also construct it as a typed struct (see predicate-root example)
    let query: Query = serde_json::from_value(serde_json::json!({
        // 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": [
            {
            "asset_id": ["0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea"]
            }
        ],
        // fields we want returned from loaded inputs
        "field_selection": {
            "input": [
                "tx_id",
                "block_height",
                "input_type",
                "utxo_id",
                "owner",
                "amount",
                "asset_id"
            ]
        }
    }))
    .unwrap();

    let res = client.get(&query).await.unwrap();

    println!("inputs: {:?}", res.data.inputs);
}

Python (repo)

import os
import hyperfuel
from hyperfuel import InputField
import asyncio

async def main():
    client = hyperfuel.HyperfuelClient(
        url="https://fuel-testnet.hypersync.xyz",
        bearer_token=os.environ["ENVIO_API_TOKEN"],
    )

    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())

Node Js (repo)

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

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

  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();

Json Api (repo)

curl --request POST \
  --url https://fuel-testnet.hypersync.xyz/query \
  --header "Authorization: Bearer $ENVIO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
        "from_block": 0,
        "to_block":   1300000,
        "inputs": [
            {
            "asset_id": ["0x2a0d0ed9d2217ec7f32dcd9a1902ce2a66d68437aeff84e3a3cc8bebee0d2eea"]
            }
        ],
        "field_selection": {
            "input": [
                "tx_id",
                "block_height",
                "input_type",
                "utxo_id",
                "owner",
                "amount",
                "asset_id"
            ]
        }
    }'