# 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 (opens new window) API matches directly the methods defined in the Lotus API package (link to the Go documentation (opens new window). 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window)

# 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 (opens new window). 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 (opens new window) 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 (opens new window) 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 obtained.

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

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

Let us now make a request with parameters using the ChainGetMessage method (opens new window) 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}' \

And the response is a JSON-serialized Message type (opens new window)

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