useCreateAuctionListing

Hook for creating an auction listing on a Marketplace or MarketplaceV3 smart contract.

Auction listings hold the NFTs in escrow; requiring the seller to transfer the NFTs to the marketplace contract as part of the listing creation process.

Provide your Marketplace or MarketplaceV3 contract as the argument to the hook.

Then, provide the information about the listing you want to create as the argument to the mutation.

Example


import {
  useCreateAuctionListing,
  useContract,
  Web3Button,
} from "@thirdweb-dev/react";
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";
 
function App() {
  const { contract } = useContract(contractAddress, "marketplace-v3");
  const {
    mutateAsync: createAuctionListing,
    isLoading,
    error,
  } = useCreateAuctionListing(contract);
 
  return (
    <Web3Button
      contractAddress={contractAddress}
      action={() =>
        createAuctionListing({
          tokenId: "{{token_id}}", // The ID of the token to list.
          assetContractAddress: "{{asset_contract_address}}", // The contract address of the asset being listed.
          currencyContractAddress: NATIVE_TOKEN_ADDRESS, // The address of the currency to accept for the listing.
          quantity: "{{quantity}}",
          startTimestamp: new Date(),
          buyoutBidAmount: "{{buyout_bid_amount}}",
          minimumBidAmount: "{{minimum_bid_amount}}",
          endTimestamp: new Date(),
          bidBufferBps: "{{bid_buffer_bps}}",
          timeBufferInSeconds: "{{time_buffer_in_seconds}}",
        })
      }
    >
      Create Auction Listing
    </Web3Button>
  );
}


function useCreateAuctionListing(
  contract: RequiredParam<TMarketplace>,
): UseMutationResult<
  TransactionResultWithId,
  unknown,
  TMarketplace extends Marketplace ? NewAuctionListing : {},
  unknown
>;

Parameters

Instance of a Marketplace contract

Type


let contract: RequiredParam<TMarketplace>;

Returns


let returnType: UseMutationResult<
  TransactionResultWithId,
  unknown,
  TMarketplace extends Marketplace ? NewAuctionListing : {},
  unknown
>;

A mutation object to create a new auction listing.


const { mutateAsync, isLoading, error } =
  useCreateAuctionListing(contract);

options

The mutation function takes an object of type NewAuctionListing or EnglishAuctionInputParams as its argument which contains the following properties:

tokenId (required)

The token ID of the NFT you are listing for auction.

assetContractAddress (required)

The smart contract address of the NFT you are listing for auction.

buyoutBidAmount (required)

The price to buy each token in the listing.

For ERC721 NFTs, this is the price to buy the NFT outright.
For ERC1155 NFTs, this is the price to 1 quantity of the NFT.

currencyContractAddress (optional)

The address of the currency you want users to pay with and make bids in.

You likely want to use the token native to the chain you are on, e.g. Ether on Ethereum.

To do that, you can import the NATIVE_TOKEN_ADDRESS constant from @thirdweb-dev/sdk .

The default value is NATIVE_TOKEN_ADDRESS .

quantity (optional)

How many tokens to include in the listing.

For ERC721 NFTs, this is always 1 .
For ERC1155 NFTs, this is the quantity of tokens to include in the listing.

The default value is 1 .

minimumBidAmount (required)

The minimum price that a bid must be in order to be placed on the listing, per token.

Bids that are lower than the reserve price will be rejected by the contract.

The default value is 0 .

startTimestamp (optional)

A Date object for the start time of the listing.

The default value is new Date() , which is the current time.

endTimestamp (optional)

A Date object for the end time of the listing (when the listing will expire).

bidBufferBps (optional)

Bid buffer in basis points (1/100th of a percent).

The bid buffer is what percentage higher the next bid must be than the current highest bid.

For example, if you set a bid buffer of 100 , then the next bid must be at least 1% higher than the current highest bid.

timeBufferInSeconds (optional)

Time buffer in seconds.

The time buffer is how much time is added to the listing when a new bid is placed.

This is to prevent users from placing a bid at the last second and winning the auction.