Skip to content
⌘K

Contracts

Marketplace contract

The market Move package behind Rare Marketplace: listings, offers, offer pools, swaps, raffles, bundles, fees, events and PTB examples.

The market package runs trading on Rare Marketplace. It covers fixed-price listings for kiosk and wallet items, item, collection and trait offers, offer pools and item-for-item swaps, with raffles and bundles coming in a later upgrade. It depends on the Sui framework and on Mysten's kiosk rules package (royalty_rule, kiosk_lock_rule, personal_kiosk_rule, floor_price_rule).

Published on Sui mainnetView on tide
Package id0xe9386f2928838faae5a02779243f7cf877c3c43baba237c58243e135882a4e08
Config0xd11bbb6b4ff76ccd8cb95a1a48a5dc41aa537eba8ca5fb8e5bd75c7a29e7eec6

On this page, PACKAGE_ID is the latest package id, T is the item type, and every amount is in MIST. Shared objects are passed as normal object inputs: the SDK resolves initialSharedVersion.

Modules

ModuleWhat it does
configThe shared Config: fee table, treasury, halt switch and package revision.
sale_kioskListings of kiosk items through an exclusive PurchaseCap.
sale_escrowListings of wallet items held in escrow (types without a TransferPolicy).
offerItem, trait (Merkle set) and collection offers.
offer_poolOne SUI balance backing up to 128 offers.
barterItem and SUI swaps between two parties.
raffleTicketed raffles drawn with sui::random. Later upgrade.
bundleSeveral items sold as one lot, with bids and an optional sealed reserve. Later upgrade.
courierKiosk extension that lets the market deliver items into your kiosk.
clearingRoyalty quotes and the helper that settles standard transfer policy rules.
merkleThe hashing used by trait offers.
eventsEvery event the package emits.

Shared objects and caps

ObjectSharingFields
config::Configshared, onerev, halted, treasury, fees (fee rows: 1 listing, 2 offer, 3 swap, 4 raffle, 5 bundle), queued
config::ConfigCapownedFee and treasury changes and the halt switch. Held by a single Rare address today.
sale_kiosk::KioskOrder<T>shared, one per listingrev, kiosk, item, maker, ask, bps (listing rate at posting), cap
sale_escrow::EscrowOrder<T>shared, one per listingrev, maker, item, ask, bps. The item is a dynamic object field keyed by its id.
offer::Offer<T>shared, one per offerrev, maker, terms, funds
offer_pool::OfferPoolshared, one per poolrev, owner, label, funds, reserved, members (at most 128)
barter::Dealshared, one per swaprev, maker, maker_kiosk, taker, give, want, ask, bid, bps, escrow, ends_ms, open
raffle::Raffle<T>shared, one per rafflepot, price, sold, min_tickets, max_tickets, ends_ms, winner, phase (0 selling, 1 drawn, 2 void), host, item
bundle::Bundleshared, one per bundleslots, ask, seal, maker, live
bundle::BundleBidshared, one per bidescrow, amount, fee, reserve, until_ms, dest, bundle, bidder

Listings, offers and bids are deleted when they close, so a listing that no longer exists is no longer live.

barter::Swap, barter::Unwind, bundle::Checkout, bundle::Handover and bundle::Unstack are hot potatoes: they have no abilities and must be consumed in the same PTB that created them.

Rules every call follows

  • Config gate. Every call that opens an order or fills one takes &Config and aborts with 20 while the market is halted, or 21 when this package revision is retired. Cancels, refunds, payouts and unlistings never take Config, so neither a halt nor an upgrade can lock your items or SUI.
  • No contention. Buys and fills read Config by &. Each order, offer, pool, raffle, bundle and swap is its own shared object, so trades on different objects never wait on each other. The collection's TransferPolicy is taken &mut whenever royalty is paid, because royalty_rule::pay writes to it.
  • Transfer policies. Calls that move an item into a kiosk satisfy the four standard rules: they pay royalty, lock the item when the policy has a lock rule (otherwise they place it), and prove the personal kiosk and floor price rules. They return the TransferRequest<T>. You add receipts for any other rule and call 0x2::transfer_policy::confirm_request<T>(policy, request). The item is already in its destination when the request comes back.
  • Payments are &mut Coin<SUI>. Each call splits off exactly what it needs and you keep the rest. Calls that pay you return a Coin<SUI>.
  • Deliveries to someone who is not signing (offer fills, bundle bids, items a swap maker receives) go into a kiosk that has the courier extension, and only if that kiosk's owner is the recipient. Set this up once with courier::open or courier::enable.
  • Type names. kind in events and offer terms is type_name::with_defining_ids<T>(). In JSON it is the type string without the 0x prefix.

