RSS3 PreGod API

Current stable PreGod API endpoint: https://pregod.rss3.dev/v0.4.0open in new window

Introduction

PreGod marks a milestone towards our ultimate goal, a fully decentralized service that provides the Web3 feed of any instance.

As an implementation of the RSS3 Protocol, PreGod provides a set of simple-to-use APIs to access the feed of Web3. Currently, the stable version is open in new window. The source code is available on GitHubopen in new window.

The release of PreGod v0.4.0 also means that PreNode v0.3.1 will be switched to a maintenance-only state, aiming to support the existing applications that rely on it. Below we also offer a guide on the migration.

Data Sources Supported

Ethereum
Polygon
BNB Smart Chain
zkSync
Mirror Entry
Gitcoin Contribution
Crossbell

API Specification

Below is the specification of two APIs provided by PreGod. These APIs are designed to be simple to use yet powerful enough to get you started on your first Web3 application. The reason why PreGod does not offer more complicated APIs that return feeds at a finer granularity is that, we want to give the developers a more free space to use all the imaginations.

swagger

API Cookbook

The cookbook demonstrates some common use case scenarios of the APIs. Take these examples for a spin yourself for inspiration getting started with PreGod.

Here we refer to a Note as an action or an event generated by the instance, the feed of an instance therefore naturally contains multiple Note.

Get Notes by an Instance

Supposedly that DIYgod 0xC8b960D09C0078c18Dcbe7eB9AB9d816BcCa8944 (address) wants to check his own feed related to his NFT (tag1) on the Ethereum (platform), at the same time DIYgod wants to exclude POAP (tag2). To achieve that, we can simply query the GET endpoint by constructing the query following the structure shown below:

https://pregod.rss3.dev/v0.4.0/account:{address}@{platform}/notes?tags={tag1}&exclude_tags={tag2}

Request

And send the constructed query, here we use curl:

curl -X 'GET' \
  'https://pregod.rss3.dev/v0.4.0/account:[email protected]/notes?tags=NFT&exclude_tags=POAP' \
  -H 'accept: application/json'

Response

A successful query should return a response with the following data:

View response

