Skip to main content

Marketplace V3

When using the Marketplace V3 smart contract, additional top-level functionality is available to use.

To access the top-level functionality, provide the marketplace-v3 contract type when creating the contract instance:

const contract = await sdk.getContract(
  "{{contract_address}}",
  "marketplace-v3", // Provide the "marketplace-v3" contract type
);

Once connected, the capabilities unique to the Marketplace V3 are available from the following extensions:

approveBuyerForReservedListing​

Approve a wallet address to be able to buy a reserved listing.

const txResult = await contract.directListings.approveBuyerForReservedListing(
  "{{listing_id}}",
  "{{wallet_address}}",
);
Configuration

listingId​

The ID of the listing you want to approve a buyer for.

Must be a string, number, or BigNumber.

const txResult = await contract.directListings.approveBuyerForReservedListing(
  "{{listing_id}}",
  "{{wallet_address}}",
);

buyer​

The wallet address of the buyer you want to approve.

Must be a string.

const txResult = await contract.directListings.approveBuyerForReservedListing(
  "{{listing_id}}",
  "{{wallet_address}}",
);

acceptOffer​

Accept an offer placed on your NFT.

const txResult = await contract.offers.acceptOffer("{{offer_id}}");
Configuration

offerId​

The ID of the offer to accept.

You can view all offers with getAll or getAllValid.

Must be a string, number, or BigNumber.

buyFromListing​

Buy an NFT from a listing.

const txResult = await contract.directListings.buyFromListing(
  "{{listing_id}}",
  "{{quantity}}",
  "{{wallet_address}}",
);
Configuration

listingId​

The ID of the listing.

Must be a string.

const txResult = await contract.directListings.buyFromListing(
  "{{listing_id}}",
  "{{quantity}}",
  "{{wallet_address}}",
);

quantity​

The number of tokens to buy (default is 1 for ERC721 NFTs)

Must be a string or number.

const txResult = await contract.directListings.buyFromListing(
  "{{listing_id}}",
  "{{quantity}}",
  "{{wallet_address}}",
);

buyer​

The wallet address of the buyer.

Must be a string.

const txResult = await contract.directListings.buyFromListing(
  "{{listing_id}}",
  "{{quantity}}",
  "{{wallet_address}}",
);

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

cancelListing​

Cancel a listing that you created.

Only the creator of the listing can cancel it.

const txResult = await contract.directListings.cancelListing("{{listing_id}}");
Configuration

listingId​

The ID of the listing you want to cancel.

Must be a string, number, or BigNumber.

const txResult = await contract.directListings.cancelListing(
  "{{listing_id}}",
);

cancelOffer​

Cancel an offer you made on an NFT.

const txResult = await contract.offers.cancelOffer("{{offer_id}}");
Configuration

offerId​

The ID of the offer to cancel.

You can view all offers with getAll or getAllValid.

Must be a string, number, or BigNumber.

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

createListing​

Create a new direct listing on the marketplace.

const txResult = await contract.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}", // Required - smart contract address of NFT to sell
  tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
  pricePerToken: "{{price_per_token}}", // Required - price of each token in the listing
  currencyContractAddress: "{{currency_contract_address}}", // Optional - smart contract address of the currency to use for the listing
  isReservedListing: false, // Optional - whether or not the listing is reserved (only specific wallet addresses can buy)
  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)
});
Configuration

assetContractAddress (required)​

The smart contract address of the NFT you want to list for sale.

Must be a string.

const txResult = await contract.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
});

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.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
});

pricePerToken (required)​

The price of each token in the listing.

  • For ERC721 NFTs, this is the price to buy the NFT.
  • For ERC1155 NFTs, this is the price to buy one token in the listing.

Must be a string, number, or BigNumber.

const txResult = await contract.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
});

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.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
  currencyContractAddress: "{{currency_contract_address}}",
});

isReservedListing (optional)​

Whether the listing is reserved or not.

Reserved listings can only be bought by specific wallet addresses, which you can add by calling approveBuyerForReservedListing.

Must be a boolean. Defaults to false.

const txResult = await contract.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
  isReservedListing: false,
});

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.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
  quantity: "{{quantity}}",
});

startTimestamp (optional)​

The start timestamp of the listing.

Must be a Date. The default is new Date() (now).

const txResult = await contract.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
  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.directListings.createListing({
  assetContractAddress: "{{asset_contract_address}}",
  tokenId: "{{token_id}}",
  pricePerToken: "{{price_per_token}}",
  endTimestamp: new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000),
});

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 - Auction​

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
    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.
}
[];

