> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/premium-addons/economy/configuration.md).

# Configuration

## <mark style="color:blue;">Introduction</mark>

The Economy addon configuration file (`economy.json`) controls every aspect of your server's virtual currency system. This guide will walk you through each section to help you create a balanced and engaging economy.

***

## <mark style="color:blue;">Part 1: Coin Rewards</mark>

### <mark style="color:yellow;">Understanding Coin Rewards</mark>

The `coins` section defines how many coins users earn for different activities. Setting a value to `0` disables coin rewards for that activity.

```json
coins: {
    message_sent: 1,
    invite: 150,
    game_played: 5,
    game_won: 15,
    counting_game: 3,
    level_up: 100,
    daily: 125,
    weekly: 1000,
    calltime_minute: 15,
    approved_suggestion: 200,
    suggestion_vote: 25,
    poll_vote: 25,
    birthday: 5000,
    starboard_message: 200,
    punishment: -5000,
}
```

***

### <mark style="color:yellow;">Activity Breakdown</mark>

#### <mark style="color:orange;">Social Activities</mark>

**message\_sent**

* Coins earned per message sent in chat
* Recommended: `1-5` coins
* Too high = spam encouragement | Too low = no incentive

**invite**

* Coins earned when a user's invite brings a new member
* Recommended: `100-500` coins
* High value encourages organic growth

**calltime\_minute**

* Coins earned per minute in voice channels
* Recommended: `10-30` coins
* Encourages voice activity and community engagement

**suggestion\_vote** & **poll\_vote**

* Coins earned for voting on suggestions or polls
* Recommended: `10-50` coins each
* Encourages community participation in decisions

**approved\_suggestion**

* Bonus coins when your suggestion is approved
* Recommended: `100-500` coins
* Rewards quality suggestions

**starboard\_message**

* Coins earned when your message gets starred
* Recommended: `100-300` coins
* Rewards popular/quality content

***

#### <mark style="color:orange;">Game Activities</mark>

**game\_played**

* Coins earned just for playing a game
* Recommended: `1-10` coins
* Participation reward

**game\_won**

* Coins earned for winning a game
* Recommended: `10-50` coins
* Should be higher than `game_played`

**counting\_game**

* Coins earned per successful count in counting channel
* Recommended: `1-5` coins
* Small but consistent reward

***

#### <mark style="color:orange;">Progression Activities</mark>

**level\_up**

* Bonus coins when reaching a new level
* Recommended: `50-200` coins
* Scales with your leveling system difficulty

**daily**

* Base reward for daily claims
* Recommended: `100-500` coins
* Influenced by streak bonuses (see Streaks section)

**weekly**

* Base reward for weekly claims
* Recommended: `500-2000` coins
* Should be significantly higher than daily

**birthday**

* Special reward on user's birthday
* Recommended: `1000-10000` coins
* Once-per-year celebration bonus

***

#### <mark style="color:orange;">Punishment</mark>

**punishment**

* Coins deducted when a user is punished (warned, muted, etc.)
* Recommended: `-1000` to `-10000` coins
* Use negative values to deduct coins
* Serves as an economic deterrent for rule-breaking

***

## <mark style="color:blue;">Part 2: Shop Items</mark>

### <mark style="color:yellow;">Understanding Shop Structure</mark>

Shop items appear in the `/shop` command and can be purchased with earned coins. Each item has rewards that are automatically delivered upon purchase.

```json
shop_items: [
    {
        id: 0,
        emoji: '👑',
        name: 'VIP',
        description: 'Enter to purchase the VIP role',
        cost: 50000,
        requirement: {
            rankId: 5,
            oneTimePurchase: true,
        },
        reward: [
            {
                type: "ROLE",
                target: "804354029076348959",
            }
        ],
    }
]
```

***

### <mark style="color:yellow;">Item Configuration Options</mark>

#### <mark style="color:orange;">Basic Properties</mark>

**id** (Number)

* Unique identifier for the item
* **CRITICAL:** Never reuse IDs, even after deleting items
* Used to track who purchased what
* Start at 0 and increment for each new item

**emoji** (String)

* Emoji displayed next to the item in the shop
* Use any Discord emoji or Unicode emoji
* Example: `'👑'`, `'🎁'`, `'💎'`

**name** (String)

* Display name of the item
* Keep it short and descriptive
* Shown in shop list and purchase confirmations

**description** (String)

* Longer explanation of what the item does
* Tell users exactly what they're buying
* Example: "Permanent VIP role with exclusive perks"

**cost** (Number)

* Price in coins
* Must be greater than 0
* Consider your coin earning rates when pricing

