> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocks and hyperblocks

> Query blocks by nonce or hash, retrieve hyperblocks, and track altered accounts per block.

Retrieve block data from individual shards, query cross-shard hyperblocks, and track which accounts changed in a given block.

## Shard blocks

| Method | Path                              | Description                         |
| ------ | --------------------------------- | ----------------------------------- |
| GET    | `/block/{shard}/by-nonce/{nonce}` | Block by height in a specific shard |
| GET    | `/block/{shard}/by-hash/{hash}`   | Block by hash in a specific shard   |

**Query parameters**

| Parameter  | Type    | Description                          |
| ---------- | ------- | ------------------------------------ |
| `withTxs`  | boolean | Include transactions in the response |
| `withLogs` | boolean | Include event logs in the response   |

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://rust-gateway.xoxno.com/block/0/by-nonce/1234567?withTxs=true"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    const res = await fetch(
      "https://rust-gateway.xoxno.com/block/0/by-nonce/1234567?withTxs=true"
    );
    const data = await res.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    res = requests.get(
        "https://rust-gateway.xoxno.com/block/0/by-nonce/1234567",
        params={"withTxs": "true"},
    )
    print(res.json())
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    let body: serde_json::Value = reqwest::Client::new()
        .get("https://rust-gateway.xoxno.com/block/0/by-nonce/1234567")
        .query(&[("withTxs", "true")])
        .send()
        .await?
        .json()
        .await?;

    println!("{body:#?}");
    ```
  </Tab>
</Tabs>

The Gateway queries full-history observers first, then falls back to regular observers. Block responses are TTL-cached.

## Altered accounts

| Method | Path                                               | Description                            |
| ------ | -------------------------------------------------- | -------------------------------------- |
| GET    | `/block/{shard}/altered-accounts/by-nonce/{nonce}` | Accounts modified in a block           |
| GET    | `/block/{shard}/altered-accounts/by-hash/{hash}`   | Accounts modified in a block (by hash) |

**Query parameters**

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `tokens`  | string | Filter to specific token identifiers |

Use altered accounts to build an indexer that tracks which addresses changed in each block without parsing full transaction data.

## Blocks by round

| Method | Path                       | Description                                  |
| ------ | -------------------------- | -------------------------------------------- |
| GET    | `/blocks/by-round/{round}` | Blocks from all shards for a consensus round |

Returns one block per shard. The Gateway fans out to all shard observers in parallel.

## Hyperblocks

Hyperblocks provide a cross-shard unified view anchored to a metachain block. Each hyperblock contains all transactions from all shards that the metablock notarized.

| Method | Path                           | Description                         |
| ------ | ------------------------------ | ----------------------------------- |
| GET    | `/hyperblock/by-hash/{hash}`   | Hyperblock by metachain block hash  |
| GET    | `/hyperblock/by-nonce/{nonce}` | Hyperblock by metachain block nonce |

**Query parameters**

| Parameter             | Type    | Description                                           |
| --------------------- | ------- | ----------------------------------------------------- |
| `withLogs`            | boolean | Include event logs                                    |
| `notarizedAtSource`   | boolean | Include notarization-at-source data                   |
| `withAlteredAccounts` | boolean | Include altered accounts per shard                    |
| `tokens`              | string  | Filter altered accounts to specific token identifiers |

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://rust-gateway.xoxno.com/hyperblock/by-nonce/1234567?withLogs=true"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    const res = await fetch(
      "https://rust-gateway.xoxno.com/hyperblock/by-nonce/1234567?withLogs=true"
    );
    const data = await res.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    res = requests.get(
        "https://rust-gateway.xoxno.com/hyperblock/by-nonce/1234567",
        params={"withLogs": "true"},
    )
    print(res.json())
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    let body: serde_json::Value = reqwest::Client::new()
        .get("https://rust-gateway.xoxno.com/hyperblock/by-nonce/1234567")
        .query(&[("withLogs", "true")])
        .send()
        .await?
        .json()
        .await?;

    println!("{body:#?}");
    ```
  </Tab>
</Tabs>

Hyperblocks include transactions (`withTxs=true` is implicit). Use them when you need a complete cross-shard view at a specific metachain height.