streamr-client

Streamr JavaScript Client

The Streamr Client library allows you to easily interact with the Streamr Network from JavaScript-based environments, such as browsers and Node.js. The library wraps a Streamr light node for publishing and subscribing to messages. It also contains convenience functions for creating and managing streams.

Checkout our documentation for the full usage instructions.

Quickstart

The client is available on NPM and can be installed simply by:

npm install streamr-client

If using TypeScript you can import the library with:

import { StreamrClient } from 'streamr-client'

If using Node.js you can import the library with:

const { StreamrClient } = require('streamr-client')

Environments and frameworks

NodeJS

• NodeJS 16.13.x is the minimum required version. NodeJS 18.13.x, NPM 8.x and later versions are recommended.

Browser (Website/WebApps)

• To use with react please see streamr-client-react
• For usage in the browser include the latest build, e.g. by including a <script> tag pointing at a CDN:
• <script src="https://unpkg.com/streamr-client@latest/streamr-client.web.min.js"></script>

Browser extension

• Due to the stricter security rules inside browser extensions you must use the web build version of the Streamr Client.

Usage

Full API reference

For a full API reference visit https://api-docs.streamr.network/.

Client creation

In Streamr, Ethereum accounts are used for identity. You can generate an Ethereum private key using any Ethereum wallet, or you can use the utility function StreamrClient.generateEthereumAccount(), which returns the address and private key of a fresh Ethereum account. A private key is not required if you are only subscribing to public streams on the Network.

const streamr = new StreamrClient({
    auth: {
        privateKey: 'your-private-key'
    }
})

Authenticating with an Ethereum private key contained in an Ethereum (web3) provider (e.g. MetaMask):

const streamr = new StreamrClient({
    auth: {
        ethereum: window.ethereum,
    }
})

You can also create an anonymous client instance that can interact with public streams:

const streamr = new StreamrClient()

Creating a stream

// Requires MATIC tokens (Polygon blockchain gas token)
const stream = await streamr.createStream({
    id: '/foo/bar'
})

console.log(stream.id) // e.g. `0x12345.../foo/bar`

Subscribing

const streamId = '0x7d275b79eaed6b00eb1fe7e1174c1c6f2e711283/ethereum/gas-price'

streamr.subscribe(streamId, (message) => {
    // handle for individual messages
})

Publishing

Publishing messages requires your Ethereum account to have permission to publish. See the stream permission docs for more information.

// Requires MATIC tokens (Polygon blockchain gas token)
const stream = await streamr.createStream({
    id: '/foo/bar'
})

await stream.publish({ timestamp: Date.now() })

Requesting historical messages

By default subscribe will not request historical messages.

You can fetch historical messages with the resend method:

streamr.resend(streamId, { last: 10 }, (msgs) => {
  console.log("messages": msgs);
});

This Readme only scratches the surface of what's possible - be sure to checkout our documentation for the full usage instructions.