Listings
The self-assessed listing system — liquid and Dutch listings priced in floor multiples, with tax prepaid on creation.
Listings is NFTX v4's self-assessed listing system. A seller lists a non-floor item at a chosen floor multiple and duration; the listing accrues tax upfront based on that price and duration, priced and paid in the collection's ERC-20. Cancelling or shortening a listing refunds the unused tax pro-rata. Collections can override the defaults for both the tax calculator and the listing config.
Signatures and descriptions below come from the IListings interface. Two listing shapes exist — liquid and Dutch — and an expired liquid listing automatically decays through a trailing Dutch phase (see getListingType).
Data structures
Listing
The stored state of a single listing.
owner
address payable
Address that owns and can manage the listing
created
uint40
Timestamp of listing creation
duration
uint32
Prepaid duration of the listing, in seconds
floorMultiple
uint16
Price as a multiple of the floor token, to two decimal places (100 = 1.00x)
CreateListing
The input to createListings and relist.
collection
address
The collection address of the assets being listed
tokenIds
uint[]
The token IDs being listed
listing
Listing
The Listing data defining type, duration, and price
ListingConfig
Per-collection (or default) bounds that constrain what listings are allowed.
maxFloorMultiple
uint16
Inclusive upper bound on floorMultiple; two-decimal precision (100 = 1.00x)
minLiquidDuration
uint32
Inclusive lower bound on liquid-listing duration
maxLiquidDuration
uint32
Inclusive upper bound on liquid-listing duration
minDutchDuration
uint32
Inclusive lower bound on Dutch-listing duration
maxDutchDuration
uint32
Inclusive upper bound on Dutch-listing duration; must be strictly less than minLiquidDuration so the type can be discriminated
liquidDutchDuration
uint32
Length of the trailing Dutch decay applied to an expired liquid listing
FillListingsParams
The input to fillListings.
collection
address
The collection of the tokens being filled
tokenIdsOut
uint[][]
The token IDs being filled, grouped by owner (for gas efficiency)
recipient
address
The address to receive the NFTs
maxSpend
uint
Hard cap (in collection-token units) on the total buyer spend — the premium routed to owners plus the floor-equivalent burned. Excludes the protocol fill fee (funded from sellers' prepaid tax). A non-zero value protects against front-running: if owners raise prices between simulation and execution, the fill reverts with FillCostExceedsMaxSpend. Pass 0 to opt out.
Creating and managing listings
createListings
Creates one or more listings. Each token's tax is calculated and prepaid from the caller's funds; the NFTs are held in the Locker and the caller receives one collection token per NFT, minus tax.
Access: nonReentrant, Locker not paused. Reverts with InsufficientTax if the tokens received don't cover the required tax; validates each collection's config bounds; emits ListingsCreated.
_createListings
CreateListing[]
Array of listing structures to create
Returns: None.
modifyListings
Changes the duration or price of existing liquid listings. Additional tax is required for a longer/higher listing, or tax is refunded for a shorter/lower one; any refund is applied to the new tax first, for gas savings.
Access: nonReentrant, Locker not paused. Caller must be the listing owner; only liquid listings can be modified.
_collection
address
The collection address of the listing
_modifyListings
ModifyListing[]
The listings to modify (per-token duration and floorMultiple)
_payTaxWithEscrow
bool
Whether tax should be paid from the caller's escrow balance
taxRequired_
uint
The collection tokens required to modify the listings
refund_
uint
The collection tokens refunded to the owner
cancelListings
Cancels liquid listings, returning each NFT for one equivalent collection token and refunding any remaining prepaid tax.
Access: nonReentrant, Locker not paused. Caller must be the listing owner; only liquid listings can be cancelled (not Dutch or expired ones).
_collection
address
The collection address of the listing
_tokenIds
uint[]
The token IDs to cancel
_payTaxWithEscrow
bool
Whether tax should be paid from escrow
Returns: None.
relist
Buys out an existing listing and immediately re-lists that single token with new parameters — the mechanism behind permissionless re-pricing. The caller cannot be the current owner, who is paid any premium as the old listing is filled.
Access: nonReentrant, Locker not paused. Accepts a single-token payload only (reverts RelistAcceptsSingleTokenOnly otherwise); emits ListingRelisted.
_listing
CreateListing
The new listing (must contain exactly one token ID)
_payTaxWithEscrow
bool
Whether tax should be paid from escrow
Returns: None.
transferOwnership
Transfers ownership of a listing to another address.
Access: nonReentrant, Locker not paused. Caller must be the listing owner; reverts with NewOwnerIsZero on the zero address.
_collection
address
The collection address of the listing
_tokenId
uint
The tokenId of the listing
_newOwner
address payable
The new owner of the listing
Returns: None.
fillListings
Buys listed NFTs using collection tokens. Token IDs are grouped by owner for gas efficiency. The buyer pays the premium to owners plus the floor-equivalent burned, capped by maxSpend; the protocol fill fee comes out of sellers' prepaid tax, not the buyer.
Access: nonReentrant, Locker not paused. Emits ListingsFilled.
params
FillListingsParams
The fill parameters (collection, grouped token IDs, recipient, max spend)
totalBurn_
uint
The total collection tokens burned (floor equivalent, 1e18 per NFT)
Pricing and views
getListingPrice
Returns whether a token can currently be bought from NFTX and its price (in collection-token units, where 1 ether = 1.0x floor). Dutch listings apply a linear discount over their duration; expired liquid listings enter the trailing Dutch decay.
_collection
address
The collection of the listing
_tokenId
uint
The token ID of the listing
isAvailable_
bool
Whether the token is available to purchase
price_
uint
The price in collection-token terms
getListingType
Classifies a listing as DUTCH, LIQUID, or NONE, using the resolved ListingConfig for the collection (so per-collection overrides apply here too).
_collection
address
The collection of the listing
_listing
Listing
The listing to classify
(unnamed)
Enums.ListingType
DUTCH, LIQUID, or NONE
getListingTaxRequired
Calculates the tax needed to create a listing, validating against a complete Listing struct rather than individual parameters. Delegates to the collection's effective tax calculator.
_listing
Listing
The listing to price the tax for
_collection
address
The collection of the listing
taxRequired_
uint
The tax required to create the listing
Other views
locker()
ILocker
The Locker this Listings contract is bound to
listings(address _collection, uint _tokenId)
Listing
The stored listing for a token
listingCount(address _collection)
uint
Count of open listings for a collection
listingConfig(address _collection)
ListingConfig
The effective config (override if set, else default)
taxCalculator(address _collection)
ITaxCalculator
The effective tax calculator (override if set, else default)
defaultListingConfig() / defaultTaxCalculator()
tuple / ITaxCalculator
The protocol-wide defaults
collectionListingConfig(address) / collectionTaxCalculator(address)
tuple / ITaxCalculator
The raw per-collection override (zero/all-zero means "use default")
Configuration (owner only)
These setters are onlyOwner.
setDefaultTaxCalculator
_taxCalculator (address)
Sets the protocol-wide default calculator (reverts on the zero address)
setCollectionTaxCalculator
_collection (address), _taxCalculator (address)
Sets a per-collection override; pass address(0) to clear it and inherit the default
setDefaultListingConfig
_config (ListingConfig)
Sets the default config; validated for cross-field invariants (e.g. maxDutchDuration < minLiquidDuration, maxFloorMultiple > 100)
setCollectionListingConfig
_collection (address), _config (ListingConfig)
Sets a per-collection override; pass an all-zero struct (maxFloorMultiple == 0) to clear it
Last updated
Was this helpful?