block-timestamp/README.md

Block Timestamp API

Built for the replacement of Blocks Subgraph, useful when querying blocks with timestamp range (usually required when drawing charts)

Something like https://www.quicknode.com/docs/ethereum/qn_getBlocksInTimestampRange

Disclaimer

This API & indexer is mainly to assume blocks on the specific historic range not to index some trustworthy block DB like how etherscan does. The API doesn't have reorg detection so do not use for other purpose rather than fetching block numbers

Technical Requirements

• Latest LTS version of Node.js (20.x or 22.x recommended)

• RPC node & ChainID (Supply them with RPC_URL env value, see ./src/config.ts for available ENV variables).

• MongoDB (Stores blockHash, blockNum, and timestamp)

How to install

# Install libraries
yarn

# Setup ENV (RPC, ChainID - EIP-155 - can be found on chainlist.org)
nano .env

# Start indexer & API
yarn start

# Can be used to clear DB
yarn reset

Required ENV

CHAIN_ID="1"
RPC_URL="https://rpc.mevblocker.io"
MONGO_URL="mongodb://127.0.0.1:27017/ethBlocks"

Query example

GET /

• Returns API Status

{
  "chainId": 1,
  "localBlock": 21436500,
  "onSync": false,
  "errors": []
}

POST /

• Returns block numbers inside the timestamp range (Limited to 100 blocks per request, 30 request per array)

Request Body

{
    "id": 0,
    "length": 1,
    "timestamp_gte": 1734612500,
    "timestamp_lte": 1734612580
}

or

[
  {
    "id": 0,
    "length": 1,
    "timestamp_gte": 1734612500,
    "timestamp_lte": 1734612580
  },
  {}
]

Response

[{
    "id": 0,
    "blocks": []
}, {
    "id": 1,
    "blocks": []
}]

GET /number/:blockNumber or GET /hash/:blockHash

• Returns block object if found (if not will return empty object)