***

#### <mark style="color:orange;">Requirements</mark>

**rankId** (Number)

* Minimum economy rank required to purchase
* Set to `0` for no requirement
* Higher ranks = more exclusive items
* Use for progression-locked rewards

**oneTimePurchase** (Boolean)

* `true` = Can only buy once per user
* `false` = Can buy unlimited times
* Use `true` for roles and permanent items
* Use `false` for consumables (boosters, lootboxes)

***

### <mark style="color:yellow;">Reward Types</mark>

Each item can have multiple rewards. When purchased, all rewards are given simultaneously.

#### <mark style="color:orange;">ROLE Reward</mark>

Grants a Discord role to the purchaser:

```json
reward: [
    {
        type: "ROLE",
        target: "804354029076348959",
    }
]
```

* `target` = Role ID (right-click role with Developer Mode enabled)
* Bot must have permission to assign roles
* Bot's role must be higher than the target role

***

#### <mark style="color:orange;">BOOSTER Reward</mark>

Gives a coin multiplier booster:

```json
reward: [
    {
        type: "BOOSTER",
        target: "booster_coin_1h_2",
    }
]
```

* `target` = Booster ID from your booster configuration
* Format usually: `booster_coin_<duration>_<multiplier>`
* Examples: `booster_coin_1h_2` = 2x coins for 1 hour
* Users activate boosters with `/booster activate`

***

#### <mark style="color:orange;">LOOTBOX Reward</mark>

Adds lootboxes to the user's inventory:

```json
reward: [
    {
        type: "LOOTBOX",
        target: null,
        amount: 1,
    }
]
```

* `target` = Always `null` for lootboxes
* `amount` = Number of lootboxes to give
* Lootboxes contain random rewards when opened

***

#### <mark style="color:orange;">CHANNEL\_MESSAGE Reward</mark>

Sends a predefined message to a specific channel:

```json
reward: [
    {
        type: "CHANNEL_MESSAGE",
        target: "1274005906610454619",
        predefined_id: "vip_announcement",
    }
]
```

* `target` = Channel ID where the message will be sent
* `predefined_id` = ID of your saved message template
* Create templates using `/sendmsg` and `/editmsg` commands
* Useful for announcing purchases or sending instructions

***

#### <mark style="color:orange;">COUPON Reward</mark>

Generates a Tebex store coupon code:

```json
reward: [
    {
        type: "COUPON",
        target: "10",
    }
]
```

* `target` = Coupon value (percentage or fixed amount)
* Requires Tebex plugin integration
* Automatically generates and DMs the code to the user
* Perfect for bridging virtual and real economy

{% hint style="danger" %}
**Warning:** Coupon rewards can be exploited if coin earning rates are too high or if jobs generate too much passive income. Use with caution and balance your economy carefully!
{% endhint %}

***

### <mark style="color:yellow;">Shop Item Examples</mark>

#### <mark style="color:orange;">Example 1: VIP Role</mark>

Permanent role requiring rank 5:

```json
{
    id: 0,
    emoji: '👑',
    name: 'VIP',
    description: 'Permanent VIP role with exclusive perks and channels',
    cost: 50000,
    requirement: {
        rankId: 5,
        oneTimePurchase: true,
    },
    reward: [
        {
            type: "ROLE",
            target: "804354029076348959",
        }
    ],
}
```

***

#### <mark style="color:orange;">Example 2: Coin Booster</mark>

Consumable 2x booster for 1 hour:

```json
{
    id: 1,
    emoji: '🪄',
    name: 'Gilded Elixir',
    description: 'Double your coin earnings for 1 hour',
    cost: 750,
    requirement: {
        rankId: 0,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "BOOSTER",
            target: "booster_coin_1h_2",
        },
    ],
}
```

***

#### <mark style="color:orange;">Example 3: Lootbox</mark>

Random reward box:

```json
{
    id: 2,
    emoji: '🎁',
    name: 'Mystery Lootbox',
    description: 'Open for random coins, boosters, or rare items!',
    cost: 500,
    requirement: {
        rankId: 0,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "LOOTBOX",
            target: null,
            amount: 1,
        }
    ],
}
```

***

#### <mark style="color:orange;">Example 4: Announcement Purchase</mark>

Send a message to a public channel:

```json
{
    id: 3,
    emoji: '💬',
    name: 'Server Announcement',
    description: 'Post your custom message in the announcements channel',
    cost: 2000,
    requirement: {
        rankId: 3,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "CHANNEL_MESSAGE",
            target: "1274005906610454619",
            predefined_id: "user_announcement",
        }
    ],
}
```

