Blocks API - Feeds - Goldsky Docs

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

string

required

The chain’s slug, such as ethereum. See supported chains. Polygon is matic, not polygon.

integer

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

string

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

integer

Only return blocks numbered at or above this.

integer

Only return blocks numbered at or below this.

integer

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

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.

string

default:"number_desc"

number_desc, newest first, or number_asc, oldest first.

integer

default:"100"

Rows per page, up to 1000. See pagination.

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

object[]

One entry per block, in sort order.

Show properties

string

The chain’s slug.

integer

Block number.

integer

Block time, in Unix seconds.

string

Block hash.

string

Hash of the previous block.

string

Address that produced the block and received its fees.

integer

Number of transactions in the block.

integer | null

Gas used by the block’s transactions.

integer | null

Block gas limit.

integer | null

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

integer

Block size, in bytes.

string

State root.

string

Transactions root.

string

Receipts root.

string

Uncles hash.

integer

The page size used for this response.

string | null

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

Supported chains

Blocks and Chain head support 21 chains, a different list from the wallet feeds’ 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.

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 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 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, each request costs 10 atomic USDC ($0.00001), however many blocks it returns. See Feeds pricing.

Example

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

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

{
  "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.

​Parameters

​Response

​Supported chains

​How the data behaves

​Errors

​Billing

​Example

Parameters

Response

Supported chains

How the data behaves

Errors

Billing

Example