config.yml | ProtonAuctions Docs

The main settings file. ProtonAuctions writes it to plugins/ProtonAuctions/config.yml the first time the server starts. Keys are camelCase, and every block is documented below.

Applying changes. /ahadmin reload applies most of the keys on this page with no restart. Keys marked (restart) are read once when the server starts, so changing them needs a full restart. Both database blocks, the Redis connection and economyEngine.enabled are in that group.

Licence

Key	Default	What it does
`licenseKey`	filled on download	Your ProtonAuctions licence key. BuiltByBit fills this in automatically when a buyer downloads the plugin. See Integrity and Licensing.
`debugLogging`	`false`	Verbose troubleshooting logs. Leave it off unless you are chasing a problem.

database

Where the auction house keeps its data. The connection opens at startup, so any change here needs a restart. See Database for per-engine setup.

Key	Default	What it does
`type` (restart)	`sqlite`	One of `sqlite`, `mysql`, `postgresql`.
`address` (restart)	`localhost`	Host, for MySQL and PostgreSQL.
`port` (restart)	`3306`	Port, for MySQL and PostgreSQL.
`database` (restart)	`plugins/ProtonAuctions/data/protonauctions.db`	Database name, or the file path for SQLite.
`username` (restart)	`root`	Database user.
`password` (restart)	(empty)	Database password.

auctionSettings

The core auction rules.

Key	Default	What it does
`defaultDuration`	`86400`	Default listing length in seconds. 86400 is 24 hours.
`minPrice`	`1.0`	Lowest price a listing may set.
`maxPrice`	`1000000.0`	Highest price a listing may set.
`taxRate`	`0.05`	Sale tax taken from the seller. 0.05 is 5 percent.
`expirationCheckInterval` (restart)	`300`	How often, in seconds, the plugin sweeps for expired auctions.
`maxActiveAuctionsPerPlayer`	`50`	How many live listings one player may have at once.
`minBidIncrement`	`10.0`	Smallest raise over the current top bid.
`allowCancelWithBids`	`false`	Let a seller cancel their own bid auction after someone has bid on it. Off by default, so once the first bid is in, the auction runs to the end. Admins can still force-end it. When on, sellers can cancel at any time and the top bidder is told the auction was cancelled.
`guiRefreshInterval`	`5`	How often, in seconds, an open `/ah` menu refreshes.

auctionSettings.antiSnipe

Extends an auction when a bid lands right before it ends, so last-second snipes cannot win uncontested.

Key	Default	What it does
`enabled`	`true`	Turn anti-snipe on or off.
`secondsBeforeEnd`	`60`	A bid inside this many seconds of the end triggers an extension.
`secondsToAdd`	`60`	How many seconds the extension adds.

auctionSettings.delivery

Where sold items and sale payments go, and how unclaimed ones are handled. The concepts here (claims, vouchers, auto-claim, expiry) are covered in full under Claims. This section is the key reference.

Key	Default	What it does
`unifyBinAndBid`	`true`	Use one set of delivery settings for both Buy It Now and bid auctions. Set to `false` to use the separate `bin` and `bid` blocks below.
`sellerPaymentMethod` (restart)	`VOUCHER`	`VOUCHER` sends the payment to `/ah claim`. `DIRECT` deposits it straight to the seller's balance.
`buyerItemDelivery`	`CLAIM`	`CLAIM` sends the item to `/ah claim`. `INVENTORY` puts it straight in the buyer's inventory.
`autoClaimItemsWhenOnline`	`true`	When delivery is `CLAIM`, hand the item over automatically if the buyer is online with room.
`autoClaimRevenueWhenOnline`	`false`	When payment is `VOUCHER`, deposit it automatically if the seller is online.
`inventoryFullBehavior`	`KEEP_AS_CLAIM`	When delivery is `INVENTORY` and the inventory is full: `KEEP_AS_CLAIM` leaves it in `/ah claim`, `DROP` drops it at the player's feet.

When unifyBinAndBid is false, the bin and bid blocks each carry their own sellerPaymentMethod, buyerItemDelivery, autoClaimItemsWhenOnline, autoClaimRevenueWhenOnline and inventoryFullBehavior, with the same meanings as above.

delivery.expiredItems

How an unsold auction's item returns to its seller.

Key	Default	What it does
`deliveryMethod`	`CLAIM`	`CLAIM` returns it to the seller's `/ah claim`, `INVENTORY` puts it straight in their inventory if they are online.
`autoClaimWhenOnline`	`true`	Hand the returned item over automatically if the seller is online with room.

