# Lotus JSON-RPC API reference

This is the reference documentation for the Lotus JSON-RPC API.

Both the Lotus Node and the Lotus Miner serve a JSON-RPC API when started. This APIs are used by the lotus and lotus-miners CLI applications to control the running daemons, so all the necessary functionality performed by those applications also exists as API methods.

# Endpoints

The API can be accessed on:

  • http://[api:port]/rpc/v0 - HTTP RPC-API endpoint
  • ws://[api:port]/rpc/v0 - Websocket RPC-API endpoint
  • http://[api:port]/rest/v0/import (PUT only) - REST endpoint for file import (multipart upload). It requires write permissions.

The Lotus Node configures its listen interface and port in its configuration and the Lotus Miner own config file.

# Methods

The JSON-RPC API matches directly the methods defined in the Lotus API package (link to the Go documentation. This is the best place to discover what methods and types exist for the Lotus and the Lotus Miner APIs. For information on how to jump from a Go method definition to the JSON-RPC method see cURL examples below.

# Common methods

Common methods are available in both the Lotus Node API and the Lotus Miner API. The existing common methods are shown here:

https://pkg.go.dev/github.com/filecoin-project/lotus/api?tab=doc#Common

# Lotus Node methods

The following methods are only provided by the Lotus Node API:

https://pkg.go.dev/github.com/filecoin-project/lotus/api?tab=doc#FullNode

# Lotus Miner methods

The following methods are specific to the Lotus Miner API:

https://pkg.go.dev/github.com/filecoin-project/lotus/api?tab=doc#StorageMiner

# API client libraries

Read the Lotus client libraries page for an overview of existing clients.

Lotus uses its own Go library implementation of JSON-RPC. An example on how to use the client side of it is available here.

# cURL examples

To demonstrate making an API request, we will take the method ChainHead from api/api_full.go and create a CURL command. The method is defined as:

ChainHead(context.Context) (*types.TipSet, error)

Thus, ChainHead will translate as the following JSON-RPC request object:

{
  "jsonrpc": "2.0",
  "method": "Filecoin.ChainHead",
  "params": [],
  "id": 1
}

Note the id is an arbitrary number.

In order to make a cURL request we will also need an authorization token, which can be easily generated.

curl -X POST \
	 -H "Content-Type: application/json" \
	 -H "Authorization: Bearer $(cat ~/.lotusminer/token)" \
	 --data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 1 }' \
	 'http://127.0.0.1:1234/rpc/v0'

The response will be a JSON object corresponding to the Typset type (which is actually serialized to JSON from the ExpTipSet type).

Let us now make a request with parameters using the ChainGetMessage method for a message with CID bafy2bzacedcdedrghloawlwkntdhqnknqzxgh26ddwix7ld2a5ygagco3ngee. Per the above, the JSON-RPC request payload will look like:

{
  "jsonrpc": "2.0",
  "method": "Filecoin.ChainGetMessage",
  "params": [
    { "/": "bafy2bzacedcdedrghloawlwkntdhqnknqzxgh26ddwix7ld2a5ygagco3ngee" }
  ],
  "id": 1
}

Notice how the CID has been serialized (a common pitfall).

The cURL request will then be:

curl -X POST \
	 -H "Content-Type: application/json" \
	 -H "Authorization: Bearer $(cat ~/.lotusminer/token)" \
	 --data '{"jsonrpc":"2.0","method":"Filecoin.ChainGetMessage","params":[{"/":"bafy2bzacedcdedrghloawlwkntdhqnknqzxgh26ddwix7ld2a5ygagco3ngee"}],"id":1}' \
	 'http://127.0.0.1:1234/rpc/v0'

And the response is a JSON-serialized Message type

All the above should help you getting bootstrapped to harness the power of the Lotus APIs!