RPCs - Reference

This page describes the RPCs built into the Octez shell, which are independent from a particular version of the Tezos protocol.

Warning

This list could be missing RPC endpoints. The OpenAPI specification can 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/levels

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/chain_id

Protocol

The RPCs implemented by the protocol currently active on Mainnet, served under the prefix /chains/<chain_id>/blocks/<block_id>/, are described in this other page.

Shell

  • /chains/<chain_id> (PATCH)

  • /chains/<chain_id>/blocks (GET)

  • /chains/<chain_id>/blocks/<block_id> (<dynamic>)

  • /chains/<chain_id>/chain_id (GET)

  • /chains/<chain_id>/checkpoint (GET)

  • /chains/<chain_id>/invalid_blocks (GET)

  • /chains/<chain_id>/invalid_blocks/<block_hash> (GET DELETE)

  • /chains/<chain_id>/is_bootstrapped (GET)

  • /chains/<chain_id>/levels/caboose (GET)

  • /chains/<chain_id>/levels/checkpoint (GET)

  • /chains/<chain_id>/levels/savepoint (GET)

  • /chains/<chain_id>/mempool (<dynamic>)

  • /config/history_mode (GET)

  • /config/logging (PUT)

  • /config/network/user_activated_protocol_overrides (GET)

  • /config/network/user_activated_upgrades (GET)

  • /errors (GET)

  • /fetch_protocol/<Protocol_hash> (GET)

  • /injection/block (POST)

  • /injection/operation (POST)

  • /injection/protocol (POST)

  • /monitor/active_chains (GET)

  • /monitor/bootstrapped (GET)

  • /monitor/commit_hash (GET)

  • /monitor/heads/<chain_id> (GET)

  • /monitor/protocols (GET)

  • /monitor/valid_blocks (GET)

  • /network/connections (GET)

  • /network/connections/<peer_id> (GET DELETE)

  • /network/greylist (DELETE)

  • /network/greylist/clear (GET)

  • /network/greylist/ips (GET)

  • /network/greylist/peers (GET)

  • /network/log (GET)

  • /network/peers (GET)

  • /network/peers/<peer_id> (GET PATCH)

  • /network/peers/<peer_id>/ban (GET)

  • /network/peers/<peer_id>/banned (GET)

  • /network/peers/<peer_id>/log (GET)

  • /network/peers/<peer_id>/trust (GET)

  • /network/peers/<peer_id>/unban (GET)

  • /network/peers/<peer_id>/untrust (GET)

  • /network/points (GET)

  • /network/points/<point> (GET PUT PATCH)

  • /network/points/<point>/ban (GET)

  • /network/points/<point>/banned (GET)

  • /network/points/<point>/log (GET)

  • /network/points/<point>/trust (GET)

  • /network/points/<point>/unban (GET)

  • /network/points/<point>/untrust (GET)

  • /network/self (GET)

  • /network/stat (GET)

  • /network/version (GET)

  • /network/versions (GET)

  • /private/injection/operation (POST)

  • /private/injection/operations (POST)

  • /protocols (GET)

  • /protocols/<Protocol_hash> (GET)

  • /protocols/<Protocol_hash>/environment (GET)

  • /stats/gc (GET)

  • /stats/memory (GET)

  • /version (GET)

  • /workers/block_validator (GET)

  • /workers/chain_validators (GET)

  • /workers/chain_validators/<chain_id> (GET)

  • /workers/chain_validators/<chain_id>/ddb (GET)

  • /workers/chain_validators/<chain_id>/peers_validators (GET)

  • /workers/chain_validators/<chain_id>/peers_validators/<peer_id> (GET)

  • /workers/prevalidators (GET)

  • /workers/prevalidators/<chain_id> (GET)

RPCs - Full description

Shell


PATCH
/chains/<chain_id>
Description

Forcefully set the bootstrapped flag of the node


GET
/chains/<chain_id>/blocks?[length=<uint>]&(head=<block_hash>)*&[min_date=<date>]
Description