delivery.expiration

Optional cleanup of claims and vouchers players never collect. Durations use the Format Reference style, such as 30d or 12h.

Key	Default	What it does
`enabled` (restart)	`false`	Turn expiry of unclaimed items and vouchers on or off.
`checkInterval` (restart)	`5m`	How often to sweep for expired claims.
`itemClaimExpiresAfter`	`30d`	How long an unclaimed item waits before it expires. Empty or `0` disables it.
`revenueVoucherExpiresAfter`	`90d`	How long an unclaimed voucher waits before it expires. Empty or `0` disables it.
`onItemClaimExpire`	`RETURN_TO_SELLER`	`RETURN_TO_SELLER` gives an unclaimed purchase back to its seller as a fresh claim, `DELETE` removes the item. A claim with no seller to return to is deleted when it expires: the item from a listing that expired unsold, and a purchase that was already given back once. Items from a listing that was cancelled, by its seller or by staff, never expire.
`onRevenueExpire`	`FORFEIT`	`FORFEIT` removes the voucher, `AUTO_DEPOSIT` tries to pay it into the player's balance.
`notifyBeforeExpiry`	`true`	Warn players before their claims or vouchers expire.
`notifyBeforeExpiryTime`	`1d`	How long before expiry to warn.

delivery.limits

Caps on how many pending claims and vouchers a player may pile up.

Key	Default	What it does
`enabled` (restart)	`true`	Turn the caps on or off.
`maxPendingItemClaims` (restart)	`100`	Most pending item claims per player. `0` is unlimited.
`maxPendingRevenueVouchers` (restart)	`100`	Most pending vouchers per player. `0` is unlimited.
`onLimitReached` (restart)	`DENY_TRANSACTION`	`DENY_TRANSACTION` rejects the purchase or bid so nothing is lost.

delivery.failures

What happens when a sale cannot complete cleanly.

Key	Default	What it does
`winnerCantPayAction`	`RETURN_TO_SELLER`	When a winning bidder cannot pay at expiry: `RETURN_TO_SELLER` returns the item, `OFFER_NEXT_BIDDER` charges the next-highest bidder who can pay, `RELIST` relists the auction.
`maxRelistAttempts`	`1`	How many times a single auction may auto-relist before it returns to the seller. Only used with `RELIST`.
`onDirectDepositFail` (restart)	`FALLBACK_TO_VOUCHER`	The seller is paid only after the sale has been saved, so a failed `DIRECT` payout never undoes a sale. The money waits as a voucher in `/ah claim` instead, whichever value is set. The two values only differ when the seller's currency is not available while the sale is being made: `FALLBACK_TO_VOUCHER` completes the sale and gives the seller a voucher, `RETRY_LATER` refuses the sale and refunds the buyer.
`notifyPlayerOnFailure`	`true`	Tell the affected player when a transaction fails.

delivery.notifications

The chat lines sent as items and payments move. Each can be turned off on its own.

Key	Default	What it does
`enabled`	`true`	Master switch for delivery notifications.
`notifyOnVoucherCreated`	`true`	Tell a seller when their sale payment is waiting in `/ah claim`.
`notifyOnAutoProcessed`	`true`	Tell a player when items or payments were auto-collected on join.
`notifyOnExpired`	`true`	Tell a player when their claims or vouchers expired.

restrictions

Where and when players can use the auction house.

Key	Default	What it does
`blockedWorlds`	`[]`	Worlds where `/ah` is turned off, for example a PvP arena or a minigame world. World names are matched without regard to case.
`blockCreativeSelling`	`true`	Stop players in creative mode from listing items or making barter offers, so items they spawned cannot be sold.

restrictions.combat

Stops players using /ah for a while after a fight, so they cannot hide their gear in it. A player who gets tagged also has their open auction house menu closed.

Key	Default	What it does
`enabled`	`true`	Turn on ProtonAuctions' own combat tag.
`tagSeconds`	`15`	How long, in seconds, the block lasts after the last hit.
`includeMobs`	`false`	Also count fights with mobs, not only fights between players.
`followCombatLogX`	`true`	With CombatLogX installed, a player it has tagged is blocked as well, for as long as CombatLogX says. This works even with `enabled` off, so turning `enabled` off lets CombatLogX alone decide.

barterSettings

Item-for-item trading with no currency. Off by default. See Barter for how it works in game.

