Leverage the BuyModal to purchase a token using ReservoirKit

BuyModal provides an easy way to purchase any NFT at the best price.

Prerequisites ⚙️

Install and configure ReservoirKit.

BuyModal Setup

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={(data, stepData, currentStep) => console.log('Modal Closed')}


Let's dive into the parameters:

triggerA react node that will be presented to the user, usually a button or something clickable.Y
tokenThe token to purchase in the following format: {CONTRACT}:{TOKEN_ID}Y
onConnectWalletA function that beings the connect wallet flow. Use this to prompt your connect modal and continue the ux of connecting the user's wallet.Y
orderIdThe specific orderId to purchase for the given token.N
feesOnTopBpsUsed to conditionally apply a referral fee on top of an order when purchasing. The parameter is an array of strings with the referrer and the fee separated by a colon: ['0xabc:250']. The fee is in bps. The fee currency will follow the default rules for the execute buy endpoint feesOnTop parameter. This takes precedence over the feesOnTopUsd.N
feesOnTopUsdUsed to conditionally apply a referral fee on top of an order when purchasing. The parameter is an array of strings with the referrer and the fee separated by a colon: ['0xabc:1000000']. The fee is a flat fee in the atomic unit of usd (6 decimals). It will then be converted to the purchase currency to match the same value in USD. So for example if you have 1000000 configured (1 usd) and the total price is in ETH the fee applied will be ~0.00054 ETH (or whatever is equivalent to 1 usd in realtime).N
normalizeRoyaltiesUse this to ensure that royalties are added to the order. If royalties are missing from the order then the correct royalties are added on top. If unspecified then the global setting will be used if provided.N
openStateThis is a state tuple from react's useState, you can use this to programmatically open or close the modal. The modal will use this state when determining if the modal is open or closed.N
copyOverridesAn object containing copy overrides for titles and ctas contained in the modal. Refer to the ModalCopy type for which tokens map to what copy.N
walletClientA valid WalletClient from viem or a ReservoirWallet generated from an adapter. Learn more about adaptersN
chainIdThe chain id to force the modal to render, ensure that this is a chain that is configured in the ReservoirKit provider. If not specified then the active chain configured in the ReservoirKitProvider will be used.N
usePermitUse permit to avoid approvals, enable this if you want to support gasless meta transactions. Ensure that you're using gelato via the adapter and you have usdc as the only paymentToken or you may run into issues.N
defaultQuantityThe default quantity to open the modal with, if the quantity available is higher than the default then the maximum is prefilled.N
executeBuyOptionsAn object mapping to the buyToken options, above props will override these values. The options map directly to the execute buy api or the buyToken sdk method. Only use these options if you know what you are doing as they may impact the ui and require custom ui, not all options are compatible.N
onPurchaseCompleteTriggered when the purchase was completed successfully, returns some useful data about the purchase.N
onPurchaseErrorTriggered when the purchase resulted in an error, returns the error and the purchase data.N
onCloseTriggered when the modal was closed. Returns some useful data about the purchase as well as the step data and the current step.N

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.


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