{
  "openrpc": "1.2.6",
  "info": {
    "title": "Bitcoin Block Timestamp Lookup",
    "description": "Quicknode Bitcoin Block Timestamp Lookup reference",
    "version": "1.0.0"
  },
  "methods": [
    {
      "name": "qn_getBlockFromTimestamp",
      "summary": "Retrieves the most recent block on the blockchain that was generated at or before the specified Unix timestamp (in secon",
      "description": "Retrieves the most recent block on the blockchain that was generated at or before the specified Unix timestamp (in seconds)",
      "params": [
        {
          "name": "timestamp",
          "description": "A Unix timestamp (in seconds) representing the time at or before which the desired block should be retrieved",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "result": {
        "name": "result",
        "description": "The result object which contains the following fields:",
        "schema": {
          "type": "object",
          "properties": {
            "network": {
              "type": "string",
              "description": "The blockchain network on which the block exists"
            },
            "blockNumber": {
              "type": "integer",
              "description": "The most recent block on the blockchain that was generated at or before the specified Unix timestamp"
            },
            "timestamp": {
              "type": "integer",
              "description": "The actual timestamp of the returned block in seconds"
            }
          }
        }
      },
      "tags": [
        {
          "name": "qn"
        }
      ],
      "externalDocs": {
        "description": "Quicknode docs",
        "url": "https://www.quicknode.com/docs/bitcoin/qn_getBlockFromTimestamp"
      },
      "examples": [
        {
          "name": "qn_getBlockFromTimestamp example",
          "params": [
            {
              "name": "timestamp",
              "value": 1730000000
            }
          ],
          "result": {
            "name": "qn_getBlockFromTimestamp result",
            "value": {
              "network": "ethereum",
              "blockNumber": 29402654,
              "timestamp": 1730000000
            }
          }
        }
      ]
    },
    {
      "name": "qn_getBlocksInTimestampRange",
      "summary": "Retrieves all blocks within a specified Unix timestamp range, allowing you to query historical blocks in a defined time",
      "description": "Retrieves all blocks within a specified Unix timestamp range, allowing you to query historical blocks in a defined time window. The response can be paginated to efficiently handle large sets of data, making it useful for detailed analysis across extended time periods.",
      "params": [
        {
          "name": "startTimestamp",
          "description": "The Unix timestamp (in seconds) marking the start of the desired time range",
          "required": true,
          "schema": {
            "type": "integer"
          }
        },
        {
          "name": "endTimestamp",
          "description": "The Unix timestamp (in seconds) marking the end of the desired time range",
          "required": true,
          "schema": {
            "type": "integer"
          }
        },
        {
          "name": "pageSize",
          "description": "(Optional) Defines how many blocks to return per page. The default value is 100, with a maximum of 1000",
          "schema": {
            "type": "integer"
          }
        },
        {
          "name": "lastTimestamp",
          "description": "(Optional) The timestamp of the last block from the previous page, used to paginate through large result sets",
          "schema": {
            "type": "integer"
          }
        },
        {
          "name": "lastBlockNumber",
          "description": "(Optional) The block number of the last block from the previous page, used in conjunction with lastTimestamp for pagination",
          "schema": {
            "type": "integer"
          }
        }
      ],
      "result": {
        "name": "result",
        "description": "The result object which contains the following fields:",
        "schema": {
          "type": "object",
          "properties": {
            "blocks": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "blockNumber": {
                    "type": "integer",
                    "description": "The unique number of the block on the blockchain"
                  },
                  "network": {
                    "type": "string",
                    "description": "The blockchain network on which the block exists"
                  },
                  "timestamp": {
                    "type": "integer",
                    "description": "The Unix timestamp (in seconds) representing when the block was created"
                  }
                }
              },
              "description": "An array that contains the list of block objects that fall within the specified timestamp range. Each object represents a block and contains the following fields:"
            },
            "pagination": {
              "type": "object",
              "properties": {
                "hasNextPage": {
                  "type": "boolean",
                  "description": "A boolean value that indicates whether there are more pages of results to retrieve. If true, it means there are additional blocks that fall within the specified timestamp range but were not included in the current response due to the pageSize limit"
                },
                "nextPageParams": {
                  "type": "object",
                  "properties": {
                    "lastBlockNumber": {
                      "type": "integer",
                      "description": "The block number of the last block in the current page"
                    },
                    "lastTimestamp": {
                      "type": "integer",
                      "description": "The timestamp of the last block in the current page"
                    }
                  },
                  "description": "The nextPageParams object which contains the following fields:"
                },
                "pageSize": {
                  "type": "integer",
                  "description": "The number of blocks that were returned in the current response"
                }
              },
              "description": "The pagination object which contains the following fields:"
            }
          }
        }
      },
      "tags": [
        {
          "name": "qn"
        }
      ],
      "externalDocs": {
        "description": "Quicknode docs",
        "url": "https://www.quicknode.com/docs/bitcoin/qn_getBlocksInTimestampRange"
      },
      "examples": [
        {
          "name": "qn_getBlocksInTimestampRange example",
          "params": [
            {
              "name": "startTimestamp",
              "value": 1730000000
            },
            {
              "name": "endTimestamp",
              "value": 1730000100
            },
            {
              "name": "pageSize",
              "value": 5
            }
          ],
          "result": {
            "name": "qn_getBlocksInTimestampRange result",
            "value": {
              "blocks": [
                {
                  "blockNumber": 29402654,
                  "network": "ethereum",
                  "timestamp": 1730000000
                },
                {
                  "blockNumber": 29402655,
                  "network": "ethereum",
                  "timestamp": 1730000012
                },
                {
                  "blockNumber": 29402656,
                  "network": "ethereum",
                  "timestamp": 1730000024
                },
                {
                  "blockNumber": 29402657,
                  "network": "ethereum",
                  "timestamp": 1730000036
                },
                {
                  "blockNumber": 29402658,
                  "network": "ethereum",
                  "timestamp": 1730000048
                }
              ],
              "pagination": {
                "hasNextPage": true,
                "nextPageParams": {
                  "lastBlockNumber": 29402658,
                  "lastTimestamp": 1730000048,
                  "pageSize": 5
                }
              }
            }
          }
        }
      ]
    }
  ],
  "servers": [
    {
      "name": "Block Timestamp Lookup",
      "url": "https://docs-demo.btc.quiknode.pro"
    }
  ]
}