# 💰🏪 BellTrade — The Ultimate Player Economy Suite

### *Turn your server into a thriving marketplace where players drive the economy.*

![Version](https://img.shields.io/badge/version-1.26.1.2-blue)
![API](https://img.shields.io/badge/Spigot | Paper-1.21+-green)
![Java](https://img.shields.io/badge/Java-21-orange)

---

## 📖 Overview

**BellTrade** is a comprehensive, player-driven economy plugin that brings a complete trading ecosystem to your Minecraft server. From a global marketplace and auction house to peer-to-peer trading and physical shop signs — BellTrade covers every aspect of player commerce.

Whether you run a survival economy server or a towny-style community, BellTrade gives your players the tools to buy, sell, bid, and trade with confidence.

---

## ✨ Features

🏬 **Global Player Market**
- List any item for sale at your chosen price
- Browse, search, and filter listings with an intuitive GUI
- Per-group listing limits synced via BellLP integration

🔨 **Auction House**
- Create timed auctions with starting prices
- Competitive bidding system with outbid notifications
- Automatic winner resolution and item delivery

🤝 **Peer-to-Peer Trading**
- Secure two-player trade window with item preview
- Both parties must confirm before the trade completes
- No risk of scams — full confirmation system

🪧 **Physical Sell Shops**
- Place shop signs in the world for walk-up purchases
- Visual, immersive shopping experience
- Perfect for player markets and shopping districts

💸 **Tax & Fee System**
- Configurable transaction taxes on all sales
- Different rates for market, auction, and shop sales
- Bypass permissions for VIP players

📊 **Transaction History**
- Full logging of all trades, sales, and auctions
- Player-accessible transaction history
- Admin audit tools

🔄 **BellLP Integration**
- Per-group market listing limits via GroupSyncHandler
- Auto-reload when group definitions change
- Seamless permission group synchronization

🌍 **Multi-Language**
- Built-in English and Polish translations
- Fully customizable message files

---

## 📋 Dependencies

| Plugin | Type | Notes |
|--------|------|-------|
| **Vault** | ⚠️ Required | Economy API bridge |
| Economy Plugin | ⚠️ Required | e.g. EssentialsX Economy |
| BellLands | 📌 Optional | Land integration for shop placement |
| BellLP | 📌 Optional | Per-group listing limits |

---

## 💻 Commands

| Command | Description |
|---------|-------------|
| `/market` | Open the market GUI |
| `/market sell <price>` | List the item in your hand for sale |
| `/market search <query>` | Search market listings |
| `/auction` | Open the auction house GUI |
| `/auction create <startPrice> <duration>` | Create a new auction |
| `/auction bid <amount>` | Place a bid on the current auction |
| `/trade <player>` | Send a trade request to a player |
| `/sellshop create <price>` | Create a sell shop sign |
| `/belltrade admin` | Open admin management panel |
| `/belltrade reload` | Reload plugin configuration |

---

## 🔐 Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `belltrade.market` | Access the global market | `true` |
| `belltrade.auction` | Access the auction house | `true` |
| `belltrade.trade` | Use peer-to-peer trading | `true` |
| `belltrade.sellshop` | Create sell shop signs | `true` |
| `belltrade.admin` | Admin management commands | `op` |
| `belltrade.bypass.limit` | Bypass market listing limits | `op` |
| `belltrade.bypass.tax` | Bypass transaction taxes | `op` |

---

## ⚙️ Configuration Highlights

```yaml
# config.yml — Key settings

market:
default-listing-limit: 10
listing-duration: 7d
tax-rate: 5.0

auction:
min-duration: 1h
max-duration: 7d
min-bid-increment: 1.0
anti-snipe-extension: 30s

trade:
timeout: 60s
max-slots: 9

sellshop:
require-land-ownership: true
max-per-player: 5

language: en
```

> All values are fully configurable. Durations support human-readable formats (`1h`, `7d`, `30s`).

---

## 🚀 BellTrade-Pro — Premium Addon

Take your server economy to the next level with **BellTrade-Pro**:

https://bellforge.pl/en/pluginy/belltrade-pro/

| Feature | Description |
|---------|-------------|
| 📈 **Adaptive Pricing Engine** | Supply/demand-based price suggestions that react to real market activity |
| 🛡️ **Anomaly Detection** | Automatic detection of market manipulation and suspicious trading patterns |
| 🎨 **Admin Catalog Editor** | Multi-step GUI wizard for managing market categories and featured items |
| 📊 **Analytics & Statistics** | Detailed sales analytics, revenue charts, and player economy insights |
| 🔄 **Listing Auto-Renewal** | Automatic renewal of expiring listings with configurable conditions |
| 📋 **Enhanced Reporting** | Advanced admin reports on market health and player activity |

> *BellTrade-Pro is a separate premium addon. Drop it into your plugins folder alongside BellTrade — no extra configuration needed.*

---

## 📸 Screenshots

*Coming soon — GUI previews, market interface, auction house, and trade window.*

---

## 🔧 Installation

1. Download **BellTrade** and place it in your `plugins/` folder
2. Ensure **Vault** and an economy plugin are installed
3. Restart your server
4. Edit `plugins/BellTrade/config.yml` to your liking
5. `/belltrade reload` — you're ready to go!

---

## 🆘 Support

- **Issues & Bugs:** [GitHub Issues](#)
- **Discord:** [https://discord.gg/6q7bnSYaR](#)
- **Wiki:** [Documentation](#)

---

## 📜 Changelog

See [CHANGELOG.md](#) for full version history.

---

BellTrade — Powering player economies since day one. 
Made with ❤️ for the Minecraft community.