openapi: 3.1.0
info:
title: Polkadot REST Account blocks API
description: High-performance Rust REST API for Substrate/Polkadot blockchain data. Drop-in replacement for substrate-api-sidecar.
contact:
url: https://github.com/paritytech/polkadot-rest-api
license:
name: GPL-3.0-or-later
version: 0.1.3
servers:
- url: http://localhost:8080/v1
description: Localhost
tags:
- name: blocks
description: Block queries and extrinsic data
paths:
/v1/blocks:
get:
tags:
- blocks
summary: Get blocks by range
description: Returns a collection of blocks given a numeric range. Range is inclusive and limited to 500 blocks.
operationId: get_blocks
parameters:
- name: range
in: query
description: Block range in format 'start-end' (e.g. '100-200')
required: false
schema:
type: string
- name: eventDocs
in: query
description: Include documentation for events
required: false
schema:
type: boolean
- name: extrinsicDocs
in: query
description: Include documentation for extrinsics
required: false
schema:
type: boolean
- name: noFees
in: query
description: Skip fee calculation for extrinsics
required: false
schema:
type: boolean
- name: useRcBlock
in: query
description: Treat range as Relay Chain blocks
required: false
schema:
type: boolean
- name: useEvmFormat
in: query
description: Convert AccountId32 addresses to EVM format for revive pallet events
required: false
schema:
type: boolean
responses:
'200':
description: Array of block information
content:
application/json:
schema:
type: array
items:
type: object
'400':
description: Invalid range parameter
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/head:
get:
tags:
- blocks
summary: Get latest block
description: Returns the latest finalized or canonical block with full extrinsic and event details.
operationId: get_block_head
parameters:
- name: finalized
in: query
description: When true (default), returns finalized head. When false, returns canonical head.
required: false
schema:
type: boolean
- name: eventDocs
in: query
description: Include documentation for events
required: false
schema:
type: boolean
- name: extrinsicDocs
in: query
description: Include documentation for extrinsics
required: false
schema:
type: boolean
- name: noFees
in: query
description: Skip fee calculation for extrinsics
required: false
schema:
type: boolean
- name: decodedXcmMsgs
in: query
description: Decode and include XCM messages
required: false
schema:
type: boolean
- name: paraId
in: query
description: Filter XCM messages by parachain ID
required: false
schema:
type: integer
format: int32
minimum: 0
- name: useRcBlock
in: query
description: When true, use relay chain head to find corresponding Asset Hub blocks
required: false
schema:
type: boolean
- name: useEvmFormat
in: query
description: Convert AccountId32 addresses to EVM format for revive pallet events
required: false
schema:
type: boolean
responses:
'200':
description: Latest block information
content:
application/json:
schema:
type: object
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/head/header:
get:
tags:
- blocks
summary: Get head block header
description: Returns the header of the latest finalized or canonical block (lightweight, no extrinsics/events).
operationId: get_blocks_head_header
parameters:
- name: finalized
in: query
description: When true (default), returns finalized head header. When false, returns canonical head header.
required: false
schema:
type: boolean
- name: useRcBlock
in: query
description: Treat as Relay Chain block and return Asset Hub blocks
required: false
schema:
type: boolean
responses:
'200':
description: Block header information
content:
application/json:
schema:
type: object
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/{blockId}:
get:
tags:
- blocks
summary: Get block by ID
description: Returns block information for a given block identifier (hash or number), including extrinsics, events, and fees.
operationId: get_block
parameters:
- name: blockId
in: path
description: Block height number or block hash
required: true
schema:
type: string
- name: eventDocs
in: query
description: Include documentation for events
required: false
schema:
type: boolean
- name: extrinsicDocs
in: query
description: Include documentation for extrinsics
required: false
schema:
type: boolean
- name: noFees
in: query
description: Skip fee calculation for extrinsics
required: false
schema:
type: boolean
- name: finalizedKey
in: query
description: When true (default), include finalized status in response
required: false
schema:
type: boolean
- name: decodedXcmMsgs
in: query
description: Decode and include XCM messages
required: false
schema:
type: boolean
- name: paraId
in: query
description: Filter XCM messages by parachain ID
required: false
schema:
type: integer
format: int32
minimum: 0
- name: useRcBlock
in: query
description: Treat blockId as Relay Chain block and return Asset Hub blocks
required: false
schema:
type: boolean
- name: useEvmFormat
in: query
description: Convert AccountId32 addresses to EVM format for revive pallet events
required: false
schema:
type: boolean
responses:
'200':
description: Block information
content:
application/json:
schema:
type: object
'400':
description: Invalid block identifier
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/{blockId}/extrinsics-raw:
get:
tags:
- blocks
summary: Get raw extrinsics
description: Returns raw block data with hex-encoded extrinsics for a given block identifier. The extrinsics are returned as raw hex strings without decoding.
operationId: get_block_extrinsics_raw
parameters:
- name: blockId
in: path
description: Block height number or block hash
required: true
schema:
type: string
- name: useRcBlock
in: query
description: When true, treat blockId as Relay Chain block and return Asset Hub blocks
required: false
schema:
type: boolean
responses:
'200':
description: Raw block data with hex-encoded extrinsics
content:
application/json:
schema:
type: object
'400':
description: Invalid block identifier
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/{blockId}/extrinsics/{extrinsicIndex}:
get:
tags:
- blocks
summary: Get extrinsic by index
description: Returns a specific extrinsic from a block by its index within the block.
operationId: get_extrinsic
parameters:
- name: blockId
in: path
description: Block height number or block hash
required: true
schema:
type: string
- name: extrinsicIndex
in: path
description: Index of the extrinsic within the block
required: true
schema:
type: string
- name: eventDocs
in: query
description: Include documentation for events
required: false
schema:
type: boolean
- name: extrinsicDocs
in: query
description: Include documentation for extrinsics
required: false
schema:
type: boolean
- name: noFees
in: query
description: Skip fee calculation
required: false
schema:
type: boolean
- name: useRcBlock
in: query
description: When true, treat blockId as Relay Chain block and return Asset Hub extrinsics
required: false
schema:
type: boolean
- name: useEvmFormat
in: query
description: Convert AccountId32 addresses to EVM format for revive pallet events
required: false
schema:
type: boolean
responses:
'200':
description: Extrinsic details
content:
application/json:
schema:
type: object
'400':
description: Invalid block identifier or extrinsic index
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/{blockId}/header:
get:
tags:
- blocks
summary: Get block header by ID
description: Returns the header of the specified block (lightweight, no extrinsics/events).
operationId: get_block_header
parameters:
- name: blockId
in: path
description: Block height number or block hash
required: true
schema:
type: string
- name: useRcBlock
in: query
description: Treat blockId as Relay Chain block and return Asset Hub blocks
required: false
schema:
type: boolean
responses:
'200':
description: Block header information
content:
application/json:
schema:
type: object
'400':
description: Invalid block identifier
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/blocks/{blockId}/para-inclusions:
get:
tags:
- blocks
summary: Get parachain inclusions
description: Returns parachain inclusion information for a given relay chain block. Extracts CandidateIncluded events from the ParaInclusion pallet.
operationId: get_block_para_inclusions
parameters:
- name: blockId
in: path
description: Block height number or block hash
required: true
schema:
type: string
- name: paraId
in: query
description: Filter results by a specific parachain ID
required: false
schema:
type: integer
format: int32
minimum: 0
responses:
'200':
description: Parachain inclusion information
content:
application/json:
schema:
type: object
'400':
description: Invalid block identifier
'500':
description: Internal server error
'503':
description: Service unavailable
/blocks:
get:
tags:
- blocks
summary: Get a range of blocks by their height.
description: Given a range query parameter return an array of all the blocks within that range. When `useRcBlock` parameter is used, the range represents relay chain block numbers and the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp` for each block. Relay chain blocks without corresponding Asset Hub blocks are skipped.
operationId: getBlock
parameters:
- name: range
in: query
description: A range of integers. There is a max limit of 500 blocks per request.
required: true
example: 0-499
schema:
type: string
- name: eventDocs
in: query
description: When set to `true`, every event will have an extra `docs` property with a string of the events documentation.
required: false
schema:
type: boolean
default: false
- name: extrinsicDocs
in: query
description: When set to `true`, every extrinsic will have an extra `docs` property with a string of the extrinsics documentation.
required: false
schema:
type: boolean
default: false
- name: noFees
in: query
description: When set to `true`, the fee won't be calculated for the extrinsics.
required: false
schema:
type: boolean
default: false
- name: useEvmFormat
in: query
description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
required: false
schema:
type: boolean
default: false
- name: useRcBlock
in: query
description: When set to `true`, the range parameter represents relay chain block numbers and the response includes additional fields for each block. Only supported for Asset Hub endpoints with relay chain API available. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Blocks'
'400':
description: invalid Block identifier supplied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/blocks/{blockId}:
get:
tags:
- blocks
summary: Get a block by its height or hash.
description: Returns a single block. BlockId can either be a block hash or a block height. Replaces `/block/{number}` from versions < v1.0.0. When `useRcBlock` parameter is used, the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp`.
operationId: getBlockById
parameters:
- name: blockId
in: path
description: Block identifier, as the block height or block hash.
required: true
schema:
pattern: ^0[xX][0-9a-fA-F]{1,64}$|[0-9]{1,12}
type: string
- name: eventDocs
in: query
description: When set to `true`, every event will have an extra `docs` property with a string of the events documentation.
required: false
schema:
type: boolean
default: false
- name: extrinsicDocs
in: query
description: When set to `true`, every extrinsic will have an extra `docs` property with a string of the extrinsics documentation.
required: false
schema:
type: boolean
default: false
- name: noFees
in: query
description: When set to `true`, the fee won't be calculated for the extrinsics.
required: false
schema:
type: boolean
default: false
- name: finalizedKey
in: query
description: When set to false, this will override the chain-config, and omit the finalized key in the response. This can increase performance slightly by avoiding an additional RPC call to the node.
required: false
schema:
type: boolean
- name: decodedXcmMsgs
in: query
description: When set to `true`, this will show the decoded XCM messages within the extrinsics of the requested block.
required: false
schema:
type: boolean
default: false
- name: paraId
in: query
description: When it is set, this will return only the decoded XCM messages for the specified origin Parachain Id (originParaId). To activate this functionality, ensure that the `decodedXcmMsgs` parameter is set to true.
required: false
schema:
type: string
- name: useRcBlock
in: query
description: When set to `true`, it will use the relay chain block identifier to determine the corresponding Asset Hub block. Only supported for Asset Hub endpoints with relay chain API available. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
- name: useEvmFormat
in: query
description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BlockWithDecodedXcmMsgs'
- type: array
items:
$ref: '#/components/schemas/BlockWithDecodedXcmMsgs'
description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
'400':
description: invalid Block identifier supplied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/blocks/{blockId}/header:
get:
tags:
- blocks
summary: Get a block's header by its height or hash.
description: Returns a single block's header. BlockId can either be a block hash or a block height. When `useRcBlock` parameter is used, the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp`.
operationId: getBlockHeaderById
parameters:
- name: blockId
in: path
description: Block identifier, as the block height or block hash.
required: true
schema:
pattern: ^0[xX][0-9a-fA-F]{1,64}$|[0-9]{1,12}
type: string
- name: useRcBlock
in: query
description: When set to `true`, it will use the relay chain block identifier to determine the corresponding Asset Hub block. Only supported for Asset Hub endpoints with relay chain API available. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BlockHeader'
- type: array
items:
$ref: '#/components/schemas/BlockHeader'
description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
'400':
description: invalid Block identifier supplied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/blocks/{blockId}/extrinsics/{extrinsicIndex}:
get:
tags:
- blocks
summary: Get an extrinsic by its extrinsicIndex and block height or hash. The pair blockId, extrinsicIndex is sometimes referred to as a Timepoint.
description: Returns a single extrinsic. When `useRcBlock` parameter is used, the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp`.
operationId: getExtrinsicByTimepoint
parameters:
- name: blockId
in: path
description: Block identifier, as the block height or block hash.
required: true
schema:
pattern: ^0[xX][0-9a-fA-F]{1,64}$|[0-9]{1,12}
type: string
- name: extrinsicIndex
in: path
description: The extrinsic's index within the block's body.
required: true
schema:
type: string
- name: eventDocs
in: query
description: When set to `true`, every event will have an extra `docs` property with a string of the events documentation.
required: false
schema:
type: boolean
default: false
- name: extrinsicDocs
in: query
description: When set to `true`, every extrinsic will have an extra `docs` property with a string of the extrinsics documentation.
required: false
schema:
type: boolean
default: false
- name: noFees
in: query
description: When set to `true`, the fee won't be calculated for the extrinsic.
required: false
schema:
type: boolean
default: false
- name: useRcBlock
in: query
description: When set to `true`, it will use the relay chain block identifier to determine the corresponding Asset Hub block. Only supported for Asset Hub endpoints with relay chain API available. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
- name: useEvmFormat
in: query
description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ExtrinsicIndex'
- type: array
items:
$ref: '#/components/schemas/ExtrinsicIndex'
description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
'400':
description: Requested `extrinsicIndex` does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/blocks/head:
get:
tags:
- blocks
summary: Get the most recently finalized block.
description: Returns the most recently finalized block. Replaces `/block` from versions < v1.0.0. When `useRcBlock` parameter is used, the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp`.
operationId: getHeadBlock
parameters:
- name: finalized
in: query
description: Boolean representing whether or not to get the finalized head. If it is not set the value defaults to true. When set to false it will attempt to get the newest known block, which may not be finalized.
required: false
schema:
type: boolean
default: true
- name: eventDocs
in: query
description: When set to `true`, every event will have an extra `docs` property with a string of the events documentation.
required: false
schema:
type: boolean
default: false
- name: extrinsicDocs
in: query
description: When set to `true`, every extrinsic will have an extra `docs` property with a string of the extrinsics documentation.
required: false
schema:
type: boolean
default: false
- name: noFees
in: query
description: When set to `true`, the fee won't be calculated for the extrinsics.
required: false
schema:
type: boolean
default: false
- name: decodedXcmMsgs
in: query
description: When set to `true`, this will show the decoded XCM messages within the extrinsics of the requested block.
required: false
schema:
type: boolean
default: false
- name: paraId
in: query
description: When it is set, this will return only the decoded XCM messages for the specified origin Parachain Id (originParaId). To activate this functionality, ensure that the `decodedXcmMsgs` parameter is set to true.
required: false
schema:
type: string
- name: useRcBlock
in: query
description: When set to `true`, it will use the latest relay chain block to determine the corresponding Asset Hub block. Only supported for Asset Hub endpoints with relay chain API available. Respects the `finalized` parameter when determining which relay chain block to use. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
- name: useEvmFormat
in: query
description: When set to `true`, every extrinsic's event emitted by pallet-revive will have the address data formatted to EVM.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BlockWithDecodedXcmMsgs'
- type: array
items:
$ref: '#/components/schemas/BlockWithDecodedXcmMsgs'
description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
/blocks/head/header:
get:
tags:
- blocks
summary: Get information about the header of the most recent finalized block.
description: Returns the most recently finalized block's header. When `useRcBlock` parameter is used, the response includes additional fields `rcBlockHash`, `rcBlockNumber`, and `ahTimestamp`.
operationId: getLatestBlockHeader
parameters:
- name: finalized
in: query
description: Boolean representing whether or not to get the finalized head. If it is not set the value defaults to true. When set to false it will attempt to get the newest known block, which may not be finalized.
required: false
schema:
type: boolean
default: true
- name: useRcBlock
in: query
description: When set to `true`, it will use the latest relay chain block to determine the corresponding Asset Hub block header. Only supported for Asset Hub endpoints with relay chain API available. Respects the `finalized` parameter when determining which relay chain block to use. When used, returns an array of response objects or empty array if no Asset Hub block found.
required: false
schema:
type: boolean
default: false
- name: useRcBlockFormat
in: query
description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
required: false
schema:
type: string
enum:
- array
- object
description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BlockHeader'
- type: array
items:
$ref: '#/components/schemas/BlockHeader'
description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty ar
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polkadot/refs/heads/main/openapi/polkadot-blocks-api-openapi.yml