Commands and Permissions

This page is the complete reference for every DynaTrade command, its syntax, expected output, and the permission node that controls access.

Player commands

These commands are available to all players by default. You can restrict them through your permission plugin.

`/market`

Opens the DynaTrade market GUI.

Permission: dynatrade.market (default: true)

What it does: - Opens the central market hub where players can browse categories, view items, and trade without memorizing item names. - The GUI shows the current market price, buy price, sell price, and trend for each item. - Trades made through the GUI use the same backend as the chat commands.

Notes: - If the economy provider is unavailable, the GUI still opens but buy and sell actions are disabled.

`/price <item>`

Shows the current quote for a single item.

Permission: dynatrade.price (default: true)

Syntax: /price <MATERIAL_KEY>

Example: /price DIAMOND

Output: - Market price (the internal reference) - Buy price (what the player would pay) - Sell price (what the player would receive)

Notes: - Item keys are Minecraft material names such as DIAMOND, IRON_INGOT, or OAK_LOG. - Commands still use the English material key even if the server is showing translated item names in chat or the GUI. - This command never modifies the market. It is always safe to use for price lookups.

`/buy <item> <quantity>`

Buys items from the market at the current buy price.

Permission: dynatrade.buy (default: true)

Syntax: /buy <MATERIAL_KEY> <quantity>

Example: /buy DIAMOND 5

What it does: 1. Validates the item exists in the catalog 2. Validates the requested quantity 3. Confirms the player has enough funds 4. Deducts the cost from the player's balance via Vault 5. Delivers the items to the player's inventory 6. Records buy pressure for the next market cycle

Safeguards: - Rejects invalid or unknown items - Rejects quantity of zero or negative - Fails cleanly if the economy provider is unavailable - Attempts rollback (refund) if item delivery fails after payment

Important: - /buy still expects the English material key. - Example: /buy diamond 1 works, but /buy diamante 1 does not. - If the player enters an invalid translated name, DynaTrade now responds with a hint telling them to use the English key.

`/sell <item> <quantity|all>`

Sells items to the market at the current sell price.

Permission: dynatrade.sell (default: true)

Syntax: /sell <MATERIAL_KEY> <quantity|all>

Examples: /sell IRON_INGOT 64, /sell IRON_INGOT all

What it does: 1. Validates the item exists in the catalog 2. Resolves either an explicit quantity or all for the full stack count the player is carrying 3. Removes the items from the player's inventory 4. Deposits the proceeds into the player's balance via Vault 5. Records sell pressure for the next market cycle

Safeguards: - Rejects invalid or unknown items - Rejects quantity the player does not hold - Rejects all if the player does not hold any of the target item - Attempts to restore removed items if the deposit fails

Important: - /sell still expects the English material key. - Example: /sell iron_ingot 64 works, but /sell barra_de_ferro 64 does not. - /sell <item> all sells every matching item found in the player's inventory. - If the player enters an invalid translated name, DynaTrade now responds with a hint telling them to use the English key.

Admin commands

All admin commands are grouped under /dt, which acts as the operator root command for diagnostics, reloads, and manual cycle control.

Important runtime detail:

plugin.yml does not declare a Bukkit permission node on the root /dt command itself
/dt and /dt help can therefore be reached at the command-root level
the admin gate is applied in code for the protected subcommands such as /dt status, /dt item, /dt diagnose, /dt pricingstatus, /dt reload, and /dt cycle
the destructive reset flow is intentionally split into the separate dynatrade.admin.reset permission

`/dt help`

Shows a summary of available /dt subcommands.

Permission: no Bukkit command-level permission on the root help path

Behavior:

/dt and /dt help show the public help lines to any sender
the protected status, item, diagnose, pricingstatus, reload, and cycle help lines are added only when the sender also has dynatrade.admin
the destructive reset help line is added only when the sender also has dynatrade.admin.reset

Use this first if a staff member has access to /dt but is not sure which operational actions are available on the current server.

`/dt status`

Shows the current health of the DynaTrade runtime.

Permission: dynatrade.admin

Output includes: - degraded-runtime warning when no active runtime exists - Economy provider status (connected or unavailable) - Scheduler status (running or stopped) - Time until the next scheduled cycle - Current cycle generation number - Number of tracked items - Number of pending signals in the buffer - Player-aware pricing normalization status - Whether the last processed cycle saw player participation data - Whether a prepared checkpoint is present - Storage health summary