Listings

sale_kiosk: kiosk items

Use this for any type that has a TransferPolicy. The item stays in the seller's kiosk, listed exclusively through a PurchaseCap held by the order, so it can only leave through this module.

Move
public fun post<T: key + store>(
    cfg: &Config,
    kiosk: &mut Kiosk,
    kiosk_cap: &KioskOwnerCap,
    item: ID,
    ask: u64,
    ctx: &mut TxContext,
): ID

Lists item at ask and returns the order id. The listing rate is locked into the order; the fee is ask * bps / 10000 (rounded down) and the item is listed in the kiosk at ask - fee. Aborts: 40 when ask is 0.

Move
public fun buy<T: key + store>(
    order: KioskOrder<T>,
    cfg: &Config,
    kiosk: &mut Kiosk,          // the seller's kiosk
    dest: &mut Kiosk,           // the buyer's kiosk
    dest_cap: &KioskOwnerCap,
    policy: &mut TransferPolicy<T>,
    pay: &mut Coin<SUI>,
    ctx: &mut TxContext,
): TransferRequest<T>

Buys the item into the buyer's kiosk. Takes ask from pay, sends the fee to the treasury, then pays royalty on ask - fee from the same coin. Confirm the returned request. Aborts: 11 wrong seller kiosk, 30 when pay is below ask, 31 when what is left cannot cover the royalty.

Move
public fun take<T: key + store>(
    order: KioskOrder<T>,
    cfg: &Config,
    kiosk: &mut Kiosk,
    pay: &mut Coin<SUI>,
    ctx: &mut TxContext,
): (T, TransferRequest<T>)

Raw purchase. You get the item and the request and resolve the policy yourself, for example with clearing::settle_into(policy, &mut request, item, kiosk, kiosk_cap, royalty_coin), then confirm.

Move
public fun reprice<T: key + store>(order: &mut KioskOrder<T>, cfg: &Config, kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap, ask: u64, ctx: &mut TxContext)
public fun pull<T: key + store>(order: KioskOrder<T>, kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap)

reprice keeps the order id and re-issues the exclusive listing at the new price with the current rate. pull unlists and is never gated. Both need the kiosk's owner cap (11 wrong kiosk, 12 no access).

The buyer pays ask plus royalty. The treasury gets the fee. The seller's kiosk profits get ask - fee, which the seller withdraws with 0x2::kiosk::withdraw.

sale_escrow: wallet items

For types without a TransferPolicy. This path cannot enforce a policy, so route any type that has one to sale_kiosk.

Move
public fun post<T: key + store>(cfg: &Config, item: T, ask: u64, ctx: &mut TxContext): ID
public fun take<T: key + store>(order: EscrowOrder<T>, cfg: &Config, pay: &mut Coin<SUI>, ctx: &mut TxContext): T
public fun reprice<T: key + store>(order: &mut EscrowOrder<T>, cfg: &Config, ask: u64, ctx: &TxContext)
public fun pull<T: key + store>(order: EscrowOrder<T>, ctx: &TxContext): T

take sends the fee to the treasury and ask - fee to the seller's address, and returns the item. reprice and pull are seller only (10). pull is never gated. Aborts: 40 zero ask, 30 short payment.

Sweeps

There is no sweep function. A sweep is one PTB that calls sale_kiosk::buy (or sale_escrow::take) once per order and passes the same payment coin to every call. Each call splits off what it needs, so you do not need a SplitCoins per listing. Orders are independent objects, so a sweep only touches the orders and seller kiosks involved.

Offers

offer: item, trait and collection offers

