# getblockstats

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

POST https://bitcoin-mainnet.g.alchemy.com/v2/{apiKey}

Calculates various statistics for a given block by hash or height.


Reference: https://www.alchemy.com/docs/chains/bitcoin/bitcoin-api-endpoints/getblockstats

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| hash_or_height | string or integer | Yes | The block hash (string) or height (integer) of the target block. |
| stats | string[] | No | Optional list of specific stats to retrieve. If empty or omitted, returns all stats.  |

## Result

**result** (object): A set of statistical metrics for the specified block.

## Example

### Request

```json
{
  "jsonrpc": "2.0",
  "method": "getblockstats",
  "params": [
    "00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80",
    []
  ],
  "id": 1
}
```

### Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "avgfee": 1565,
    "avgfeerate": 3,
    "avgtxsize": 668,
    "blockhash": "00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80",
    "feerate_percentiles": [
      2,
      2,
      3,
      3,
      4
    ],
    "height": 894470,
    "ins": 7718,
    "outs": 5666,
    "maxfee": 376692,
    "maxfeerate": 79,
    "maxtxsize": 200604,
    "medianfee": 453,
    "mediantime": 1745928076,
    "mediantxsize": 228,
    "minfee": 141,
    "minfeerate": 1,
    "mintxsize": 150,
    "subsidy": 312500000,
    "swtotal_size": 1049707,
    "swtotal_weight": 2349304,
    "swtxs": 2075,
    "time": 1745931642,
    "total_out": 271147032190,
    "total_size": 1460379,
    "total_weight": 3991992,
    "totalfee": 3420664,
    "txs": 2186,
    "utxo_increase": -2052,
    "utxo_size_inc": -137484,
    "utxo_increase_actual": -2841,
    "utxo_size_inc_actual": -199799
  },
  "id": 1
}
```

## Code Examples

### cURL

```bash
curl --request POST \
  --url https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo \
  --header 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getblockstats",
  "params": [
    "00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80",
    []
  ]
}'
```

### JavaScript

```javascript
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'getblockstats',
    params: ['00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80', []]
  })
};

fetch('https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo"

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getblockstats",
    "params": ["00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80", []]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

### Go

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"getblockstats\",\n  \"params\": [\n    \"00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80\",\n    []\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

### Java

```java
HttpResponse<String> response = Unirest.post("https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"getblockstats\",\n  \"params\": [\n    \"00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80\",\n    []\n  ]\n}")
  .asString();
```

### C#

```csharp
using RestSharp;


var options = new RestClientOptions("https://bitcoin-mainnet.g.alchemy.com/v2/docs-demo");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddJsonBody("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"getblockstats\",\n  \"params\": [\n    \"00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80\",\n    []\n  ]\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

```


## OpenRPC Method Specification

```yaml
name: getblockstats
summary: Get per-block statistics
description: |
  Calculates various statistics for a given block by hash or height.
params:
  - name: hash_or_height
    required: true
    description: The block hash (string) or height (integer) of the target block.
    schema:
      oneOf:
        - title: Bitcoin Block Hash
          type: string
          pattern: ^[a-fA-F0-9]{64}$
          description: A 64-character hex string representing the block hash.
        - title: Block Height
          type: integer
          minimum: 0
          description: The block height (index) used to fetch the block hash.
  - name: stats
    required: false
    description: |
      Optional list of specific stats to retrieve. If empty or omitted, returns all stats.
    schema:
      type: array
      items:
        type: string
result:
  name: result
  description: A set of statistical metrics for the specified block.
  schema:
    title: Bitcoin Block Statistics
    type: object
    properties:
      avgfee:
        type: integer
        description: Average fee in the block (satoshis)
      avgfeerate:
        type: integer
        description: Average fee rate
      avgtxsize:
        type: integer
        description: Average transaction size
      blockhash:
        title: Bitcoin Block Hash
        type: string
        pattern: ^[a-fA-F0-9]{64}$
        description: A 64-character hex string representing the block hash.
      feerate_percentiles:
        type: array
        description: Feerates at 10th, 25th, 50th, 75th, and 90th percentile
        items:
          type: integer
      height:
        title: Block Height
        type: integer
        minimum: 0
        description: The block height (index) used to fetch the block hash.
      ins:
        type: integer
        description: Number of inputs
      outs:
        type: integer
        description: Number of outputs
      maxfee:
        type: integer
      maxfeerate:
        type: integer
      maxtxsize:
        type: integer
      medianfee:
        type: integer
      mediantime:
        type: integer
      mediantxsize:
        type: integer
      minfee:
        type: integer
      minfeerate:
        type: integer
      mintxsize:
        type: integer
      subsidy:
        type: integer
      swtotal_size:
        type: integer
      swtotal_weight:
        type: integer
      swtxs:
        type: integer
      time:
        type: integer
      total_out:
        type: integer
      total_size:
        type: integer
      total_weight:
        type: integer
      totalfee:
        type: integer
      txs:
        type: integer
      utxo_increase:
        type: integer
      utxo_size_inc:
        type: integer
      utxo_increase_actual:
        type: integer
      utxo_size_inc_actual:
        type: integer
examples:
  - name: getblockstats example
    params:
      - name: hash_or_height
        value: 00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80
      - name: stats
        value: []
    result:
      name: result
      value:
        avgfee: 1565
        avgfeerate: 3
        avgtxsize: 668
        blockhash: 00000000000000000000669ed57030eb18020ee7029c064f10505156be203d80
        feerate_percentiles:
          - 2
          - 2
          - 3
          - 3
          - 4
        height: 894470
        ins: 7718
        outs: 5666
        maxfee: 376692
        maxfeerate: 79
        maxtxsize: 200604
        medianfee: 453
        mediantime: 1745928076
        mediantxsize: 228
        minfee: 141
        minfeerate: 1
        mintxsize: 150
        subsidy: 312500000
        swtotal_size: 1049707
        swtotal_weight: 2349304
        swtxs: 2075
        time: 1745931642
        total_out: 271147032190
        total_size: 1460379
        total_weight: 3991992
        totalfee: 3420664
        txs: 2186
        utxo_increase: -2052
        utxo_size_inc: -137484
        utxo_increase_actual: -2841
        utxo_size_inc_actual: -199799
```