useListings

Hook for getting all listings (including expired ones) from a Marketplace contract.

Marketplace V3

Note: this hook is only available for Marketplace contracts.

If you are using Marketplace V3, use useListingsV3 instead.

import { useListings } from "@thirdweb-dev/react";

Usage

Provide your marketplace contract and an optional filter you wish to use as the arguments.

import { useContract, useListings } from "@thirdweb-dev/react";

const contractAddress = "{{contract_address}}";

function App() {
  const { contract } = useContract(contractAddress, "marketplace");
  const { data, isLoading, error } = useListings(contract);
}

Configuration

filter (optional)

import { useContract, useListings } from "@thirdweb-dev/react";

const contractAddress = "{{contract_address}}";

function App() {
  const { contract } = useContract(contractAddress, "marketplace");
  const { data, isLoading, error } = useListings(
    contract,
    {
      count: 100, // number of listings to fetch
      offeror: "{{offeror_address}}", // only show listings with offers from this address
      seller: "{{seller_address}}", // only show listings where this address is the seller
      start: 0, // start at this listing index (pagination)
      tokenContract: "{{token_contract_address}}", // only show listings from this collection
      tokenId: "{{token_id}}", // only show listings for this token
    },
  );
}

Return Value

The hook's data property, once loaded, is an array of listing objects.

The exact shape of each object depends on the type of listing.

For auctions, it will be a AuctionListing object. For direct listings, it will be a DirectListing object.

(AuctionListing | DirectListing)[] | undefined;

You can use the shared type property to determine which type of listing is being returned.

interface AuctionListing {
  /**
   * The id of the listing
   */
  id: string;
  /**
   * The address of the asset being listed.
   */
  assetContractAddress: string;
  /**
   * The ID of the token to list.
   */
  tokenId: BigNumberish;
  /**
   * The asset being listed.
   */
  asset: NFTMetadata;
  /**
   * The start time of the listing.
   */
  startTimeInEpochSeconds: BigNumberish;
  /**
   * Number of seconds until the auction expires.
   */
  endTimeInEpochSeconds: BigNumberish;
  /**
   * The quantity of tokens to include in the listing.
   *
   * For ERC721s, this value should always be 1 (and will be forced internally regardless of what is passed here).
   */
  quantity: BigNumberish;
  /**
   * The address of the currency to accept for the listing.
   */
  currencyContractAddress: string;
  /**
   * The reserve price is the minimum price that a bid must be in order to be accepted.
   */
  reservePrice: BigNumber;
  /**
   * The buyout price of the listing.
   */
  buyoutPrice: BigNumber;
  /**
   * The `CurrencyValue` of the buyout price listing.
   * Useful for displaying the price information.
   */
  buyoutCurrencyValuePerToken: CurrencyValue;
  /**
   * The `CurrencyValue` of the reserve price.
   * Useful for displaying the price information.
   */
  reservePriceCurrencyValuePerToken: CurrencyValue;
  /**
   * The address of the seller.
   */
  sellerAddress: string;
  type: ListingType.Auction;
}

interface DirectListing {
  /**
   * The id of the listing.
   */
  id: string;
  /**
   * The address of the asset being listed.
   */
  assetContractAddress: string;
  /**
   * The ID of the token to list.
   */
  tokenId: BigNumberish;
  /**
   * The asset being listed.
   */
  asset: NFTMetadata;
  /**
   * The start time of the listing.
   */
  startTimeInSeconds: BigNumberish;
  /**
   * Number of seconds until the listing expires.
   */
  secondsUntilEnd: BigNumberish;
  /**
   * The quantity of tokens to include in the listing.
   *
   * For ERC721s, this value should always be 1 (and will be forced internally regardless of what is passed here).
   */
  quantity: BigNumberish;
  /**
   * The address of the currency to accept for the listing.
   */
  currencyContractAddress: string;
  /**
   * The `CurrencyValue` of the listing. Useful for displaying the price information.
   */
  buyoutCurrencyValuePerToken: CurrencyValue;
  /**
   * The buyout price of the listing.
   */
  buyoutPrice: BigNumber;
  /**
   * The address of the seller.
   */
  sellerAddress: string;
  type: ListingType.Direct;