Move
public fun place<T: key + store>(
    cfg: &Config,
    item: Option<ID>,            // one item (units must be 1)
    root: Option<vector<u8>>,    // or any item in a Merkle set, 32 bytes; neither: any item of T
    price: u64,                  // per unit, paid to the seller
    units: u64,
    reserve: u64,                // royalty budget per unit: clearing::royalty_due(policy, price)
    ends_ms: Option<u64>,        // end time, none for no end
    dest: Option<ID>,            // your courier-enabled kiosk, needed for kiosk fills
    pay: &mut Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
): ID

Escrows units * (price + fee + reserve), where fee = price * offer_bps / 10000. Pass reserve = clearing::royalty_due(policy, price) for a type with a royalty policy; with 0, kiosk fills of such a type abort with 31 and wallet fills still work. Aborts: 42 both item and root, a root that is not 32 bytes, or an item offer with more than one unit; 40 zero price, 41 zero units, 64 end time not in the future, 30 short payment.

Move
public fun fill<T: key + store>(
    offer: &mut Offer<T>,
    cfg: &Config,
    seller_kiosk: &mut Kiosk,
    seller_cap: &KioskOwnerCap,
    item: ID,
    dest: &mut Kiosk,                // must be the offer's dest kiosk
    policy: &mut TransferPolicy<T>,
    proof: vector<vector<u8>>,       // empty unless the offer has a root
    clock: &Clock,
    ctx: &mut TxContext,
): (Coin<SUI>, TransferRequest<T>)

Sells a kiosk item into the offer. The item is bought out of the seller's kiosk at price and delivered into the bidder's kiosk through courier. Royalty comes out of the reserve and the unused reserve for that unit goes back to the bidder. Returns the seller's proceeds (price, in full) and the request to confirm. Aborts: 45 wrong type, 25 no units left, 23 ended (an offer is live while now < ends_ms), 43 wrong item, 44 not in the set, 48 offer has no dest, 49 wrong dest, 14 the dest kiosk is not the bidder's, 31 reserve short.

Move
public fun fill_owned<T: key + store>(offer: &mut Offer<T>, cfg: &Config, item: T, proof: vector<vector<u8>>, clock: &Clock, ctx: &mut TxContext): Coin<SUI>
public fun revoke<T>(offer: Offer<T>, ctx: &mut TxContext): Coin<SUI>
public fun retire<T>(offer: Offer<T>, clock: &Clock, ctx: &mut TxContext)

fill_owned sells a wallet item: it goes to the bidder's address, the unit's reserve goes back to the bidder and the seller gets price. revoke is bidder only (10) and refunds the whole remaining escrow, fees included. It is never gated. retire can be called by anyone once the offer has ended or is used up (24 otherwise) and sends the escrow to the bidder.

Views: terms, maker, escrowed, units_left, unit_price, unit_fee, unit_reserve, target_item, target_root.

Trait offers

The bidder commits a Merkle root over the eligible item ids. The seller passes the proof for their item.

  • Leaf: blake2b256(0x00 || bcs(id)).
  • Node: blake2b256(0x01 || min(a, b) || max(a, b)), in lexicographic byte order.
  • Proof: the sibling hashes from leaf to root.

merkle::leaf, merkle::join and merkle::contains compute the same thing on chain.

offer_pool: many offers on one balance

One balance backs up to 128 offers. Each member reserves its full cost from the pool, and reserved can never exceed funds.

Move
public fun new(cfg: &Config, label: Option<String>, ctx: &mut TxContext): OfferPool   // unshared
public fun share(pool: OfferPool)
public fun deposit(pool: &mut OfferPool, coin: Coin<SUI>, ctx: &TxContext)
public fun withdraw(pool: &mut OfferPool, amount: u64, ctx: &mut TxContext): Coin<SUI>
public fun add<T: key + store>(pool: &mut OfferPool, cfg: &Config, item: Option<ID>, root: Option<vector<u8>>, price: u64, units: u64, reserve: u64, ends_ms: Option<u64>, dest: Option<ID>, clock: &Clock, ctx: &mut TxContext): ID
public fun fill<T: key + store>(pool: &mut OfferPool, member: ID, cfg: &Config, seller_kiosk: &mut Kiosk, seller_cap: &KioskOwnerCap, item: ID, dest: &mut Kiosk, policy: &mut TransferPolicy<T>, proof: vector<vector<u8>>, clock: &Clock, ctx: &mut TxContext): (Coin<SUI>, TransferRequest<T>)
public fun fill_owned<T: key + store>(pool: &mut OfferPool, member: ID, cfg: &Config, item: T, proof: vector<vector<u8>>, clock: &Clock, ctx: &mut TxContext): Coin<SUI>
public fun drop_member(pool: &mut OfferPool, member: ID, ctx: &TxContext)
public fun prune(pool: &mut OfferPool, member: ID, clock: &Clock)
public fun close(pool: OfferPool, ctx: &mut TxContext): Coin<SUI>