Key	Default	What it does
`enabled`	`false`	Turn the barter system on.
`maxActiveListingsPerPlayer`	`10`	Most live barter listings one player may have.
`maxItemsPerOffer`	`9`	Most item stacks a buyer may put in a single offer.
`maxOffersPerListing`	`20`	Most pending offers one listing may hold.
`maxPendingOffersPerPlayer`	`50`	Most pending offers one player may have across all listings.
`allowRequestedItems`	`true`	Let sellers name the items they want in return, rather than taking any offer.
`maxRequestedItemsPerListing`	`5`	Most requested items a listing may name.
`showInMainView`	`true`	Show barter listings in the main `/ah` view as well as the Barter category.
`requireSellerOnline`	`false`	Only accept offers while the seller is online.
`allowSelfOffer`	`false`	Let a player make offers on their own listings. Meant for testing.

barterSettings.offerExpiration

Key	Default	What it does
`enabled`	`false`	Expire pending offers after a time. Off means offers never expire.
`expiresAfter`	`7d`	How long a pending offer lasts.
`notifyBeforeExpiry`	`true`	Warn the offerer before their offer expires.
`notifyBeforeExpiryTime`	`1d`	How long before expiry to warn.

barterSettings.listingExpiration

Key	Default	What it does
`enabled`	`false`	Expire listings after a time. Off means listings are persistent.
`expiresAfter`	(empty)	How long a listing lasts. Empty or `0` keeps it forever.
`notifyBeforeExpiry`	`true`	Warn the seller before their listing expires.
`notifyBeforeExpiryTime`	`1d`	How long before expiry to warn.

barterSettings.notifications

Key	Default	What it does
`enabled`	`true`	Master switch for barter notifications.
`notifyOnOfferReceived`	`true`	Tell the seller when a new offer arrives.
`notifyOnOfferAccepted`	`true`	Tell the offerer when their offer is accepted.
`notifyOnOfferRejected`	`true`	Tell the offerer when their offer is rejected.
`notifyOnOfferExpired`	`true`	Tell the offerer when their offer expires.
`notifyOnListingExpired`	`true`	Tell the seller when their listing expires.

barterSettings.delivery

Key	Default	What it does
`deliveryMethod`	`CLAIM`	`CLAIM` sends traded items to `/ah claim`, `INVENTORY` puts them straight in the inventory.
`autoClaimWhenOnline`	`true`	Hand traded items over automatically when the player is online with room.
`inventoryFullBehavior`	`KEEP_AS_CLAIM`	With `INVENTORY` and a full inventory: `KEEP_AS_CLAIM` keeps it in `/ah claim`, `DROP` drops it.

discord

Key	Default	What it does
`enabled`	`false`	Post auction events to a Discord webhook.
`webhookUrl`	(empty)	The webhook URL to post to.
`staffWebhookUrl`	(empty)	When set, the economy engine's fraud and exploit warnings are posted to this webhook. Point it at a staff-only channel. It works whether or not `enabled` is on.

redis

Cross-server sync for a network running one shared database. See Redis.

Redis 6 or newer is required. ProtonAuctions publishes and subscribes on one connection, which older Redis does not allow.

Key	Default	What it does
`enabled` (restart)	`false`	Turn cross-server sync on.
`uri` (restart)	`redis://localhost:6379`	The Redis connection URI.
`channel` (restart)	`proton:updates`	The pub/sub channel servers share.

economyEngine

The machine-learning price and fraud engine. See the Economy Engine section for what it does and how it learns.

In this block, /ahadmin reload applies the hook switches and the keys marked (reload). Keys marked (restart) need a full restart. For any other key here, a restart is the sure way to apply it.

Key	Default	What it does
`enabled` (restart)	`true`	On by default. The engine collects sales locally from the start and begins suggesting prices after the grace period.

economyEngine.database

A separate analytics database, which can differ from the main one. See Database.

Key	Default	What it does
`type` (restart)	`sqlite`	One of `sqlite`, `mysql`, `postgresql`.
`host` (restart)	`localhost`	Host, for MySQL and PostgreSQL.
`port` (restart)	`5432`	Port, for MySQL and PostgreSQL.
`database` (restart)	`plugins/ProtonAuctions/data/proton_analytics.db`	Database name, or the file path for SQLite.
`username` (restart)	`proton`	Database user.
`password` (restart)	(empty)	Database password.

economyEngine.gracePeriod

The warmup before the engine starts suggesting prices. See Warmup and Grace.

Key	Default	What it does
`durationHours` (reload)	`24`	Hours of collecting data before suggestions turn on.
`triggerOnWipe`	`true`	Start the grace period again if auction data is wiped.