{
    "version": "v0.4.0",
    "date_updated": "2022-05-15T11:57:26.000Z",
    "identifier": "rss3://account:[email protected]/notes?exclude_tags=POAP\u0026limit=100\u0026tags=NFT",
    "total": 49,
    "list": [
        {
            "identifier": "rss3://note:0x5e598d0ce[email protected]ethereum",
            "date_created": "2022-03-17T23:23:35.000Z",
            "date_updated": "2022-03-17T23:23:35.000Z",
            "related_urls": [
                "https://etherscan.io/tx/0x5e598d0ce1811daf39c350ee5e7b2dcbe59c68adb4ec609a6bba173f025bdd28",
                "https://etherscan.io/nft/0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13/539",
                "https://opensea.io/assets/0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13/539"
            ],
            "tags": [
                "NFT"
            ],
            "authors": [
                "rss3://account:[email protected]"
            ],
            "title": "The Genesis RSS3 Avatar NFT #539",
            "summary": "The Genesis RSS3 Avatar NFT is a collection of 10,000 unique avatars meticulously designed to identify RSS3 community members.",
            "attachments": [
                {
                    "type": "preview",
                    "address": "ipfs://QmSX9QiwjTGBk5m22UscTg3vrbMwUfFsmxVzMH57hkPD5U/539.png",
                    "mime_type": "image/png",
                    "size_in_bytes": 58017
                }
            ],
            "source": "Ethereum NFT",
            "metadata": {
                "collection_address": "0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13",
                "collection_name": "The Genesis RSS3 Avatar NFT",
                "contract_type": "ERC721",
                "from": "0x0000000000000000000000000000000000000000",
                "log_index": 430,
                "network": "ethereum",
                "proof": "0x5e598d0ce1811daf39c350ee5e7b2dcbe59c68adb4ec609a6bba173f025bdd28-430-539",
                "to": "0xc8b960d09c0078c18dcbe7eb9ab9d816bcca8944",
                "token_id": "539",
                "token_standard": "ERC721",
                "token_symbol": "The Genesis RSS3 Avatar NFT"
            }
        },
        // .....
        {
            "identifier": "rss3://note:0xb8adc75[email protected]ethereum",
            "date_created": "2021-06-03T04:02:46.000Z",
            "date_updated": "2021-06-03T04:02:46.000Z",
            "related_urls": [
                "https://etherscan.io/tx/0xb8adc7580145efeca0a77dfd9453c09f9e1fdb78a77ea51a8c8f8a791ee59bde",
                "https://etherscan.io/nft/0xacbe98efe2d4d103e221e04c76d7c55db15c8e89/5",
                "https://opensea.io/assets/0xacbe98efe2d4d103e221e04c76d7c55db15c8e89/5"
            ],
            "links": "rss3://note:0xb8adc75[email protected]ethereum/links",
            "backlinks": "rss3://note:0xb8adc75[email protected]ethereum/backlinks",
            "tags": [
                "NFT"
            ],
            "authors": [
                "rss3://account:[email protected]"
            ],
            "title": "RSS Fruit Token #5",
            "summary": "RSS Fruits Token (RTF) are demon fruits for those who contribute significantly to the open protocol of RSS3",
            "attachments": [
                {
                    "type": "preview",
                    "address": "https://gateway.pinata.cloud/ipfs/Qmaou2nCtmy1dJX4QQdsCf9HLax5yFCUdkuoyZ2mStWTdd",
                    "mime_type": "image/png",
                    "size_in_bytes": 88330
                },
                {
                    "type": "attributes",
                    "content": "[{\"trait_type\":\"direction\",\"value\":\"right\"},{\"trait_type\":\"life cycle\",\"value\":\"1 leaf\"},{\"trait_type\":\"left fruit\",\"value\":\"orange\"},{\"trait_type\":\"right fruit\",\"value\":\"apple\"}]",
                    "mime_type": "text/json"
                }
            ],
            "source": "Ethereum NFT",
            "metadata": {
                "collection_address": "0xacbe98efe2d4d103e221e04c76d7c55db15c8e89",
                "collection_name": "RSS Fruits Token",
                "contract_type": "ERC721",
                "from": "0x0000000000000000000000000000000000000000",
                "log_index": 207,
                "network": "ethereum",
                "proof": "0xb8adc7580145efeca0a77dfd9453c09f9e1fdb78a77ea51a8c8f8a791ee59bde-207-5",
                "to": "0xc8b960d09c0078c18dcbe7eb9ab9d816bcca8944",
                "token_id": "5",
                "token_standard": "ERC721",
                "token_symbol": "RFT"
            }
        }
    ]
}

From the response we can see that a list of chronologically ordered Notes containing 49 NFTs acquisitions, each Note also carries all the details you need to enrich the experience of your app.

There are many filtering options available to further customize the result, please refer to the API Specification.

Get Notes by a list of Instances

If now DIYgod wants to check the feed of his friends Songkeys and Henry, he can use PreGod's POST endpoint that returns a list of Note for multiple instances.

Request

A request body can be formed in this way:

{
  "addresses": [
    "rss3://account:[email protected]",
    "rss3://account:[email protected]"
  ],
  "tags": [
    "NFT"
  ],
  "exclude_tags": [
    "POAP"
  ]
}

In this query, results are filtered in the same way as the GET exmaple introduced previously. We use curl to send the request:

curl -X 'POST' \
  'https://pregod.rss3.dev/v0.4.0/notes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "addresses": [
    "rss3://account:[email protected]",
    "rss3://account:[email protected]"
  ],
  "tags": [
    "NFT"
  ],
  "exclude_tags": [
    "POAP"
  ]
}'

Response

A successful query should return a response with the following data:

View response