Create the pool with new, deposit and add members in the same PTB, then share it. add takes the same terms as offer::place. fill and fill_owned follow the same rules as the offer versions, and a used-up member is deleted. deposit, withdraw, relabel, add, drop_member and close are owner only (10). withdraw and add are limited to unreserved funds (32). prune lets anyone remove an ended or used-up member (24). withdraw, drop_member and close are never gated. Aborts: 46 more than 128 members, 63 unknown member.

Swaps (barter)

A swap trades items and SUI between a maker and a taker, both sides in kiosks.

The maker builds the deal in one PTB:

Move
public fun draft(cfg: &Config, maker_kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap, want: vector<ID>, ask: u64, bid: u64, taker: Option<address>, ends_ms: Option<u64>, pay: &mut Coin<SUI>, clock: &Clock, ctx: &mut TxContext): Deal
public fun pledge<T: key + store>(deal: &mut Deal, maker_kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap, item: ID, ctx: &mut TxContext)
public fun publish(deal: Deal)

draft enables courier on the maker's kiosk and escrows bid plus the swap fee on it (bid * swap_bps / 10000), which is only charged if the swap settles. The kiosk owner must be the sender (15). Up to 32 items per side, with no repeats (46, 47), and ends_ms in the future (64). pledge adds each offered item under an exclusive cap (a listed item is refused by the kiosk). publish shares the deal (62 when nothing is offered).

The taker settles in one PTB:

Move
public fun begin(deal: &mut Deal, cfg: &Config, pay: &mut Coin<SUI>, clock: &Clock, ctx: &mut TxContext): Swap
public fun hand<T: key + store>(swap: &mut Swap, deal: &mut Deal, maker_kiosk: &mut Kiosk, taker_kiosk: &mut Kiosk, taker_cap: &KioskOwnerCap, policy: &mut TransferPolicy<T>, item: ID, pay: &mut Coin<SUI>, ctx: &mut TxContext): TransferRequest<T>
public fun receive<T: key + store>(swap: &mut Swap, deal: &mut Deal, taker_kiosk: &mut Kiosk, taker_cap: &KioskOwnerCap, maker_kiosk: &mut Kiosk, policy: &mut TransferPolicy<T>, item: ID, pay: &mut Coin<SUI>, ctx: &mut TxContext): TransferRequest<T>
public fun finish(swap: Swap, deal: Deal, ctx: &mut TxContext)

begin checks the deal is open (27), has not ended (23) and that the sender is the named taker, if any (13). It takes ask from pay and charges the swap fee on both SUI legs. Call hand once per offered item (it moves into the taker's kiosk at an even part of ask - fee) and receive once per wanted item (it moves into the maker's kiosk through courier, and the taker is paid an even part of bid); the first item of each side carries the rounding remainder. Royalty for both comes from pay. finish aborts unless every item moved (28). Confirm every returned request. If a side has no items, its SUI goes straight to the other party.

To cancel, call unwind(&mut Deal, &Clock), then restore<T> per pledged item, then unwound(u, deal, &Clock). The maker can always cancel. Anyone can once now >= ends_ms (10 otherwise). The bid and its fee go back to the maker. Cancelling is never gated.

Raffles

Raffles and bundles are not in the first mainnet release of the market package. They come in a later package upgrade, as described here; their fee rows and event types are already in the first release.

Move
public fun open_kiosk<T: key + store>(cfg: &Config, policy: &TransferPolicy<T>, kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap, item: ID, price: u64, min_tickets: u64, max_tickets: u64, ends_ms: u64, clock: &Clock, ctx: &mut TxContext): ID
public fun open_owned<T: key + store>(cfg: &Config, prize: T, price: u64, min_tickets: u64, max_tickets: u64, ends_ms: u64, clock: &Clock, ctx: &mut TxContext): ID
public fun buy<T>(raffle: &mut Raffle<T>, cfg: &Config, qty: u64, pay: &mut Coin<SUI>, clock: &Clock, ctx: &mut TxContext)
entry fun draw<T>(raffle: &mut Raffle<T>, rnd: &Random, clock: &Clock, ctx: &mut TxContext)

