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

# Gas statistics

> Subscribe to per-shard gas price and price-per-unit statistics from the Relayer WebSocket.

Subscribe to `gasStats` to receive per-shard gas price and PPU statistics.

## Request

```json theme={"system"}
{
  "action": "subscribe",
  "requestId": "gas-001",
  "topic": "gasStats"
}
```

## Acknowledgment

```json theme={"system"}
{
  "action": "subscribe",
  "requestId": "gas-001",
  "status": "ok",
  "topic": "gasStats"
}
```

## Pushed Event

```json theme={"system"}
{
  "type": "gasStats",
  "data": {
    "shard": 0,
    "gasPrice": {
      "min": 1000000000,
      "max": 1500000000,
      "avg": 1200000000,
      "bucketAvg": 1210000000,
      "percentiles": {
        "p50": 1150000000,
        "p75": 1350000000,
        "p90": 1450000000
      }
    },
    "ppu": {
      "avg": 0.0000012,
      "percentiles": {
        "p50": 0.0000011,
        "p75": 0.0000013,
        "p90": 0.0000014
      }
    }
  }
}
```

## Fields

| Field                  | Meaning                                         |
| ---------------------- | ----------------------------------------------- |
| `data.shard`           | Shard ID.                                       |
| `gasPrice.avg`         | Arithmetic average across the 30-minute window. |
| `gasPrice.bucketAvg`   | Average of 10-second bucket averages.           |
| `gasPrice.percentiles` | `p50`, `p75`, and `p90` gas prices.             |
| `ppu`                  | Price per gas unit after data payload costs.    |

## Limits

| Limit             | Value                                      |
| ----------------- | ------------------------------------------ |
| Update cadence    | 50 ms debounce on state changes            |
| Periodic fallback | 5 s                                        |
| Window            | 30 minutes, divided into 10-second buckets |
| Topic slot usage  | 1 of 64 active topics                      |

## Unsubscribe

```json theme={"system"}
{
  "action": "unsubscribe",
  "requestId": "gas-stop",
  "topic": "gasStats"
}
```

## Reconnect Handling

After reconnect, send the `subscribe` control message again. Keep the last received shard values in memory until fresh events arrive.

## Related Pages

* [WebSocket lifecycle](/relayer/websocket-lifecycle)
* [Gas optimization](/resources/gas-optimization)
* [gasStats event schema](/api-reference/events/gas-stats)