Tezos Blocks API
The Blocks API from Tezos — 7 operation(s) for blocks.
OpenAPI Specification
openapi: 3.0.0
info:
title: TzKT Accounts Blocks API
description: "# Introduction\r\n\r\nTzKT is the most widely used tool in Tezos that provides you with convenient and flexible access to the Tezos blockchain data, processed and indexed by its own indexer. \r\nYou can fetch all historical data via REST API, or subscribe for real-time data via WebSocket API. TzKT was built by the joint efforts of the entire Tezos community \r\nto help developers build more services and dapps on top of Tezos.\r\n\r\nTzKT Indexer and API are [open-source](https://github.com/baking-bad/tzkt), so don't be afraid to depend on the third-party service,\r\nbecause you can always clone, build and run it yourself to have full control over all the components.\r\n\r\nFeel free to contact us if you have any questions or feature requests.\r\nYour feedback is much appreciated!\r\n\r\n- Discord: https://discord.gg/aG8XKuwsQd\r\n- Telegram: https://t.me/baking_bad_chat\r\n- X: https://x.com/TezosBakingBad\r\n- Email: hello@bakingbad.dev\r\n\r\nAnd don't forget to star TzKT [on GitHub](https://github.com/baking-bad/tzkt) if you like it \U0001F60A\r\n\r\n# Get Started\r\n\r\nThere are two API services provided for public use:\r\n- **Free TzKT API** with free anonymous access;\r\n- **TzKT Pro** with paid subscriptions with increased rate limits, off-chain data, extended support and business-level SLA.\r\n\r\nYou can find more details about differences between available tiers [here](https://tzkt.io/api).\r\n\r\n## Free TzKT API\r\n\r\nFree-tier TzKT API is the best way to get started and explore available Tezos data and API functionality.\r\nIt doesn't require authorization and is free for everyone and for both commercial and non-commercial use.\r\n\r\n> #### Note: attribution required\r\nIf you use free-tier TzKT API, you **must** mention it on your website or application by placing the label\r\n\"Powered by TzKT API\", or \"Built with TzKT API\", or \"Data provided by TzKT API\" with a direct link to [tzkt.io](https://tzkt.io).\r\n\r\nIt's available for the following Tezos networks with the following base URLs:\r\n\r\n- Mainnet: `https://api.tzkt.io/` or `https://api.mainnet.tzkt.io/` ([view docs](https://api.tzkt.io))\r\n- Ghostnet: `https://api.ghostnet.tzkt.io/` ([view docs](https://api.ghostnet.tzkt.io))\r\n- Shadownet: `https://api.shadownet.tzkt.io/` ([view docs](https://api.shadownet.tzkt.io))\r\n- Seoulnet: `https://api.seoulnet.tzkt.io/` ([view docs](https://api.seoulnet.tzkt.io))\r\n- Tallinnnet: `https://api.tallinnnet.tzkt.io/` ([view docs](https://api.tallinnnet.tzkt.io))\r\n\r\n### Sending Requests\r\n\r\nTo send a request to Free TzKT API you need literally nothing. Just take the base URL of the particular network\r\n(for example, Tezos mainnet: `https://api.tzkt.io`) and append the path of the particular endpoint\r\n(for example, chain's head: `/v1/head`), that's pretty much it: \r\n\r\n```bash\r\ncurl https://api.tzkt.io/v1/head\r\n```\r\n\r\nRead through this documentation to explore available endpoints, query parameters\r\n(note, if you click on a query parameter, you will see available modes, such as `.eq`, `.in`, etc.)\r\nand response models. If you have any questions, do not hesitate to ask for support, Tezos community has always been very friendly! \U0001F609\r\n\r\n### Rate Limits\r\n\r\nPlease, refer to https://tzkt.io/api to check relevant rate limits.\r\n\r\nIf you exceed the limit, the API will respond with `HTTP 429` status code.\r\n\r\n## TzKT Pro\r\n\r\nTzKT Pro is intended for professional use, for those who seek for extended capabilities, performance, reliability and business-level SLA.\r\nTzKT Pro service is provided via paid subscriptions. Please, refer to [Pricing Plans](https://tzkt.io/api) to check available tiers.\r\n\r\nIt's available for the following Tezos networks with the following base URLs:\r\n\r\n- Mainnet: `https://pro.tzkt.io/` ([view docs](https://api.tzkt.io))\r\n- Testnets: *let us know if you need TzKT Pro for testnets*\r\n\r\n### Authorization\r\n\r\nTo access TzKT Pro you will need to authorize requests with your personal API key, that you will receive on your email after purchasing a subscription.\r\nThis can be done by adding the query string parameter `?apikey={your_key}` or by adding the HTTP header `apikey: {your_key}`.\r\n\r\nNote that you can have multiple API keys within a single subscription.\r\n\r\nKeep your API keys private, do not publish it anywhere and do not hardcode it, especially in public repositories.\r\nIf your key was compromised, just let us know and we will issue a new one.\r\n\r\nAlso note that passing the API key via HTTP headers is more secure, because in HTTPS headers are encrypted,\r\nbut query string is not, so the key can be unintentionally exposed to third parties.\r\n\r\n### Sending Requests\r\n\r\nSending a request with the API key passed as a query string parameter:\r\n\r\n```bash\r\ncurl https://pro.tzkt.io/v1/head?apikey={your_key}\r\n```\r\n\r\nSending a request with the API key passed via an HTTP header:\r\n\r\n```bash\r\ncurl https://pro.tzkt.io/v1/head \\\r\n -H 'apikey: {your_key}'\r\n```\r\n\r\n### Rate Limits\r\n\r\nPlease, refer to https://tzkt.io/api to check relevant rate limits for different pricing plans.\r\n\r\nAlso, TzKT Pro provides you with the additional HTTP headers to show the allowed limits, number of available requests\r\nand the time remaining (in seconds) until the quota is reset. Here's an example:\r\n\r\n```\r\nRateLimit-Limit: 50\r\nRateLimit-Remaining: 49\r\nRateLimit-Reset: 1\r\n```\r\n\r\nIt also sends general information about your rate limits per second and per day:\r\n\r\n```\r\nX-RateLimit-Limit-Second: 50\r\nX-RateLimit-Remaining-Second: 49\r\nX-RateLimit-Limit-Day: 3000000\r\nX-RateLimit-Remaining-Day: 2994953\r\n```\r\n\r\nIf you exceed the limit, the API will respond with `HTTP 429` status code.\r\n"
contact:
name: Baking Bad Team
url: https://bakingbad.dev
email: hello@bakingbad.dev
version: 1.17.1
x-logo:
url: https://tzkt.io/logo.png
href: https://tzkt.io/
servers:
- url: https://api.tzkt.io
tags:
- name: Blocks
paths:
/v1/blocks/count:
get:
tags:
- Blocks
summary: Get blocks count
description: Returns the total number of blocks.
operationId: Blocks_GetCount
responses:
'200':
description: ''
content:
application/json:
schema:
type: integer
format: int32
/v1/blocks:
get:
tags:
- Blocks
summary: Get blocks
description: Returns a list of blocks.
operationId: Blocks_Get
parameters:
- name: anyof
in: query
description: 'Filters by any of the specified fields. Example: `anyof.proposer.producer=tz1...`.'
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/AnyOfParameter'
x-position: 1
x-tzkt-extension: anyof-parameter
x-tzkt-anyof-parameter: proposer,producer
- name: proposer
in: query
description: 'Filters blocks by block proposer. Allowed fields for `.eqx` mode: none.'
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/AccountParameter'
x-position: 2
x-tzkt-extension: query-parameter
- name: producer
in: query
description: 'Filters blocks by block producer. Allowed fields for `.eqx` mode: none.'
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/AccountParameter'
x-position: 3
x-tzkt-extension: query-parameter
- name: level
in: query
description: Filters blocks by level.
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/Int32Parameter'
x-position: 4
x-tzkt-extension: query-parameter
- name: timestamp
in: query
description: Filters blocks by timestamp.
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/DateTimeParameter'
x-position: 5
x-tzkt-extension: query-parameter
- name: blockRound
in: query
description: Filters blocks by block round.
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/Int32Parameter'
x-position: 6
x-tzkt-extension: query-parameter
- name: select
in: query
description: Specify comma-separated list of fields to include into response or leave it undefined to return full object. If you select single field, response will be an array of values in both `.fields` and `.values` modes.
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/SelectParameter'
x-position: 7
x-tzkt-extension: query-parameter
- name: sort
in: query
description: 'Sorts blocks by specified field. Supported fields: `id` (default), `level`, `payloadRound`, `blockRound`, `attestationPower`, `reward`, `bonus`, `fees`.'
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/SortParameter'
x-position: 8
x-tzkt-extension: query-parameter
- name: offset
in: query
description: Specifies which or how many items should be skipped
schema:
nullable: true
oneOf:
- $ref: '#/components/schemas/OffsetParameter'
x-position: 9
x-tzkt-extension: query-parameter
- name: limit
in: query
description: Maximum number of items to return
schema:
type: integer
format: int32
default: 100
maximum: 10000.0
minimum: 0.0
x-position: 10
- name: quote
in: query
description: Comma-separated list of ticker symbols to inject historical prices into response
schema:
default: None
oneOf:
- $ref: '#/components/schemas/Symbols'
x-position: 11
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Block'
/v1/blocks/{hash}:
get:
tags:
- Blocks
summary: Get block by hash
description: Returns a block with the specified hash.
operationId: Blocks_GetByHash
parameters:
- name: hash
in: path
required: true
description: Block hash
schema:
type: string
x-position: 1
- name: operations
in: query
description: Flag indicating whether to include block operations into returned object or not
schema:
type: boolean
default: false
x-position: 2
- name: micheline
in: query
description: 'Format of the parameters, storage and diffs: `0` - JSON, `1` - JSON string, `2` - raw micheline, `3` - raw micheline string'
schema:
default: Json
oneOf:
- $ref: '#/components/schemas/MichelineFormat'
x-position: 3
- name: quote
in: query
description: Comma-separated list of ticker symbols to inject historical prices into response
schema:
default: None
oneOf:
- $ref: '#/components/schemas/Symbols'
x-position: 4
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Block'
/v1/blocks/{level}:
get:
tags:
- Blocks
summary: Get block by level
description: Returns a block at the specified level.
operationId: Blocks_GetByLevel
parameters:
- name: level
in: path
required: true
description: Block level
schema:
type: integer
format: int32
x-position: 1
- name: operations
in: query
description: Flag indicating whether to include block operations into returned object or not
schema:
type: boolean
default: false
x-position: 2
- name: micheline
in: query
description: 'Format of the parameters, storage and diffs: `0` - JSON, `1` - JSON string, `2` - raw micheline, `3` - raw micheline string'
schema:
default: Json
oneOf:
- $ref: '#/components/schemas/MichelineFormat'
x-position: 3
- name: quote
in: query
description: Comma-separated list of ticker symbols to inject historical prices into response
schema:
default: None
oneOf:
- $ref: '#/components/schemas/Symbols'
x-position: 4
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Block'
/v1/blocks/{level}/timestamp:
get:
tags:
- Blocks
summary: Get timestamp by level
description: Returns a timestamp of the block at the specified level.
operationId: Blocks_GetByLevel2
parameters:
- name: level
in: path
required: true
description: Block level
schema:
type: integer
format: int32
x-position: 1
responses:
'200':
description: ''
content:
application/json:
schema:
type: string
format: date-time
/v1/blocks/{timestamp}:
get:
tags:
- Blocks
summary: Get block by timestamp
description: Returns a block closest to the specified timestamp.
operationId: Blocks_GetByDate
parameters:
- name: timestamp
in: path
required: true
description: Timestamp, e.g. `2020-01-01T00:00:00Z`
schema:
type: string
format: date-time
x-position: 1
- name: operations
in: query
description: Flag indicating whether to include block operations into returned object or not
schema:
type: boolean
default: false
x-position: 2
- name: micheline
in: query
description: 'Format of the parameters, storage and diffs: `0` - JSON, `1` - JSON string, `2` - raw micheline, `3` - raw micheline string'
schema:
default: Json
oneOf:
- $ref: '#/components/schemas/MichelineFormat'
x-position: 3
- name: quote
in: query
description: Comma-separated list of ticker symbols to inject historical prices into response
schema:
default: None
oneOf:
- $ref: '#/components/schemas/Symbols'
x-position: 4
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Block'
/v1/blocks/{timestamp}/level:
get:
tags:
- Blocks
summary: Get level by timestamp
description: Returns a level of the block closest to the specified timestamp.
operationId: Blocks_GetByDate2
parameters:
- name: timestamp
in: path
required: true
description: Timestamp, e.g. `2020-01-01T00:00:00Z`
schema:
type: string
format: date-time
x-position: 1
responses:
'200':
description: ''
content:
application/json:
schema:
type: integer
format: int32
components:
schemas:
TxRollupOriginationOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `tx_rollup_origination`
id:
type: integer
description: Unique ID of the operation, stored in the TzKT indexer database
format: int64
level:
type: integer
description: The height of the block from the genesis block, in which the operation was included
format: int32
timestamp:
type: string
description: Datetime of the block, in which the operation was included (ISO 8601, e.g. `2020-02-20T02:40:57Z`)
format: date-time
block:
type: string
description: Hash of the block, in which the operation was included
hash:
type: string
description: Hash of the operation
sender:
description: Information about the account who has sent the operation
oneOf:
- $ref: '#/components/schemas/Alias'
counter:
type: integer
description: An account nonce which is used to prevent operation replay
format: int32
gasLimit:
type: integer
description: A cap on the amount of gas a given operation can consume
format: int32
gasUsed:
type: integer
description: Amount of gas, consumed by the operation
format: int32
storageLimit:
type: integer
description: A cap on the amount of storage a given operation can consume
format: int32
bakerFee:
type: integer
description: Fee to the baker, produced block, in which the operation was included (micro tez)
format: int64
allocationFee:
type: integer
description: The amount of funds burned from the sender account for account creation (micro tez)
format: int64
rollup:
description: Information about the rollup to which the operation was sent
nullable: true
oneOf:
- $ref: '#/components/schemas/Alias'
status:
type: string
description: 'Operation status (`applied` - an operation applied by the node and successfully added to the blockchain,
`failed` - an operation which failed with some particular error (not enough balance, gas limit, etc),
`backtracked` - an operation which was successful but reverted due to one of the following operations in the same operation group was failed,
`skipped` - all operations after the failed one in an operation group)'
errors:
type: array
description: List of errors provided by the node, injected the operation to the blockchain. `null` if there is no errors
nullable: true
items:
$ref: '#/components/schemas/OperationError'
quote:
description: Injected historical quote at the time of operation
nullable: true
oneOf:
- $ref: '#/components/schemas/QuoteShort'
SortParameter:
type: object
additionalProperties: false
properties:
asc:
type: string
description: '**Ascending** sort mode (optional, i.e. `sort.asc=id` is the same as `sort=id`). \
Specify a field name to sort by.
Example: `?sort=balance`.'
nullable: true
desc:
type: string
description: '**Descending** sort mode. \
Specify a field name to sort by descending.
Example: `?sort.desc=id`.'
nullable: true
x-tzkt-extension: query-parameter
SmartRollupExecuteOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `sr_execute`
id:
type: integer
description: "Unique ID of the operation, stored in the TzKT indexer database \n**[sortable]**"
format: int64
level:
type: integer
description: The height of the block from the genesis block, in which the operation was included
format: int32
timestamp:
type: string
description: Datetime of the block, in which the operation was included (ISO 8601, e.g. `2020-02-20T02:40:57Z`)
format: date-time
hash:
type: string
description: Hash of the operation
sender:
description: Information about the account who has sent the operation
oneOf:
- $ref: '#/components/schemas/Alias'
counter:
type: integer
description: An account nonce which is used to prevent operation replay
format: int32
gasLimit:
type: integer
description: A cap on the amount of gas a given operation can consume
format: int32
gasUsed:
type: integer
description: Amount of gas, consumed by the operation
format: int32
storageLimit:
type: integer
description: A cap on the amount of storage a given operation can consume
format: int32
storageUsed:
type: integer
description: Amount of storage, consumed by the operation
format: int32
bakerFee:
type: integer
description: Fee to the baker, produced block, in which the operation was included (micro tez)
format: int64
storageFee:
type: integer
description: The amount of funds burned from the sender account for used the blockchain storage (micro tez)
format: int64
status:
type: string
description: 'Operation status (`applied` - an operation applied by the node and successfully added to the blockchain,
`failed` - an operation which failed with some particular error (not enough balance, gas limit, etc),
`backtracked` - an operation which was successful but reverted due to one of the following operations in the same operation group was failed,
`skipped` - all operations after the failed one in an operation group)'
rollup:
description: Smart rollup to which the operation was sent
nullable: true
oneOf:
- $ref: '#/components/schemas/Alias'
commitment:
description: Executed commitment
nullable: true
oneOf:
- $ref: '#/components/schemas/SrCommitmentInfo'
errors:
type: array
description: List of errors provided by the node, injected the operation to the blockchain. `null` if there is no errors
nullable: true
items:
$ref: '#/components/schemas/OperationError'
ticketTransfersCount:
type: integer
description: Number of ticket transfers produced by the operation, or `null` if there are no transfers
format: int32
nullable: true
quote:
description: Injected historical quote at the time of operation
nullable: true
oneOf:
- $ref: '#/components/schemas/QuoteShort'
SetDelegateParametersOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `set_delegate_parameters`
id:
type: integer
description: "Internal TzKT ID. \n**[sortable]**"
format: int64
level:
type: integer
description: Height of the block from the genesis
format: int32
timestamp:
type: string
description: Datetime at which the block is claimed to have been created (ISO 8601, e.g. `2020-02-20T02:40:57Z`)
format: date-time
hash:
type: string
description: Hash of the operation
sender:
description: Information about the account who has sent the operation
oneOf:
- $ref: '#/components/schemas/Alias'
counter:
type: integer
description: An account nonce which is used to prevent operation replay
format: int32
gasLimit:
type: integer
description: A cap on the amount of gas a given operation can consume
format: int32
gasUsed:
type: integer
description: Amount of gas, consumed by the operation
format: int32
storageLimit:
type: integer
description: A cap on the amount of storage a given operation can consume
format: int32
bakerFee:
type: integer
description: Fee to the baker, produced block, in which the operation was included (micro tez)
format: int64
limitOfStakingOverBaking:
type: integer
description: This parameter determines the maximum portion (millionth) of external stake by stakers over the baker's own staked funds
format: int64
nullable: true
edgeOfBakingOverStaking:
type: integer
description: This parameter determines the fraction (billionth) of the rewards that accrue to the delegate’s frozen deposit – the remainder is shared among its stakers
format: int64
nullable: true
activationCycle:
type: integer
description: Cycle from which the specified staking parameters are activated
format: int32
nullable: true
status:
type: string
description: 'Operation status (`applied` - an operation applied by the node and successfully added to the blockchain,
`failed` - an operation which failed with some particular error (not enough balance, gas limit, etc),
`backtracked` - an operation which was successful but reverted due to one of the following operations in the same operation group was failed,
`skipped` - all operations after the failed one in an operation group)'
errors:
type: array
description: List of errors provided by the node, injected the operation to the blockchain. `null` if there is no errors
nullable: true
items:
$ref: '#/components/schemas/OperationError'
quote:
description: Injected historical quote at the time of operation
nullable: true
oneOf:
- $ref: '#/components/schemas/QuoteShort'
BallotOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `ballot` - is used to vote for a proposal in a given voting cycle
id:
type: integer
description: Unique ID of the operation, stored in the TzKT indexer database
format: int64
level:
type: integer
description: The height of the block from the genesis block, in which the operation was included
format: int32
timestamp:
type: string
description: Datetime of the block, in which the operation was included (ISO 8601, e.g. `2020-02-20T02:40:57Z`)
format: date-time
block:
type: string
description: Hash of the block, in which the operation was included
hash:
type: string
description: Hash of the operation
period:
description: Information about the voting period for which the ballot was submitted
oneOf:
- $ref: '#/components/schemas/PeriodInfo'
proposal:
description: Information about the proposal for which ballot was submitted
oneOf:
- $ref: '#/components/schemas/ProposalAlias'
delegate:
description: Information about the delegate (baker), submitted the ballot
oneOf:
- $ref: '#/components/schemas/Alias'
votingPower:
type: integer
description: Baker's voting power
format: int64
vote:
type: string
description: Vote, given in the ballot (`yay`, `nay`, or `pass`)
quote:
description: Injected historical quote at the time of operation
nullable: true
oneOf:
- $ref: '#/components/schemas/QuoteShort'
SmartRollupPublishOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `sr_publish`
id:
type: integer
description: "Unique ID of the operation, stored in the TzKT indexer database \n**[sortable]**"
format: int64
level:
type: integer
description: The height of the block from the genesis block, in which the operation was included
format: int32
timestamp:
type: string
description: Datetime of the block, in which the operation was included (ISO 8601, e.g. `2020-02-20T02:40:57Z`)
format: date-time
hash:
type: string
description: Hash of the operation
sender:
description: Information about the account who has sent the operation
oneOf:
- $ref: '#/components/schemas/Alias'
counter:
type: integer
description: An account nonce which is used to prevent operation replay
format: int32
gasLimit:
type: integer
description: A cap on the amount of gas a given operation can consume
format: int32
gasUsed:
type: integer
description: Amount of gas, consumed by the operation
format: int32
storageLimit:
type: integer
description: A cap on the amount of storage a given operation can consume
format: int32
bakerFee:
type: integer
description: Fee to the baker, produced block, in which the operation was included (micro tez)
format: int64
status:
type: string
description: 'Operation status (`applied` - an operation applied by the node and successfully added to the blockchain,
`failed` - an operation which failed with some particular error (not enough balance, gas limit, etc),
`backtracked` - an operation which was successful but reverted due to one of the following operations in the same operation group was failed,
`skipped` - all operations after the failed one in an operation group)'
rollup:
description: Smart rollup to which the operation was sent
nullable: true
oneOf:
- $ref: '#/components/schemas/Alias'
commitment:
description: Published commitment
nullable: true
oneOf:
- $ref: '#/components/schemas/SrCommitmentInfo'
bond:
type: integer
description: Amount of bonds locked (micro tez)
format: int64
errors:
type: array
description: List of errors provided by the node, injected the operation to the blockchain. `null` if there is no errors
nullable: true
items:
$ref: '#/components/schemas/OperationError'
quote:
description: Injected historical quote at the time of operation
nullable: true
oneOf:
- $ref: '#/components/schemas/QuoteShort'
TxRollupRejectionOperation:
allOf:
- type: object
additionalProperties: false
properties:
type:
type: string
description: Type of the operation, `tx_rollup_rejection`
id:
type: integer
description: Unique ID of the operation, stored in the TzKT indexer database
format: int64
level:
type: in
# --- truncated at 32 KB (187 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tezos/refs/heads/main/openapi/tezos-blocks-api-openapi.yml