Skip to main content

RPC API tutorial ☎️

This tutorial will teach you how to interact with a Celestia Node's RPC (Remote Procedure Call) API.

First, you will need to install celestia-node if you have not already.

If you have not yet initalized your node, initialize it:

celestia <node_type> init --p2p.network <network>

Start your node if it is not yet running:

celestia <node_type> start --p2p.network <network>
tip

The --core.ip gRPC port defaults to 9090, so if you do not specify it in the command line, it will default to that port. You can add the port after the IP address or use the --core.grpc.port flag to specify another port if you prefer.

Please refer to the ports section for information on which ports are required to be open on your machine.

Celestia Node CLI guide​

The Celestia Node CLI (Command Line Interface) has a rpc subcommand that allows you to interact with the node's RPC API via your terminal.

The format for the rpc subcommand is as follows:

celestia rpc [module] [method] [...args]

Auth token​

In order to interact with the API using the rpc subcommand, you will need to set your authentication token.

The --auth TOKEN flag sets the authentication token, otherwise it will read from the environment's CELESTIA_NODE_AUTH_TOKEN variable. If a token is not found, authentication will not be set. And if authentication is not set, the request will fail.

To set your authentication token, you can use the following command. Be sure to replace <node-type> with the type of node and <network> with the network that you are running your node on:

export CELESTIA_NODE_AUTH_TOKEN=$(celestia <node-type> auth admin --p2p.network <network>)

Host URL​

The --host URL flag sets the host address, the default is localhost:26658 over HTTP.

SubmitPayForBlob arguments​

Using the rpc subcommand, you can submit a blob to the network using the SubmitPayForBlob method.

The arguments for SubmitPayForBlob are parsed specially, to improve UX.

SubmitPayForBlob can be done in a few ways:

  • The namespace ID can be encoded as either hex or base64
  • The blob can be hex (0x...), base64 ("..."), or a normal string which will be encoded to base64 ('"Hello There!"')

Completions​

If you would like to turn on completions for the Celestia Node CLI rpc subcommand, you can use the following command and follow the instructions in the CLI:

celestia completion

If you'd like to see the help menu for your shell, you can then run:

celestia completion [bash | fish | powershell | zsh] --help

Examples​

Set your auth token on a light node on Blockspace Race:

export CELESTIA_NODE_AUTH_TOKEN=$(celestia light auth admin --p2p.network blockspacerace)

Submit a blob to the network:

celestia rpc state SubmitPayForBlob 0x1874e642f5dde589 '"Hello there!!"' 2000 100000

Query node information:

celestia rpc node Info

Get share by data availibility header and index:

celestia rpc share GetShare "$(celestia rpc header GetByHeight 162011 | jq '.result.dah' -r)" 162011 0

Get share by namespace:

celestia rpc share GetSharesByNamespace "$(celestia rpc header GetByHeight 162011 | jq '.result.dah' -r)" GHTmQvXd5Yk=

Get header by height:

celestia rpc header GetByHeight 5

Get data availability sampler stats:

celestia rpc das SamplingStats

CLI tutorial​

If you'd like to create your own SVG, post it to Celestia, and retrieve it, you can check out the Base64 SVG Tutorial.

Golang guide​

If you're interested in interacting with the node's API in Go (client.go), you can use the da-rpc-client-tutorial repo.