lotus/documentation/en/api.md

API

Here is an early overview of how to make API calls.

Implementation details for the JSON-RPC package are here.

Overview

API requests are made against 127.0.0.1:1234 unless you modify ~/.lotus/api.

Options:

• http://[api:port]/rpc/v0 - HTTP endpoint
• ws://[api:port]/rpc/v0 - Websocket endpoint
• PUT http://[api:port]/rest/v0/import - File import, it requires write permissions.

What methods can I use?

Every method is available in api/api.go.

The necessary permissions for each are in api/struct.go.

How do I make an API request?

To demonstrate making an API request, we will take the method ChainHead from api/api.go.

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

And create a CURL command. In this command, ChainHead is included as { "method": "Filecoin.ChainHead" }:

curl -X POST \
     -H "Content-Type: application/json" \
     --data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
     'http://127.0.0.1:1234/rpc/v0'

If the request requires authorization, add an authorization header:

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

In the future we will add a playground to make it easier to build and experiment with API requests.

Authorization

To authorize your request, you will need to include the JWT in a HTTP header, for example:

-H "Authorization: Bearer $(cat ~/.lotusstorage/token)"

Admin token is stored in ~/.lotus/token for the Lotus Node or ~/.lotusstorage/token for the Lotus Storage Miner.

Authorization types

When viewing api/struct.go, you will encounter these types:

• read - Read node state, no private data.
• write - Write to local store / chain, read private data.
• sign - Use private keys stored in wallet for signing.
• admin - Manage permissions.

Payload

{
  "Allow": [
    "read", 
    "write",
    /* other options */
  ]
}