Skip to main content

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Required - Minimum amount that bids must be to placed
currencyContractAddress: "{{currency_contract_address}}", // Optional - smart contract address of the currency to use for the listing
quantity: "{{quantity}}", // Optional - number of tokens to sell (1 for ERC721 NFTs)
startTimestamp: new Date(), // Optional - when the listing should start (default is now)
endTimestamp: new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000), // Optional - when the listing should end (default is 7 days from now)
bidBufferBps: 100, // Optional - percentage the next bid must be higher than the current highest bid (default is contract-level bid buffer bps)
timeBufferInSeconds: 60 * 10, // Optional - time in seconds that are added to the end time when a bid is placed (default is contract-level time buffer in seconds)
});
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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
currencyContractAddress: "{{currency_contract_address}}", // Optional - smart contract address of the currency to use for the listing
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
quantity: "{{quantity}}", // Optional - number of tokens to sell (1 for ERC721 NFTs)
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
startTimestamp: new Date(), // Optional - when the listing should start (default is now)
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
endTimestamp: new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000), // Optional - when the listing should end (default is 7 days from now)
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
bidBufferBps: 100, // Optional - percentage the next bid must be higher than the current highest bid (default is contract-level bid buffer bps)
});

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}}", // Required - smart contract address of NFT to sell
tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
buyoutBidAmount: "{{price_to_buy_nft}}", // Required - amount to buy the NFT and close the listing
minimumBidAmount: "{{reserve_price_for_bids}}", // Minimum amount that bids must be to
timeBufferInSeconds: 60 * 10, // Optional - time in seconds that are added to the end time when a bid is placed (default is contract-level time buffer in seconds)
});

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, // Number of listings to fetch
offeror: "{{offeror_address}}", // Has offers from this address
seller: "{{seller_address}}", // Being sold by this address
start: 0, // Start from this index (pagination)
tokenContract: "{{token_contract_address}}", // Only show NFTs from this collection
tokenId: "{{token_id}}", // Only show NFTs with this ID
},
);

Return Value

Returns an array of EnglishAuction objects containing the following properties:

{
id: string; // The id of the auction listing
creatorAddress: string; // The wallet address of the creator of auction.
assetContractAddress: string; // The address of the asset being auctioned.
tokenId: string; // The ID of the token being auctioned.
quantity: string; // The quantity of tokens included in the auction.
currencyContractAddress: string; // The address of the currency to accept for the auction.
minimumBidAmount: string; // The minimum price that a bid must be in order to be accepted.
minimumBidCurrencyValue: CurrencyValue; // The `CurrencyValue` of the minimum bid amount. Useful for displaying the price information.
buyoutBidAmount: string; // The buyout price of the auction.
buyoutCurrencyValue: CurrencyValue; // The `CurrencyValue` of the buyout price. Useful for displaying the price information.
timeBufferInSeconds: number; // This is a buffer e.g. x seconds.
bidBufferBps: number; // To be considered as a new winning bid, a bid must be at least x% greater than the previous bid.
startTimeInSeconds: number; // The start time of the auction.
endTimeInSeconds: number; // The end time of the auction.
asset: NFTMetadata; // The asset being auctioned.
status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}
[];

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, // Number of listings to fetch
offeror: "{{offeror_address}}", // Has offers from this address
seller: "{{seller_address}}", // Being sold by this address
start: 0, // Start from this index (pagination)
tokenContract: "{{token_contract_address}}", // Only show NFTs from this collection
tokenId: "{{token_id}}", // Only show NFTs with this ID
},
);

Return Value

{
id: string; // The id of the auction listing
creatorAddress: string; // The wallet address of the creator of auction.
assetContractAddress: string; // The address of the asset being auctioned.
tokenId: string; // The ID of the token being auctioned.
quantity: string; // The quantity of tokens included in the auction.
currencyContractAddress: string; // The address of the currency to accept for the auction.
minimumBidAmount: string; // The minimum price that a bid must be in order to be accepted.
minimumBidCurrencyValue: CurrencyValue; // The `CurrencyValue` of the minimum bid amount. Useful for displaying the price information.
buyoutBidAmount: string; // The buyout price of the auction.
buyoutCurrencyValue: CurrencyValue; // The `CurrencyValue` of the buyout price. Useful for displaying the price information.
timeBufferInSeconds: number; // This is a buffer e.g. x seconds.
bidBufferBps: number; // To be considered as a new winning bid, a bid must be at least x% greater than the previous bid.
startTimeInSeconds: number; // The start time of the auction.
endTimeInSeconds: number; // The end time of the auction.
asset: NFTMetadata; // The asset being auctioned.
status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}
[];

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; // The id of the auction listing
creatorAddress: string; // The wallet address of the creator of auction.
assetContractAddress: string; // The address of the asset being auctioned.
tokenId: string; // The ID of the token being auctioned.
quantity: string; // The quantity of tokens included in the auction.
currencyContractAddress: string; // The address of the currency to accept for the auction.
minimumBidAmount: string; // The minimum price that a bid must be in order to be accepted.
minimumBidCurrencyValue: CurrencyValue; // The `CurrencyValue` of the minimum bid amount. Useful for displaying the price information.
buyoutBidAmount: string; // The buyout price of the auction.
buyoutCurrencyValue: CurrencyValue; // The `CurrencyValue` of the buyout price. Useful for displaying the price information.
timeBufferInSeconds: number; // This is a buffer e.g. x seconds.
bidBufferBps: number; // To be considered as a new winning bid, a bid must be at least x% greater than the previous bid.
startTimeInSeconds: number; // The start time of the auction.
endTimeInSeconds: number; // The end time of the auction.
asset: NFTMetadata; // The asset being auctioned.
status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}

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.

number;

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.

BigNumber;

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.

string;

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; // The id of the auction.
bidderAddress: string; // The address of the buyer who made the offer.
currencyContractAddress: string; // The currency contract address of the offer token.
bidAmount: string; // The amount of coins offered per token.
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.

boolean;

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