Rarible Protocol Software Development Kit

Rarible Multichain Protocol is a decentralized toolset that simplifies the way developers can work with NFTs. The protocol builds an abstraction layer for several blockchains and isolates the developer from their specifics with a Multichain SDK.

Rarible Multichain SDK is fully blockchain-agnostic. You can find a list of supported blockchains on our Features page.

We use different environments for blockchain networks. See actual information on API Reference page.

Rarible Multichain SDK enables applications to easily interact with Rarible Protocol: query, issue and trade NFTs on any blockchain supported. See more information on our documentation Reference section.

Installation

Install Protocol SDK:

yarn add @rarible/sdk -D
yarn add web3@1.5.0
yarn add tslib@2.3.1

Also, you can install ethers if you need it to initialize the wallets:

yarn add ethers

Make sure the SDK is installed correctly:

npm view @rarible/sdk version

If you have any problems installing the SDK on your M1 MacBook, see our Troubleshooting section.

Using SDK on client application

SDK is written in TypeScript. You can use typings to explore SDK possibilities.

Initialize SDK

import { createRaribleSdk } from "@rarible/sdk"

Initialize wallets

To use SDK, you have to create a Wallet — abstraction to communicate with real blockchain wallets.

Initialize wallets for used blockchains or use Rarible Wallet Connector (in general for frontend) It is possible to use SDK without wallet (for ex. sdk.balances.getBalance), but in that case you can't send transactions and sign messages:

const raribleSdk = createRaribleSdk(undefined, "prod")

Initialize simple wallets

• Ethereum / Polygon

  You can create EthereumWallet with one of the following providers:

  • Web3 instance. For example, Metamask (window.ethereum) or HDWalletProvider
  • ethers.providers.Web3Provider
  • ethers.Wallet

  import Web3 from "web3"
  import * as HDWalletProvider from "@truffle/hdwallet-provider"
  import { Web3Ethereum } from "@rarible/web3-ethereum"
  import { ethers } from "ethers"
  import { EthersEthereum, EthersWeb3ProviderEthereum } from "@rarible/ethers-ethereum"
  import { EthereumWallet } from "@rarible/sdk-wallet"
  
  //Creating EthereumWallet with Web3
  const web3 = new Web3(provider)
  const web3Ethereum = new Web3Ethereum({ web3 })
  const ethWallet = new EthereumWallet(web3Ethereum)
  
  //or with HDWalletProvider
  const provider = new HDWalletProvider({
    url: "<NODE_URL>",
    privateKeys: ["0x0..."],
    chainId: 1,
  })
  const web3 = new Web3(provider)
  const web3Ethereum = new Web3Ethereum({ web3 })
  const ethWallet = new EthereumWallet(web3Ethereum)
  
  //Creating EthereumWallet with ethers.providers.Web3Provider
  const ethersWeb3Provider = new ethers.providers.Web3Provider(provider)
  const ethersProvider = new EthersWeb3ProviderEthereum(ethersWeb3Provider)
  const ethWallet = new EthereumWallet(ethersProvider)
  
  //Creating EthereumWallet with ethers.Wallet
  const ethersWeb3Provider = new ethers.providers.Web3Provider(provider)
  const ethersProvider = new EthersEthereum(new ethers.Wallet(wallet.getPrivateKeyString(), ethersWeb3Provider))
  const ethWallet = new EthereumWallet(ethersProvider)
  
  // Second parameter — is environment: "prod" | "staging" | "e2e" | "dev"
  const raribleSdk = createRaribleSdk(ethWallet, "staging")

• Flow

  import * as fcl from "@onflow/fcl"
  import { FlowWallet } from "@rarible/sdk-wallet"
  
  const wallet =  new FlowWallet(fcl)

  You also need to configure Flow Client Library (FCL), because Flow-sdk use @onflow/fcl-js:

  //example config for testnet
  import { config } from "@onflow/fcl";
  config({
    "accessNode.api": "https://access-testnet.onflow.org", // Mainnet: "https://access-mainnet-beta.onflow.org"
    "discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn" // Mainnet: "https://fcl-discovery.onflow.org/authn"
  })

  See more configuration details on Flow documentation.

• Tezos

  To initialize wallets, you can use:

  • in_memory_provider (also for backend)
  • beacon_provider (@rarible/tezos-sdk/dist/providers/beacon/beacon_provider)

  //in_memory_provider usage example
  import { in_memory_provider } from "@rarible/tezos-sdk/dist/providers/in_memory/in_memory_provider"
  import { TezosWallet } from "@rarible/sdk-wallet"
  
  const provider = in_memory_provider("edsk...", nodeUrl)
  const wallet = new TezosWallet(provider)

Use Rarible SDK Wallet Connector

Wallet Connector make possible to connect the following providers:

