Add Buying

Learn how to buy a token using ReservoirKit.

Prerequisites ⚙️

Install and configure ReservoirKit.


ReservoirKit provides a simple to configure modal for facilitating token purchases in your react app. Below is an example of a simple BuyModal setup.

import { BuyModal } from '@reservoir0x/reservoir-kit-ui'

      Buy Token
  onPurchaseComplete={(data) => console.log('Purchase Complete')}
  onPurchaseError={(error, data) => console.log('Transaction Error', error, data)}
  onClose={() => console.log('Modal Closed')}


Let's dive into the parameters. You'll need to provide an element to trigger the modal, this can be any valid html element. Next you'll want to provide a collectionId and a tokenId. These can be set to undefined until the data is ready.

It can be useful to conditionally apply a referral fee on top of an order when purchasing. The BuyModal exposes two props to meet this need: referrer and referrerFeeBps. When supplied these props will override the globally set configuration and set the fee on top of the order, we call this the referrer fee.

Finally you can set some optional callbacks:

onPurchaseComplete: Triggered when the purchase was completed successfully, returns some useful data about the purchase.

onPurchaseError: Triggered when the purchase resulted in an error, returns the error and the purchase data.

onClose: Triggered when the modal was closed.

Conditional Rendering

ReservoirKit's BuyModal doesn't take care of conditionally showing the button/modal based on if the item is purchasable, we leave that logic up to the developer. Below are the requirements for purchasing and how to go about getting that data:

  • The user needs to have a connected wallet. You can check this by looking for a signer from the useSigner wagmi hook.
  • The user cannot be the owner of the token, you can check this by comparing the current address and the address of the owner.
  • The token must have a valid listing, you can check if the floorAskPrice is available for that token using the Tokens api endpoint.

Custom BuyModal

The BuyModal also comes with a custom renderer which can be used to just get the data layer that the BuyModal uses internally to handle the underlying business logic. With the renderer you can rebuild the UI completely to your liking. Below is an example of how it works in practice.

import { BuyModal, BuyStep } from '@reservoir0x/reservoir-kit-ui'

  }) => {
    { Your Custom React Elements }

The custom BuyModal takes a few parameters like before with one additional one being the open parameter. This is because there is no trigger, you have control over what sort of modal you want this to eventually live in and how to trigger that modal. You'll have the ability to add a custom button with a custom handler, etc. The custom BuyModal then passes some key data into the children which we parse above and use in our custom UI. It's also important to note the BuyStep here which is used to manage the internal state of the BuyModal's logic. You can decide to use all or some of the data passed into your custom implementation.


Nice job!

Now that we've added a buy modal to your dApp, let's customize the theme to match your brand.

Did this page help you?