Use this command first when diagnosing any issue with the economy. It is safe to delegate to moderators or support staff because it is read-only.

`/dt item <item>`

Shows full diagnostics for one item, separating current state from the last completed pricing cycle.

Permission: dynatrade.admin

Syntax: /dt item <MATERIAL_KEY>

Example: /dt item NETHERITE_INGOT

Output when full data is available:

-- Item -- Coal [WARN VREF_DRIFT, WARN LOW_PARTICIPATION]
-- Current --
Price: $12.40
Buy Price: $13.02
Sell Price: $11.78
Trend: bullish
VREF: 128.00 / 32.00 (4.00x)
Limits: $0.20 - $15.00

-- Calibration --
State: CALIBRATED
Reason: CALIBRATED
VREF: 128.00 / 32.00 (4.00x)
Samples: 8 / 5
History: 8 / 8
Max Change Cap: yes
Max Multiplier Cap: no
Configured Floor: no
Last Updated Cycle: 42
Risk Score: 0.34
Volatility Profile: MODERATE
Thin Market: no
Adaptive Spread Bonus: 0.017
Adaptive Spread Active: yes

-- Last Cycle --
Price: $11.90 -> $12.40 (+4.2%)
Buy Count: 96
Sell Count: 12
Trigger: volume

-- Pressure --
Raw Pressure: +2.63
Adjusted Pressure: +0.74
Participation: 0.28
Players: 2

Note: High pressure was dampened by limited participation.

What each section means:

Header — item name followed by active diagnostic flags. Flags use the format [WARN FLAG_NAME, WARN OTHER_FLAG]. If no flags are raised, no bracket suffix appears.
Current — live market state: price, buy/sell spread, trend direction, effective VREF and configured VREF ratio (VREF ratio) when available, and configured price limits.
Calibration — calibration state: state label, reason label, effective / configured VREF ratio, sample count (current / required), ring buffer fill count, whether the max-change cap or max-multiplier cap is active, whether the configured floor was used, and the last cycle that updated calibration state. It also shows one-sided pressure, risk score, volatility profile, thin-market/dampening state, and adaptive-spread status.
Last cycle — the most recently completed pricing cycle: old price → new price with change percentage, buy/sell volume, and the event that triggered the cycle (time, volume, or manual).
Pressure — the pressure values from the last cycle: raw pressure, adjusted pressure (after dampening by limited participation), the participation factor, and how many unique players were on the dominant side.
Note — an operator-readable sentence that explains why a flag was raised, when a meaningful explanation exists.

Output rules: - Sections always appear in the order above. Sections with missing data are omitted entirely — no placeholder lines like "no data" are printed. - Last Cycle, Pressure, and Note are omitted when no completed cycle exists for this item yet (e.g., a freshly added item or after a restart). - Calibration is omitted when the calibration builder is unavailable (during startup or reload) or when the calibration state is empty. - VREF ratio under Current is omitted when the effective volume reference is unavailable (after restart, before a cycle completes). - Flags and brackets are omitted entirely when no flags are raised — no empty [] suffix. - If the diagnostics builder is unavailable (during startup or reload), the command falls back to the compact price/trend/limits output.

Use this command when you need to understand why a specific item moved, verify that diagnostics data exists for an item, or inspect pressure values and volume participation.

`/dt diagnose`

Lists all items with active diagnostic flags, ordered by priority. This is your triage command for a quick market health overview.

Permission: dynatrade.admin

Syntax: /dt diagnose

Output when items are flagged:

[Diagnose] 3 items flagged
IRON_INGOT [WARN VREF_DRIFT, WARN LOW_PARTICIPATION]
COPPER_ORE [WARN HIGH_VOLATILITY]
WHEAT      [INFO NO_RECENT_ACTIVITY]

Output when no items are flagged:

[Diagnose] No flagged items.

How it works: - Iterates every item in the market catalog and checks whether DiagnosticFlagEvaluator raised any flags. - Healthy items (no flags) are completely omitted. - Items are sorted by: 1. Most severe flag first (VREF_DRIFT > HIGH_VOLATILITY > LOW_PARTICIPATION > STALE_CYCLE > NO_RECENT_ACTIVITY) 2. Number of flags (more flags = higher priority) 3. Display name (alphabetical) 4. Item key (alphabetical, final tiebreaker) - The output is capped at 10 items. If more than 10 are flagged, the header reports the total: [Diagnose] 17 items flagged, showing top 10...

