# 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",
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iynxdev.com/premium-addons/economy/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.