The shop, items and trading

A currency with nothing to buy is a scoreboard. The shop is what turns a balance into a decision, so it is worth building before you switch the earning rules on.

The shop lives on the Economy page, Shop tab: categories, items and sales.

Categories

Categories group items into browsable sections. Each has a name, an optional description, an emoji and a position. They are optional: items without one still show up in the shop.

Items

Every item has a name, a price, and optionally a description, an emoji, an image and a category. Beyond that:

Deleting an item also destroys every copy of it in members' inventories, plus any market listing for it. To pull an item from the shop while letting owners keep what they bought, switch Enabled off instead of deleting.

What an item actually does

Each item is one of four kinds.

Role grants a role. Leave the duration empty for a permanent role, or set one for a temporary role that is removed automatically when the timer runs out, even if the bot restarts in between. The duration can run from one minute to a year.

XP boost multiplies the buyer's XP for a while. The multiplier goes from 1.25x to 3x in steps of 0.25, and the duration from five minutes to thirty days. It stacks with any role XP multiplier the member has, and the combined result is capped at 3x, so a boost can never push someone past what the server could already configure.

Workflow runs a list of actions, up to ten of them, through the same automation pipeline as the autoresponder. You choose when they run:

• Purchase: on buying the item.
• Use: every time the member runs /economy item use.
• On consumption: only when a copy is actually burned, which means the item has to be both Usable and Consumable, otherwise it never fires.

Cosmetic does nothing on purpose: a collectible, a badge, something to show off in an inventory or to require as the price of entry for something else.

Purchase requirements

An item can demand any combination of:

• a required role;
• a minimum balance, checked against what the member is holding before paying, on top of the price, so you can reserve an item for members who have already accumulated a certain amount;
• a required item, so items can chain into a progression;
• a minimum level, read from the level system.

All of the requirements you set must be met. A member who fails any of them is told the requirements are not met rather than being charged.

Sales

A sale is a time-boxed discount over the whole shop, one category, or one item, from 1% to 99%, with a start (optional, immediate if left empty) and an end (required).

Sales never stack. If several apply to the same item, the largest discount wins and that is the price charged.

Buying and using

The item options autocomplete, so members can type a name instead of hunting for an id.

A purchase is one atomic operation: the availability window, the stock, the per-member limit and the balance are all re-checked at the moment of payment, and either everything happens or nothing does. If the item's effect then fails in a way that leaves the member paying for nothing, such as a role the bot cannot grant or an XP boost that could not be activated, the item is taken back and the coins are refunded.

Sell-back deserves one note. The refund is the sell-back percentage of the lower of the item's current price and the average price the member actually paid for it. That prevents buying at a discount during a sale and selling back at full price for a profit.

Sending coins to another member

/economy pay user amount transfers coins. The bot asks for a confirmation before anything moves.

Under Transfers on the Settings tab:

• Allow transfers can turn the whole thing off.
• Transfer tax (%) is burned on every transfer: the sender pays the full amount, the recipient receives the amount minus the tax, and the difference leaves circulation. It is your main lever against a currency that only ever grows.
• Daily transfer cap limits how much one member can send per UTC day. Empty means no cap.

You cannot pay yourself or a bot, and both sides must clear the minimum account age gate. A transfer that would push the recipient past the maximum balance is refused rather than partially delivered.

Trading

/economy trade offer user opens a trade panel in the channel. Both members stage what they are putting in, coins and items, and both must lock before anything moves. Execution is a single operation that re-checks both sides' balances and inventories, so nothing can be traded twice or traded away in the meantime.

A trade expires after 10 minutes, and /economy trade cancel drops your pending one. Items marked as not tradeable cannot be staged.

The marketplace

The market is member-to-member selling, without both people needing to be online at once.

Listing costs a fee, taken when the listing is created: a percentage of the total asking price, 2% by default, never less than one coin. It is not refunded if you cancel, which is what stops the market being spammed with listings nobody intends to sell.

The items are held in escrow while the listing is up, so they cannot be traded or used at the same time. Listings run for 7 days, and the items come back if one expires or is cancelled. Only tradeable items can be listed.

Reacting to a purchase

economy_item_purchase is an autoresponder trigger: it fires after a purchase commits, and can be limited to specific items. Use it to announce a purchase, open a ticket, or give something the item itself cannot.

Autoresponder actions can also give and take items directly, so an automation can hand out a collectible without a shop transaction. See triggers and actions.