getAll - Direct​

Retrieve data for all direct listings on the marketplace.

const allListings = await contract.directListings.getAll();
Configuration

filter (optional)​

Optionally, provide a filter object to narrow the returned results.

const allListings = await contract.directListings.getAll(
  {
    count: 100, // Number of listings to fetch
    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 DirectListingV3 objects containing the following properties:

{
  id: string; // The id of the listing.
  creatorAddress: string; // The address of the creator of listing.
  assetContractAddress: string; // The address of the asset being listed.
  tokenId: string; // The ID of the token to list.
  quantity: string; //  The quantity of tokens to include in the listing (always 1 for ERC721).
  currencyContractAddress: string; // The address of the currency to accept for the listing.
  currencyValuePerToken: CurrencyValue; // The `CurrencyValue` of the listing. Useful for displaying the price information.
  pricePerToken: string; // The price to pay per unit of NFTs listed.
  asset: NFTMetadata; // The asset being listed.
  startTimeInSeconds: number; // The start time of the listing.
  endTimeInSeconds: number; // The end time of the listing.
  isReservedListing: boolean; // Whether the listing is reserved to be bought from a specific set of buyers.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}

getAll - Offers​

Get all offers on the smart contract.

Optionally, provide a filter to filter the offers returned.

const offers = await contract.offers.getAll();
Configuration

filter (optional)​

Filter the results returned by the function.

const offers = await contract.offers.getAll({
  offeror: "{{wallet_address}}", // Offers made by this wallet address
  tokenContract: "{{contract_address}}", // Offers on items from this contract
  tokenId: "{{token_id}}", // Offers on this specific token
  start: 0, // Pagination: Start from this index
  count: 100, // Pagination: Return this many results
});

Return Value​

Returns an array of OfferV3 objects, containing the following properties:

{
  id: string; // The id of the offer.
  offerorAddress: string; // The wallet address of the creator of offer.
  assetContractAddress: string; // The address of the asset being offered on.
  tokenId: string; // The ID of the token.
  quantity: string; // The quantity of tokens offered to buy
  currencyContractAddress: string; // The address of the currency offered for the NFTs.
  currencyValue: CurrencyValue; // The `CurrencyValue` of the offer. Useful for displaying the price information.
  totalPrice: string; // The total offer amount for the NFTs.
  asset: NFTMetadata; // Metadata of the asset
  endTimeInSeconds: number; // The end time of the offer.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}
[];

getAllValid - Auction​

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.
}
[];

getAllValid - Direct​

Get all the valid direct listings on the marketplace.

A listing is considered valid if the:

  • Seller still owns the NFT
  • Listing has not expired (time is before endTimeInSeconds)
  • Listing has not been canceled
  • Listing has not been bought out (all quantity of the NFTs have not been purchased)
const validListings = await contract.directListings.getAllValid();
Configuration

filter (optional)​

Optionally, provide a filter object to narrow the returned results.

const validListings = await contract.directListings.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​

Returns an array of DirectListingV3 objects containing the following properties:

{
  id: string; // The id of the listing.
  creatorAddress: string; // The address of the creator of listing.
  assetContractAddress: string; // The address of the asset being listed.
  tokenId: string; // The ID of the token to list.
  quantity: string; //  The quantity of tokens to include in the listing (always 1 for ERC721).
  currencyContractAddress: string; // The address of the currency to accept for the listing.
  currencyValuePerToken: CurrencyValue; // The `CurrencyValue` of the listing. Useful for displaying the price information.
  pricePerToken: string; // The price to pay per unit of NFTs listed.
  asset: NFTMetadata; // The asset being listed.
  startTimeInSeconds: number; // The start time of the listing.
  endTimeInSeconds: number; // The end time of the listing.
  isReservedListing: boolean; // Whether the listing is reserved to be bought from a specific set of buyers.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}

getAllValid - Offers​

Get all the valid offers on the smart contract.

Valid offers are offers that have not expired, been canceled, or been accepted.

const offers = await contract.offers.getAllValid();
Configuration

filter (optional)​

Filter the results returned by the function.

const offers = await contract.offers.getAllValid({
  offeror: "{{wallet_address}}", // Offers made by this wallet address
  seller: "{{wallet_address}}", // Offers on items being sold by this wallet address
  tokenContract: "{{contract_address}}", // Offers on items from this contract
  tokenId: "{{token_id}}", // Offers on this specific token
  start: 0, // Pagination: Start from this index
  count: 100, // Pagination: Return this many results
});

Return Value​

Returns an array of OfferV3 objects, containing the following properties:

{
  id: string; // The id of the offer.
  offerorAddress: string; // The wallet address of the creator of offer.
  assetContractAddress: string; // The address of the asset being offered on.
  tokenId: string; // The ID of the token.
  quantity: string; // The quantity of tokens offered to buy
  currencyContractAddress: string; // The address of the currency offered for the NFTs.
  currencyValue: CurrencyValue; // The `CurrencyValue` of the offer. Useful for displaying the price information.
  totalPrice: string; // The total offer amount for the NFTs.
  asset: NFTMetadata; // Metadata of the asset
  endTimeInSeconds: number; // The end time of the offer.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}
[];

getAuction - Auction​

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;

getListing - Direct​

Retrieve data for a specific direct listing on the marketplace using the listing ID.

const listing = await contract.directListings.getListing("{{listing_id}}");
Configuration

listingId​

The ID of the listing to retrieve.

Must be a string, number, or BigNumber.

const listing = await contract.directListings.getListing(
  1,
);

Return Value​

Returns a DirectListingV3 object containing the following properties:

{
  id: string; // The id of the listing.
  creatorAddress: string; // The address of the creator of listing.
  assetContractAddress: string; // The address of the asset being listed.
  tokenId: string; // The ID of the token to list.
  quantity: string; //  The quantity of tokens to include in the listing (always 1 for ERC721).
  currencyContractAddress: string; // The address of the currency to accept for the listing.
  currencyValuePerToken: CurrencyValue; // The `CurrencyValue` of the listing. Useful for displaying the price information.
  pricePerToken: string; // The price to pay per unit of NFTs listed.
  asset: NFTMetadata; // The asset being listed.
  startTimeInSeconds: number; // The start time of the listing.
  endTimeInSeconds: number; // The end time of the listing.
  isReservedListing: boolean; // Whether the listing is reserved to be bought from a specific set of buyers.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}

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

getOffer​

Get information about a specific offer using the offer’s ID.

const offer = await contract.offers.getOffer("{{offer_id}}");
Configuration

offerId​

The ID of the offer to get information about.

You can view all offers with getAll or getAllValid.

Return Value​

Returns a single OfferV3 object containing the following properties:

{
  id: string; // The id of the offer.
  offerorAddress: string; // The wallet address of the creator of offer.
  assetContractAddress: string; // The address of the asset being offered on.
  tokenId: string; // The ID of the token.
  quantity: string; // The quantity of tokens offered to buy
  currencyContractAddress: string; // The address of the currency offered for the NFTs.
  currencyValue: CurrencyValue; // The `CurrencyValue` of the offer. Useful for displaying the price information.
  totalPrice: string; // The total offer amount for the NFTs.
  asset: NFTMetadata; // Metadata of the asset
  endTimeInSeconds: number; // The end time of the offer.
  status: Status; // Whether the listing is CREATED, COMPLETED, or CANCELLED.
}

getTotalCount - Auction​

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;

getTotalCount - Direct​

Get the total number of direct listings on the marketplace.

const numListings = await contract.directListings.getTotalCount();
Configuration

Return Value​

Returns a BigNumber representing the total number of direct listings on the marketplace.

BigNumber;

getTotalCount - Offers​

Get the total number of offers on the smart contract

const numOffers = await contract.offers.getTotalCount();
Configuration

Return Value​

Returns a BigNumber representing the total number of offers on the smart contract.

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

isBuyerApprovedForListing​

Check if a buyer is approved to purchase a reserved listing.

const isApproved = await contract.directListings.isBuyerApprovedForListing(
  "{{listing_id}}",
  "{{wallet_address}}",
);
Configuration

listingId​

The ID of the listing to check.

Must be a string, number, or BigNumber.

const isApproved = await contract.directListings.isBuyerApprovedForListing(
  1,
  "{{wallet_address}}",
);

buyerAddress​

The wallet address of the buyer to check.

Must be a string.

const isApproved = await contract.directListings.isBuyerApprovedForListing(
  "{{listing_id}}",
  "{{wallet_address}}",
);

Return Value​

Returns a boolean representing whether the buyer is approved to purchase the listing.

boolean;

isCurrencyApprovedForListing​

Check whether you can use a specific currency to purchase a listing.

const isApproved = await contract.directListings.isCurrencyApprovedForListing(
  "{{listing_id}}",
  "{{currency_contract_address}}",
);
Configuration

listingId​

The ID of the listing to check.

Must be a string, number, or BigNumber.

const isApproved = await contract.directListings.isCurrencyApprovedForListing(
  1,
  "{{currency_contract_address}}",
);

currencyContractAddress​

The smart contract address of the ERC20 token to check.

Must be a string.

const isApproved = await contract.directListings.isCurrencyApprovedForListing(
  "{{listing_id}}",
  "{{currency_contract_address}}",
);

Return Value​

Returns a boolean representing whether the currency is approved to purchase the listing.

boolean;

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

makeOffer​

Make a new offer on an NFT.

Offers can be made on any NFT, regardless of whether it is listed for sale or not.

const txResult = await contract?.offers.makeOffer({
  assetContractAddress: "{{contract_address}}", // Required - the contract address of the NFT to offer on
  tokenId: "{{token_id}}", // Required - the token ID to offer on
  totalPrice: "{{offer_price}}", // Required - the price to offer in the currency specified
  currencyContractAddress: "{{contract_address}}", // Optional - defaults to the native wrapped currency
  endTimestamp: new Date(Date.now() + 1000 * 60 * 60 * 24 * 365 * 10), // Optional - Defaults to 10 years from now
  quantity: 1, // Optional - defaults to 1
});
Configuration

assetContractAddress​

The smart contract address of the NFT to make an offer on.

Required. Must be a string.

tokenId​

The token ID of the NFT to make an offer on.

Required. Must be a string, number, or BigNumber.

totalPrice​

The price to offer.

Required. Must be a string or a number.

currencyContractAddress​

The smart contract address of the currency to offer in.

Optional. Defaults to the native wrapped currency. e.g. Wrapped Ether for Ethereum, or wMatic for Polygon.

Must be a string.

endTimestamp​

The timestamp at which the offer will expire.

Optional. Defaults to 10 years from now.

Must be a Date object.

quantity​

The quantity of NFTs you are offering to buy.

This is relevant for ERC1155 NFTs where you can buy multiple tokens at once.

Optional. Defaults to 1.

Must be a string, number, or BigNumber.

revokeBuyerApprovalForReservedListing​

Revoke approval for a buyer to purchase a reserved listing.

const txResult =
  await contract.directListings.revokeBuyerApprovalForReservedListing(
    "{{listing_id}}",
    "{{wallet_address}}",
  );
Configuration

listingId​

The ID of the listing to revoke approval for.

Must be a string, number, or BigNumber.

const txResult =
  await contract.directListings.revokeBuyerApprovalForReservedListing(
    1,
    "{{wallet_address}}",
  );

buyerAddress​

The wallet address of the buyer to revoke approval for.

Must be a string.

const txResult =
  await contract.directListings.revokeBuyerApprovalForReservedListing(
    "{{listing_id}}",
    "{{wallet_address}}",
  );

revokeCurrencyApprovalForListing​

Revoke approval for a currency to purchase a listing.

const txResult = await contract.directListings.revokeCurrencyApprovalForListing(
  "{{listing_id}}",
  "{{currency_contract_address}}",
);
Configuration

listingId​

The ID of the listing to revoke approval for.

Must be a string, number, or BigNumber.

const txResult = await contract.directListings.revokeCurrencyApprovalForListing(
  1,
  "{{currency_contract_address}}",
);

currencyContractAddress​

The smart contract address of the ERC20 token to revoke approval for.

Must be a string.

Use the NATIVE_TOKEN_ADDRESS constant to revoke approval for the native currency.

const txResult = await contract.directListings.revokeCurrencyApprovalForListing(
  "{{listing_id}}",
  "{{currency_contract_address}}",
);

updateListing​

Update a previously created listing.

const txResult = await contract.directListings.updateListing("{{listing_id}}", {
  assetContractAddress: "{{asset_contract_address}}", // Required - smart contract address of NFT to sell
  tokenId: "{{token_id}}", // Required - token ID of the NFT to sell
  pricePerToken: "{{price_per_token}}", // Required - price of each token in the listing
  currencyContractAddress: "{{currency_contract_address}}", // Optional - smart contract address of the currency to use for the listing
  isReservedListing: false, // Optional - whether or not the listing is reserved (only specific wallet addresses can buy)
  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)
});
Configuration

listingId​

The ID of the listing to update.

listing​

The information to update about the listing.

If you do not want to update a field, do not include it in the provided listing object. The previous value will be used.

For information about each property, see createListing.