When to use: - As a first check when you suspect the economy has unusual activity - To find which items need closer inspection - Before running /dt item <itemKey> on specific items

This command is read-only and does not change any market state, prices, or configuration.

`/dt pricingstatus`

Shows the current optional quote-adjustment configuration and the latest momentum values visible to the runtime.

Permission: dynatrade.admin

What it shows: - whether the optional momentum-spread layer is enabled - current tau-* and k-* runtime parameters - up to 10 item momentum values with warmup state

Notes: - this is an admin diagnostic command - it does not change prices or trigger a cycle - it is useful only if you are evaluating the optional premium.momentum-spread layer

`/dt reload`

Reloads configuration files and rebuilds the runtime.

Permission: dynatrade.admin

What it does: 1. Closes new trade admission and drains in-flight apply and durability work for up to about 3 seconds 2. Persists the current runtime while the old runtime can still be kept active on failure 3. Stops the old runtime completely after persistence succeeds 4. Reloads config.yml, items.yml, items_pt.yml, and the active language file 5. Rebuilds the pricing runtime using the reloaded configuration 6. Restores the current market state from market-state.yml 7. Recovers any valid pending signals from the journal 8. Enters degraded mode if recreation fails only after the old runtime was already stopped

When to use: - After editing config.yml, items.yml, or items_pt.yml - After changing the language setting - After adding or removing items from the catalog

Notes: - In-memory prices are not reset by a reload. The persisted market state is restored as-is. - If market-state.yml is invalid, reload will not silently apply base prices. It will log the problem and preserve the previous runtime. - If runtime recreation fails only after the old runtime was already stopped, DynaTrade enters degraded mode and trades stay unavailable until a full restart. - /dt reload is synchronous in the current line and may block the main server thread briefly while it drains in-flight work. - This command requires dynatrade.admin because it changes live runtime behavior and should be limited to trusted operators.

`/dt cycle`

Forces an immediate market cycle.

Permission: dynatrade.admin

What it does: 1. Drains the pending transaction buffer 2. Runs the pricing pipeline for all affected and idle items 3. Writes the cycle checkpoint to disk 4. Saves the updated market state 5. Applies the new prices to the live runtime 6. Cleans up the checkpoint and processed signals

When to use: - During testing to see the effect of recent trades immediately - After a controlled trade scenario to advance the market state - When you want to process accumulated signals without waiting for the scheduled cycle

This command requires dynatrade.admin because it actively advances the market.

`/dt reset`

Performs a full reset of the dynamic market state, restoring base prices from items.yml.

Permission: dynatrade.admin.reset

⚠️ This is a destructive operation. It cannot be undone. Use it only when you intend to wipe all dynamic price history and return the market to its configured starting state.

How it works: 1. The first call outputs a short confirmation token (5 characters) that expires in 60 seconds. 2. You must re-run /dt reset <token> within that window to confirm. 3. On confirmation, the scheduler is paused and the cycle lock is acquired. 4. In-memory buffers are cleared. 5. pending-signals.yml, pending-signals.log, and cycle-checkpoint.yml are deleted. 6. market-state.yml is rebuilt from the current items.yml base prices. 7. The runtime is restarted with a clean state.

When to use: - After extensive test trading that you want to discard - When recovering from a manually corrupted state that DynaTrade cannot read - When restarting the economy from scratch intentionally

Permissions reference

Permission	Default	Controls
`dynatrade.market`	`true`	`/market`
`dynatrade.price`	`true`	`/price`
`dynatrade.buy`	`true`	`/buy`
`dynatrade.sell`	`true`	`/sell`
`dynatrade.admin`	`op`	`/dt status`, `/dt item`, `/dt diagnose`, `/dt pricingstatus`, `/dt reload`, `/dt cycle`, plus the matching help lines under `/dt help`
`dynatrade.admin.reset`	`op`	`/dt reset`, plus the reset help line under `/dt help`

The dynatrade.admin node is the main gate for protected /dt administration subcommands. It is appropriate for trusted staff who need to inspect the economy, reload config, or force a cycle. The dynatrade.admin.reset permission is intentionally separate so only owners or senior administrators can wipe the market state.