Custom Villager Trades

569,558 Downloads Last Updated: Mar 28, 2022 Game Version: 1.18.2   +1

PSA: Please take a look at the "Features" spoiler for a full list of what this mod is capable of.

You can now refresh trades without having to restart the game/server. Use /reloadTrades

Please note that the refreshTrades command is experimental, and I hold no responsibility for broken games. Please triple check your JSONs before refreshing!


This mod is designed to expand upon the vanilla villager trading offers. It is made for modpack authors.

By default, no extra trades are added. You need to go in to the config file and add them yourself!

That being said, if you load this mod for the first time it will create an example trade for the armorer profession (which you should modify or remove).

How does it work?

This mod reads json files from the "config/custom villager trades" directory. The directory will be created (with an example file) when you load the mod for the first time (and if no config files are present).

The profession modified will depend on what you put inside the file.

After getting the trades, it will inject in to the villager trade event provided by forge (exactly how other mods do it), the only difference is you can create the trade exactly how you want it.

The mod will perform a check on each trade to make sure they are valid. If there are any problems it will then report this on the console.

The file must be built as specified below. I have made an example file if you are unsure how to make it.


 A fully customizable trade creation system where you can define basic or advanced trades using JSON.

Modify trades for any profession using a simple named config file (including the nitwit).

You can set "global" trades, these will be applied to any villager that can trade (call the config file "all.json")

Trades can be applied based on level.

All aspects of the trade can be modified (trade experience, discounts, etc.)

Enchantments can be applied to any trade item. This allows for whacky unique items that can't be acquired via normal (vanilla) means.

Enchantments can now be randomized in 3 ways, read below.

Enchantments can be blacklisted, usable with random enchantment feature.

Modded item and block support.

Modded profession support - you can add trades to other people's villagers.

Remove all vanilla trades - you can do this per-profession.

Vanilla wanderer trades can be modified/replaced.

Custom potion trades, including random and blacklisted.

Custom suspicious stew trades.

Custom treasure map trades (with modded structure support).

Custom tipped arrow trades (with modded potion effect support). Includes random and blacklisted.

Custom potions and tipped arrows can be coloured.

Force an NPC's level up whilst in creative (press UP arrow key).

Custom NBTs (basic and advanced).

Modder/developer support.

/reloadTrades command to use ingame - EXPERIMENTAL FEATURE


List of vanilla professions (this is what the files should be named):

















The wanderer must have a separate file in a different directory, this is "config/custom trades/wanderer"





Note that this mod does not give you the option to create trades for villagers who have no profession/unemployed.

Your trade is not guaranteed to appear every time - this is because of the trade pools. You can however remove vanilla trades.

If you are unsure what the item ID is, press f3+h ingame to enable tooltips and hover over the item you want to add.

If you have any problems launching the game with a custom config, please first start the game without a config and see if it goes to the title screen. If it does then your config is not formatted correctly. There will also be an error message in the console/log if it is caused by custom villager trades.

If you remove a trade that a villager already has, the villager will still keep that trade because it is stored in the NBT.

The wanderer must have a minimum of 5 "common" and 1 "rare" trades.


Config Files

For each profession, you can specify custom trades. Some fields are required and others are not. Here is an example: Example villager trade -

Required fields:

  • profession - This MUST be defined only once, it must not be nested inside of any objects.
  • removeOtherTrades - This will remove other trades for this profession (works with vanilla).
  • trades - This is an array of objects, each object defines a trade.
  • trades / isRare - This is only for the wanderer and will have no effect on other trades. Does exactly as the label indicates. True / False.
  • trades / offer - REQUIRED for each trade definition. See "Trade Object" below.
  • trades / multiOffer - OPTIONAL, if this is set it will replace the "offer" object above. This is an array of "Trade Objects" and the mod will choose from one of these when generating the trade. This allows for several variants of the same trade without adding to the weight (how common the trade is). Example multiOffer
  • trades / request - REQUIRED for each trade definition. See "Trade Object" below.
  • trades / additionalRequest - OPTIONAL. See "Trade Object".
  • trades / tradeExp - REQUIRED, how much experience does the villager get for this trade (this experience is for the villager to go to the next trade level). I suggest not going below 1.
  • trades / maxUses - REQUIRED
  • trades / priceMultiplier - REQUIRED, check out the Minecraft wiki for an explanation on how price multipliers work.
  • trades / demand - REQUIRED, check out the Minecraft wiki for an explanation on how demand works.
  • trades / tradeLevel - REQUIRED, at what level does this trade become available? The range is 1-5 where 1 is lowest.