economyEngine.training

When and how the engine trains its model.

Key	Default	What it does
`autoSchedule` (reload)	`true`	Pick a quiet training window automatically from player activity. Ignores `startHour` and `endHour` when on.
`startHour` (reload)	`3`	Hour to start training, 24-hour clock. Only when `autoSchedule` is off.
`endHour` (reload)	`6`	Hour to stop training. Only when `autoSchedule` is off.
`timezone`	(empty)	Timezone for the schedule, such as `UTC`. Empty uses the server timezone. Only when `autoSchedule` is off.
`maxPlayersOnline` (reload)	`5`	Do not train while more than this many players are online.
`minTransactions`	`100`	Fewest sales needed before training runs.
`dataWindowDays`	`7`	How many days of past sales the model learns from.
`minDistinctTraders`	`5`	How many different players must have traded in that window before training runs, to resist price poisoning.
`ignoreBannedPlayers` (reload)	`true`	Leave the sales of banned players out of prices. Bans are read from the server ban list, EssentialsX, AdvancedBan and LiteBans.

economyEngine.training.evolution

An advanced, opt-in overnight tuner that searches for better model settings. Off by default, and not needed for normal use.

Key	Default	What it does
`enabled`	`false`	Turn the overnight tuner on.
`populationSize`	`50`	Candidate models per generation. Keep it above `survivorCount`.
`eliteCount`	`2`	Best models carried forward unchanged each generation.
`survivorCount`	`10`	Models bred from each generation.
`mutationRate`	`0.15`	Chance of changing each setting, 0.0 to 1.0.
`maxGenerations`	`100`	Most generations to run.
`maxHours`	`8.0`	Stop after this many hours.

economyEngine.suggestions

The price hints players see. See Price Suggestions.

Key	Default	What it does
`enabled` (reload)	`true`	Show price suggestions at all.
`minConfidence` (reload)	`0.6`	Lowest confidence, 0.0 to 1.0, before a suggestion is shown.
`showPriceRange` (reload)	`true`	Show a low-to-high range alongside the suggested price.
`priceNewItems`	`true`	Also price brand-new and rarely-traded items from the value family they belong to, at a lower confidence.
`showPricesInBrowse` (reload)	`true`	Show the market-value hint on each listing in the `/ah` browse view.
`dealDeviationPercent` (reload)	`20.0`	How far a listing's price must sit from market value, as a percent, before `/ah` shows the overpriced or great-deal badge.
`sellWarningPercent` (reload)	`50.0`	How far over market value a listing must be before the seller gets a warning when they list it.
`minSalesForSuggestion`	`5`	Fewest sales an item needs before it gets a suggested price. On busy servers this grows with volume, up to the cap.
`maxSalesForSuggestion`	`50`	The sales requirement never grows past this.
`activityScaling`	`0.1`	How much the sales requirement grows with hourly trade volume.
`variancePenaltyEnabled` (reload)	`true`	Lower confidence when an item's sale prices are all over the place.
`echoPenaltyEnabled`	`true`	Lower confidence when sales just mirror the engine's own suggestion.
`stalenessPenaltyEnabled`	`true`	Lower confidence the longer it has been since the model last trained.

economyEngine.hooks

One switch for each plugin the engine can read. A hook only starts when its switch is on and its plugin is installed. /ahadmin reload applies these switches with no restart. What each hook reads is on Supported Plugins, and how hooks work is on How Hooks Work.

