NFT Marketplace Architecture: Contract Standards, Indexing, and Settlement Models

Web3 marketplaces mediate NFT exchange without holding custody, relying instead on smart contract coordination between buyer, seller, and sometimes third party protocols. The mechanics diverge sharply from centralized order books: every listing, bid, and sale involves onchain state changes or offchain signatures that settle onchain. Understanding which data lives where, how indexers reconstruct market state, and where counterparty risk actually sits determines whether you can build on, integrate with, or safely use a given marketplace.

This article dissects the technical plumbing: order representation and storage, the role of indexers in surfacing liquidity, settlement paths for offers and auctions, and the failure modes that emerge when these components interact badly.

Order Representation and Storage Models

Marketplaces store orders in three canonical ways, each with distinct trade offs.

Fully onchain orders write every listing or bid into contract state. The marketplace contract tracks token ID, price, expiration, and seller address in a mapping or struct array. Buyers call a purchase function that reads this state, transfers payment, and moves the NFT atomically. Gas costs scale with listing volume. This model guarantees composability: any contract can query available listings directly. Sudoswap’s AMM pools and some early fixed price markets used this approach.

Offchain orders with onchain settlement keep the order book offchain. Sellers sign a message containing the asset, price, expiration, and approved settlement contract. The marketplace backend indexes these signatures. When a buyer wants to purchase, they submit the signed message and payment to the settlement contract, which verifies the signature, checks expiration, and executes the transfer. OpenSea’s Seaport and Blur’s core contracts follow this pattern. Gas cost per listing drops to zero until sale. The trade off: you must trust the indexer to surface all available liquidity, and orders cannot be read by other contracts without a relay mechanism.

Hybrid models post a commitment onchain (often a Merkle root or order hash) while keeping full order details offchain. Settlement requires submitting a Merkle proof or the full order data. LooksRare and X2Y2 have used order hash registries. This adds a small onchain footprint per listing while retaining most offchain flexibility.

Indexer Role and Liquidity Fragmentation

Offchain order models make the indexer the source of truth for what is actually for sale. The marketplace backend must monitor wallet signatures, check for cancellations, track NFT ownership changes that invalidate listings, and serve this filtered dataset via API. If the indexer misses a cancellation event or fails to detect a transfer, it displays phantom liquidity.

Aggregators like Blur’s aggregation layer, Gem, or Reservoir query multiple marketplace APIs and attempt to unify liquidity. They face three problems:

1. Signature replay across marketplaces. A seller may sign identical orders on multiple platforms. Aggregators must deduplicate or risk showing the same item multiple times at different effective fees.
2. Stale order detection. An NFT sold on platform A may still appear available on platform B if the indexer has not yet processed the transfer event.
3. Private order books. Some platforms withhold certain orders (private sales, pro tier listings) from public APIs, fragmenting the visible liquidity set.

Aggregators typically settle through a router contract that attempts execution on the marketplace with the best net price, falling back if the order has expired or the NFT moved.

Settlement Paths: Fixed Price, Offers, and Auctions

Fixed price listings are the simplest settlement. The buyer calls a function (or submits a signed order) with payment equal to the listing price. The contract verifies ownership, transfers the NFT to the buyer, splits payment between seller and fee recipients, and emits an event. If the NFT has been transferred or the listing cancelled, the transaction reverts.

Collection wide or trait based offers let buyers bid on any token matching criteria. The offer signature includes a filter (e.g., token IDs in a Merkle tree, or a trait verifier contract address). A holder matching the criteria can accept by submitting the offer and proving their token qualifies. Seaport criteria resolvers and Blur’s collection bids implement this. The risk: the buyer must ensure sufficient token approval and balance when any eligible seller decides to accept.

Auctions come in two flavors. English auctions (ascending bid) typically store the current high bid onchain. Each new bid must exceed the previous by a minimum increment. When the auction ends, the seller or high bidder triggers settlement. Reserve prices and time extensions (if a bid arrives near expiration) are common. Dutch auctions (descending price) start high and drop at a defined rate until someone purchases. These are usually implemented as a price function of block timestamp, avoiding the need to store bid state.

Reserve auctions that fail to meet the reserve refund the high bidder and return the NFT to the seller. Settlement functions must handle this case without locking funds.

Royalty Enforcement and Operator Filters

