Mercantile

Getting Started

A linear walkthrough — install Mercantile, pick up your first villager, learn how reputation works, and refresh trades with cycling.

1. Installation

Mercantile is a Fabric mod for Minecraft 1.21.1. Like every Fabric mod, you'll need:

  1. Install Fabric Loader 0.16+ via the official Fabric installer.
  2. Download Fabric API from Modrinth and drop it into your mods/ folder.
  3. Download Mercantile from GitHub Releases and drop the jar into mods/.
  4. Launch Minecraft once. The first run generates .minecraft/config/mercantile.json with default values.

For an in-game settings GUI (recommended), also install:

  • Mod Menu — adds an entry point on the mods list.
  • Cloth Config API — provides the settings UI builder.

All other integrations (Jade, WTHIT, EMI, REI, JEI) are optional. Mercantile loads cleanly without any of them. See the full config reference for every available setting.

2. Your First Villager Pickup

Mercantile turns villagers into portable items, preserving everything about them — profession, trades, gossip, name, even their inventory. Try it:

  1. Find an adult villager (any profession, or unemployed) or a wandering trader.
  2. Make sure you have 5 XP levels available (creative mode waives the cost). The cost is configurable via pickupXpCost.
  3. Empty your main hand, then Sneak + Right-Click the villager.
  4. A green particle burst and sweep sound confirm the pickup. The villager vanishes; a profession-styled player head appears in your hand.
  5. The head item's tooltip shows the villager's profession, level, and trades. Each trade includes lock indicators and a strikethrough for out-of-stock entries.
  6. To place the villager again, Right-Click the head item on a block. The villager respawns facing you with all original data intact.

Pickup is blocked during raids, while another player is trading with the villager, and while the villager is following someone. Wandering traders use the same flow — their despawn countdown is frozen while held and resumes on placement, and any leashed trader llamas drop their lead and stay put. Read more →

3. Understanding Reputation

Mercantile tracks a persistent global reputation score per player, from −200 to +1500. The score affects pricing across every villager in the world and survives death.

The six tiers

TierRangeEffect
Reviled−200 to −150Trade refusal, angry particles, head shake
Distrusted−149 to −110–25% markup
Neutral0 to 74No effect
Liked75 to 2995% discount
Trusted300 to 99910% discount + profession-exclusive trades
Honored1000+15% discount + all exclusive trades

Ways to gain reputation

  • Complete trades: +1 per 5 trades
  • Cure a zombie villager: +5 (one-time per villager UUID)
  • Cycle a villager's trades: +1
  • Stand near a villager for 10 minutes: +1 (capped at +1/day total)
  • Gift a villager a profession item: +1 (toss crops to a Farmer, iron to an Armorer, etc.)
  • Defend a village from a raid: +10 (awarded with Hero of the Village; bypasses the daily cap)
  • Earnings from trades, cycles, and gifts are capped at 5 reputation per in-game day by default (configurable). Raid wins and zombie cures are granted in full on top of that cap.

Ways to lose reputation

  • Attack a villager: −15
  • Kill a villager: −40

Recovering from a bad reputation

Fallen to Reviled and finding villagers refuse to trade? There are two ways back. Gifting — drop a profession-appropriate item next to a villager and it will walk over, accept the gift, and nudge your reputation up (with happy particles). And time — a negative score slowly climbs back toward Neutral on its own, by default 1 point per in-game day. Positive reputation never decays, so you only ever drift upward.

Knowing where you stand

A compact HUD overlay appears in the top-left corner when a villager is within 32 blocks, showing your current tier. The icon is the Mercantile balance scale; the text is your tier name.

For a precise score, run:

/mercantile reputation

See the commands reference for op-restricted set/add variants, and features → Reputation for the full details.

Browsing trades by reputation

If you run a recipe viewer (EMI, REI, or JEI), Mercantile's trade index splits into filtered tabs alongside the full Villager Trades listing:

  • Available Trades — only the trades you can use at your current reputation, so exclusive trades you haven't earned yet stay hidden.
  • <Tier> Trades — one tab per tier that gates a trade (e.g. Trusted Trades), showing exactly what reaching that standing unlocks.

The tabs read straight from your synced reputation, so they stay in step as your standing changes.

4. Trade Cycling Basics

Tired of breaking and replacing workstations to chase a Mending book? Cycle the villager's trades for 6 emeralds (configurable) instead.

  1. Find any villager with at least one profession (Librarian for enchant books, Cleric for glowstone, etc.).
  2. Right-click to open the trade GUI. Look for the "Re-roll Trades" button in the villager info panel.
  3. Make sure you have at least tradeCycleEmeraldCost emeralds in your inventory or offhand.
  4. Click the button. Six emeralds are consumed (the cost is waived in creative). All unlocked trades are re-rolled from the profession's trade pool.
  5. You'll see a gold-diamond particle flash and hear a villager "yes" sound on success.

Locked trades are preserved. A trade becomes locked once you've purchased it at least once. Lock state is tracked by a stable hash of the trade's input/output items, so the same trade keeps the same lock across cycles. The button disables when every trade is locked.

Cycling also grants +1 reputation per cycle, so chasing trades helps your standing too. Read more →

Where to go next

  • Features — full breakdown of every Mercantile feature.
  • Config — tune every value, disable features you don't want.
  • Commands — server-side commands for ops.
  • FAQ — performance, compat, and common questions.