EnglishAuctions
Functionality available for contracts that implement the IEnglishAuctions
interface.
buyoutAuction
Pay the full price per token to buy an NFT from an auction listing.
const txResult = await contract.englishAuctions.buyoutAuction("{{listing_id}}");
Configuration
listingId
The ID of the listing to buy NFT(s) from.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.buyoutAuction(
"{{listing_id}}",
);
cancelAuction
Cancel an auction listing you previously created.
Only the creator of the listing can cancel it. Auctions cannot be canceled once a bid has been made.
const txResult = await contract.englishAuctions.cancelAuction("{{listing_id}}");
Configuration
listingId
The ID of the listing to buy NFT(s) from.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.cancelAuction(
"{{listing_id}}",
);
closeAuctionForBidder
After an auction has concluded (and a buyout
did not occur), execute the sale for the buyer,
meaning the buyer receives the NFT(s).
You must also call closeAuctionForSeller
to execute the sale for the seller,
meaning the seller receives the payment from the highest bid.
const txResult = await contract.englishAuctions.closeAuctionForBidder(
"{{listing_id}}",
);
Configuration
listingId
The ID of the listing to execute the sale for.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.closeAuctionForBidder(
"{{listing_id}}",
);
closeAuctionForSeller
After an auction has concluded (and a buyout
did not occur), execute the sale for the seller,
meaning the seller receives the payment from the highest bid.
You must also call closeAuctionForBidder
to execute the sale for the buyer, meaning the buyer receives the NFT(s).
const txResult = await contract.englishAuctions.closeAuctionForSeller(
"{{listing_id}}",
);
Configuration
listingId
The ID of the listing to execute the sale for.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.closeAuctionForSeller(
"{{listing_id}}",
);
createAuction
Create a new auction listing on the marketplace.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
currencyContractAddress: "{{currency_contract_address}}",
quantity: "{{quantity}}",
startTimestamp: new Date(),
endTimestamp: new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000),
bidBufferBps: 100,
timeBufferInSeconds: 60 * 10,
});
Configuration
assetContractAddress (required)
The smart contract address of the NFT you want to list for sale.
Must be a string
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
});
tokenId (required)
The token ID of the NFT you want to list for sale.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
});
buyoutBidAmount (required)
The price to buy the NFT and close the listing immediately, executing a sale event for both buyer and seller.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
});
minimumBidAmount (required)
The minimum "reserve price" for bids.
The first bid must be at least this amount, and all subsequent bids must be higher than the previous highest bid by the
percentage set in bidBufferBps
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
});
currencyContractAddress (optional)
The address of the ERC20 token smart contract you want buyers to pay with.
Defaults to NATIVE_TOKEN_ADDRESS
if not provided. e.g. Ether for Ethereum.
Must be a string
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
currencyContractAddress: "{{currency_contract_address}}",
});
quantity (optional)
For ERC1155 NFTs, the number of tokens to sell in the listing.
For ERC721 NFTs, this is always 1
.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
quantity: "{{quantity}}",
});
startTimestamp (optional)
The start timestamp of the listing.
Must be a Date
. The default is new Date()
(now).
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
startTimestamp: new Date(),
});
endTimestamp (optional)
The end timestamp of the listing.
Must be a Date
. The default is 7 days from now.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
endTimestamp: new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000),
});
bidBufferBps (optional)
The percentage the next bid must be higher than the current highest bid.
This is used to avoid users placing bids minuscule amounts higher than the current highest bid.
Must be a string
, number
, bigint
, or BigNumber
.
The default value is the bid buffer BPS set on the marketplace contract.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
bidBufferBps: 100,
});
timeBufferInSeconds (optional)
The time in seconds that is added to the end time of the auction when a bid is placed.
This is used to avoid users placing a bid at the last moment and winning the auction.
Must be a string
, number
, bigint
, or BigNumber
.
The default value is the time buffer in seconds set on the marketplace contract.
const txResult = await contract.englishAuctions.createAuction({
assetContractAddress: "{{asset_contract_address}}",
tokenId: "{{token_id}}",
buyoutBidAmount: "{{price_to_buy_nft}}",
minimumBidAmount: "{{reserve_price_for_bids}}",
timeBufferInSeconds: 60 * 10,
});
executeSale
Close the auction for both buyer and seller.
This means the NFT(s) will be transferred to the buyer and the seller will receive the funds.
This function can only be called after the auction has ended.
const txResult = await contract.englishAuctions.executeSale("{{listing_id}}");
Configuration
listingId
The ID of the listing to execute the sale for.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.executeSale("{{listing_id}}");
getAll
Retrieve data for all auction listings on the marketplace.
const txResult = await contract.englishAuctions.getAll();
Configuration
filter (optional)
Optionally, provide a filter object to narrow the returned results.
const allListings = await contract.englishAuctions.getAll(
{
count: 100,
offeror: "{{offeror_address}}",
seller: "{{seller_address}}",
start: 0,
tokenContract: "{{token_contract_address}}",
tokenId: "{{token_id}}",
},
);
Return Value
Returns an array of EnglishAuction
objects containing the following properties:
{
id: string;
creatorAddress: string;
assetContractAddress: string;
tokenId: string;
quantity: string;
currencyContractAddress: string;
minimumBidAmount: string;
minimumBidCurrencyValue: CurrencyValue;
buyoutBidAmount: string;
buyoutCurrencyValue: CurrencyValue;
timeBufferInSeconds: number;
bidBufferBps: number;
startTimeInSeconds: number;
endTimeInSeconds: number;
asset: NFTMetadata;
status: Status;
}
[];
getAllValid
Get all the valid auction listings on the marketplace.
A listing is considered valid if the:
- Auction has not expired (i.e. current time is before the end time of the auction)
- Auction has not been canceled
- Auction has not been bought out (all quantity has been sold)
const validListings = await contract.englishAuctions.getAllValid();
Configuration
filter (optional)
const validListings = await contract.englishAuctions.getAllValid(
{
count: 100,
offeror: "{{offeror_address}}",
seller: "{{seller_address}}",
start: 0,
tokenContract: "{{token_contract_address}}",
tokenId: "{{token_id}}",
},
);
Return Value
{
id: string;
creatorAddress: string;
assetContractAddress: string;
tokenId: string;
quantity: string;
currencyContractAddress: string;
minimumBidAmount: string;
minimumBidCurrencyValue: CurrencyValue;
buyoutBidAmount: string;
buyoutCurrencyValue: CurrencyValue;
timeBufferInSeconds: number;
bidBufferBps: number;
startTimeInSeconds: number;
endTimeInSeconds: number;
asset: NFTMetadata;
status: Status;
}
[];
getAuction
Retrieve data for a specific auction listing on the marketplace using the listing ID.
const listing = await contract.englishAuctions.getAuction("{{listing_id}}");
Configuration
listingId
The ID of the listing to retrieve.
Must be a string
, number
, or BigNumber
.
const listing = await contract.englishAuctions.getAuction(
"{{listing_id}}",
);
Return Value
{
id: string;
creatorAddress: string;
assetContractAddress: string;
tokenId: string;
quantity: string;
currencyContractAddress: string;
minimumBidAmount: string;
minimumBidCurrencyValue: CurrencyValue;
buyoutBidAmount: string;
buyoutCurrencyValue: CurrencyValue;
timeBufferInSeconds: number;
bidBufferBps: number;
startTimeInSeconds: number;
endTimeInSeconds: number;
asset: NFTMetadata;
status: Status;
}
getBidBufferBps
Get the basis points of the bid buffer.
This is the percentage higher that a new bid must be than the current highest bid in order to be placed.
If there is no current bid, the bid must be at least the minimum bid amount.
Returns the value in percentage format, e.g. 100 = 1%.
const bidBufferBps = await contract.englishAuctions.getBidBufferBps(
"{{listing_id}}",
);
Configuration
listingId
The ID of the listing to retrieve.
Must be a string
, number
, or BigNumber
.
const bidBufferBps = await contract.englishAuctions.getBidBufferBps(
"{{listing_id}}",
);
Return Value
Returns a number
representing the basis points of the bid buffer.
getMinimumNextBid
Helper function to calculate the value that the next bid must be in order to be accepted.
- If there is no current bid, the bid must be at least the minimum bid amount.
- If there is a current bid, the bid must be at least the current bid amount + the bid buffer.
const minimumNextBid = await contract.englishAuctions.getMinimumNextBid(
"{{listing_id}}",
);
Configuration
listingId
The ID of the listing to retrieve the minimum next bid for.
Must be a string
, number
, or BigNumber
.
const minimumNextBid = await contract.englishAuctions.getMinimumNextBid(
"{{listing_id}}",
);
Return Value
Returns a CurrencyValue
object containing the following properties:
{
symbol: string;
value: BigNumber;
name: string;
decimals: number;
displayValue: string;
}
getTotalCount
Get the total number of auction listings on the marketplace.
const numListings = await contract.englishAuctions.getTotalCount();
Configuration
Return Value
Returns a BigNumber
representing the total number of auction listings on the marketplace.
getWinner
Get the wallet address that won an auction.
Can only be called after the auction has ended.
const winner = await contract.englishAuctions.getWinner("{{listing_id}}");
Configuration
listingId
The ID of the listing to retrieve the winner for.
Must be a string
, number
, or BigNumber
.
const winner = await contract.englishAuctions.getWinner(
"{{listing_id}}",
);
Return Value
Returns a string
representing the wallet address of the winner.
getWinningBid
Get the current highest bid of an active auction.
const winningBid = await contract.englishAuctions.getWinningBid(
"{{listing_id}}",
);
Configuration
listingId
The ID of the listing to retrieve the winning bid for.
Must be a string
, number
, or BigNumber
.
const winningBid = await contract.englishAuctions.getWinningBid(
"{{listing_id}}",
);
Return Value
Returns a Bid
object containing the following properties:
{
auctionId: string;
bidderAddress: string;
currencyContractAddress: string;
bidAmount: string;
bidAmountCurrencyValue: {
symbol: string;
value: BigNumber;
name: string;
decimals: number;
displayValue: string;
}
}
isWinningBid
Check if a value is/would be the current winning bid of an auction.
const isWinningBid = await contract.englishAuctions.isWinningBid(
"{{listing_id}}",
"{{bid_amount}}",
);
Configuration
listingId
The ID of the listing to check if a value is the winning bid for.
Must be a string
, number
, or BigNumber
.
const isWinningBid = await contract.englishAuctions.isWinningBid(
"{{listing_id}}",
"{{bid_amount}}",
);
bidAmount
The amount of the bid to check if it is the winning bid.
Must be a string
, number
, or BigNumber
.
const isWinningBid = await contract.englishAuctions.isWinningBid(
"{{listing_id}}",
"{{bid_amount}}",
);
Return Value
Returns a boolean
representing whether the value is the winning bid.
makeBid
Place a new bid on an auction listing.
const txResult = await contract.englishAuctions.makeBid(
"{{listing_id}}",
"{{bid_amount}}",
);
Configuration
listingId
The ID of the listing to place a bid on.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.makeBid(
"{{listing_id}}",
"{{bid_amount}}",
);
bidAmount
The amount of the bid to place in the currency of the listing.
Use getNextBidAmount
to get the minimum amount for the next bid.
Must be a string
, number
, or BigNumber
.
const txResult = await contract.englishAuctions.makeBid(
"{{listing_id}}",
"{{bid_amount}}",
);