Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Lotus JS Client

Lotus Loves JS

The Lotus JS Client is a collection of small JavaScript libraries that you can use to control the Lotus implementation of Filecoin via its JSON-RPC API.

You can combine the libraries to build your own lightweight custom client that works in any JavaScript based environment!

Check out the full documentation, the official tutorial as well as the examples. Also check out the "Build" category in the Filecoin Docs for full tutorials and other ways to build things that use Filecoin.


The following libraries are included:

Check the list of libraries page in the documentation for more information!


On the Web

Let's try using it with JavaScript in a web page!

<!DOCTYPE html>
<html lang="en">
    <title>Chain Height</title>
    <h1>Chain Height</h1>
    <div id="chainHeight">Loading...</div>
    <script type="module">
      // Import ES modules from the npm packages via the CDN
      import { mainnet } from ''
      import { BrowserProvider } from ''
      import { LotusRPC } from ''

      // Public endpoint for demos
      const endpointUrl = 'wss://'
      // To connect to your local Lotus node, try using:
      // const endpointUrl = 'ws://localhost:1234/rpc/v0'

      // Instantiate a provider for the endpoint -- wraps the http and
      // websockets transports for use in a web browser
      const provider = new BrowserProvider(endpointUrl)

      // Create a client object with callable methods using a schema and
      // our provider. Calling methods on this object will send JSON-RPC
      // requests over the websocket.
      const client = new LotusRPC(provider, { schema: mainnet.fullNode })

      // Using the client and the "ChainHead" method, every second,
      // retrieve the chain height and update the web page
      async function run () {
        const chainHeightEl = document.getElementById('chainHeight')
        while (true) {
          const { Height: height } = await client.chainHead()
          chainHeightEl.textContent = height
          await new Promise(resolve => { setTimeout(resolve, 1000) })

See it running here!

It will look like this: (5x speed)

Chain Head Demo

From Node.js

(gist with quick example)

Full Tutorial

Check out the tutorial on

More examples

Here are some more examples to get started:

  • ObservableHQ Notebooks - Observable Notebooks are a great way to learn about and try out the API.
    • Here's the simplest example, which connects to the "local net" and gets the chain head
    • A more complex example connects to the Testnet and gets a list of miners and displays them on a 3D map using
    • And here's an example of how to query an ask from a miner on the Testnet
    • ... more to come. Submissions welcome!

We also built a workshop for the Ready Layer One conference. We have been updating it since the conference and it contains code that shows how to store and retrieve files using a Lotus node (connected to our demo "local net").

Workshop Videos



Feel free to join in. All welcome. Open an issue!

Conversations and questions about the Lotus JS Client libraries are welcome in the #fil-storage-dev channel in the Filecoin Commmunity Slack. Find out how to sign up over at the Filecoin Community page.


Dual-licensed under MIT + Apache 2.0


No releases published


No packages published

Contributors 4