Marketplace
When using the Marketplace smart contract, additional top-level functionality is available to use.
To access the top-level functionality, provide the marketplace contract type when creating the contract instance:
const contract = await sdk.getContract(
"{{contract_address}}",
"marketplace", // Provide the "marketplace" contract type
);
allowListingFromAnyAsset
Set the marketplace to accept the listing of NFTs from any smart contract.
const txResult = await contract.allowListingFromAnyAsset();
allowListingFromSpecificAssetOnly
Set the marketplace to accept the listing of only NFTs from a specific NFT smart contract.
const txResult = await contract.allowListingFromSpecificAssetOnly(
"{{asset_contract_address}}",
);
Configuration
Auction - buyoutListing
const txResult = await contract.auction.buyoutListing("{{listing_id}}");
Configuration
Auction - cancelListing
Cancel a listing that you made.
Note: Auction listings cannot be canceled if a bid has been made.
const txResult = await contract.auction.cancelListing("{{listing_id}}");
Configuration
Auction - closeListing
Closes the auction and execute the sale for the buyer or the seller.
When an auction is finished, the closeAuction needs to be called for both the buyer and the seller.
The closeAuction function takes in a closeFor value as the second parameter.
- When the
closeForvalue is the address of the buyer, they are transferred the funds from the highest bid. - When the
closeForvalue is the address of the seller, the NFT is transferred to them.
Any wallet address can call this function once an auction has completed.
const txResult = await contract.auction.closeListing(
"{{listing_id}}",
"{{wallet_address}}", // Buyer or seller wallet address
);
Configuration
Auction - createListing
List an NFT for sale in an auction listing on the marketplace.
// If you want to use the native token as the currency, import the NATIVE_TOKEN_ADDRESS constant
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";
const tx = await contract.auction.createListing({
assetContractAddress: "{{contract_address}}", // address of the contract the asset you want to list is on
tokenId: "{{token_id}}", // token ID of the asset you want to list
startTimestamp: new Date(), // when should the listing open up for offers
listingDurationInSeconds: 86400, // how long the listing will be open for in seconds
quantity: "{{quantity}}", // how many of the asset you want to list
currencyContractAddress: NATIVE_TOKEN_ADDRESS, // address of the currency contract that will be used to pay for the listing
buyoutPricePerToken: "{{price_to_buy}}", // how much people would have to bid to instantly buy the asset
reservePricePerToken: "{{minimum_bid_price}}", // the minimum bid that will be accepted for the token
});
Configuration
assetContractAddress
The address of the NFT smart contract that you are listing.
Must be a string.
tokenId
The token ID of the NFT to list for sale.
Must be a string, number, or BigNumber.
startTimestamp
The date and time that the listing should start.
Must be a Date object.
listingDurationInSeconds
How long the auction is open for, in seconds.
Must be a string, number, or BigNumber.
quantity
The quantity of the NFT to list for sale.
Only relevant for ERC1155 NFTs. For ERC721 NFTs, this value should be 1.
Must be a string, number, or BigNumber.
currencyContractAddress
The address of the currency contract that will be used to pay for the listing.
To use the native currency, use the NATIVE_TOKEN_ADDRESS constant.
Must be a string.
buyoutPricePerToken
The price that users must pay to purchase the NFT from the auction, immediately closing the auction and executing a sale event for both buyer and seller.
Must be a string, number, or BigNumber.
reservePricePerToken
The minimum bid that will be accepted for the NFT.
Bids below this amount cannot be placed on the auction.
Must be a string, number, or BigNumber.
Auction - executeSale
Close the auction for both buyer and seller.
This means that the NFT is transferred to the buyer, and the seller is paid the amount of the winning bid.
const txResult = await contract.auction.executeSale("{{listing_id}}");
Configuration
Auction - getBidBufferBps
View the current bid buffer set on the marketplace.
The bid buffer is what percentage higher the next bid must be than the current highest bid.
The value is returned in basis points format, i.e. 100 basis points is equal to 1%.
const bidBufferBps = await contract.auction.getBidBufferBps();
Configuration
Auction - getListing
Get the details of a listing using the listing ID.
const listing = await contract.auction.getListing("{{listing_id}}");
Configuration
listingId
The ID of the listing to get the details for.
Must be a string, number, or BigNumber.
Return Value
Returns an AuctionListing object, containing the following properties:
{
/**
* 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;
}
Auction - getMinimumNextBid
Get the value that the next bid must be in order to be accepted.
- If there is no current bid, this value is the reserve price.
- If there is a current bid, this value is the current bid plus the bid buffer.
const minimumNextBid = await contract.auction.getMinimumNextBid(
"{{listing_id}}",
);
Configuration
Auction - getWinner
Get the address that won an auction after an auction has ended.
const winner = await contract.auction.getWinner("{{listing_id}}");
Configuration
Auction - getWinningBid
Get the current highest bid of an active auction.
const winningBid = await contract.auction.getWinningBid("{{listing_id}}");
Configuration
listingId
The ID of the listing to get the winning bid for.
Must be a string, number, or BigNumber.
Return Value
The current highest bid of the auction.
{
/**
* The id of the listing.
*/
listingId: BigNumberish;
/**
* The address of the buyer who made the offer.
*/
buyerAddress: string;
/**
* The quantity of tokens to be bought.
*/
quantityDesired: BigNumberish;
/**
* The amount of coins offered per token.
*/
pricePerToken: BigNumber;
/**
* The `CurrencyValue` of the listing. Useful for displaying the price information.
*/
currencyValue: CurrencyValue;
/**
* The currency contract address of the offer token.
*/
currencyContractAddress: string;
}
Auction - makeBid
Place a bid on an auction listing.
const txResult = await contract.auction.makeBid(
"{{listing_id}}",
"{{bid_amount}}",
);
Configuration
Auction - updateListing
Update the listing details of an auction listing.
// If you want to use the native token as the currency, import the NATIVE_TOKEN_ADDRESS constant
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";
const txResult = await contract.auction.updateListing({
id: "{{listing_id}}", // The listing you want to update
// New information about the listing (see "createListing" for more details)
assetContractAddress: "{{contract_address}}", // address of the contract the asset you want to list is on
tokenId: "{{token_id}}", // token ID of the asset you want to list
startTimestamp: new Date(), // when should the listing open up for offers
listingDurationInSeconds: 86400, // how long the listing will be open for in seconds
quantity: "{{quantity}}", // how many of the asset you want to list
currencyContractAddress: NATIVE_TOKEN_ADDRESS, // address of the currency contract that will be used to pay for the listing
buyoutPricePerToken: "{{price_to_buy}}", // how much people would have to bid to instantly buy the asset
reservePricePerToken: "{{minimum_bid_price}}", // the minimum bid that will be accepted for the token
});
Configuration
Provide an id property to specify the listing you want to update.
See createListing for details that you can update about the listing.
Direct - acceptOffer
Accept an offer placed on your direct listing.
const txResult = await contract.direct.acceptOffer(
"{{listing_id}}",
"{{wallet_address_of_offeror}}",
);
Configuration
Direct - buyoutListing
Buy the NFT(s) for sale on a direct listing.
const txResult = await contract.direct.buyoutListing(
"{{listing_id}}",
"{{quantity}}",
);
Configuration
listingId
The ID of the listing to buyout.
Must be a string, number, or BigNumber.
quantity
The quantity of NFTs to buy from the listing.
Only applicable for ERC1155 NFTs. For ERC721 NFTs, this should be 1.
Must be a string, number, or BigNumber.
receiver (optional)
Optionally, buy the NFTs for a different wallet address other than the connected wallet.
Must be a string.
Direct - cancelListing
Cancel a direct listing you created.
Direct listings can be canceled at any time, unless a buyout has already been made.
const txResult = await contract.direct.cancelListing("{{listing_id}}");
Configuration
Direct - createListing
List an NFT for sale on the marketplace for direct purchase.
// If you want to use the native token as the currency, import the NATIVE_TOKEN_ADDRESS constant
import { NATIVE_TOKEN_ADDRESS } from "@thirdweb-dev/sdk";
const tx = await contract.direct.createListing({
assetContractAddress: "0x...", // address of the contract the asset you want to list is on
tokenId: "0", // token ID of the asset you want to list
startTimestamp: new Date(), // when should the listing open up for offers
listingDurationInSeconds: 86400, // how long the listing will be open for
quantity: 1, // how many of the asset you want to list
currencyContractAddress: NATIVE_TOKEN_ADDRESS, // address of the currency contract that will be used to pay for the listing
buyoutPricePerToken: "1.5", // how much the asset will be sold for
});
Configuration
assetContractAddress
The address of the NFT smart contract the asset you want to list is on.
Must be a string.
tokenId
The token ID of the NFT you want to list.
Must be a string, number, or BigNumber.
startTimestamp
The date and time when the listing should open up for offers.
Must be a Date object.
listingDurationInSeconds
How long the listing is open for, in seconds.
Must be a string, number, or BigNumber.
quantity
The quantity of NFTs to list.
Only applicable for ERC1155 NFTs. For ERC721 NFTs, this should be 1.
Must be a string, number, or BigNumber.
currencyContractAddress
The address of the currency contract that will be used to pay for the listing.
To use the native token, use the NATIVE_TOKEN_ADDRESS constant.
Must be a string.
buyoutPricePerToken
The price that users can buy the NFT for.
Must be a string, number, or BigNumber.
Direct - getActiveOffer
Get an active offer on a listing from a specific wallet address, if there is one.
const offer = await contract.direct.getActiveOffer(
"{{listing_id}}",
"{{wallet_address}}",
);
Configuration
listingId
The ID of the listing to get the active offer for.
Must be a string, number, or BigNumber.
offerorAddress
The wallet address of the offeror.
Must be a string.
Return Value
If there is no active offer made by the offerorAddress, returns undefined.
Otherwise, returns an Offer object with the following properties:
{
/**
* The id of the listing.
*/
listingId: BigNumberish;
/**
* The address of the buyer who made the offer.
*/
buyerAddress: string;
/**
* The quantity of tokens to be bought.
*/
quantityDesired: BigNumberish;
/**
* The amount of coins offered per token.
*/
pricePerToken: BigNumber;
/**
* The `CurrencyValue` of the listing. Useful for displaying the price information.
*/
currencyValue: CurrencyValue;
/**
* The currency contract address of the offer token.
*/
currencyContractAddress: string;
}
Direct - getListing
Get a direct listing by its ID.
const listing = await contract.direct.getListing("{{listing_id}}");
Configuration
listingId
The ID of the listing to get.
Must be a string, number, or BigNumber.
Return Value
Returns a DirectListing object containing the following properties:
{
/**
* 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;
}
Direct - isStillValidListing
Check if a direct listing is still valid, meaning:
The asset holder has not transferred the asset to another wallet The asset holder has not burned the asset The asset holder has not removed the approval on the marketplace
const isValid = await contract.direct.isStillValidListing("{{listing_id}}");
Configuration
Direct - makeOffer
Make an offer to buy an NFT for a certain price on a direct listing.
const txResult = await contract.direct.makeOffer(
"{{listing_id}}",
"{{quantity}}",
"{{currency_contract_address}}",
"{{price_per_token}}",
new Date(Date.now() + 60 * 60 * 24 * 1000), // e.g offer expires 1 day from now
);
Configuration
listingId
The ID of the listing to make an offer for.
Must be a string, number, or BigNumber.
quantity
The quantity of NFTs to buy.
Only applicable for ERC1155 NFTs. For ERC721 NFTs, this should be 1.
Must be a string, number, or BigNumber.
currencyContractAddress
The address of the currency contract that will be used to pay for the listing.
To use the native token, use the NATIVE_TOKEN_ADDRESS constant.
Must be a string.
pricePerToken
The price to offer to buy the NFT for.
Must be a string, number, or BigNumber.
expiresAt (optional)
The time at which the offer expires.
If not provided, the offer will never expire (uses max possible timestamp MaxUint256).
Must be a Date object.
Direct - updateListing
Update a direct listing.
const txResult = await contract.direct.updateListing({
id: "{{listing_id}}", // The listing you want to update
// The new information about the listing
assetContractAddress: "0x...", // address of the contract the asset you want to list is on
tokenId: "0", // token ID of the asset you want to list
startTimestamp: new Date(), // when should the listing open up for offers
listingDurationInSeconds: 86400, // how long the listing will be open for
quantity: 1, // how many of the asset you want to list
currencyContractAddress: NATIVE_TOKEN_ADDRESS, // address of the currency contract that will be used to pay for the listing
buyoutPricePerToken: "1.5", // how much the asset will be sold for
});
Configuration
Provide the id of the listing you want to update, and the new information about the listing.
See createListing for more information about the properties.
getActiveListings
Get all active listings on the marketplace, both direct and auction listings.
An active listing means it can be bought or bid on.
const listings = await contract.getActiveListings();
Configuration
filter (optional)
A filter to apply to the listings returned.
const listings = await contract.getActiveListings(
{
offeror: "{[wallet_address}}", // Only return listings that have an offer from this address
seller: "{{wallet_address}}", // Only return listings that have been created by this address
tokenContract: "{{contract_address}}", // Only return listings that are selling tokens from this contract
tokenId: "{{token_id}}", // Only return listings that are selling this token ID
start: 0, // Pagination: start at this index
count: 0, // Pagination: return this many listings
},
);
Return Value
Returns an array containing both DirectListing objects and AuctionListing objects.
(DirectListing | AuctionListing)[];
getAllListings
Get all the listings on the marketplace, including inactive ones.
const listings = await contract.getAllListings();
Configuration
filter (optional)
A filter to apply to the listings returned.
await contract.getAllListings(
{
offeror: "{[wallet_address}}", // Only return listings that have an offer from this address
seller: "{{wallet_address}}", // Only return listings that have been created by this address
tokenContract: "{{contract_address}}", // Only return listings that are selling tokens from this contract
tokenId: "{{token_id}}", // Only return listings that are selling this token ID
start: 0, // Pagination: start at this index
count: 0, // Pagination: return this many listings
},
);
Return Value
Returns an array containing both DirectListing objects and AuctionListing objects.
(DirectListing | AuctionListing)[];
getBidBufferBps
Get the current bid buffer basis points of the marketplace.
const bidBufferBps = await contract.getBidBufferBps();
Configuration
getListing
Get a listing by its ID, regardless of whether it is a direct or auction listing.
const listing = await contract.getListing("{{listing_id}}");
Configuration
getOffers
Get all the offers made on a listing.
const offers = await contract.getOffers("{{listing_id}}");
Configuration
listingId
The ID of the listing to get offers for.
Must be a string, number, or BigNumber.
Return Value
Returns an array of Offer objects.
{
/**
* The id of the listing.
*/
listingId: BigNumberish;
/**
* The address of the buyer who made the offer.
*/
buyerAddress: string;
/**
* The quantity of tokens to be bought.
*/
quantityDesired: BigNumberish;
/**
* The amount of coins offered per token.
*/
pricePerToken: BigNumber;
/**
* The `CurrencyValue` of the listing. Useful for displaying the price information.
*/
currencyValue: CurrencyValue;
/**
* The currency contract address of the offer token.
*/
currencyContractAddress: string;
}
[];
getTimeBufferInSeconds
Get the current time buffer in seconds of the marketplace.
The time buffer is the amount of seconds that are added to the close time of the auction listing when a new bid is made.
const timeBufferInSeconds = await contract.getTimeBufferInSeconds();
Configuration
getTotalCount
Get the total number of listings on the marketplace.
const totalCount = await contract.getTotalCount();
Configuration
isRestrictedToListerRoleOnly
A marketplace can be restricted to only allow wallet addresses with the LISTER role to create listings.
This method returns true or false depending on whether this configuration is set.
const isRestrictedToListerRoleOnly =
await contract.isRestrictedToListerRoleOnly();
Configuration
makeOffer
Create a new bid on an auction listing or a new offer on a direct listing.
const txResult = await contract.makeOffer(
"{{listing_id}}",
"{{price_per_token}}",
"{{quantity}}",
);
Configuration
setBidBufferBps
Set the bid buffer basis points of the marketplace.
The bid buffer is the amount of percentage that is added to the current highest bid when a new bid is made.
const txResult = await contract.setBidBufferBps("{{bid_buffer_bps}}");
Configuration
setTimeBufferInSeconds
Set the time buffer in seconds of the marketplace.
The time buffer is the amount of seconds that are added to the close time of the auction listing when a new bid is made.
const txResult = await contract.setTimeBufferInSeconds(
"{{time_buffer_seconds}}",
);