Trade Object:

The below are requirements for each item defined within each 'trade object' instance.

  • / itemKey - REQUIRED
  • / amount - REQUIRED
  • / priceModifier - OPTIONAL, will add this number to the price (can be a minus number to make it discounted). This modifier is added/subtracted to the "request" object's "amount".
  • / enchantments - OPTIONAL, An object array of enchantments that can be applied, see "enchantment object" below.
  • / semiRandomEnchantments - OPTIONAL, see option 3 in the enchantments section (advanced semi-random enchantments).
  • / effects - OPTIONAL, An object array of Effects that can be applied, see "effect object" below
  • / blacklistedEffects - OPTIONAL, works the same way as blacklistedEnchantments
  • / customColourR - OPTIONAL, red value for custom potion/tipped arrow colour
  • / customColourG - OPTIONAL, green value for custom potion/tipped arrow colour
  • / customColourB - OPTIONAL, blue value for custom potion/tipped arrow colour
  • / metadata - OPTIONAL
  • / customName - OPTIONAL, you can rename the item if you like.
  • / nbtTags - OPTIONAL, you can define any NBTs if you like. See "NBT Object" below. Example NBT input -
  • / advancedNBTData - OPTIONAL, this can be used alongside nbtTags. This is basically a JSON represented as a string. All quotes inside must be escaped (by putting a backslash before the quote \" ) Example: Custom Villager Trades - Example advanced NBT -

Enchantment Object:

  • / enchantmentKey - REQUIRED, this must be the key of the enchantment, example - minecraft:sharpness or minecraft:swiftness
  • / enchantmentLevel - REQUIRED, this can also be random, to do so set it as -1
  • / maxEnchantmentLevel - OPTIONAL, This is used to set the maximum random level. If not set, this defaults to 3.

Effects Object:

  • / effectKey - REQUIRED, this must be the key of the effect, example - minecraft:slow_falling or minecraft:speed
  • / duration - REQUIRED, in ticks (20 ticks = 1 second)
  • / level - REQUIRED, must be greater than 0.
  • / isVisible - REQUIRED, default is true, setting this to false will make the effect invisible to the player (I do not recommend this).
  • / potionKey - CONDITIONAL, only required if the item is "minecraft:tipped_arrow".
  • / blacklistedPotionKeys - OPTIONAL, string array, works the same as all other blacklists. Custom Villager Trades - example tipped arrows -

NBT Object:

  •  / nbtName - REQUIRED, this is the name of the NBT
  • / data - REQUIRED, this is the data that the NBT will hold
  • / nbtType - OPTIONAL, if undeclared this will default to string. Allows you to convert to the required nbt type. Accepted values: String, Boolean, Integer, Float, Byte, Long


You can find existing vanilla trades to use as a guide here: https:\\\wiki\Trading#Java_Edition


As of version 7, you can now apply random enchantments in 2 ways. There are 3 ways if you use version 8 and above.


Option 1 - True random

Set the enchantment key to "random" (just random, none of that "minecraft:" stuff). This will tell the mod to search for ALL enchantments that will work with the trade item and apply one of them at the specified level.

Example: Random Enchantment Example

You can also blacklist specific enchantments. This means if you don't want one to be included in this "random" list, you can specify it here.

Example: Blacklisted Enchantments Example -


Option 2 - Semi-Random

You can set a list of enchantments for the mod to choose for a specific item. Set the enchantment key as normal and then add a hash (#) followed by another enchantment key.

Example: Semi-Random Enchantment Example


Option 3 - Advanced Semi-Random

The mod will look at the enchantments objects in this field and choose one of them.
The benefit of using this to the normal "semi-random" method is that you can also set enchantment levels per-enchantment (instead of using one level for all).
This will add enchantments alongside any defined objects in the "enchantments" field. Meaning you can have both defined and random enchantments on the same item.

Example: Advanced Semi-Random Enchantment Example -


You can apply effects in a very similar way to how enchantments are applied, in the sense that you have the same 3 options for random enchantments (see Enchantments) above.

You can also specify specific effects if you would like to.


Effects can only be applied to potions, splash potions, lingering potions, suspicious stew and anything else that applies potion effects in vanilla minecraft.


Example potion: Custom Villager Trades - example potion -

Example blacklist: Custom Villager Trades - example blacklisted effects -

Example suspicious stew: Custom Villager Trades - example suspicious stew -


Specific items

As of version 10, I have started to implement support for specific items.


Treasure Maps (version 10 and up)

For treasure maps, you must:

  • Set the "itemKey" as "minecraft:filled_map"
  • Define the "mapStructure" that you would like, eg: "mapStructure": "minecraft:buried_treasure"

This works with modded structures too, as long as you know their registry key.

Please note that as of version 16 for Minecraft 1.18.2 (only), maps will not work due to restrictions in the code.

Example: Custom Villager Trades - example map -


Tipped Arrows (version 11 and up)

For tipped arrows, you must:

  • Set the "itemKey" as "minecrarft:tipped_arrow"
  • Set "effects/potionKey" to the correct potion key. This is the only field you need to specify. The normal "effect" fields do not matter.

Example: Custom Villager Trades - example tipped arrows -


Wanderer Trades

You can now modify wanderer trades! To do this search for the folder "config/custom trades/wanderer" and create a JSON in there called "wanderer.json".

One slight difference between the wanderer trades and the existing villager trades is that you need to add a field called "isRare" and set it to either true or false.
TradeLevel does not matter for the wandering trader.

An example file for the wanderer can be found here: Wanderer Example -


WARNING: You MUST have at least 5 common and 1 rare trade in order for this to work. If you do not, then your wander trades won't be added.
If you are not removing existing wanderer trades, you do not need to worry about the above warning.


Help! My trade isn't appearing!

If your config entry is not created properly, the mod will throw a warning explaining what is wrong with that entry. It will then try to add the rest of the trades. This is an example of what you would see if there is a problem:

[14:26:03] [Worker-Main-9/INFO] [customvillagertrades/]: Checking custom villager trades...
[14:26:03] [Worker-Main-9/WARN] [customvillagertrades/]: Unable to add a custom trade! Reason: item/block does not exist - dotcoinmod:ironcoin
[14:26:03] [Worker-Main-9/INFO] [customvillagertrades/]: Check complete!


If you don't know the JSON language, please take the time to learn it before coming to me with problems - it is an easy language to learn, read and understand.

Developer / Modder integration

As of version 13, you can now register trades in your mod directly with CVT (as a dependency).

To add CVT as a dependency for your mod:

Add the following in to build.gradle:

          repositories {maven {url ""}}
In the dependencies object (build.gradle), add this:

          implementation 'curse.maven:customvillagertrades-463402:{FILEID}'
Replace {FILEID} with the last number in the url of the mod file.

          For example:

The above would look like this:

          implementation 'curse.maven:customvillagertrades-463402:3542495'
Note that the above example is for 1.16 version 13. You will have to manually update this when a new version is released.
Run "gradlew eclipse" or whatever command you use to create your workspace.



To add trades using the dependency:

- Create a "TradeCollection" / "WandererTradeCollection" object. Set the values inside.

- Define the "MyTrade" / "MyWandererTrade" object array, and add the related created objects inside. Be sure to assign values to everything needed in these objects.

- Subscribe to the InterModEnqueueEvent and send your "TradeCollection" / "WandererTradeCollection" object.
If you are confused by the above, I've left a working example in "CVTMessage.exampleTradeCollection()".

The MODID for CVT is "customvillagertrades".

A list of message options can be found in the CVTMessage class.

Your supplier must provide an instance of the trade collection. There is a built in .build() function to make this easier for you.

Please note that if a config already adds trades, you will only be able to merge your trades with it - you will not be able to remove all trades unless there are no configs for the profession.

Here is an example method you'd use to send the data to CVT.

public void imcSend(final InterModEnqueueEvent event) {

          InterModComms.sendTo("customvillagertrades", CVTMessage.ADD_VILLAGER_TRADES, () -> CVTMessage.exampleTradeCollection().build());


Mod Support

This mod should work with all other modded items (in some cases, you may need to use NBT). If there is a problem please let me know.


Something extremely important to remember when trying to remove all other trades (Version 14 onwards):


In forge, all the trade events are registered before they're fired, and they are then ordered by priority. Highest are first and lowest are last. I've made it so my event is registered as "LOWEST" priority.


Because most mods register their events as "NORMAL", it should mean that the majority of modded trades are removed when CVT trades are added.

I've tested this and it seems to be working... However, there is still a chance that modded trades will be added, especially if they register their trades at "LOWEST" priority, or at some other point of mod loading. There's nothing I can do to control how other people add their trades unfortunately.


Do feel free to share your custom trades in the comments!


This mod works really well with my other mods: Dot Coin Mod and Custom Villager Professions!


If you would like some example files (or ones you can use straight off the bat, with no configuring on your side), please head over to my discord server (below)!

Please feel free to join my discord server if you need any support!


  • To post a comment, please or register a new account.
Posts Quoted: