# Inventory

Inventories are intended to let you set up a set of items that users in your channel can acquire & use. Unlike currencies & ranks, there is no rate at which items are acquired by users. Instead, items are added or removed from a user by using either the [Currency/Rank/Inventory Action](/docs/actions/consumable-action) or by using an [Inventory Usage Requirement](/docs/commands#currencyrankinventory).

Inventories have an additional feature to them known as the shop. The shop is meant to be a means to let your users buy & sell items using a currency that you have set. You have the ability to set the buy & sell cost for all items. Items can only be bought/sold if their respective buy/sell cost is set. Users can also trade items with each other using the built-in trade command.

**NOTE**: The maximum number for any currency, rank, inventory, or stream pass value is **2,147,483,647**.

## Shop

The Shop command allows your users to buy & sell items with Mix It Up (not with other users). To enable the Shop, simply toggle the switch next to it and assign a currency to that shop that users will spend/receive for the items. For an item to be available for buying and/or selling, you must assign a buy and/or sell price for it. You are not required to assign a number for both. For example, you could have an item that is only buyable, but not sellable and vice versa.

The Shop command supports the following options (assuming your shop is called "!shop"):

- !shop list = List all the items available for buying/selling
- !shop < ITEM NAME > = Lists the buy/sell price for the specified item
- !shop buy < ITEM NAME > [ AMOUNT ] = Buys 1 or the amount specified of the item
- !shop sell < ITEM NAME > [ AMOUNT ] = Sells 1 or the amount specified of the item

## Trade

The Trade command allows your users to trade inventory items with each other. To enable trading, toggle the switch next to the Trade command in the inventory editor. The command name defaults to "!trade" and can be customized there. You can also customize the optional Items Traded command that is run whenever a trade completes.

A trade is a three-step handshake between two users, where each step is performed with the same trade command (assuming your trade command is called "!trade"):

- !trade < USERNAME > < ITEM NAME > [ AMOUNT ] = Starts a trade with the specified user, offering 1 or the amount specified of the item. A chat message is sent telling the other user to reply back with their offer within 60 seconds.
- !trade < ITEM NAME > [ AMOUNT ] = Run by the user that was traded with to reply back with their offer of 1 or the amount specified of one of their items.
- !trade = Run by the user that started the trade to accept the offer. The items are then exchanged between both users.

For example, if User1 wants to trade 5 of their "Gold Coin" items to User2 for 2 of their "Silver Key" items:

- User1: !trade User2 Gold Coin 5
- User2: !trade Silver Key 2
- User1: !trade

Some things to note about how trading works:

- Each user must have the amount of the item they are offering, and a trade will not complete if it would put either user over the item's max amount.
- The user being traded with must be present in chat for the trade to start.
- Only one trade can be active at a time. Any other user that tries to use the trade command while a trade is active will be told "A trade is already underway, please wait until it is completed".
- If the handshake is not completed within 60 seconds, the trade is automatically cancelled.

When a trade completes, the Items Traded command is run with the following additional Special Identifiers:

- $itemtotal = The amount of the item offered by the user that started the trade (EX: 5)
- $itemname = The name of the item offered by the user that started the trade (EX: Gold Coin)
- $targetitemtotal = The amount of the item offered by the user that was traded with (EX: 2)
- $targetitemname = The name of the item offered by the user that was traded with (EX: Silver Key)

The user that was traded with is also passed to the Items Traded command as its first argument, so the [Target User](/docs/reference/special-identifiers#target-user) Special Identifiers (EX: $targetusername) will reference the trade partner. The default Items Traded command sends the chat message `@$username traded $itemtotal $itemname to @$targetusername for $targetitemtotal $targetitemname`, which for the example above would resolve to "@User1 traded 5 Gold Coin to @User2 for 2 Silver Key".

## Special Identifiers

Inventory Special Identifiers are ways to reference a user's inventory item amounts. The actual Special Identifiers for your Inventory will be different for every single one, as they vary based off of the name. However, they do fit into a pre-determined format. These can also be used with other Special Identifiers that work for users such as Target, Argument, Streamer, & Random (EX: $targetuser____)

For example, if I have an Inventory named "Power", then all of the ____'s below would be replaced with "power". If the name of your Inventory has spaces in it, then those spaces will NOT be in it (EX: "Super Power" -> "superpower").

- \$user____< ITEM > = The amount of a specific item that a user has. For example, if my inventory is called "Items" and the item I want to check is called "Potions", I would use "$useritemspotions". (EX: 200).
- $user____< ITEM >display = The amount of a specific item that the user has in a display-friendly format. (EX: 20,000)
- $user____all = Lists out all of the items that the user has and the total amount of each. (EX: Potion x2, Revive x5, ...)
- $user____randomitem = The name of an item selected randomly from all of the items that a user has for the inventory. (EX: "Potion")
- $user____uniqueitemstotal = The total number of unique items that the user has for the inventory. (EX: 17)
- $user____itemstotal = The total number of items the user has for the inventory (EX: 54)
- $____randomitem = The name of an item selected randomly from all possible items in the inventory. (EX: "Potion")
- $____uniqueitemstotal = The total number of unique items that exist in the inventory. (EX: 17)
- $____allitems = Returns the list of all the items in the inventory (EX: ItemA, ItemB, ItemC)

### Top
- $top#____ = Top # users by specific item amount. For example, if my inventory is called "Power" and the item I want to check is called "Potion", I would use "$top3powerpotion". (EX: #1) User1 - 10, #2) User2 - 8, #3) User3 - 5)
- $top#____total = Top # users by total items in inventory. (EX: $top3powertotal -> #1) User1 - 45, #2) User2 - 32, #3) User3 - 28)
- $top#____unique = Top # users by unique item types owned. (EX: $top5powerunique -> #1) User1 - 12, #2) User2 - 10, #3) User3 - 8)

- $top____totaluser = Get user data of #1 user by total items. Can be combined with user special identifiers. (EX: $toppowertotalusername -> "User1")
- $top____uniqueuser = Get user data of #1 user by unique items. Can be combined with user special identifiers. (EX: $toppoweruniqueusername -> "User1")