Rarible Protocol SDK enables applications to easily interact with Rarible Protocol: query, issue, trade NFTs on any blockchain supported.
Currently, these blockchains are supported:
- Ethereum
- Flow
- Tezos
- Polygon
Install Protocol SDK:
yarn add @rarible/sdk -D
yarn add web3
Install SDK Wallet Connector:
yarn add @rarible/connector
# optional: add additional connectors
yarn add @rarible/connector-walletconnect
yarn add @rarible/connector-fortmatic
# check other @rarible/connector-* packages to see what's supported
SDK is written in TypeScript. You can use typings to explore SDK possibilities.
import { createRaribleSdk } from "@rarible/sdk"
import { Blockchain } from "@rarible/api-client"
To use SDK, you have to create a Wallet — abstraction to communicate with real blockchain wallets.
- Use Rarible SDK Wallet Connector
Create Connector
, add all needed ConnectionProvider's
import { Connector, InjectedWeb3ConnectionProvider, DappType } from "@rarible/connector"
import { WalletConnectConnectionProvider } from "@rarible/connector-walletconnect"
// create providers with the required options
const injected = new InjectedWeb3ConnectionProvider()
const walletConnect = new WalletConnectConnectionProvider()
// create connector and push providers to it
const connector = Connector
.create([injected, walletConnect])
// subscribe to connection status
connector.connection.subscribe((con) =>
console.log("connection: " + JSON.stringify(con))
)
const options = await connector.getOptions(); // get list of available option
await connector.connect(options[0]); // connect to selected provider
- Initialize wallets
See code example in the repository for initialize wallets with Wallet Connector.
Ethereum / Polygon
import Web3 from "web3"
import { Web3Ethereum } from "@rarible/web3-ethereum"
import { EthereumWallet } from "@rarible/sdk-wallet"
const web3 = new Web3(provider)
const web3Ethereum = new Web3Ethereum({ web3 })
const ethWallet = new EthereumWallet(web3Ethereum)
// 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) for using Flow. See more information on Configure fcl.
Tezos
Use Wallet Connector to initialize wallet for Tezos.
The SDK was designed for use on the frontend side. To use the SDK on the server side (backend):
-
Install packages:
yarn add tslib@2.3.1 yarn add form-data yarn add node-fetch
-
Add dependencies:
global.FormData = require("form-data") global.window = { fetch: require("node-fetch"), dispatchEvent: () => { }, } global.CustomEvent = function CustomEvent() { return }
Here are some basic examples of how to use APIs to query data. You can find much more methods in the doc: http://api-dev.rarible.org/v0.1/doc 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
You can use SDK to create(mint), trade, transfer, 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)
- this PrepareResponse contains all needed information to show the user a form (for example, response for sell 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
You can find more information about Action abstraction in the dedicated GitHub readme. Or you can use it as a regular async function and work with regular Promises.
//Invoke mint function. It will return a PrepareResponse with some useful information
const {
multiple, // Does the smart contract supports multiple editions or not
supportsRoyalties, // Does the smart contract supports royalties or not
supportsLazyMint, // Does the smart contract supports lazy minting or not
} = await sdk.order.mint({ itemId })
//collect information from the user (show the form etc)
//then use submit Action to execute this action
const orderId = await submit({
collection, // Information about the NFT collection (id, type, name, etc.)
uri, // URI of the NFT token
supply, // Amount of the NFT tokens to be minted
lazyMint, // Minting the NFT token off-chain until the moment it's sold to its first buyer
creators, // Address of the NFT creator
royalties, // Royalties from the NFT contract for the creator
})
First, sell-order should be created:
//Invoke sell function. It will return a PrepareResponse with some useful information
const {
supportedCurrencies, // list of currency types supported by the blockchain (ETH, ERC20 etc.)
maxAmount, // max amount of the NFT that can be put on sale
baseFee, // present it to a user, it's a base protocol fee that is taken on the trade
submit, // use this Action to submit information after user input
} = await sdk.order.sell({ itemId })
//collect information from the user (show the form etc)
//then use submit Action to execute this action
const orderId = await submit({
amount, // amount of NFTs to put on sale: must be <= maxAmount
price, // price of the NFT being sold (0.2 for example if price is 0.2 ETH)
currency, // curreny (ETH or specific ERC20 or Tez, Flow etc)
originFees, // optional array of origin fees (TODO add link to origin fees explanation)
payouts, // optional array of payouts (TODO add link to explanation)
})
When the order is created, it's propagated to all Protocol users. Any app can initiate the process to fill the order.
const {
maxAmount, // max amount of NFTs available for purchase
baseFee, // fee that will be taken from the buyer
originFeeSupport, // if smart contract supports custom origin fees
payoutsSupport, // if smart contract supports payouts
supportsPartialFill, // if smart contract supports partial fills
} = await sdk.order.fill({ order }) //you can also use orderId if you don't have order
//collect information from the user
//then submit
const tx = await submit({
amount, // amount to buy
originFees, // optional origin fees (TODO add link to explanation)
payouts, // optional payouts (TODO add link)
infiniteApproval, // if sdk should use infinite approval (usually applicable for ERC-20)
})
After the call submits action, you will get IBlockchainTransaction object which can be used to watch for transaction status (error or confirmed).
A bid is just an unmatched buy order. The bidder submits the order to the indexer. The seller accepts it by creating a matched order.
//Invoke bid function. It will return a PrepareResponse with some useful information
const {
supportedCurrencies, // list of currency types supported by the blockchain (ETH, ERC20 etc.)
multiple, // does the smart contract supports multiple editions or not
maxAmount, // max amount of the NFT that can be put on sale
baseFee, // present it to a user, it's a base protocol fee that is taken on the trade
submit, // use this Action to submit information after user input
getConvertableValue // see description below
} = await sdk.order.bid({ itemId })
/*
Get the value of the native token that will be converted if you use a wrapped token (Wrapped Ether for Ethereum, wXTZ for Tezos, etc.) to place a bid
Example of returned values, when passed wrapped token contract:
1. Returns "undefined" if you have sufficient funds to make a bid
2. Returns if needed to convert funds to wrapped token (ex. Wrapped Ether).
The value will be converted automatically after invoking the "submit" function. Convertable value also includes origin fees
{
type: "convertable",
currency: { '@type': 'ETH' },
value: BigNumber {...}
}
3. Returns if native token funds is insufficient for convert operation
{
type: "insufficient",
currency: { '@type': 'ETH' },
value: BigNumber {...}
}
The Result of invoking getConvertableValue function is always undefined if you pass a non-wrapped token contract because converting of non-wrapped tokens is not supported.
*/
getConvertableValue({
assetType: { "@type": "ERC20", contract: wethContract }, // payment asset
price: "0.00000001", // price per 1 NFT
amount: 4, // amount of NFTs to bid (total needed value for bid calculated as price * amount)
originFees: [{
account: feeAccount,
value: 250, // fee percent in range 0-10000, where 0 - 0%, 250 - 2,5%, 5000 - 50%, 10000 - 100%
}], // origin fees, by default []
})
//collect information from the user (show the form etc.)
//then use submit Action to execute this action
const orderId = await submit({
amount, // amount of NFTs to put on sale: must be <= maxAmount
price, // price of the NFT being sold (0.2 for example if price is 0.2 ETH)
currency, // curreny (ETH or specific ERC20 or Tez, Flow etc)
originFees, // optional array of origin fees (TODO add link to origin fees explanation)
payouts, // optional array of payouts (TODO add link to explanation)
})
When the order is created, it's propagated to all Protocol users. Any app can initiate the process to fill the order.
Use sdk.order.buy()
or sdk.order.acceptBid()
methods to fill sell or bid orders.
const {
maxAmount, // max amount of NFTs available for purchase
baseFee, // fee that will be taken from the buyer
originFeeSupport, // if smart contract supports custom origin fees
payoutsSupport, // if smart contract supports payouts
supportsPartialFill, // if smart contract supports partial fills
} = await sdk.order.buy({ order }) //you can also use orderId if you don't have order
//collect information from the user
//then submit
const tx = await submit({
amount, // amount to buy
originFees, // optional origin fees (TODO add link to explanation)
payouts, // optional payouts (TODO add link)
infiniteApproval, // if sdk should use infinite approval (usually applicable for ERC-20)
})
After the call submits action, you will get IBlockchainTransaction object which can be used to watch for transaction status (error or confirmed).
//Invoke transfer function. It will return a PrepareResponse with some useful information
const {
multiple, // Does the smart contract supports multiple editions or not
maxAmount, // Max amount of NFTs available for transfer
} = await sdk.order.transfer({ itemId })
//collect information from the user (show the form etc.)
//then use submit Action to execute this action
const orderId = await submit({
to, // Recipient NFT address
amount, // Amount of NFTs to transfer
})
//Invoke burn function. It will return a PrepareResponse with some useful information
const {
multiple, // Does the smart contract supports multiple editions or not
maxAmount, // Max amount of NFTs available for burn
} = await sdk.order.burn({ itemId })
//collect information from the user (show the form etc.)
//then use submit Action to execute this action
const orderId = await submit({
amount, // Amount of NFTs to burn
})
import { Blockchain } from "@rarible/api-client"
//Convert 0.1 ETH to 0.1 wETH (Wrapped Ether)
const tx = await sdk.balances.convert(Blockchain.ETHEREUM, true, "0.1")
await tx.wait()
//Or unwrap 0.1 wETH to 0.1 ETH
const tx = await sdk.balances.convert(Blockchain.ETHEREUM, false, "0.1")
await tx.wait()
import { toContractAddress, toUnionAddress } from "@rarible/types";
import { Blockchain } from "@rarible/api-client";
const walletAddress = toUnionAddress("ETHEREUM:0x...")
//Get balance of ethereum wallet
const ethBalance = await sdk.balances.getBalance(walletAddress, {
"@type": "ETH"
})
//Get balance of polygon wallet
const polygonBalance = await sdk.balances.getBalance(walletAddress, {
"@type": "ETH",
blockchain: Blockchain.POLYGON,
})
//Get wallet balance of erc20 contract
const erc20Balance = await sdk.balances.getBalance(walletAddress, {
"@type": "ERC20",
contract: toContractAddress("ETHEREUM:0x...")
})
"getBalance" method is not supports balance of NFT-tokens
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).