🏪 Marketplace

Player-to-player item trading with escrow, configurable tax rates, and listing expiration.

How It Works

Seller lists item → Item escrowed (removed from inventory)
                    → Listing visible to all players

Buyer purchases    → Currency deducted from buyer
                    → Tax burned (economy sink)
                    → Remaining currency paid to seller
                    → Item transferred to buyer

Listing an Item

Use POST /marketplace/list. The item is immediately removed from the seller's inventory (escrow) so it can't be used while listed.

Soulbound items cannot be listed. The system checks ownership and rejects if the player doesn't have sufficient quantity.

Buying a Listing

Use POST /marketplace/buy. The purchase is fully atomic — if any step fails, everything rolls back.

• • Buyer cannot purchase their own listing
• • Expired listings are automatically rejected
• • Buyer must have sufficient currency balance

Transaction Fees (Tax)

Marketplace fees are configured through the economy rules engine. Define an on_purchase rule with an apply_tax action to set the tax rate. The tax is burned (removed from circulation), acting as a currency sink.

// Example: 5% marketplace tax via rules engine
await ctx.runMutation(api.economyRulesEngine.defineRule, {
  gameId,
  ruleId: "marketplace_tax",
  trigger: "on_purchase",
  conditions: [],
  actions: [{ type: "apply_tax", params: { rate: 0.05 } }],
});

// Result: seller lists for 500 gold
// → buyer pays 500 gold
// → seller receives 475 gold
// → 25 gold is burned

Listing Expiry

Set expiresAt (unix timestamp in ms) when creating a listing. Expired listings are automatically rejected on purchase attempts and their status is updated to expired. Sellers can cancel active listings at any time to recover escrowed items.

Listing States