{
    "version": "v0.4.0",
    "date_updated": "2022-05-10T20:16:27.000Z",
    "total": 25,
    "list": [
        {
            "identifier": "rss3://note:0x6e1b2a3cc4[email protected]ethereum",
            "date_created": "2022-04-11T02:02:20.000Z",
            "date_updated": "2022-04-11T02:02:20.000Z",
            "related_urls": [
                "https://etherscan.io/tx/0x6e1b2a3cc4e86c4f22e5eff44cc4cc7b303543a1b052461a866c9665b4fd7b47",
                "https://etherscan.io/nft/0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13/1008",
                "https://opensea.io/assets/0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13/1008"
            ],
            "links": "rss3://note:0x6e1b2a3cc4[email protected]ethereum/links",
            "backlinks": "rss3://note:0x6e1b2a3cc4[email protected]ethereum/backlinks",
            "tags": [
                "NFT"
            ],
            "authors": [
                "rss3://account:[email protected]"
            ],
            "title": "The Genesis RSS3 Avatar NFT #1008",
            "summary": "The Genesis RSS3 Avatar NFT is a collection of 10,000 unique avatars meticulously designed to identify RSS3 community members.",
            "attachments": [
                {
                    "type": "preview",
                    "address": "ipfs://QmSX9QiwjTGBk5m22UscTg3vrbMwUfFsmxVzMH57hkPD5U/1008.png",
                    "mime_type": "image/png",
                    "size_in_bytes": 50746
                }
            ],
            "source": "Ethereum NFT",
            "metadata": {
                "collection_address": "0x5452c7fb99d99fab3cc1875e9da9829cb50f7a13",
                "collection_name": "The Genesis RSS3 Avatar NFT",
                "contract_type": "ERC721",
                "from": "0x0000000000000000000000000000000000000000",
                "log_index": 582,
                "network": "ethereum",
                "proof": "0x6e1b2a3cc4e86c4f22e5eff44cc4cc7b303543a1b052461a866c9665b4fd7b47-582-1008",
                "to": "0x08d66b34054a174841e2361bd4746ff9f4905cc2",
                "token_id": "1008",
                "token_standard": "ERC721",
                "token_symbol": "The Genesis RSS3 Avatar NFT"
            }
        },
        {
            "identifier": "rss3://note:0x5039d3f8[email protected]ethereum",
            "date_created": "2022-01-19T14:00:00.000Z",
            "date_updated": "2022-01-19T14:00:00.000Z",
            "related_urls": [
                "https://etherscan.io/tx/0x5039d3f855cdacc81e4251abc5f3fd81cb634c144f8b5ed9d67cb1f42d537a02",
                "https://etherscan.io/nft/0xb9619cf4f875cdf0e3ce48b28a1c725bc4f6c0fb/19",
                "https://opensea.io/assets/0xb9619cf4f875cdf0e3ce48b28a1c725bc4f6c0fb/19"
            ],
            "links": "rss3://note:0x5039d3f8[email protected]ethereum/links",
            "backlinks": "rss3://note:0x5039d3f8[email protected]ethereum/backlinks",
            "tags": [
                "NFT"
            ],
            "authors": [
                "rss3://account:[email protected]"
            ],
            "title": "RSS3 Whitepaper v1.0",
            "summary": "RSS3 Whitepaper v1.0 - Commemorative & Limited Edition",
            "attachments": [
                {
                    "type": "external_url",
                    "content": "https://rss3.io/RSS3-Whitepaper.pdf",
                    "mime_type": "text/uri-list"
                },
                {
                    "type": "preview",
                    "address": "ipfs://bafybeiahqmf43pqwuq4vz4fugtg7nby4svjsn4f6a7mxfqnlfrgkww6maa/rss3-whitepaper-no-19.png",
                    "mime_type": "image/png",
                    "size_in_bytes": 117143
                },
                {
                    "type": "object",
                    "address": "ipfs://bafybeigyalxntwfje42gaylvc7qvkbsjhxyz54jdh6lzielalkkuift5ze/rss3-whitepaper-no-19.glb",
                    "mime_type": "model/gltf-binary",
                    "size_in_bytes": 3890832
                },
                {
                    "type": "attributes",
                    "content": "[{\"trait_type\":\"Author(s)\",\"value\":\"Natural Selection Labs\"},{\"trait_type\":\"Edition\",\"value\":\"First Edition\"},{\"trait_type\":\"Edition Language\",\"value\":\"English\"},{\"trait_type\":\"File Format\",\"value\":\"PDF\"},{\"trait_type\":\"No.\",\"value\":19},{\"trait_type\":\"Released Data\",\"value\":1610323200,\"display_type\":\"date\"}]",
                    "mime_type": "text/json"
                }
            ],
            "source": "Ethereum NFT",
            "metadata": {
                "collection_address": "0xb9619cf4f875cdf0e3ce48b28a1c725bc4f6c0fb",
                "collection_name": "RSS3 Whitepaper",
                "contract_type": "ERC721",
                "from": "0x0000000000000000000000000000000000000000",
                "log_index": 230,
                "network": "ethereum",
                "proof": "0x5039d3f855cdacc81e4251abc5f3fd81cb634c144f8b5ed9d67cb1f42d537a02-230-19",
                "to": "0x827431510a5d249ce4fdb7f00c83a3353f471848",
                "token_id": "19",
                "token_standard": "ERC721",
                "token_symbol": "RWP"
            }
        }
    ]
}

