RPCs - Reference¶
This page describes the RPCs specific to a particular version of the Tezos protocol (specified below).
Note
They are all served under the prefix /chains/<chain_id>/blocks/<block_id>/.
To make the RPC reference more readable, this prefix is not repeated every time below, but instead shortened as ../.
Warning
This list could be missing RPC endpoints. The OpenAPI
specification may be used to retrieve the
complete list of protocol RPCs and their associated schemas
(search the .json files that are linked from that page).
RPCs - Index¶
Note that the RPCs served under a given prefix can also be listed using the client, e.g.:
tezos-client rpc list /chains/main/blocks/head/context/constants
Any RPC endpoint may also be described, using the describe RPC to
retrieve all JSON and binary schemas, e.g.:
tezos-client rpc get /describe/chains/main/blocks/head/context/constants
Shell¶
The protocol-independent RPCs are described in this other page.
Protocol Kathmandu¶
../<block_id> (GET)
../<block_id>/context/big_maps/<big_map_id> (GET)
../<block_id>/context/big_maps/<big_map_id>/<script_expr> (GET)
../<block_id>/context/cache/contracts/all (GET)
../<block_id>/context/cache/contracts/rank (POST)
../<block_id>/context/cache/contracts/size (GET)
../<block_id>/context/cache/contracts/size_limit (GET)
../<block_id>/context/constants (GET)
../<block_id>/context/constants/errors (GET)
../<block_id>/context/contracts (GET)
../<block_id>/context/contracts/<contract_id> (GET)
../<block_id>/context/contracts/<contract_id>/balance (GET)
../<block_id>/context/contracts/<contract_id>/balance_and_frozen_bonds (GET)
../<block_id>/context/contracts/<contract_id>/big_map_get (POST)
../<block_id>/context/contracts/<contract_id>/counter (GET)
../<block_id>/context/contracts/<contract_id>/delegate (GET)
../<block_id>/context/contracts/<contract_id>/entrypoints (GET)
../<block_id>/context/contracts/<contract_id>/entrypoints/<entrypoint> (GET)
../<block_id>/context/contracts/<contract_id>/frozen_bonds (GET)
../<block_id>/context/contracts/<contract_id>/manager_key (GET)
../<block_id>/context/contracts/<contract_id>/script (GET)
../<block_id>/context/contracts/<contract_id>/single_sapling_get_diff (GET)
../<block_id>/context/contracts/<contract_id>/storage (GET)
../<block_id>/context/delegates (GET)
../<block_id>/context/delegates/<pkh> (GET)
../<block_id>/context/delegates/<pkh>/current_frozen_deposits (GET)
../<block_id>/context/delegates/<pkh>/deactivated (GET)
../<block_id>/context/delegates/<pkh>/delegated_balance (GET)
../<block_id>/context/delegates/<pkh>/delegated_contracts (GET)
../<block_id>/context/delegates/<pkh>/frozen_deposits (GET)
../<block_id>/context/delegates/<pkh>/frozen_deposits_limit (GET)
../<block_id>/context/delegates/<pkh>/full_balance (GET)
../<block_id>/context/delegates/<pkh>/grace_period (GET)
../<block_id>/context/delegates/<pkh>/participation (GET)
../<block_id>/context/delegates/<pkh>/staking_balance (GET)
../<block_id>/context/delegates/<pkh>/voting_info (GET)
../<block_id>/context/delegates/<pkh>/voting_power (GET)
../<block_id>/context/liquidity_baking/cpmm_address (GET)
../<block_id>/context/merkle_tree (GET)
../<block_id>/context/nonces/<block_level> (GET)
../<block_id>/context/raw/bytes (GET)
../<block_id>/context/raw/json (<dynamic>)
../<block_id>/context/sapling/<sapling_state_id>/get_diff (GET)
../<block_id>/context/seed (POST)
../<block_id>/context/seed_computation (GET)
../<block_id>/context/selected_snapshot (GET)
../<block_id>/context/tx_rollup/<tx_rollup_id>/commitment/<block_level> (GET)
../<block_id>/context/tx_rollup/<tx_rollup_id>/inbox/<block_level> (GET)
../<block_id>/context/tx_rollup/<tx_rollup_id>/pending_bonded_commitments/<pkh> (GET)
../<block_id>/context/tx_rollup/<tx_rollup_id>/state (GET)
../<block_id>/hash (GET)
../<block_id>/header (GET)
../<block_id>/header/protocol_data (GET)
../<block_id>/header/protocol_data/raw (GET)
../<block_id>/header/raw (GET)
../<block_id>/header/shell (GET)
../<block_id>/helpers/complete/<prefix> (GET)
../<block_id>/helpers/forge_block_header (POST)
../<block_id>/helpers/preapply/block (POST)
../<block_id>/helpers/preapply/operations (POST)
../<block_id>/live_blocks (GET)
../<block_id>/metadata (GET)
../<block_id>/metadata_hash (GET)
../<block_id>/operation_hashes (GET)
../<block_id>/operation_hashes/<list_offset> (GET)
../<block_id>/operation_hashes/<list_offset>/<operation_offset> (GET)
../<block_id>/operation_metadata_hashes (GET)
../<block_id>/operation_metadata_hashes/<list_offset> (GET)
../<block_id>/operation_metadata_hashes/<list_offset>/<operation_offset> (GET)
../<block_id>/operations (GET)
../<block_id>/operations/<list_offset> (GET)
../<block_id>/operations/<list_offset>/<operation_offset> (GET)
../<block_id>/operations_metadata_hash (GET)
../<block_id>/protocols (GET)
../<block_id>/votes/ballot_list (GET)
../<block_id>/votes/ballots (GET)
../<block_id>/votes/current_period (GET)
../<block_id>/votes/current_proposal (GET)
../<block_id>/votes/current_quorum (GET)
../<block_id>/votes/listings (GET)
../<block_id>/votes/proposals (GET)
../<block_id>/votes/successor_period (GET)
../<block_id>/votes/total_voting_power (GET)
RPCs - Full description¶
Protocol Kathmandu¶
Description
All the information about a block. The associated metadata may not be present depending on the history mode and block's distance from the head.
Optional query arguments:
- force_metadata : DEPRECATED: Forces to recompute the operations metadata if it was considered as too large.
- metadata = <metadata_rpc_arg> : Specifies whether or not if the operations metadata should be returned. To get the metadata, even if it is needed to recompute them, use "always". To avoid getting the metadata, use "never". By default, the metadata will be returned depending on the node's metadata size limit policy.
Description
Get the (optionally paginated) list of values in a big map. Order of values is unspecified, but is guaranteed to be consistent.
Optional query arguments:
- offset = <uint> : Skip the first [offset] values. Useful in combination with [length] for pagination.
- length = <uint> : Only retrieve [length] values. Useful in combination with [offset] for pagination.
Description
Access the value associated with a key in a big map.
Description
Return the list of cached contracts
Description
Return the number of cached contracts older than the provided contract
Description
Return the size of the contract cache
Description
Return the size limit of the contract cache
Description
All constants
Description
Schema for all the RPC errors from this protocol version
Description
All existing contracts (excluding empty implicit contracts).
Description
Access the complete status of a contract.
Optional query arguments:
- normalize_types : Whether types should be normalized (annotations removed, combs flattened) or kept as they appeared in the original script.
Description
Access the spendable balance of a contract, excluding frozen bonds.
Description
Access the sum of the spendable balance and frozen bonds of a contract. This sum is part of the contract's stake, and it is exactly the contract's stake if the contract is not a delegate.
Description
Access the value associated with a key in a big map of the contract (deprecated).
Description
Access the counter of a contract, if any.
Description
Access the delegate of a contract, if any.
Description
Return the list of entrypoints of the contract
Optional query arguments:
- normalize_types : Whether types should be normalized (annotations removed, combs flattened) or kept as they appeared in the original script.
Description
Return the type of the given entrypoint of the contract
Optional query arguments:
- normalize_types : Whether types should be normalized (annotations removed, combs flattened) or kept as they appeared in the original script.
Description
Access the frozen bonds of a contract.
Description
Access the manager of an implicit contract.
Description
Access the code and data of the contract.
Description
Returns the root and a diff of a state starting from an optional offset which is zero by default.
Optional query arguments:
- offset_commitment = <uint63> : Commitments and ciphertexts are returned from the specified offset up to the most recent.
- offset_nullifier = <uint63> : Nullifiers are returned from the specified offset up to the most recent.
Description
Access the data of the contract.
Description
Lists all registered delegates by default. The arguments `active`, `inactive`, `with_minimal_stake`, and `without_minimal_stake` allow to enumerate only the delegates that are active, inactive, have at least a minimal stake to participate in consensus and in governance, or do not have such a minimal stake, respectively. Note, setting these arguments to false has no effect.
Optional query arguments:
- active
- inactive
- with_minimal_stake
- without_minimal_stake
Description
Everything about a delegate.
Description
Returns the current amount of the frozen deposits (in mutez).
Description
Tells whether the delegate is currently tagged as deactivated or not.
Description
Returns the sum (in mutez) of all balances of all the contracts that delegate to a given delegate. This excludes the delegate's own balance, its frozen deposits and its frozen bonds.
Description
Returns the list of contracts that delegate to a given delegate.
Description
Returns the initial amount (that is, at the beginning of a cycle) of the frozen deposits (in mutez). This amount is the same as the current amount of the frozen deposits, unless the delegate has been punished.
Description
Returns the frozen deposits limit for the given delegate or none if no limit is set.
Description
Returns the full balance (in mutez) of a given delegate, including the frozen deposits and the frozen bonds. It does not include its delegated balance.
Description
Returns the cycle by the end of which the delegate might be deactivated if she fails to execute any delegate action. A deactivated delegate might be reactivated (without loosing any stake) by simply re-registering as a delegate. For deactivated delegates, this value contains the cycle at which they were deactivated.
Description
Returns cycle and level participation information. In particular this indicates, in the field 'expected_cycle_activity', the number of slots the delegate is expected to have in the cycle based on its active stake. The field 'minimal_cycle_activity' indicates the minimal endorsing slots in the cycle required to get endorsing rewards. It is computed based on 'expected_cycle_activity. The fields 'missed_slots' and 'missed_levels' indicate the number of missed endorsing slots and missed levels (for endorsing) in the cycle so far. 'missed_slots' indicates the number of missed endorsing slots in the cycle so far. The field 'remaining_allowed_missed_slots' indicates the remaining amount of endorsing slots that can be missed in the cycle before forfeiting the rewards. Finally, 'expected_endorsing_rewards' indicates the endorsing rewards that will be distributed at the end of the cycle if activity at that point will be greater than the minimal required; if the activity is already known to be below the required minimum, then the rewards are zero.
Description
Returns the total amount of tokens (in mutez) delegated to a given delegate. This includes the balances of all the contracts that delegate to it, but also the balance of the delegate itself, its frozen deposits, and its frozen bonds.
Description
Returns the delegate info (e.g. voting power) found in the listings of the current voting period.
Description
The voting power in the vote listings for a given delegate.
Description
Liquidity baking CPMM address
Description
Returns the merkle tree of a piece of context.
Optional query arguments:
- holey = <bool> : Send only hashes, omit data of key
Description
Info about the nonce of a previous block.
Description
Returns the raw context.
Optional query arguments:
- depth = <uint>
Description
Returns the root and a diff of a state starting from an optional offset which is zero by default.
Optional query arguments:
- offset_commitment = <uint63> : Commitments and ciphertexts are returned from the specified offset up to the most recent.
- offset_nullifier = <uint63> : Nullifiers are returned from the specified offset up to the most recent.
Description
Seed of the cycle to which the block belongs.
Description
Seed computation status
Description
Returns the index of the selected snapshot for the current cycle or for the specific `cycle` passed as argument, if any.
Optional query arguments:
- cycle = <block_cycle>
Description
Return the commitment for a level, if any
Description
Get the inbox of a transaction rollup
Description
Get the number of pending bonded commitments for a pkh on a rollup
Description
Access the state of a rollup.
Description
The block's hash, its unique identifier.
Description
The whole block header.
Description
The version-specific fragment of the block header.
Description
The version-specific fragment of the block header (unparsed).
Description
The whole block header (unparsed).
Description
The shell-specific fragment of the block header.
Description
Try to complete a prefix of a Base58Check-encoded data. This RPC is actually able to complete hashes of block, operations, public_keys and contracts.
Description
Forge a block header
Description
Simulate the validation of a block that would contain the given operations and return the resulting fitness and context hash.
Optional query arguments:
- sort
- timestamp = <date>
Description
Simulate the application of the operations with the context of the given block and return the result of each operation application.
Description
List the ancestors of the given block which, if referred to as the branch in an operation header, are recent enough for that operation to be included in the current block.
Description
All the metadata associated to the block.
Description
Hash of the metadata associated to the block. This is only set on blocks starting from environment V1.
Description
The hashes of all the operations included in the block.
Description
All the operations included in `n-th` validation pass of the block.
Description
The hash of then `m-th` operation in the `n-th` validation pass of the block.
Description
The hashes of all the operation metadata included in the block. This is only set on blocks starting from environment V1.
Description
All the operation metadata included in `n-th` validation pass of the block. This is only set on blocks starting from environment V1.
Description
The hash of then `m-th` operation metadata in the `n-th` validation pass of the block. This is only set on blocks starting from environment V1.
Description
All the operations included in the block.
Optional query arguments:
- force_metadata : DEPRECATED: Forces to recompute the operations metadata if it was considered as too large.
- metadata = <metadata_rpc_arg> : Specifies whether or not if the operations metadata should be returned. To get the metadata, even if it is needed to recompute them, use "always". To avoid getting the metadata, use "never". By default, the metadata will be returned depending on the node's metadata size limit policy.
Description
All the operations included in `n-th` validation pass of the block.
Optional query arguments:
- force_metadata : DEPRECATED: Forces to recompute the operations metadata if it was considered as too large.
- metadata = <metadata_rpc_arg> : Specifies whether or not if the operations metadata should be returned. To get the metadata, even if it is needed to recompute them, use "always". To avoid getting the metadata, use "never". By default, the metadata will be returned depending on the node's metadata size limit policy.
Description
The `m-th` operation in the `n-th` validation pass of the block.
Optional query arguments:
- force_metadata : DEPRECATED: Forces to recompute the operations metadata if it was considered as too large.
- metadata = <metadata_rpc_arg> : Specifies whether or not if the operations metadata should be returned. To get the metadata, even if it is needed to recompute them, use "always". To avoid getting the metadata, use "never". By default, the metadata will be returned depending on the node's metadata size limit policy.
Description
The root hash of the operations metadata from the block. This is only set on blocks starting from environment V1.
Description
Current and next protocol.
Description
Ballots casted so far during a voting period.
Description
Sum of ballots casted so far during a voting period.
Description
Returns the voting period (index, kind, starting position) and related information (position, remaining) of the interrogated block.
Description
Current proposal under evaluation.
Description
Current expected quorum.
Description
List of delegates with their voting power.
Description
List of proposals with number of supporters.
Description
Returns the voting period (index, kind, starting position) and related information (position, remaining) of the next block.Useful to craft operations that will be valid in the next block.
Description
Total voting power in the voting listings.