Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
85 lines (56 sloc) 3.02 KB

API

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

Implementation details for the JSON-RPC package are here.

Overview: How do you modify the config.toml to change the API endpoint?

API requests are made against 127.0.0.1:1234 unless you modify .lotus/config.toml.

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?

For now, you can look into different files to find methods available to you based on your needs:

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.

CURL 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.

How do I generate a token?

To generate a JWT with custom permissions, use this command:

# Lotus Node
lotus auth create-token --perm admin

# Lotus Storage Miner
lotus-storage-miner auth create-token --perm admin

What authorization level should I use?

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

  • read - Read node state, no private data.
  • write - Write to local store / chain, and read permissions.
  • sign - Use private keys stored in wallet for signing, read and write permissions.
  • admin - Manage permissions, read, write, and sign permissions.
You can’t perform that action at this time.