***

#### <mark style="color:orange;">Example 5: Store Coupon</mark>

Real-money store discount:

```json
{
    id: 4,
    emoji: '🎟️',
    name: 'Store Coupon',
    description: '10% discount code for our Tebex store',
    cost: 100000,
    requirement: {
        rankId: 10,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "COUPON",
            target: "10",
        }
    ],
}
```

***

#### <mark style="color:orange;">Example 6: Multiple Rewards</mark>

Item granting multiple rewards at once:

```json
{
    id: 5,
    emoji: '🎉',
    name: 'Ultimate Package',
    description: 'VIP role + 3 lootboxes + announcement',
    cost: 75000,
    requirement: {
        rankId: 8,
        oneTimePurchase: true,
    },
    reward: [
        {
            type: "ROLE",
            target: "804354029076348959",
        },
        {
            type: "LOOTBOX",
            target: null,
            amount: 3,
        },
        {
            type: "CHANNEL_MESSAGE",
            target: "1274005906610454619",
            predefined_id: "vip_welcome",
        }
    ],
}
```

***

## <mark style="color:blue;">Part 3: Streak Bonuses</mark>

### <mark style="color:yellow;">Understanding Streaks</mark>

Streaks encourage users to claim their daily/weekly rewards consistently. Each consecutive claim increases their streak counter, which adds bonus coins on top of the base reward.

```json
streaks: {
    daily: {
        enabled: true,
        bonus: "%streak% * 25 + 25",
    },
    weekly: {
        enabled: true,
        bonus: "%streak% * 250 + 250",
    }
}
```

***

### <mark style="color:yellow;">Streak Configuration</mark>

**enabled** (Boolean)

* `true` = Streak bonuses are active
* `false` = Only base reward is given (no streak tracking)

**bonus** (String - Formula)

* Mathematical formula to calculate bonus coins
* `%streak%` placeholder = Current streak count (0, 1, 2, 3...)
* Can use operators: `+`, `-`, `*`, `/`, `( )`

***

### <mark style="color:yellow;">Streak Formula Examples</mark>

#### <mark style="color:orange;">Linear Growth</mark>

```json
bonus: "%streak% * 25 + 25"
```

* Streak 0: 0 \* 25 + 25 = **25 coins**
* Streak 1: 1 \* 25 + 25 = **50 coins**
* Streak 5: 5 \* 25 + 25 = **150 coins**
* Streak 10: 10 \* 25 + 25 = **275 coins**

***

#### <mark style="color:orange;">Exponential Growth</mark>

```json
bonus: "%streak% * %streak% * 10"
```

* Streak 0: 0 \* 0 \* 10 = **0 coins**
* Streak 1: 1 \* 1 \* 10 = **10 coins**
* Streak 5: 5 \* 5 \* 10 = **250 coins**
* Streak 10: 10 \* 10 \* 10 = **1000 coins**

***

#### <mark style="color:orange;">Capped Growth</mark>

For formulas, you'll need to handle caps in your economy system logic, but you can design slower growth:

```json
bonus: "%streak% * 10"
```

* Streak 0: 0 \* 10 = **0 coins**
* Streak 10: 10 \* 10 = **100 coins**
* Streak 30: 30 \* 10 = **300 coins**

***

### <mark style="color:yellow;">How Streaks Work</mark>

1. User claims their daily/weekly reward
2. Base reward is given (from `coins` section)
3. Streak counter increases by 1
4. Bonus is calculated using the formula
5. Bonus is added to the base reward
6. If user misses the claim window, streak resets to 0

**Example with Daily:**

* Base daily reward: `125` coins
* User on 5-day streak
* Bonus formula: `%streak% * 25 + 25` = 5 \* 25 + 25 = `150` coins
* **Total reward: 125 + 150 = 275 coins**

***

## <mark style="color:blue;">Part 4: Game Wagers</mark>

### <mark style="color:yellow;">Understanding Wagers</mark>

The wager system lets users bet coins on games. If they win, they get their wager back plus additional coins based on the multiplier.

```json
game_wagers: {
    enabled: true,
    max: 1000,
    cooldown: "5m",
    multipliers: {
        gtn: 1.5,
        hangman: 1.5,
        rps: 2,
        trivia: 2.5,
    }
}
```

***

### <mark style="color:yellow;">Wager Configuration</mark>

**enabled** (Boolean)

* `true` = Wager system is active for games
* `false` = Wagers are disabled (only base game rewards apply)

**max** (Number)