open_kiosk keeps the prize in the host's kiosk under an exclusive cap and binds the policy. open_owned escrows a wallet item. Limits: 1 <= min_tickets <= max_tickets <= 1,000,000 (42), price above 0 (40), and ends_ms in the future and within 30 days (64). buy works before ends_ms (23) up to max_tickets (25).

draw is an entry function that reads 0x8 (Random). Anyone can call it once the raffle has ended or sold out (24) with at least min_tickets sold (34). Because a call that uses Random cannot be followed by other commands, settlement is a separate transaction:

  • settle_kiosk<T>(raffle, host_kiosk, policy): TransferRequest<T>: anyone. The prize goes into a new kiosk owned by the winner (personal when the policy needs it). The policy must be the bound one (45).
  • claim_kiosk<T>(raffle, host_kiosk, policy, kiosk, kiosk_cap): TransferRequest<T>: winner only (10), into their own kiosk.
  • settle_owned<T>(raffle): anyone, for wallet prizes.

The pot pays the fee to the treasury, then (for kiosk prizes) royalty on the sale price, and the rest to the host. void cancels a raffle: the host before any sale, anyone after the end with too few tickets sold, or anyone when a drawn raffle has gone unsettled for 7 days. After void, anyone can call refund<T>(raffle, holder) to pay a ticket holder back in full and reclaim_kiosk<T> to return a kiosk prize, and dispose deletes the raffle once everything is returned. None of these are gated.

Bundles

Raffles and bundles are not in the first mainnet release of the market package. They come in a later package upgrade, as described here; their fee rows and event types are already in the first release.

The maker lists several kiosk items as one lot:

Move
public fun draft(cfg: &Config, ctx: &mut TxContext): Bundle
public fun stack<T: key + store>(bundle: &mut Bundle, kiosk: &mut Kiosk, kiosk_cap: &KioskOwnerCap, item: ID, ctx: &mut TxContext)
public fun publish(bundle: Bundle, ask: u64, seal: Option<vector<u8>>)

At most 32 items (46). The price is split evenly across the items and the last item takes the remainder. seal is an optional sealed reserve for bids: commitment(reserve, salt) = blake2b256(bcs(reserve) || salt). reseal changes it later. Unlisting is unstack, restore<T> per item, then unstacked, and is never gated.

A buyer takes the whole bundle in one PTB:

Move
public fun checkout(bundle: &mut Bundle, cfg: &Config, pay: &mut Coin<SUI>, _ctx: &mut TxContext): Checkout
public fun collect<T: key + store>(co: &mut Checkout, bundle: &mut Bundle, seller_kiosk: &mut Kiosk, dest: &mut Kiosk, dest_cap: &KioskOwnerCap, policy: &mut TransferPolicy<T>, item: ID, royalty: &mut Coin<SUI>, ctx: &mut TxContext): TransferRequest<T>
public fun checkout_done(co: Checkout, bundle: Bundle, cfg: &Config, ctx: &mut TxContext)

checkout takes ask + ask * bundle_bps / 10000 (30 if short). Call collect once per item, then checkout_done, which aborts unless every item was collected (28).

Bids escrow amount + amount * bundle_bps / 10000 + reserve, where reserve is the royalty budget, and name the bidder's courier-enabled kiosk as dest:

Move
public fun bid(bundle: &Bundle, cfg: &Config, amount: u64, reserve: u64, until_ms: u64, dest: ID, pay: &mut Coin<SUI>, clock: &Clock, ctx: &mut TxContext): ID
public fun withdraw_bid(b: BundleBid, ctx: &mut TxContext): Coin<SUI>
public fun lapse_bid(b: BundleBid, clock: &Clock, ctx: &mut TxContext)