NFT creators often expect a percentage of secondary sales. EIP-2981 provides an onchain royalty query interface: royaltyInfo(tokenId, salePrice) returns the recipient and amount. Marketplaces may choose to honor this or not.

Some projects deployed operator filter registries (notably the OpenSea operator filter) that let contracts block transfers through non compliant marketplaces. Token contracts check isApprovedForAll or transfer calls against a registry of banned operators. Marketplaces that do not enforce royalties get added to the blocklist. This creates a coordination problem: a marketplace must decide whether to enforce royalties and access these collections, or skip enforcement and be blocked by participating contracts.

Operator filters are opt in by the token contract. Enforcement has fragmented: major platforms adopted different stances in the 2022 to 2023 period, and some projects later removed filters when trading volume fell.

Worked Example: Accepting a Collection Wide Bid

Alice has Bored Ape 5234. Bob signs a collection wide offer offchain: buy any Bored Ape for 50 ETH, valid until block 18000000, settling via Seaport contract 0xabc. The signature includes a criteria resolver that verifies the token belongs to the Bored Ape contract.

Alice queries Blur’s API and sees Bob’s bid. She decides to accept. The Blur frontend constructs a transaction that calls Seaport’s fulfillAdvancedOrder function, passing Bob’s signed order, the criteria proof (confirming token 5234 matches), and Alice’s approval for the Bored Ape contract to transfer the NFT.

Seaport executes:

1. Verify Bob’s signature and check block.number is under 18000000.
2. Call the criteria resolver to confirm token 5234 is valid.
3. Check Bob’s ETH balance and approval for Seaport to spend it.
4. Transfer 50 ETH from Bob (minus fees) to Alice and the marketplace fee recipient.
5. Transfer Bored Ape 5234 from Alice to Bob.
6. Emit a fulfillment event.

If Bob’s balance is insufficient at acceptance time, the transaction reverts and Alice pays gas but keeps her NFT. This is a known risk with collection offers: buyers must maintain liquidity for the entire validity window.

Common Mistakes and Misconfigurations

• Approving marketplace contracts without revoking after listing cancellation. Your NFT remains transferable if the approval persists and someone submits a stale signed order.
• Setting no expiration or a very distant expiration on offchain orders. If the indexer fails to mark it cancelled, the order may be filled months later at an outdated price.
• Ignoring the difference between ERC-721 approve (single token) and setApprovalForAll (entire collection). Many marketplaces require setApprovalForAll, granting broad transfer rights.
• Assuming royalties are enforced. Always check the marketplace’s policy and the token contract’s operator filter status.
• Bid sniping assumptions in auction extensions. Some contracts extend the auction by a fixed duration (e.g., 10 minutes) if a bid arrives in the final window. Others do not. Read the contract before bidding near expiration.
• Using the same nonce or salt across marketplaces. If two platforms share a settlement contract, replaying the signature can result in unintended sales.

What to Verify Before You Rely on This

• Current settlement contract address and version for the marketplace you are using. Upgrades or migrations can strand old signed orders.
• Whether the marketplace indexer supports cancellation propagation and how quickly it processes ownership transfers.
• Operator filter registry status for the NFT collection, and whether the marketplace is on the allowlist.
• Fee structure, including protocol fees, creator royalties, and whether buyer or seller pays gas. Some marketplaces subsidize gas or batch operations.
• Signature standard (EIP-712 domain, order struct format). Aggregators and custom integrations need to construct valid signatures.
• Criteria resolver or trait verification logic if you are accepting or placing collection wide or trait offers.
• Auction settlement rules: time extension policy, minimum bid increment, reserve price behavior, and who triggers the final settlement transaction.
• Token approval scope required by the marketplace. Check whether you are granting single token or collection wide transfer rights.
• How the marketplace handles ERC-1155 partial fills and bundle listings. Not all platforms support these uniformly.
• Fallback behavior in aggregator routers. If the primary marketplace reverts, does the router try alternatives or simply fail?

Next Steps

• Simulate a full listing and purchase flow on a testnet using the marketplace’s settlement contract directly (not just the frontend) to understand approval requirements and fee distribution.
• Decode a recent sale transaction from the marketplace you plan to integrate with. Trace token and ETH movements to confirm your mental model of the settlement path.
• Implement a cancellation monitoring script that listens for marketplace cancellation events and your own wallet’s NFT transfer events, then cross references against your active listings to detect stale approvals.

Category: NFTs & Web3 Markets