For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Field
Type
Description

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.

Field
Type
Description

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.

Field
Type
Description

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.

Field
Type
Description

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.

Parameter
Type
Description

_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.

Parameter
Type
Description

_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

Return
Type
Description

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).

Parameter
Type
Description

_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.

Parameter
Type
Description

_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.

Parameter
Type
Description

_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.

Parameter
Type
Description

params

FillListingsParams

The fill parameters (collection, grouped token IDs, recipient, max spend)

Return
Type
Description

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.

Parameter
Type
Description

_collection

address

The collection of the listing

_tokenId

uint

The token ID of the listing

Return
Type
Description

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).

Parameter
Type
Description

_collection

address

The collection of the listing

_listing

Listing

The listing to classify

Return
Type
Description

(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.

Parameter
Type
Description

_listing

Listing

The listing to price the tax for

_collection

address

The collection of the listing

Return
Type
Description

taxRequired_

uint

The tax required to create the listing

Other views

Function
Returns
Description

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.

Function
Parameters
Description

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?