Master RSS3 SDK in 10 Minutes

To help you get a taste of how simple it is to use the RSS3 SDK, in this tutorial we will:

Show you how to retrieve cross-network activities of any user (using a supported Name Service, and of course, a wallet address).
Show you how to obtain readable data for interpreting activities.
Show you how to use filters to form a flexible data querying strategy.
Show you how to retrieve cross-network profiles of any user.

👍
Throughout the tutorial, you may copy the code snippets and paste them into this code sandbox to get a real-time result.

Get Activities

First, let's get all the activities of vitalik.eth:

import { dataClient } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth')

console.log(res.data)

The data we have just retrieved is a list of activities generated by vitalik.eth on multiple decentralized networks.

By default it will fetch 100 recent activities, we can use thelimit parameter to reduce it to 20:

import { dataClient } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', { limit: 20 })

console.log(res.data)

We can also use the res.nextPage helper recursively to get to the next page, to make the tutorial simple we will not implement the pagination here.

Make the Data Readable

The data structure (we call it the UMS) might look intimidating at first, let's use the formatPlain helper to convert it into a plain and readable sentence that describes the underlying activity:

import { dataClient, formatPlain } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', { limit: 20 })

res.data.forEach((activity) => {
  console.log(formatPlain(activity))
})

For example, an activity is actually:

vitalik.eth published a post "Hello World" on Farcaster [2023-10-13T05:05:32.000Z]

By making the data readable, the helper enables us to gain an overview of the activity.

Custom Format

The formatPlain helper is a wrapper for format, you can invoke format directly with your own custom theme:

import { dataClient, format, Theme, themePlain } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', {
  limit: 20,
})

// here we override the themePlain's time renderer
const myTheme: Theme<string> = {
  ...themePlain,
  time: (s) => `[${new Date(s).toLocaleString()}]`,
}

res.data.forEach((activity) => {
  console.log(format(activity, myTheme).join(''))
})

It now formats the timestamp into a date:

Jack made a comment "Good to hear" on post "Hello World" of vitalik on Farcaster [10/18/2023, 10:26:45 AM]

You can further customize the theme to suit your needs, we include themePlain and themeHTML in the SDK for your reference.

Filter Activities

There are many filters supported by the RSS3 Network to enable a flexible data querying strategy.

Here we use the platform option to filter the activities by platform:

import { dataClient, formatPlain } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', {
  limit: 20,
  platform: ['Farcaster'],  // <-- a new `platform` filter here
})

const myTheme: Theme<string> = {
  ...themePlain,
  time: (s) => `[${new Date(s).toLocaleString()}]`,
}

res.data.forEach((activity) => {
  console.log(format(activity, myTheme).join(''))
})

Here we get 20 recent activities of vitalik.eth on Farcaster.

The platform option is an array, so you can get activities from multiple platforms in one request.

Not just the platform, we can also combine multiple filters such as network, type, and tag.
Here we use type=['comment'] to retrieve comments related to vitalik.eth (including comments made by others on vitalik.eth's activities):

import { dataClient, formatPlain } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', {
  limit: 20,
  platform: ['Farcaster'],
  type: ['comment'], // <-- a new `type` filter here
})

const myTheme: Theme<string> = {
  ...themePlain,
  time: (s) => `[${new Date(s).toLocaleString()}]`,
}

res.data.forEach((activity) => {
  console.log(format(activity, myTheme).join(''))
})

Here is an example:

Jack made a comment "Good to hear" on post "Hello World" of vitalik on Farcaster [10/18/2023, 10:26:45 AM]

If we want to focus on the comments made by vitalik.eth, we can utilize the direction parameter:

import { dataClient, formatPlain } from '@rss3/js-sdk'

const res = await dataClient().activities('vitalik.eth', {
  limit: 20,
  platform: ['Farcaster'],
  type: ['comment'],
  direction: 'out'  // <-- a new `direction` parameter here
})

const myTheme: Theme<string> = {
  ...themePlain,
  time: (s) => `[${new Date(s).toLocaleString()}]`,
}

res.data.forEach((activity) => {
  console.log(format(activity, myTheme).join(''))
})

Where direction: 'in' simply means to get the activities initiated by others but are related to vitalik.eth, such as comments on vitalik.eth's posts. direction: 'out' means the opposite, the activities must be initiated by vitalik.eth himself.

Here is an example:

vitalik.eth made a comment "(i) quickly detect it" on Farcaster [10/18/2023, 02:06:03 AM]

Get Profiles

Profiles refer to user's decentralized identifiers (DIDs), in the context of the RSS3 Network, they are mostly referred to as Name Service.

Here we use profiles to get an address's DIDs in one request:

import { dataClient } from '@rss3/js-sdk'

const res = await dataClient().profiles('vitalik.eth')

console.log(res.data)

The response will contain all the profiles of vitalik.eth from all decentralized networks and platforms:

[
  {
    address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    handle: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045.csb',
    platform: 'Crossbell',
    network: 'crossbell',
    url: 'https://crossbell.io/@0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
  },
  {
    address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    handle: 'vitalik.eth',
    name: 'vitalik',
    platform: 'ENS Registrar',
    network: 'ethereum',
    url: 'https://vitalik.ca',
    expireAt: '2036-06-03T07:36:18Z',
    profileURI: [ 'https://metadata.ens.domains/mainnet/avatar/vitalik.eth' ]
  },
  {
    address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    handle: 'vitalik.lens',
    bio: 'Ethereum\n' +
      '\n' +
      "Fable of the Dragon Tyrant (not mine but it's important): https://www.youtube.com/watch?v=cZYNADOHhVY\n" +
      '\n' +
      'Abolish daylight savings time and leap seconds',
    name: 'vitalik.lens',
    platform: 'Lens',
    network: 'polygon',
    url: 'https://lenster.xyz/u/vitalik.lens',
    profileURI: [
      'https://ipfs.io/ipfs/QmQP1DyNH8upeBxKJYtfCDdUj3mRcZep8zhJTLe3ePXB7M/'
    ]
  },
  {
    address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    handle: 'vitalik.eth',
    bio: 'hullo',
    name: 'Vitalik Buterin',
    platform: 'Farcaster',
    network: 'farcaster',
    url: 'https://warpcast.com/vitalik.eth'
  }
]

From there you can apply your own logic to process and present the profiles in your app.

That's it, you have just mastered the RSS3 JavaScript SDK. We hope you have an enjoyable development experience.

🤙 Your feedback is essential to us. Please don't hesitate to reach out and share your thoughts.

🎤 We invite you to join our dedicated Discord channel for developers, where you can directly communicate with our engineering team.