The response contains a list of Notes belonging to Songkeys and Henry, includes only NFT and excludes POAP, in a chronologically order.

You are now familiar with PreGod's APIs, you can try them out in the API Specification by expanding the API and clicking on Try it out.

Build a simple Mirror reader under 5 mins

In this tutorial, we demonstrate how easy it is to build your first dApp, a simple Mirror reader, under 5 minutes using RSS3 PreGod APIs. All source code used in this tutorial is available on GitHubopen in new window.

Tools required

RSS3 PreGod offers simple-to-use yet powerful enough APIs to access the feed of Web3.

Mirror.xyzopen in new window is a decentralized publishing platform.

Unidata.jsopen in new window provides easy access to various Web3 data.

Steps

Get Data from PreGod via unidata.js

Here we merely require 4 LOCs to retrieve all Mirror entries of a Web3 instance.

await unidata.notes.get({
    source: 'Mirror Entry';     // the feed type from PreGod API
    identity: string;           // the instance address
});

And add some of your own frontend rendering logic.

View result

1. Enter an address

The instance address:

42 / 42

2. Render the data returned by PreGod API

3. View data retrieved from PreGod API

View data

{}

Migration from PreNode

In order to offer extra robustness comparing to PreNode, Dev 🌀 RSS3 have completely redesigned the architecture. That means breaking changes have to be made.

For now existing projects that rely on PreNode v0.3.1 can continue doing so, it will be switched to a long-term support version, and eventually getting phased out. We recommend that all developers start migrating to PreGod. If you need any assistance, simply open an issue on GitHubopen in new window or join the dedicated Discord channel #ask-the-developersopen in new window.

Features Removed

PreGod has removed the support for Profile, you may use Crossbellopen in new window or ENSopen in new window as a replacement.

PreGod has removed the support for Links, you may use Crossbellopen in new window or CyberConnectopen in new window as a replacement.

# RSS3 PreGod API

# Introduction

# Data Sources Supported

# API Specification

# API Cookbook

# Get Notes by an Instance

# Request

# Response

# Get Notes by a list of Instances

# Request

# Response

# Build a simple Mirror reader under 5 mins

# Tools required

# Steps

# Get Data from PreGod via unidata.js

1. Enter an address

2. Render the data returned by PreGod API

3. View data retrieved from PreGod API

# Migration from PreNode

# Features Removed

RSS3 PreGod API

Introduction

Data Sources Supported

API Specification

API Cookbook

Get Notes by an Instance

Request

Response

Get Notes by a list of Instances

Request

Response

Build a simple Mirror reader under 5 mins

Tools required

Steps

Get Data from PreGod via unidata.js

Migration from PreNode

Features Removed