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

# Shard-aware routing

> How the Gateway routes requests to the correct shard observer based on address derivation.

MultiversX is a sharded blockchain. The Gateway abstracts sharding by routing each request to the correct shard observer. You do not need to know which shard hosts an account: the Gateway resolves it from the address.

## Address-to-shard derivation

Every MultiversX address maps to exactly one shard. The Gateway computes the shard assignment locally using this process:

1. Decode the bech32 address (`erd1...`) to its raw public key bytes.
2. Take the last byte of the public key.
3. Compute `lastByte % numberOfShards`. The mainnet currently runs 3 shards (0, 1, 2).

Smart contract addresses follow the same rule: the last byte of the contract's public key determines the shard.

The `/address/{address}/shard` endpoint returns the computed shard for any address without contacting an observer. This is a local computation that completes in microseconds.

```bash theme={"system"}
curl https://rust-gateway.xoxno.com/address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th/shard
```

## Metachain

The metachain (shard ID `4294967295`) handles protocol-level operations. These endpoints target metachain observers:

* **ESDT role queries:** `/address/{address}/esdts-with-role/{role}`, `/address/{address}/esdts/roles`, `/address/{address}/registered-nfts`
* **Network economics:** `/network/economics`
* **Staking info:** `/network/direct-staked-info`, `/network/delegated-info`
* **Validator data:** `/validator/statistics`, `/validator/auction`
* **Hyperblocks:** `/hyperblock/by-hash/{hash}`, `/hyperblock/by-nonce/{nonce}`

You do not need to specify the metachain shard ID for these endpoints. The Gateway recognizes them and routes to a metachain observer.

## Observer selection

Within each shard, the Gateway selects observers using round-robin load balancing. This distributes requests evenly across all available observers in the target shard.

If the primary observer fails, the Gateway falls back to backup observers marked as fallback in the configuration.

For historical queries (requests with `blockNonce`, `blockHash`, or similar parameters), the Gateway skips snapshotless observers that lack full history. The Gateway prefers full-history observers for block and hyperblock queries to ensure data availability.

## Fan-out patterns

Some endpoints query multiple shards in parallel and aggregate the results:

| Endpoint                       | Behavior                                                               |
| ------------------------------ | ---------------------------------------------------------------------- |
| `/network/esdt/supply/{token}` | Aggregates token supply from all shards and the metachain              |
| `/node/heartbeatstatus`        | Collects heartbeat data from all observers, deduplicates by public key |
| `/blocks/by-round/{round}`     | Fetches one block per shard for the given round                        |
| `/transaction/{txhash}`        | Queries all shards in parallel, returns the first match                |
| `/address/bulk`                | Groups addresses by shard, then queries each shard concurrently        |

These fan-out requests run concurrently across shards. The Gateway merges the results into a single response.

## The forced-shard-id override

Add `?forced-shard-id={shardId}` to any request to bypass automatic shard routing and direct the request to a specific shard observer.

```bash theme={"system"}
# Force the request to shard 1 regardless of the address
curl "https://rust-gateway.xoxno.com/address/erd1.../balance?forced-shard-id=1"
```

Use cases include debugging observer behavior, testing shard-specific responses, and verifying cross-shard data consistency.

<Warning>
  Forcing the wrong shard returns empty or incorrect results. Use this parameter only for debugging.
</Warning>