• InjectedWeb3ConnectionProvider — Metamask, Coinbase, etc
• FortmaticConnectionProvider
• PortisConnectionProvider
• TorusConnectionProvider
• WalletLinkConnectionProvider
• MEWConnectionProvider
• IframeConnectionProvider
• WalletConnectConnectionProvider
• BeaconConnectionProvider
• FclConnectionProvider

Read more about installation and using examples of Rarible SDK Wallet Connector.

Using SDK on server application

The SDK was designed for use on the frontend side. To use the SDK on the server side (backend):

1. Install packages:

   yarn add tslib@2.3.1
   yarn add form-data
   yarn add node-fetch

2. Add dependencies:

   global.FormData = require("form-data")
   global.window = {
     fetch: require("node-fetch"),
     dispatchEvent: () => {
     },
   }
   global.CustomEvent = function CustomEvent() {
     return
   }

3. Try our example to buy Ethereum NFT item on Rinkeby network:

   Pass private key, node RPC URL, network ID, item ID for buyout and start:

   ETH_PRIVATE_KEY="0x..." \
   ETHEREUM_RPC_URL="https://rinkeby.infura.io/..." \
   ETHEREUM_NETWORK_ID="4" \
   BUYOUT_ITEM_ID="0x1AF7A7555263F275433c6Bb0b8FdCD231F89B1D7:102581254137174039089845694331937600507918590364933200920056519678660477714440" \
   ts-node packages/sdk/example/backend/buy.ts

Querying

Here are some basic examples of how to use APIs to query data. You can find much more methods in the doc: https://multichain.redoc.ly/ or right in the typescript typings.

//Fetch items by creator
sdk.apis.item.getItemsByCreator({ creator: someAddress })

//Fetch activity (events) by the Item
sdk.apis.activity.getActivitiesByItem({ type: ["TRANSFER"], contract, tokenId })

//etc. Please explore SDK APIs and openAPI docs

Executing actions

You can use SDK to create (mint), trade, transfer, and burn NFTs. All actions are handled in the same manner:

• You invoke function from SDK (e.g.: mint)
• Async function returns the so-called PrepareResponse (it's different for different actions)
• PrepareResponse contains all needed information to show the user a form (for example, response for sale contains all supported currency types)
• Collect input from the user (show form and let the user enter the data)
• Pass this data to submit Action

See how to use common SDK functionality in our documentation:

• Quick Start
• Create collection
• Mint NFT
• Sell NFTs
• Mint and Sell
• Create and Accept Bid
• Transfer tokens
• Burn tokens
• Get wallet balance
• Contract Addresses
• Search Capabilities

Troubleshooting

Possible errors after npm install -D @rarible/sdk command:

Failed to replace env in config: ${NPM_TOKEN}

error An unexpected error occurred: "Failed to replace env in config: ${NPM_TOKEN}".

Solution

Type in the command line while in the project folder:

rm -f ./.npmrc

Adding the dependency to the workspace

error Running this command will add the dependency to the workspace root rather than the workspace itself, which might not be what you want - if you really meant it, make it explicit by running this command again with the -W flag (or --ignore-workspace-root-check).

Solution

Type in the command line while in the project folder:

yarn add @rarible/sdk -D -W

darwin-arm64.tar.gz downloading error

...
node-pre-gyp info it worked if it ends with ok
node-pre-gyp info using node-pre-gyp@0.13.0
node-pre-gyp info using node@16.13.1 | darwin | arm64
node-pre-gyp WARN Using request for node-pre-gyp https download
...
node-pre-gyp http GET https://node-webrtc.s3.amazonaws.com/wrtc/v0.4.7/Release/darwin-arm64.tar.gz
node-pre-gyp http 404 https://node-webrtc.s3.amazonaws.com/wrtc/v0.4.7/Release/darwin-arm64.tar.gz
node-pre-gyp ERR! install error
node-pre-gyp ERR! stack Error: 404 status code downloading tarball https://node-webrtc.s3.amazonaws.com/wrtc/v0.4.7/Release/darwin-arm64.tar.gz
...

Solution

Type in the command line while in the project folder:

sudo npm install -g n
sudo n 14.17.6

Suggestions

You are welcome to suggest features and report bugs found!

Contributing

The codebase is maintained using the "contributor workflow" where everyone without exception contributes patch proposals using "pull requests" (PRs). This facilitates social contribution, easy testing, and peer review.

See more information on CONTRIBUTING.md.

License

Rarible Multichain SDK is available under the MIT License.

Note

This is a pre-release version. Backward compatibility is not fully supported before 1.0 release. Backward compatibility is only guaranteed in minor releases.

For example, 0.2.x version may not be compatible with 0.1.x. So, it's advised to include dependencies using package versions (ex. rarible/sdk@0.2.x).