> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpectrum.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Xmarket

> Secondary trading contract

Xmarket handles all resale activity on Xpectrum. It works with any XNS-1 compliant contract, so both `XNS1` and `Xcollection` deployments are tradeable out of the box. The platform deploys one Xmarket; every collection shares it.

The current deployed version is **Xmarket v3**, which carries all v2.2 audit fixes and changes the offer ABI (see Collection offers below).

## Listings

A seller creates a fixed-price listing via `list_nft(contract, token_id, price)`. Before listing, the seller approves Xmarket as an operator on the token (`approve` or `set_operator`).

A buyer purchases via `buy_nft(listing_id)`. Payment splits automatically at settlement:

| Recipient         | Share                              |
| ----------------- | ---------------------------------- |
| Platform          | 2.5%                               |
| Creator (royalty) | As set by the collection (max 10%) |
| Seller            | Remainder                          |

If a listed token changes hands after listing, the stale listing is dropped on the next interaction with it. Overpayment is refunded immediately at settlement.

## Individual offers

A buyer submits an offer via `make_offer(contract, token_id, duration_epochs)` with OCT attached. `duration_epochs` sets how long the offer stays open and is capped at `MAX_OFFER_DURATION = 518400` epochs (roughly 60 days at the current epoch time). The OCT is held in Xmarket until the offer is accepted, cancelled, or expires. The token owner accepts via `accept_offer(offer_id)`; the buyer reclaims their OCT via `cancel_offer(offer_id)`. Once expired, an offer can no longer be accepted.

Offer amounts and expiries are publicly visible on-chain.

## Collection offers

A collection offer targets any token in a collection rather than a specific one. Submit via `make_collection_offer(contract, duration_epochs)` with OCT attached (the same `MAX_OFFER_DURATION` cap applies).

<Note>
  In Xmarket v3, collection offers are flagged with an explicit `offer_is_collection` field, not the legacy `token_id == -1` sentinel. `get_offer` returns this flag so integrators can distinguish individual from collection offers reliably.
</Note>

When a seller accepts via `accept_collection_offer(offer_id, token_id)`, they choose which token from their wallet fills the offer. Xmarket verifies ownership and marketplace approval at settlement.

## Pull-based proceeds

All proceeds are pull-based. Sellers, creators, and the platform collect via `claim_proceeds()`. This sidesteps AML atomicity: if a `call()` fails, any prior `transfer()` in the same function reverts. With pull-based proceeds, your funds are never at risk from a failed downstream call. The platform's trading fees are withdrawn separately via `withdraw_fees()`.

## Lookups

Xmarket indexes active listings so the frontend can resolve them in a single view call:

| View                                    | Returns                                       |
| --------------------------------------- | --------------------------------------------- |
| `get_token_listing(contract, token_id)` | active listing for one token                  |
| `get_listings_for_collection(contract)` | active listings in a collection               |
| `get_listings_page(offset, limit)`      | paginated active listings                     |
| `get_offer(offer_id)`                   | offer detail, including `offer_is_collection` |
| `get_market_info()`                     | market-level stats                            |
| `get_total_volume()`                    | lifetime settled volume                       |