* Maximum coins that can be wagered on a single game
* Prevents large losses/gains that imbalance economy
* Recommended: `500-2000` coins

**cooldown** (String)

* Time users must wait between placing wagers
* Prevents rapid betting/grinding
* Format: `"5m"`, `"1h"`, `"30s"`
* Recommended: `"5m"` to `"30m"`

**multipliers** (Object)

* Defines payout multiplier for each game type
* Higher multiplier = Higher difficulty/risk
* Format: `game_name: multiplier`

***

### <mark style="color:yellow;">Game Multipliers</mark>

**gtn** (Guess The Number)

* Recommended: `1.5` - `2.0`
* Easy game, lower multiplier

**hangman**

* Recommended: `1.5` - `2.0`
* Medium difficulty

**rps** (Rock Paper Scissors)

* Recommended: `1.5` - `2.5`
* Pure luck, moderate multiplier

**trivia**

* Recommended: `2.0` - `3.0`
* Knowledge-based, higher multiplier

***

### <mark style="color:yellow;">Wager Calculation Example</mark>

User wagers `500` coins on Trivia (2.5x multiplier):

**If they win:**

* Wager returned: `500` coins
* Winnings: `500 * 2.5 = 1,250` coins
* **Total gained: 1,750 coins** (net +1,250)

**If they lose:**

* **Total lost: 500 coins** (wager is taken)

***

## <mark style="color:blue;">Part 5: Cooldowns</mark>

### <mark style="color:yellow;">Understanding Cooldowns</mark>

Cooldowns prevent spam and balance the economy by limiting how often certain actions can be performed.

```json
cooldowns: {
    spy: "30m",
    rob: "3h",
    beg: "2h",
}
```

***

### <mark style="color:yellow;">Cooldown Configuration</mark>

**spy** (String)

* Cooldown for `/bank spy` command
* Prevents constant wealth checking
* Recommended: `"15m"` to `"1h"`

**rob** (String)

* Cooldown for `/rob` command
* Prevents repeated robbery attempts
* Recommended: `"1h"` to `"6h"`
* Should be longer due to potential for large gains/losses

**beg** (String)

* Cooldown for `/beg` command
* Limits passive income from begging
* Recommended: `"30m"` to `"3h"`

***

### <mark style="color:yellow;">Time Format</mark>

Use these formats for cooldown values:

* `"30s"` = 30 seconds
* `"5m"` = 5 minutes
* `"2h"` = 2 hours
* `"1d"` = 1 day
* `"1w"` = 1 week

***

## <mark style="color:blue;">Complete Configuration Example</mark>

Here's a balanced economy configuration for a medium-sized server:

```json
config: {
    coins: {
        message_sent: 2,
        invite: 200,
        game_played: 5,
        game_won: 20,
        counting_game: 3,
        level_up: 150,
        daily: 200,
        weekly: 1500,
        calltime_minute: 20,
        approved_suggestion: 300,
        suggestion_vote: 30,
        poll_vote: 30,
        birthday: 5000,
        starboard_message: 250,
        punishment: -3000,
    },

    shop_items: [
        {
            id: 0,
            emoji: '👑',
            name: 'VIP',
            description: 'Permanent VIP role',
            cost: 50000,
            requirement: {
                rankId: 5,
                oneTimePurchase: true,
            },
            reward: [
                { type: "ROLE", target: "YOUR_ROLE_ID" }
            ],
        },
        {
            id: 1,
            emoji: '🪄',
            name: '2x Coin Booster',
            description: 'Double coins for 1 hour',
            cost: 1000,
            requirement: {
                rankId: 0,
                oneTimePurchase: false,
            },
            reward: [
                { type: "BOOSTER", target: "booster_coin_1h_2" }
            ],
        },
        {
            id: 2,
            emoji: '🎁',
            name: 'Lootbox',
            description: 'Random reward box',
            cost: 750,
            requirement: {
                rankId: 0,
                oneTimePurchase: false,
            },
            reward: [
                { type: "LOOTBOX", target: null, amount: 1 }
            ],
        },
    ],

    streaks: {
        daily: {
            enabled: true,
            bonus: "%streak% * 30 + 30",
        },
        weekly: {
            enabled: true,
            bonus: "%streak% * 300 + 300",
        }
    },

    game_wagers: {
        enabled: true,
        max: 1500,
        cooldown: "10m",
        multipliers: {
            gtn: 1.5,
            hangman: 1.75,
            rps: 2,
            trivia: 2.5,
        }
    },

    cooldowns: {
        spy: "30m",
        rob: "4h",
        beg: "2h",
    }
}
```