Prerequisites ⚙️

Install and configure ReservoirKit

SWR powered hooks

These hooks use SWR, a performant lightweight data-fetching hook library. Using SWR means that we can cache requests, batch requests and use powerful features developed and tested by the SWR team. You can utilize hooks across your components without worrying about performance or duplicate network requests. You can also pass in SWR configuration options to each SWR powered hook. Below are the properties returned in each SWR powered hook.

response: The response returned from the api
data: The data extracted from the response
mutate: SWR's mutate function for refreshing data.
error: An api error
isValidating: If there's an ongoing request or revalidation

useCollections
useAttributes
useTrendingCollections
useTrendingMints
useMarketplaceConfigs

Infinite Loading Hooks

The following hooks are built with infinite loading in mind. They expose a some useful methods and properties to build an infinite loading UX, in addition to the properties returned by all SWR infinite powered hooks.

hasNextPage: If there is more data to load
isFetchingInitialData: If the initial data has been fetched or not
isFetchingPage: If data is currently being fetched
fetchNextPage: A method to fetch the next page, takes no parameters.
resetCache: A method to clear the SWR cache, resets the page to 0. Calling fetchNextPage will behave like the first time the hook was called

https://swr.vercel.app/docs/pagination#return-values

useTokens
useListings
useOwnerListings
useBids
useUserBids
useUserListings
useUserTopBids
useCollectionActivity
useUsersActivity
useUserCollections
useUserTokens
useTokenActivity

Utility Hooks

Just like every good tool belt there are usually some utility hooks included. These hooks don't necessarily fetch Reservoir data but they are quite useful.

useReservoirClient

Manually overriding chain endpoint

The hooks above fetch data from the default chain configured in the ReservoirKitProvider, read more on that here. You can also manually override the chainId for all of these hooks to fetch specific data. Please note that the manually overridden chain needs to be in the list of chains passed to the provider.

useTokens

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch token details, using the Tokens endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

const { data: tokens } = useTokens({
  tokens: ["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb:1"],
})

useCollections

This hook is SWR powered. Use this hook to fetch a collection, using the Collections endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

const { data: collection } = useCollections({
  id: "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
})

useCollectionActivity

This hook is SWR powered. Use this hook to fetch a collection's activity, using the Collection Activity endpoint. It takes the collection ID, as the first parameter, an optional query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

const { data: activity } = useCollectionActivity(
  "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"
)

useUsersActivity

This hook is SWR powered. Use this hook to fetch a single user or multiple user's activity, using the Users Activity endpoint. It takes an array of users (i.e. wallet addresses), as the first parameter, an optional query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

const { data: activity } = useUsersActivity(
  ["0xFd03726FD90ccc7386bf62b44Bb594f7cbFB3995"]
)

useTokenActivity

This hook is SWR powered. Use this hook to fetch a token's activity, using the Token Activity endpoint. It takes the collection ID appended to the token ID (collectionID:tokenID), as the first parameter, an optional query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

const { data: activity } = useTokenActivity(
  "0x744df993f93c89801cadbea8a4a3fd2b4a443d2c:1793"
)

useListings

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch listings, using the Asks (listings) endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

 const {
   data: listings,
   fetchNextPage,
   hasNextPage,
 } = useListings({
    contracts: ['0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb'],
 })

To skip this hook, you can pass in false for the enabled parameter. Use the code snippet below:

export default function (
  options: AsksQuery,
  swrOptions: SWRInfiniteConfiguration = {},
  enabled: boolean = true,
  chainId?: number
)

useListings(options, swrOptions, enabled, chainId)

useOwnerListings

This hook is SWR powered and also handles infinite loading UX. The hook is an extension of the useListings hook. It's a convenient way to fetch the listings that belong to the currently connected wallet. The parameters are exactly the same as the aforementioned useListings hook.

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

 const {
   data: listings,
   fetchNextPage,
   hasNextPage,
 } = useOwnerListings()

useReservoirClient

This hook exposes the underlying ReservoirKit client which is in charge of making the underlying execute requests and interacting with web3 interfaces. The hook can also be useful to get the underlying global configuration of ReservoirKit (apiBase, apiKey etc).

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

const client = useReservoirClient()
console.log(client?.apiBase)

It can also be useful to trigger actions in a flexible way. Actions are the underlying execute apis that ReservoirKit's ui triggers. Here's an example of how to trigger the underlying execute/buy api.

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

const client = useReservoirClient()
await reservoirClient.actions
      .buyToken({
        ...
      })
      .then(()=> {})
      .catch(() => {})

useAttributes

This hook is SWR powered. Use this hook to fetch collection attributes, using the All Attributes endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

  const attributes = useAttributes(collectionId)

