# @glif/filecoin-rpc-client

> a convenience library for interacting with the Lotus jsonrpc

Latest version **4.0.0** (published 2025-04-25) · (Apache-2.0 OR MIT) license · 0 weekly downloads

## Install

```sh
npm install @glif/filecoin-rpc-client
pnpm add @glif/filecoin-rpc-client
yarn add @glif/filecoin-rpc-client
bun add @glif/filecoin-rpc-client
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-04-25 |
| First published | 2020-10-05 |
| Weekly downloads | 0 |
| License | (Apache-2.0 OR MIT) |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 62.4 KB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Infinite Scroll <squad@infinitescroll.org> (https://infinitescroll.org) |
| Maintainers | schwartzz8990, bret, glifbot |

## Links

- npm: https://www.npmjs.com/package/@glif/filecoin-rpc-client
- Repository: https://github.com/glifio/modules/tree/primary/packages/filecoin-rpc-client
- npm.io page: https://npm.io/package/@glif/filecoin-rpc-client

## Dependencies (1)

- [axios](https://npm.io/package/axios.md) ^0.27.2

## Recent versions

- 4.0.0 (latest) — 2025-04-25
- 3.0.2 — 2024-02-06
- 3.0.0 — 2024-01-15
- 2.0.43 — 2023-03-11
- 2.0.8 — 2022-10-13
- 2.0.7 — 2022-10-05
- 2.0.1 — 2022-08-31
- 2.0.0-beta.8 — 2022-04-07
- 2.0.0-beta.0 — 2022-02-22
- 2.0.0-alpha.13 — 2022-01-18
- 2.0.0-alpha.11 — 2022-01-10
- 2.0.0-alpha.10 — 2022-01-07
- 2.0.0-alpha.9 — 2021-12-27
- 1.1.0 — 2021-03-31
- 1.1.0-beta.19 — 2021-03-31
- … 13 more at https://npm.io/package/@glif/filecoin-rpc-client/versions

## README

# Lotus JSON-RPC engine

## :warning: UNMAINTAINED PACKAGE :warning:

This package is no longer maintained. We highly recommend looking for alternative solutions.

--- 

A convenience library for interacting with the [Lotus JSON-RPC api](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go). We'll be actively updating and maintaining this library as needed for our use in the [Filecoin web wallet](https://github.com/glifio/wallet). Several of the methods we're using are documented [here](https://documenter.getpostman.com/view/4872192/SWLh5mUd?version=latest).

## Basic usage

`npm i @glif/filecoin-rpc-client`<br />

```js
const LotusRPCEngine = require('@glif/filecoin-rpc-client')

const lotusJWT = 'aaaaaaaa.bbbbbbbbbbbb.i_ZZZZZZ-3xYYYYYY'

const config = {
  // defaults to local as seen below
  apiAddress: 'http://127.0.0.1:1234/rpc/v0',
  token: lotusJWT,
}

const lotusRPC = new LotusRpcEngine(config)

const chainHead = await lotusRPC.request('ChainHead')
```

## Structuring requests

This library is simply a wrapper around Lotus' JSON-RPC. To send requests, follow this pattern:

lotusRPC.request(rpcmethod, arg1, arg2....etc) where the "methodName" corresponds to each available JSON-RPC method (found [here](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)). After the method name, each argument is passed to Lotus' JSON-RPC in the same order.

For example, the `WalletBalance` JSON-RPC method takes a single argument, "address". Therefore, we should structure the request like:

```js
const address = 't1jdlfl73voaiblrvn2yfivvn5ifucwwv5f26nfza'
const balance = await lotusRPC.request('WalletBalance', address)
```

## Handling responses

When making a request to Lotus' JSON-RPC server, a success response looks like:

```js
const successResponse = {
  jsonrpc: '2.0',
  result: 'fake response result',
  id: 1,
}
```

The `result` key is the return data as specified in the [Lotus api](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go[]). The Lotus JSON-RPC Engine will just return you the `result`, and not any of the other data.

```js
const errorResponse = {
  jsonrpc: '2.0',
  result: '',
  id: 1,
  error: {
    code: 1,
    message: 'Specific error returned by Lotus API',
  },
}
```

This functionality may change, but for now, the Lotus JSON-RPC Engine will throw an error if the Lotus API comes back with an error, so be sure to catch them:

```js
try {
  // send a malformed request (need to pass an address)
  await lotusRPC.request('WalletBalance')
} catch (err) {
  console.log(err)
  // 'get actor: GetActor called on undefined address' <== error directly passed from Lotus' API
}
```

## Cids

Several JSON-RPC methods take `Cid` as arguments. We need to structure a cid as:

```js
const cid = {
  '/': 'bafy2bzacedavr434vvbck3nkowrffk2x67lgl7kfujlw3lyj2zjvmihn5rf7i',
}

const message = await lotusRPC.request('ChainGetMessage', cid)
```

## CORS

If you're planning on using this library in a web browser communicating with a raw Lotus node, you will run into CORS issues. There are a couple ways around this:

1. Wrap your Lotus node in a proxy server that explicitly handles CORS requests. We're working on publishing a proxy server to help unstuck anyone who needs to take this route.
2. Wrap your web browser in a "forwarder API", which is responsible for sending / receiving information from the Lotus node (essentially sending browser requests to a remote server to make the request to Lotus).
3. Figure out how to handle CORS natively inside Lotus (not suggested). Security issues with this approach.

## Contributing / development

If you're planning on forking this lib or developing with it locally, use the build script:

`npm run build`

## Troubleshooting

Please make sure an existing issue doesn't already cover your problem before asking. If you don't see a similar issue, go ahead and file a new one in the repository.

---
_Source: https://npm.io/package/@glif/filecoin-rpc-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._