Lists block hashes from '<chain>', up to the last checkpoint, sorted with decreasing fitness. Without arguments it returns the head of the chain. Optional arguments allow to return the list of predecessors of a given block or of a set of blocks.

Optional query arguments:
  • length = <uint> : The requested number of predecessors to return (per request; see next argument).
  • head = <block_hash> : An empty argument requests blocks starting with the current head. A non empty list allows to request one or more specific fragments of the chain.
  • min_date = <date> : When `min_date` is provided, blocks with a timestamp before `min_date` are filtered out. However, if the `length` parameter is also provided, then up to that number of predecessors will be returned regardless of their date.

GET
/chains/<chain_id>/chain_id
Description

The chain unique identifier.


GET
/chains/<chain_id>/checkpoint
Description

DEPRECATED: use `../levels/{checkpoint, savepoint, caboose, history_mode}` instead. The current checkpoint for this chain.


GET
/chains/<chain_id>/invalid_blocks
Description

Lists blocks that have been declared invalid along with the errors that led to them being declared invalid.


GET
/chains/<chain_id>/invalid_blocks/<block_hash>
Description

The errors that appears during the block (in)validation.


DELETE
/chains/<chain_id>/invalid_blocks/<block_hash>
Description

Remove an invalid block for the tezos storage


GET
/chains/<chain_id>/is_bootstrapped
Description

The bootstrap status of a chain


GET
/chains/<chain_id>/levels/caboose
Description

The current caboose for this chain.


GET
/chains/<chain_id>/levels/checkpoint
Description

The current checkpoint for this chain.


GET
/chains/<chain_id>/levels/savepoint
Description

The current savepoint for this chain.


GET
/config/history_mode
Description

Returns the history mode of the node's underlying storage.


PUT
/config/logging
Description

Replace the logging configuration of the node.


GET
/config/network/user_activated_protocol_overrides
Description

List of protocols which replace other protocols


GET
/config/network/user_activated_upgrades
Description

List of protocols to switch to at given levels


GET
/errors
Description

Schema for all the RPC errors from the shell


GET
/fetch_protocol/<Protocol_hash>
Description

Fetch a protocol from the network.


POST
/injection/block?[async]&[force]&[chain=<chain_id>]
Description

Inject a block in the node and broadcast it. The `operations` embedded in `blockHeader` might be pre-validated using a contextual RPCs from the latest block (e.g. '/blocks/head/context/preapply'). Returns the ID of the block. By default, the RPC will wait for the block to be validated before answering. If ?async is true, the function returns immediately. Otherwise, the block will be validated before the result is returned. If ?force is true, it will be injected even on non strictly increasing fitness. An optional ?chain parameter can be used to specify whether to inject on the test chain or the main chain.

Optional query arguments:
  • async
  • force
  • chain = <chain_id>

POST
/injection/operation?[async]&[chain=<chain_id>]
Description

Inject an operation in node and broadcast it. Returns the ID of the operation. The `signedOperationContents` should be constructed using contextual RPCs from the latest block and signed by the client. The injection of the operation will apply it on the current mempool context. This context may change at each operation injection or operation reception from peers. By default, the RPC will wait for the operation to be (pre-)validated before returning. However, if ?async is true, the function returns immediately. The optional ?chain parameter can be used to specify whether to inject on the test chain or the main chain.

Optional query arguments:
  • async
  • chain = <chain_id>

POST
/injection/protocol?[async]
Description

Inject a protocol in node. Returns the ID of the protocol. If ?async is true, the function returns immediately. Otherwise, the protocol will be validated before the result is returned.

Optional query arguments:
  • async

GET
/monitor/active_chains
Description

Monitor every chain creation and destruction. Currently active chains will be given as first elements


GET
/monitor/bootstrapped
Description