withdraw_bid is bidder only and never gated. lapse_bid returns an expired bid to its bidder and anyone can call it. To accept, call accept(bundle, bid, cfg, reveal, salt, clock), then deliver<T> per item, then accepted. The maker can accept any bid without a reveal. Anyone else needs the reveal of the sealed reserve (16), and the bid must be at least the reserve (33). A reveal that lands on chain, even in a failed transaction, discloses the reserve, so reseal after using it.

Courier and clearing helpers

Move
public fun open(personal: bool, ctx: &mut TxContext): ID
public fun enable(kiosk: &mut Kiosk, cap: &KioskOwnerCap, ctx: &mut TxContext)
public fun ready(kiosk: &Kiosk): bool

courier::open creates and shares a kiosk for the sender with deliveries enabled. With personal = true the owner cap is wrapped as a PersonalKioskCap, which collections with a personal kiosk rule require. courier::enable installs (or re-enables) the extension on an existing kiosk. For a personal kiosk, pass the cap borrowed from your PersonalKioskCap.

Move
public fun royalty_due<T: key + store>(policy: &TransferPolicy<T>, paid: u64): u64
public fun needs_lock<T>(policy: &TransferPolicy<T>): bool
public fun needs_personal<T>(policy: &TransferPolicy<T>): bool
public fun settle_into<T: key + store>(policy: &mut TransferPolicy<T>, req: &mut TransferRequest<T>, item: T, kiosk: &mut Kiosk, cap: &KioskOwnerCap, royalty: &mut Coin<SUI>, ctx: &mut TxContext): u64

royalty_due quotes the royalty on a payment (0 without a royalty rule); it is also how you size an offer's reserve. settle_into stows an item you bought into your kiosk, satisfies the standard rules, pays royalty from royalty and returns the amount paid.

Fees and royalties