useBids

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch bids, using the Bids (offers) endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

 const {
   data: bids,
   fetchNextPage,
   hasNextPage,
 } = useBids({
    contracts: ['0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb'],
 })

useUserBids

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch a single user’s bids, using the User Bids (offers) endpoint. It takes in an address, as the first parameter, a query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

 const {
   data: bids,
   fetchNextPage,
   hasNextPage,
 } = useUserBids("0x03508bB71268BBA25ECaCC8F620e01866650532c", {
    contracts: ['0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb'],
 })

useUserTopBids

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch a single user’s top bids, using the User Top Bids endpoint. It takes in a user, as the first parameter, a query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

 const {
   data: bids,
   fetchNextPage,
   hasNextPage,
 } = useUserTopBids('0xF296178d553C8Ec21A2fBD2c5dDa8CA9ac905A00', {})

useUserListings

This hook is SWR powered and also handles infinite loading UX. Use this hook to fetch a single user’s listings, using the User Listings endpoint. It takes in an address, as the first parameter, a query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

 const {
   data: bids,
   fetchNextPage,
   hasNextPage,
 } = useUserListings('0x03508bB71268BBA25ECaCC8F620e01866650532c', {
	 contracts: ['0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb']
 })

useUserCollections

This hook is SWR powered. Use this hook to fetch a single user's collections using the Users Collections endpoint. It takes an address, as the first parameter, an optional query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

const { data: collections } = useUserCollections("0xFd03726FD90ccc7386bf62b44Bb594f7cbFB3995")

useUserTokens

This hook is SWR powered. Use this hook to fetch a single user's tokens using the Users Tokens endpoint. It takes an address, as the first parameter, an optional query object which maps to the same parameters that the API endpoint uses, as the second parameter, and an optional SWR Infinite configuration object, as the third parameter.

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

const { data: tokens } = useUserTokens("0xFd03726FD90ccc7386bf62b44Bb594f7cbFB3995")

useTrendingCollections

This hook is SWR powered. Use this hook to fetch collection attributes, using the Trending Collections endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

const { data: collections } = useTrendingCollections({period: '24h', limit: 1000})

useTrendingMints

This hook is SWR powered. Use this hook to fetch collection attributes, using the Trending Mints endpoint. It takes a query parameter which maps to the same parameters that the api endpoint uses.

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

const { data: mints } = useTrendingMints({period: '24h', limit: 50})

useCurrencyConversion

This hook is SWR powered. Use this hook to fetch a currency conversion from one currency to another, using the Currency Conversions endpoint. Also returns the usd value.

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

const preferredCurrencyConversions = useCurrencyConversions(
  adress,
  chain,
  true //enabled or not
)

useSolverCapacity

This hook is SWR powered. Use this hook to fetch the solver capacity for the base chain, using the Solver Capacity endpoint. It takes an optional ReservoirChain, if not passed it falls back to the active chain.

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

const { data: solverCapacity } = useSolverCapacity(chain)

useMarketplaceConfigs

This hook is SWR powered. Use this hook to fetch marketplace configurations, using the Marketpace Configurations endpoint. It takes a collectionId as well as an optional enabled and chain parameter.

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

const { data: mints } = useMarketplaceConfigs("0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d")

useCart

Make sure you've installed ReservoirKit and followed the installation steps for adding a cart to your application.

This hook interacts with the CartProvider to expose the cart state and some useful methods to manage the cart.

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

  const { data, clear, clearTransaction, validate, remove, add, checkout } =
    useCart((cart) => cart)

The hook takes one parameter, which is a selector. To make the hook performant we've given developers the ability to select a piece of state to get updates on. This means that the hook won't trigger unnecessary rerenders. In the example above we select the whole state but if you simply want to just get the items you can do something like this:

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

  const { data: items } =
    useCart((cart) => cart.items)

The code above will just expose the items and only rerender when the items in the cart change. Let's dig into some of the methods returned by the hook:

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

  const { data, clear, clearTransaction, validate, remove, add, checkout } =
    useCart((cart) => cart)
  const tokens = useTokens({collection: "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"})

//add: Simplified interface
add([{id: "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb:1"}], 1)

//add: Optimized interface
add([tokens[0]], 1)

remove(["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb:1"])
checkout({ ...buyEndpointOptions })
validate()
clear()
clearTransaction()

useDynamicTokens

While you can have a cart and use the useTokens hook to display a grid of tokens, this hook is specifically designed to make it easier to use the cart in a token grid. The hook handles the following things:

• Sorting the tokens if a token in a dynamically priced pool is in the cart
• Automatically returning cart actions from the useCart hook
• Adding a isInCart boolean property to each token to make it easier to display which token is in the cart

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

const { data: tokens, add, remove } = useDynamicTokens({
  collection: "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
})

//Display the tokens in your app