Key	Default	What it does
`vault`	`true`	Read the server economy and currency through Vault.
`quickshop`	`true`	QuickShop-Hikari chest-shop sales between players. Unlimited admin shops become price limits.
`chestshop`	`true`	ChestShop player shop sales. Admin shops become price limits.
`signshop`	`true`	SignShop player sign-shop sales. Admin signs become price limits.
`shopkeepers`	`true`	Shopkeepers trades paid in its currency item, once that item has an exchange rate in `currencies.yml`. Admin shopkeepers become price limits.
`insaneshops`	`true`	InsaneShops player shop trades. Admin shops become price limits. Only shops paid in Vault money.
`excellentshop`	`true`	ExcellentShop chest-shop trades. Its virtual shop becomes price limits. Prices in Vault money or a currency listed by `/ahadmin currencies`.
`axtrade`	`true`	AxTrade item-for-money trades between players.
`tradesystem`	`true`	Trade System item-for-money trades. Money handed over for nothing is checked for alt rings.
`ultimateshop`	`true`	UltimateShop buys and sells become price limits.
`shopguiplus`	`true`	ShopGUIPlus buys and sells become price limits, in the shop's own currency.
`economyshopgui`	`true`	EconomyShopGUI buy and sell prices become price limits.
`guishop`	`true`	GUIShop's price list becomes price limits, when its prices are Vault money.
`autosellchests`	`true`	What AutoSellChests chests sell at becomes a price floor.
`dtltraders`	`true`	What dtlTraders NPC traders pay and charge becomes price limits, for traders that use Vault money.
`shopconjurate`	`true`	Shop by Conjurate prices become price limits, for items every player can buy or sell, when its shop is paid in the Vault economy.
`essentials`	`true`	EssentialsX `worth.yml` prices become price floors, and `/pay` is checked for alt rings.
`cmi`	`true`	CMI `/sell` sales and its worth list become price floors, and `/pay` is checked for alt rings. With CMI's own economy off, only a `/pay` typed with the payee's full name is seen, and none while CMI asks to confirm payments.
`zessentials`	`true`	zEssentials `/pay` between two players who are online is checked for alt rings. A payment to a player who is offline is not seen.
`xprison`	`true`	X-Prison payments between players are checked for alt rings, and what its autosell pays becomes a price floor once that currency has an exchange rate in `currencies.yml`.
`ultracoinflip`	`true`	What a player wins from another in an UltraCoinFlip coinflip is checked for alt rings.
`duels`	`true`	The money a player wins from another in a money-bet duel is checked for alt rings. Covers Duels and the Duels Optimised fork.

economyEngine.ingestion

Key	Default	What it does
`marketSnapshotIntervalMinutes` (reload)	`60`	How often, in minutes, to capture a market-wide snapshot for trend analysis.

economyEngine.anomalyDetection

Tuning for the fraud and manipulation checks. See Anomaly Detection.

Key	Default	What it does
`zScoreThreshold`	`3.0`	How far from normal a trade must sit to be flagged. Lower is more sensitive.
`exploitAlertsEnabled` (reload)	`true`	Log an alert when the engine spots likely exploit activity.
`washTradeWindowHours`	`24`	How many hours back to look when spotting a player selling then re-buying the same item.
`coordinatedWindowMinutes`	`5`	The window, in minutes, used to spot a burst of coordinated trades by a small group.
`bulkVolumeThreshold` (reload)	`576`	Flag a single trade of at least this many items as suspicious bulk activity.

telemetry

Optional data collection during the beta. What each tier sends, and how player identities are hashed before anything leaves your server, is spelled out on the Data & Privacy page. The plugin never depends on it, and the auction house works the same either way.

Key	Default	What it does
`enabled`	`true`	Master switch. Turn it off and the plugin sends nothing home.
`sendIntervalMinutes` (restart)	`30`	How often, in minutes, to send. Minimum 5.
`anonymous`	`true`	Facts about the server and the plugin, such as versions, settings and which hooks are on. No player data of any kind.
`economy`	`true`	The trade records the engine stores, including server shop trades and money sent between players, with each item's details such as its custom name and enchantments, plus market snapshots and price suggestions. Player UUIDs are hashed on your server first.
`playerBehaviour`	`false`	For each player, under a hashed id, how many searches they ran, how many times they opened the auction house and the claim screen, and how many claims they collected. Off by default.

pointerUi

The pointer menus, which draw the auction house on screen instead of in chest menus. Off by default. Setting Up explains the three ways to serve the resource pack in more detail.

Key	Default	What it does
`enabled` (restart)	`false`	Turn the pointer menus on. Players are offered the menus' resource pack as they join.
`pinnedView`	`true`	Hold the view still while a menu is open and move a cursor with the mouse. Off, players aim with their head instead.
`defaultMode`	`POINTER`	`POINTER` or `CHEST`, what players get until they choose for themselves with `/ah menus`.
`packHost` (restart)	(empty)	The address players download the pack from. Empty uses the address they joined with.
`packPort` (restart)	`0`	`0` sends the pack through the server's own port. Set a free port to run a separate pack server on it instead.
`packUrl` (restart)	(empty)	A direct download link to `pack.zip` that you host yourself, needed behind BungeeCord or Velocity. When it is set, the plugin serves no pack of its own.
`panelDistance`	`3.0`	How far in front of the player the menu floats, in blocks, from 1.5 to 6.
`panelAngle`	`80.0`	How wide the menu looks, in degrees, from 36 to 80. Lower it if players with a low field of view or a square screen see its edges cut off.
`sounds`	`true`	Play the click and hover sounds of the menus.