TradeFeeWho pays
Listingask * bps / 10000, taken out of ask (rate locked in at posting)Seller (nets ask - fee)
Offer and pool fillprice * offer_bps / 10000, escrowed on top of priceBidder
Swapbid * swap_bps / 10000 (escrowed with the bid) and ask * swap_bps / 10000 (out of the taker's ask), both charged when the swap settlesMaker and taker
Rafflepot * raffle_bps / 10000 at settlementHost
Bundleask * bundle_bps / 10000 (or amount * bundle_bps / 10000 for a bid), on topBuyer or bidder

Every fee row is 10 bps (0.1%) on mainnet today (see Fees and royalties) and is capped at 300 bps (53). Changes are queued with the ConfigCap and take effect only after 48 hours, through config::apply, which anyone can call. Fees round down, so a fee on an amount below 1,000 MIST is 0 and the trade goes through without one.

Royalties follow the collection's own TransferPolicy (royalty_rule). On a kiosk listing the buyer pays royalty on top, computed on the kiosk price ask - fee. On offers it comes from the reserve the bidder escrowed. On swaps and bundle purchases it comes from the pay or royalty coin you pass in. Read a quote with clearing::royalty_due.

Events

All events are in PACKAGE_ID::events, with the original package id in their type. Field order never changes, so decode them from BCS with these layouts.

EventFields
AskPostedask, seller, item, kind, kiosk: Option<ID>, price, fee, repost. Kiosk listings carry their kiosk; repost marks a new price on the same listing.
AskWithdrawnask, seller, item, kind, kiosk: Option<ID>, price
AskFilledask, seller, buyer, item, kind, kiosk: Option<ID>, buyer_kiosk: Option<ID>, price, fee, royalty. buyer_kiosk and royalty are set by sale_kiosk::buy and are none and 0 for take.
BidPostedbid, pool: Option<ID>, bidder, kind, item: Option<ID>, root: Option<vector<u8>>, price, fee, reserve, units, ends_ms: Option<u64>, dest: Option<ID>. For pool members, bid is the member id.
BidFilledbid, pool, bidder, seller, item, kind, price, fee, royalty, refund, units_left, seller_kiosk: Option<ID>, dest: Option<ID>
BidClosedbid, pool, bidder, units_left, refund, cause (1 cancelled, 2 ended, used up or pruned, 3 pool closed)
PoolOpenedpool, owner, label
PoolStatepool, owner, funds, reserved, members, label. The pool's full state after every change.
PoolClosedpool, owner, refund
SwapOffereddeal, maker, taker, maker_kiosk, give, want, ask, bid, ends_ms
SwapDonedeal, maker, taker, give, want, ask, bid, fee
SwapCancelleddeal, maker, by, refund, lapsed
RaffleOpenedraffle, host, item, kind, host_kiosk, price, min_tickets, max_tickets, ends_ms, fee_bps
TicketsBoughtraffle, buyer, first, qty, paid, sold. The buyer owns tickets first to first + qty - 1.
RaffleDrawnraffle, winner, ticket, sold
RaffleSettledraffle, winner, host, gross, fee, royalty, to_host, winner_kiosk
RaffleVoidedraffle, host, by, sold, pot
RaffleRefundedraffle, holder, qty, amount
BundleListedbundle, maker, items, kinds, ask, sealed_reserve
BundleResealedbundle, sealed_reserve
BundleClosedbundle, maker, reason
BundleSoldbundle, maker, buyer, price, fee, royalty, bid: Option<ID>
BundleBidPlacedbid, bundle, bidder, amount, fee, reserve, until_ms, dest_kiosk
BundleBidClosedbid, bidder, refunded, reason (0 withdrawn, 1 lapsed)
FeesQueuedconfig, treasury, keys, bps, at_ms
FeesAppliedconfig, treasury, keys, bps (the whole table after the change)
FeesDiscarded / MarketHalted / MarketMigratedconfig / config, halted / config, rev

Error codes

Abort codes follow one scheme across the package, by meaning. The module in the abort tells you where.

CodeMeaning
10The sender is not the owner (seller, bidder, pool owner, swap maker, raffle winner).
11 / 12Wrong kiosk / the cap does not open the kiosk.
13Not the named taker or bidder.
14 / 15The delivery kiosk is not the recipient's / the swap kiosk is not the sender's.
16Not allowed now (raffle void, bundle accept without the reveal).
20 / 21 / 22Market halted / package revision retired / object from a newer revision.
23 / 24 / 25Ended / still open / used up or sold out.
26 / 27 / 28Already published / not open / items left to move.
29Deliveries are not enabled on the kiosk.
30 / 31 / 32Payment short / royalty short / pool over-committed.
33 / 34Bid below the sealed reserve / too few raffle tickets.
40 / 41 / 42Zero price / zero quantity / bad target or limits.
43 / 44 / 45Wrong item / not in the set / wrong type or policy.
46 / 47Too many / duplicate.
48 / 49The offer has no delivery kiosk / wrong delivery kiosk.
50 to 54Config: nothing queued, still waiting, not a newer revision, above the 3% cap, bad fee rows.
60 to 64Wrong deal or bundle, item not wanted, nothing offered, unknown pool member, end time not in the future or too far.
65 to 70Raffle and bundle states (later upgrade).

Examples

These use @mysten/sui with the Transaction builder. Replace the placeholder ids with the values from the status box above.

Buy a kiosk listing

TypeScript
import { Transaction } from "@mysten/sui/transactions";

const PACKAGE_ID = "0x..."; // latest market package id
const CONFIG_ID = "0x...";  // shared market::config::Config

export function buyListing(
  tx: Transaction,
  l: {
    orderId: string;      // KioskOrder id (the `ask` field of AskPosted)
    sellerKiosk: string;  // the `kiosk` field of AskPosted
    itemType: string;     // T, for example "0xabc::nft::Nft"
    policyId: string;     // shared TransferPolicy<T>
    ask: bigint;          // in MIST
  },
  buyer: { kiosk: string; kioskCap: string },
) {
  // Pay the ask plus a royalty quote. Royalty is charged on `ask - fee`,
  // so a quote on `ask` is an upper bound and the change comes back.
  const [due] = tx.moveCall({
    target: `${PACKAGE_ID}::clearing::royalty_due`,
    typeArguments: [l.itemType],
    arguments: [tx.object(l.policyId), tx.pure.u64(l.ask)],
  });
  const [pay] = tx.splitCoins(tx.gas, [l.ask]);
  const [royalty] = tx.splitCoins(tx.gas, [due]);
  tx.mergeCoins(pay, [royalty]);

  const [request] = tx.moveCall({
    target: `${PACKAGE_ID}::sale_kiosk::buy`,
    typeArguments: [l.itemType],
    arguments: [
      tx.object(l.orderId),
      tx.object(CONFIG_ID),
      tx.object(l.sellerKiosk),
      tx.object(buyer.kiosk),
      tx.object(buyer.kioskCap),
      tx.object(l.policyId),
      pay,
    ],
  });
  tx.moveCall({
    target: "0x2::transfer_policy::confirm_request",
    typeArguments: [l.itemType],
    arguments: [tx.object(l.policyId), request],
  });
  tx.mergeCoins(tx.gas, [pay]); // return the change
}

To sweep, call sale_kiosk::buy once per listing with the same pay coin, funded with the sum of the asks and royalty quotes.

If the buyer has no kiosk yet, create one in the same PTB with 0x2::kiosk::new, pass it to buy, then share it and send the cap to the buyer:

TypeScript
const [kiosk, kioskCap] = tx.moveCall({ target: "0x2::kiosk::new" });
// ... sale_kiosk::buy with `kiosk` and `kioskCap` as dest and dest_cap ...
tx.moveCall({
  target: "0x2::transfer::public_share_object",
  typeArguments: ["0x2::kiosk::Kiosk"],
  arguments: [kiosk],
});
tx.transferObjects([kioskCap], sender);

Collections with a personal kiosk rule need a personal kiosk instead.

List a kiosk item

TypeScript
tx.moveCall({
  target: `${PACKAGE_ID}::sale_kiosk::post`,
  typeArguments: [itemType],
  arguments: [
    tx.object(CONFIG_ID),
    tx.object(kioskId),
    tx.object(kioskCapId),
    tx.pure.id(itemId),
    tx.pure.u64(5_000_000_000n), // ask: 5 SUI, buyer pays this plus royalty
  ],
});

Place a collection offer

TypeScript
const price = 2_000_000_000n; // 2 SUI per item
const units = 3n;
// Escrow is units * (price + fee + reserve):
//   fee     = price * offer_bps / 10000   (offer_bps from the Config object)
//   reserve = clearing::royalty_due(policy, price)
// Fund at least that much (quote the royalty off chain with a simulated royalty_due call).
// Whatever the call does not use stays in `pay`.
const budget = units * (price + fee + royaltyQuote);
const [reserve] = tx.moveCall({
  target: `${PACKAGE_ID}::clearing::royalty_due`,
  typeArguments: [itemType],
  arguments: [tx.object(policyId), tx.pure.u64(price)],
});
const [pay] = tx.splitCoins(tx.gas, [budget]);
tx.moveCall({
  target: `${PACKAGE_ID}::offer::place`,
  typeArguments: [itemType],
  arguments: [
    tx.object(CONFIG_ID),
    tx.pure.option("address", null),       // item: none
    tx.pure.option("vector<u8>", null),    // root: none, so any item of the collection
    tx.pure.u64(price),
    tx.pure.u64(units),
    reserve,
    tx.pure.option("u64", Date.now() + 7 * 86_400_000), // ends in 7 days
    tx.pure.option("address", myCourierKioskId),        // dest kiosk for kiosk fills
    pay,
    tx.object("0x6"),
  ],
});
tx.mergeCoins(tx.gas, [pay]);

myCourierKioskId must be a kiosk you own with the courier extension installed (courier::open or courier::enable).

Sell into an offer from your kiosk

TypeScript
const [proceeds, request] = tx.moveCall({
  target: `${PACKAGE_ID}::offer::fill`,
  typeArguments: [itemType],
  arguments: [
    tx.object(offerId),
    tx.object(CONFIG_ID),
    tx.object(myKioskId),
    tx.object(myKioskCapId),
    tx.pure.id(itemId),
    tx.object(destKioskId), // the offer's `dest` from BidPosted
    tx.object(policyId),
    tx.pure.vector("vector<u8>", []), // Merkle proof for trait offers, else empty
    tx.object("0x6"),
  ],
});
tx.moveCall({
  target: "0x2::transfer_policy::confirm_request",
  typeArguments: [itemType],
  arguments: [tx.object(policyId), request],
});
tx.transferObjects([proceeds], sender);

If the item is listed natively in your kiosk, delist it first with 0x2::kiosk::delist. For pool members, call offer_pool::fill with the pool id and the member id in front of the same arguments.

--
TPS:--