Wait for the node to have synchronized its chain with a few peers (configured by the node's administrator), streaming head updates that happen during the bootstrapping process, and closing the stream at the end. If the node was already bootstrapped, returns the current head immediately.


GET
/monitor/commit_hash
Description

DEPRECATED: use `version` instead.


GET
/monitor/heads/<chain_id>?(next_protocol=<Protocol_hash>)*
Description

Monitor all blocks that are successfully validated by the node and selected as the new head of the given chain.

Optional query arguments:
  • next_protocol = <Protocol_hash>

GET
/monitor/protocols
Description

Monitor all economic protocols that are retrieved and successfully loaded and compiled by the node.


GET
/monitor/valid_blocks?(protocol=<Protocol_hash>)*&(next_protocol=<Protocol_hash>)*&(chain=<chain_id>)*
Description

Monitor all blocks that are successfully validated by the node, disregarding whether they were selected as the new head or not.

Optional query arguments:
  • protocol = <Protocol_hash>
  • next_protocol = <Protocol_hash>
  • chain = <chain_id>

GET
/network/connections
Description

List the running P2P connection.


GET
/network/connections/<peer_id>
Description

Details about the current P2P connection to the given peer.


DELETE
/network/connections/<peer_id>?[wait]
Description

Forced close of the current P2P connection to the given peer.

Optional query arguments:
  • wait

DELETE
/network/greylist
Description

Clear all greylists tables. This will unban all addresses and peers automatically greylisted by the system.


GET
/network/greylist/clear
Description

DEPRECATED: Clear all greylists tables. This will unban all addresses and peers automatically greylisted by the system. Use DELETE `/network/greylist` instead


GET
/network/greylist/ips
Description

Returns an object that contains a list of IP and the field "not_reliable_since".

If the field "not_reliable_since" is None then the list contains the currently greylisted IP addresses.

If the field "not_reliable_since" Contains a date, this means that the greylist has been overflowed and it is no more possible to obtain the exact list of greylisted IPs. Since the greylist of IP addresses has been design to work whatever his size, there is no security issue related to this overflow.

Reinitialize the ACL structure by calling "delete /network/greylist" to get back this list reliable.


GET
/network/greylist/peers
Description

List of the last greylisted peers.


GET
/network/log
Description

Stream of all network events


GET
/network/peers?(filter=<p2p.point.state_filter>)*
Description

List the peers the node ever met.

Optional query arguments:
  • filter = <p2p.point.state_filter>

GET
/network/peers/<peer_id>
Description

Details about a given peer.


PATCH
/network/peers/<peer_id>
Description

Change the permissions of a given peer. With `{acl: ban}`: blacklist the given peer and remove it from the whitelist if present. With `{acl: open}`: removes the peer from the blacklist and whitelist. With `{acl: trust}`: trust the given peer permanently and remove it from the blacklist if present. The peer cannot be blocked (but its host IP still can).


GET
/network/peers/<peer_id>/ban
Description

DEPRECATED: Blacklist the given peer and remove it from the whitelist if present. Use PATCH `network/peers/<peer_id>` instead.


GET
/network/peers/<peer_id>/banned
Description

Check if a given peer is blacklisted or greylisted.


GET
/network/peers/<peer_id>/log?[monitor]
Description

Monitor network events related to a given peer.

Optional query arguments:
  • monitor

GET
/network/peers/<peer_id>/trust
Description

DEPRECATED: Whitelist a given peer permanently and remove it from the blacklist if present. The peer cannot be blocked (but its host IP still can). Use PATCH `network/peers/<peer_id>` instead.


GET
/network/peers/<peer_id>/unban
Description

DEPRECATED: Remove the given peer from the blacklist. Use PATCH `network/peers/<peer_id>` instead.


GET
/network/peers/<peer_id>/untrust
Description

DEPRECATED: Remove a given peer from the whitelist. Use PATCH `network/peers/<peer_id>` instead.


GET
/network/points?(filter=<p2p.point.state_filter>)*
Description

List the pool of known `IP:port` used for establishing P2P connections.

Optional query arguments:
  • filter = <p2p.point.state_filter>

GET
/network/points/<point>
Description

Details about a given `IP:addr`.


PUT
/network/points/<point>?[timeout=<timespan>]
Description

Connect to a peer

Optional query arguments:
  • timeout = <timespan>

PATCH
/network/points/<point>
Description

Change the connectivity state of a given `IP:addr`. With `{acl : ban}`: blacklist the given address and remove it from the whitelist if present. With `{acl: open}`: removes an address from the blacklist and whitelist. With `{acl: trust}`: trust a given address permanently and remove it from the blacklist if present. With `{peer_id: <id>}` set the peerId of the point. Connections from this address can still be closed on authentication if the peer is greylisted.


GET
/network/points/<point>/ban
Description

DEPRECATED: Blacklist the given address and remove it from the whitelist if present. Use PATCH `/network/point/<point_id>` instead.


GET
/network/points/<point>/banned
Description

Check if a given address is blacklisted or greylisted. Port component is unused.


GET
/network/points/<point>/log?[monitor]
Description

Monitor network events related to an `IP:addr`.

Optional query arguments:
  • monitor

GET
/network/points/<point>/trust
Description

DEPRECATED: Trust a given address permanently and remove it from the blacklist if present. Connections from this address can still be closed on authentication if the peer is greylisted. Use PATCH`/network/point/<point_id>` instead.


GET
/network/points/<point>/unban
Description

DEPRECATED: Remove an address from the blacklist. Use PATCH `/network/point/<point_id>` instead.


GET
/network/points/<point>/untrust
Description

DEPRECATED: Remove an address from the whitelist. Use PATCH `/network/point/<point_id>` instead.


GET
/network/self
Description

Return the node's peer id


GET
/network/stat
Description

Global network bandwidth statistics in B/s.


GET
/network/version
Description

DEPRECATED: use `version` instead.


GET
/network/versions
Description

DEPRECATED: use `version` instead.


POST
/private/injection/operation?[async]&[chain=<chain_id>]
Description

Inject an operation in node and broadcast it. Returns the ID of the operation. The `signedOperationContents` should be constructed using contextual RPCs from the latest block and signed by the client. The injection of the operation will apply it on the current mempool context. This context may change at each operation injection or operation reception from peers. By default, the RPC will wait for the operation to be (pre-)validated before returning. However, if ?async is true, the function returns immediately. The optional ?chain parameter can be used to specify whether to inject on the test chain or the main chain.

Optional query arguments:
  • async
  • chain = <chain_id>

POST
/private/injection/operations?[async]&[force]&[chain=<chain_id>]
Description

Inject a list of operations in a node. If [force] is [true] then the operations are immediatly injected. The injection will succeed, but it does not mean the operations are (all) valid. In any case, the injection will be quick, hence [async] will be taken into account but should have almost no impact. If [async] is [true], all the promises returned by injecting an operation will be dropped. Each injection is done independently, and does not depend on the other injected operations result. Otherwise ([async]=[force]=[false]), for each operation, we record a list of promises. If all the injections succeed, the result is the list of operation hashes injected, otherwise an error ("injection_operations_error") is returned. This error is followed by markers for each operation: "injection_operation_succeed" for success and "injection_operation_error" for failure (followed by the errors specific to this injection).

Optional query arguments:
  • async
  • force
  • chain = <chain_id>

GET
/protocols

GET
/protocols/<Protocol_hash>

GET
/protocols/<Protocol_hash>/environment

GET
/stats/gc
Description

Gets stats from the OCaml Garbage Collector


GET
/stats/memory
Description

Gets memory usage stats


GET
/version
Description

Get information on the node version


GET
/workers/block_validator
Description

Introspect the state of the block_validator worker.


GET
/workers/chain_validators
Description

Lists the chain validator workers and their status.


GET
/workers/chain_validators/<chain_id>
Description

Introspect the state of a chain validator worker.


GET
/workers/chain_validators/<chain_id>/ddb
Description

Introspect the state of the DDB attached to a chain validator worker.


GET
/workers/chain_validators/<chain_id>/peers_validators
Description

Lists the peer validator workers and their status.


GET
/workers/chain_validators/<chain_id>/peers_validators/<peer_id>
Description

Introspect the state of a peer validator worker.


GET
/workers/prevalidators
Description

Lists the Prevalidator workers and their status.


GET
/workers/prevalidators/<chain_id>
Description

Introspect the state of prevalidator workers.