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

# Blocks

> Get block headers on 21 chains by number, hash, or number or timestamp range, including the block at or before a given time.

```text theme={"dark"}
GET https://edge.goldsky.com/data/blocks/{chain}
```

Returns block headers for one chain, newest first by default. Look up one block by number or hash, or filter by a range of block numbers or timestamps. The most common use is turning a timestamp into a block number, and a block number into a timestamp.

## Parameters

**chain** `string` *required*

The chain's slug, such as `ethereum`. See [supported chains](#supported-chains). Polygon is `matic`, not `polygon`.

**number** `integer`

Return only the block with this number. Can't be combined with `hash` or any range parameter.

**hash** `string`

Return only the block with this hash: `0x` followed by 64 hex characters. Can't be combined with `number` or any range parameter.

**number\_gte** `integer`

Only return blocks numbered at or above this.

**number\_lte** `integer`

Only return blocks numbered at or below this.

**timestamp\_gte** `integer`

Only return blocks at or after this time, in Unix seconds.

**timestamp\_lte** `integer`

Only return blocks at or before this time, in Unix seconds. With `sort=number_desc` and `limit=1`, it returns the newest block at or before the time.

**sort** `string` (default: number\_desc)

`number_desc`, newest first, or `number_asc`, oldest first.

**limit** `integer` (default: 100)

Rows per page, up to `1000`. See [pagination](https://docs.goldsky.com/feeds/api/overview.md#prediction-markets-and-chain-datasets).

**cursor** `string`

The `next_cursor` from a previous response. Use the same `sort` as the request that returned it.

With no filters, the request returns the chain's newest blocks.

## Response

**data** `object[]`

One entry per block, in `sort` order.

**properties**

**chain** `string`

The chain's slug.

**number** `integer`

Block number.

**timestamp** `integer`

Block time, in Unix seconds.

**hash** `string`

Block hash.

**parent\_hash** `string`

Hash of the previous block.

**author** `string`

Address that produced the block and received its fees.

**transaction\_count** `integer`

Number of transactions in the block.

**gas\_used** `integer | null`

Gas used by the block's transactions.

**gas\_limit** `integer | null`

Block gas limit.

**base\_fee\_per\_gas** `integer | null`

Base fee per gas, in wei. `null` for blocks without a base fee.

**size** `integer`

Block size, in bytes.

**state\_root** `string`

State root.

**transactions\_root** `string`

Transactions root.

**receipts\_root** `string`

Receipts root.

**uncles\_hash** `string`

Uncles hash.

**limit** `integer`

The page size used for this response.

**next\_cursor** `string | null`

Pass it as `cursor` to get the next page. `null` on the last page.

## Supported chains

Blocks and [Chain head](https://docs.goldsky.com/feeds/api/chain-datasets/chain-head.md) support 21 chains, a different list from the [wallet feeds' chains](https://docs.goldsky.com/feeds/api/overview.md#supported-chains). Pass the slug in the path:

| Chain | Slug |
| - | - |
| ApeChain | `apechain` |
| Arbitrum Sepolia | `arbitrum-sepolia` |
| Base | `base` |
| Blast | `blast` |
| BNB Smart Chain | `bsc` |
| Celo | `celo` |
| Ethereum | `ethereum` |
| Flare | `flare` |
| Gravity | `gravity` |
| HyperEVM | `hyperevm` |
| Linea | `linea` |
| Optimism | `optimism` |
| Plasma | `plasma` |
| Plume | `plume` |
| Polygon | `matic` |
| Reya | `reya` |
| Robinhood Chain | `robinhood` |
| Sei | `sei` |
| World Chain | `worldchain` |
| Xai | `xai` |
| X Layer | `xlayer` |

Any other value returns `400 BAD_REQUEST`, and `error.message` lists the supported slugs. The live list is the `chain` enum in the [OpenAPI spec](https://edge.goldsky.com/data/openapi.json).

## How the data behaves

* **Recent blocks can change.** A block near the chain head can be replaced in a reorganization. Requests with `number`, `hash`, `number_lte`, or `timestamp_lte` carry `Cache-Control: public, max-age=300`. Other requests carry `public, max-age=2`.
* **A block that doesn't exist yet returns an empty page.** Asking for a number above the chain head returns `200` with an empty `data` array, not an error. Use [Chain head](https://docs.goldsky.com/feeds/api/chain-datasets/chain-head.md) to see how far a chain goes.
* **Timestamps are Unix seconds.** `timestamp` is an integer, not an RFC 3339 string as in the wallet feeds.

## Errors

This endpoint returns the [same errors](https://docs.goldsky.com/feeds/api/overview.md#errors) as the other feeds. These are specific to it:

| Status | `code` | When |
| - | - | - |
| `400` | `BAD_REQUEST` | The chain isn't supported, `hash` isn't `0x` followed by 64 hex characters, `sort` isn't `number_desc` or `number_asc`, or `cursor` was issued for a different `sort`. |
| `422` | `CONFLICTING_FILTERS` | `number` or `hash` is combined with another lookup or range parameter. |

## Billing

With an API key, each block returned is one compute unit, at \$10 per million. An empty page is free. With [x402](https://docs.goldsky.com/feeds/api/overview.md#pay-per-request-with-x402), each request costs 10 atomic USDC (\$0.00001), however many blocks it returns. See [Feeds pricing](https://docs.goldsky.com/pricing/summary.md#feeds).

## Example

Find the newest Ethereum block at or before Unix time `1783820990`:

```bash theme={"dark"}
curl -H "X-API-Key: $GOLDSKY_FEEDS_API_KEY" \
  "https://edge.goldsky.com/data/blocks/ethereum?timestamp_lte=1783820990&sort=number_desc&limit=1"
```

```json theme={"dark"}
{
  "data": [
    {
      "chain": "ethereum",
      "number": 25513360,
      "timestamp": 1783820987,
      "hash": "0x0bfacb3fe970ed16d7e3d78ae74ee946287e8e2738d4ad97cc706f23ef9da16c",
      "parent_hash": "0x27549b385199e0ef290c2c49f1761b0deb241295e707ee85441b3f90cf92edd1",
      "author": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
      "gas_used": 57830288,
      "gas_limit": 60000000,
      "size": 227660,
      "receipts_root": "0xfe78e7811fd1eb99e6748b6c02646c478167fa1f19cdff8c40b7e611ac609180",
      "transactions_root": "0x7563ac4529c2f09280ea6c8491b625c2a90bc1b028137810002b3d080df8c7eb",
      "state_root": "0x43cafcb18943f661221ac78246ad4c955b7badae039ccc42226de7735c80ea08",
      "uncles_hash": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "base_fee_per_gas": 72868923,
      "transaction_count": 519
    }
  ],
  "next_cursor": "eyJzIjoibnVtYmVyX2Rlc2MiLCJrIjoiMjU1MTMzNjAifQ",
  "limit": 1
}
```

To go the other way, from a block number to its timestamp, send `number=25513360` instead.


## Related topics

- [Blocks Subgraphs](https://docs.goldsky.com/subgraphs/blocks-subgraphs.md)
- [trace_block](https://docs.goldsky.com/edge-rpc/evm/methods/trace_block.md)
- [eth_blockNumber](https://docs.goldsky.com/edge-rpc/evm/methods/eth_blockNumber.md)
- [debug_traceBlockByHash](https://docs.goldsky.com/edge-rpc/evm/methods/debug_traceBlockByHash.md)
- [debug_traceBlockByNumber](https://docs.goldsky.com/edge-rpc/evm/methods/debug_traceBlockByNumber.md)