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


GET
../<block_id>?[force_metadata]&[metadata=<metadata_rpc_arg>]
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.

GET
../<block_id>/context/big_maps/<big_map_id>?[offset=<uint>]&[length=<uint>]
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.

GET
../<block_id>/context/big_maps/<big_map_id>/<script_expr>
Description

Access the value associated with a key in a big map.


GET
../<block_id>/context/cache/contracts/all
Description

Return the list of cached contracts


POST
../<block_id>/context/cache/contracts/rank
Description

Return the number of cached contracts older than the provided contract


GET
../<block_id>/context/cache/contracts/size
Description

Return the size of the contract cache


GET
../<block_id>/context/cache/contracts/size_limit
Description

Return the size limit of the contract cache


GET
../<block_id>/context/constants
Description

All constants


GET
../<block_id>/context/constants/errors
Description

Schema for all the RPC errors from this protocol version


GET
../<block_id>/context/contracts
Description

All existing contracts (excluding empty implicit contracts).


GET
../<block_id>/context/contracts/<contract_id>?[normalize_types]
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.

GET
../<block_id>/context/contracts/<contract_id>/balance
Description

Access the spendable balance of a contract, excluding frozen bonds.


GET
../<block_id>/context/contracts/<contract_id>/balance_and_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.


POST
../<block_id>/context/contracts/<contract_id>/big_map_get
Description

Access the value associated with a key in a big map of the contract (deprecated).


GET
../<block_id>/context/contracts/<contract_id>/counter
Description

Access the counter of a contract, if any.


GET
../<block_id>/context/contracts/<contract_id>/delegate
Description

Access the delegate of a contract, if any.


GET
../<block_id>/context/contracts/<contract_id>/entrypoints?[normalize_types]
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.

GET
../<block_id>/context/contracts/<contract_id>/entrypoints/<entrypoint>?[normalize_types]
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.

GET
../<block_id>/context/contracts/<contract_id>/frozen_bonds
Description

Access the frozen bonds of a contract.


GET
../<block_id>/context/contracts/<contract_id>/manager_key
Description

Access the manager of an implicit contract.


GET
../<block_id>/context/contracts/<contract_id>/script
Description

Access the code and data of the contract.


GET
../<block_id>/context/contracts/<contract_id>/single_sapling_get_diff?[offset_commitment=<uint63>]&[offset_nullifier=<uint63>]
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.

GET
../<block_id>/context/contracts/<contract_id>/storage
Description

Access the data of the contract.


GET
../<block_id>/context/delegates?[active]&[inactive]&[with_minimal_stake]&[without_minimal_stake]
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

GET
../<block_id>/context/delegates/<pkh>
Description

Everything about a delegate.


GET
../<block_id>/context/delegates/<pkh>/current_frozen_deposits
Description

Returns the current amount of the frozen deposits (in mutez).


GET
../<block_id>/context/delegates/<pkh>/deactivated
Description

Tells whether the delegate is currently tagged as deactivated or not.


GET
../<block_id>/context/delegates/<pkh>/delegated_balance
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.


GET
../<block_id>/context/delegates/<pkh>/delegated_contracts
Description

Returns the list of contracts that delegate to a given delegate.


GET
../<block_id>/context/delegates/<pkh>/frozen_deposits
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.


GET
../<block_id>/context/delegates/<pkh>/frozen_deposits_limit
Description

Returns the frozen deposits limit for the given delegate or none if no limit is set.


GET
../<block_id>/context/delegates/<pkh>/full_balance
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.


GET
../<block_id>/context/delegates/<pkh>/grace_period
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.


GET
../<block_id>/context/delegates/<pkh>/participation
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.


GET
../<block_id>/context/delegates/<pkh>/staking_balance
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.


GET
../<block_id>/context/delegates/<pkh>/voting_info
Description

Returns the delegate info (e.g. voting power) found in the listings of the current voting period.


GET
../<block_id>/context/delegates/<pkh>/voting_power
Description

The voting power in the vote listings for a given delegate.


GET
../<block_id>/context/liquidity_baking/cpmm_address
Description

Liquidity baking CPMM address


GET
../<block_id>/context/merkle_tree(/<context_path>)*?[holey=<bool>]
Description

Returns the merkle tree of a piece of context.

Optional query arguments:
  • holey = <bool> : Send only hashes, omit data of key

GET
../<block_id>/context/nonces/<block_level>
Description

Info about the nonce of a previous block.


