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.

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

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

Usage

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.

import {
  useCreateAuctionListing,
  useContract,
  Web3Button,
} from "@thirdweb-dev/react";
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";

// Your smart contract address
const contractAddress = "{{contract_address}}";

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>
  );
}

Configuration

tokenId

tokenId (required)

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

assetContractAddress

assetContractAddress (required)

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

buyoutBidAmount

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

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.

import {
  useCreateAuctionListing,
  useContract,
  Web3Button,
} from "@thirdweb-dev/react";
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";

// Your smart contract address
const contractAddress = "{{contract_address}}";

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>
  );
}

quantity

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

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

startTimestamp (optional)

A Date object for the start time of the listing.

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

id

endTimestamp (optional)

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

bidBufferBps

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

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.