GET
../<block_id>/context/raw/bytes(/<context_path>)*?[depth=<uint>]
Description

Returns the raw context.

Optional query arguments:
  • depth = <uint>

GET
../<block_id>/context/sapling/<sapling_state_id>/get_diff?[offset_commitment=<uint63>]&[offset_nullifier=<uint63>]
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.

POST
../<block_id>/context/seed
Description

Seed of the cycle to which the block belongs.


GET
../<block_id>/context/seed_computation
Description

Seed computation status


GET
../<block_id>/context/selected_snapshot?[cycle=<block_cycle>]
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>

GET
../<block_id>/context/tx_rollup/<tx_rollup_id>/commitment/<block_level>
Description

Return the commitment for a level, if any


GET
../<block_id>/context/tx_rollup/<tx_rollup_id>/inbox/<block_level>
Description

Get the inbox of a transaction rollup


GET
../<block_id>/context/tx_rollup/<tx_rollup_id>/pending_bonded_commitments/<pkh>
Description

Get the number of pending bonded commitments for a pkh on a rollup


GET
../<block_id>/context/tx_rollup/<tx_rollup_id>/state
Description

Access the state of a rollup.


GET
../<block_id>/hash
Description

The block's hash, its unique identifier.


GET
../<block_id>/header
Description

The whole block header.


GET
../<block_id>/header/protocol_data
Description

The version-specific fragment of the block header.


GET
../<block_id>/header/protocol_data/raw
Description

The version-specific fragment of the block header (unparsed).


GET
../<block_id>/header/raw
Description

The whole block header (unparsed).


GET
../<block_id>/header/shell
Description

The shell-specific fragment of the block header.


GET
../<block_id>/helpers/complete/<prefix>
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.


POST
../<block_id>/helpers/forge_block_header
Description

Forge a block header


POST
../<block_id>/helpers/preapply/block?[sort]&[timestamp=<date>]
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>

POST
../<block_id>/helpers/preapply/operations
Description

Simulate the application of the operations with the context of the given block and return the result of each operation application.


GET
../<block_id>/live_blocks
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.


GET
../<block_id>/metadata
Description

All the metadata associated to the block.


GET
../<block_id>/metadata_hash
Description

Hash of the metadata associated to the block. This is only set on blocks starting from environment V1.


GET
../<block_id>/operation_hashes
Description

The hashes of all the operations included in the block.


GET
../<block_id>/operation_hashes/<list_offset>
Description

All the operations included in `n-th` validation pass of the block.


GET
../<block_id>/operation_hashes/<list_offset>/<operation_offset>
Description

The hash of then `m-th` operation in the `n-th` validation pass of the block.


GET
../<block_id>/operation_metadata_hashes
Description

The hashes of all the operation metadata included in the block. This is only set on blocks starting from environment V1.


GET
../<block_id>/operation_metadata_hashes/<list_offset>
Description

All the operation metadata included in `n-th` validation pass of the block. This is only set on blocks starting from environment V1.


GET
../<block_id>/operation_metadata_hashes/<list_offset>/<operation_offset>
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.


GET
../<block_id>/operations?[force_metadata]&[metadata=<metadata_rpc_arg>]
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.

GET
../<block_id>/operations/<list_offset>?[force_metadata]&[metadata=<metadata_rpc_arg>]
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.

GET
../<block_id>/operations/<list_offset>/<operation_offset>?[force_metadata]&[metadata=<metadata_rpc_arg>]
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.

GET
../<block_id>/operations_metadata_hash
Description

The root hash of the operations metadata from the block. This is only set on blocks starting from environment V1.


GET
../<block_id>/protocols
Description

Current and next protocol.


GET
../<block_id>/votes/ballot_list
Description

Ballots casted so far during a voting period.


GET
../<block_id>/votes/ballots
Description

Sum of ballots casted so far during a voting period.


GET
../<block_id>/votes/current_period
Description

Returns the voting period (index, kind, starting position) and related information (position, remaining) of the interrogated block.


GET
../<block_id>/votes/current_proposal
Description

Current proposal under evaluation.


GET
../<block_id>/votes/current_quorum
Description

Current expected quorum.


GET
../<block_id>/votes/listings
Description

List of delegates with their voting power.


GET
../<block_id>/votes/proposals
Description

List of proposals with number of supporters.


GET
../<block_id>/votes/successor_period
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.


GET
../<block_id>/votes/total_voting_power
Description

Total voting power in the voting listings.