TurboTrades/PRICING_SYSTEM_COMPLETE.md

# TurboTrades Pricing & Payout System

## 📊 System Overview

TurboTrades has **two separate pricing systems** for different purposes:

### 1. **Marketplace** (User-to-User)
- Users list items at their own prices
- Other users buy from listings
- Site takes a commission (configurable in admin panel)
- Prices set by sellers

### 2. **Instant Sell** (User-to-Site)
- Site **buys items directly** from users
- Instant payout to user balance
- Price = Market Price × Payout Rate (e.g., 60%)
- Admin configures payout percentage

---

## 🗄️ Database Structure

### MarketPrice Collection (Reference Database)
- **Purpose**: Reference prices for ALL Steam market items
- **Updated**: Every 1 hour automatically
- **Source**: SteamAPIs.com market data
- **Used for**: Instant sell page pricing
- **Contents**: ~30,000+ items (CS2 + Rust)

### Item Collection (Marketplace Listings)
- **Purpose**: User-listed items for sale
- **Updated**: Every 1 hour (optional, for listed items)
- **Source**: User-set prices or suggested from MarketPrice
- **Used for**: Marketplace page

---

## ⚙️ How Instant Sell Works

### User Experience:
1. User goes to `/sell` page
2. Selects items from their Steam inventory
3. Sees **instant buy price** = Market Price × Payout Rate
4. Accepts offer
5. Site buys items, credits balance immediately

### Backend Flow:
1. **Fetch Inventory** (`GET /api/inventory/steam`)
   - Gets user's Steam inventory
   - Looks up each item in `MarketPrice` database
   - Applies payout rate (e.g., 60%)
   - Returns items with `marketPrice` (already discounted)

2. **Create Trade** (`POST /api/inventory/trade`)
   - Validates items and prices
   - Creates trade offer via Steam bot
   - User accepts in Steam
   - Balance credited on completion

### Example Calculation:
```
Market Price (MarketPrice DB): $10.00
Payout Rate (Admin Config):     60%
User Receives:                 $6.00
```

---

## 🔄 Automatic Price Updates

### On Server Startup:
```javascript
// Runs immediately when server starts
pricingService.updateAllPrices()
  → Updates MarketPrice database (CS2 + Rust)
  → Updates Item prices (marketplace listings)
```

### Every Hour:
```javascript
// Scheduled via setInterval (60 minutes)
pricingService.scheduleUpdates(60 * 60 * 1000)
  → updateMarketPriceDatabase('cs2')   // ~20,000 items
  → updateMarketPriceDatabase('rust')  // ~10,000 items
  → updateDatabasePrices('cs2')        // Marketplace items
  → updateDatabasePrices('rust')       // Marketplace items
```

### What Gets Updated:
- ✅ **MarketPrice**: ALL Steam market items
- ✅ **Item**: Only items listed on marketplace
- ⏱️ **Duration**: ~2-5 minutes per update
- 🔑 **Requires**: `STEAM_APIS_KEY` in `.env`

---

## 🎛️ Admin Configuration

### Instant Sell Settings

**Endpoint:** `PATCH /api/admin/config/instantsell`

**Settings Available:**
```json
{
  "enabled": true,                    // Enable/disable instant sell
  "payoutRate": 0.6,                  // 60% default payout
  "minItemValue": 0.1,                // Min $0.10
  "maxItemValue": 10000,              // Max $10,000
  "cs2": {
    "enabled": true,
    "payoutRate": 0.65                // CS2-specific override (65%)
  },
  "rust": {
    "enabled": true,
    "payoutRate": 0.55                // Rust-specific override (55%)
  }
}
```

### Setting Payout Rates

**Example: Set 65% payout for CS2, 55% for Rust**
```bash
curl -X PATCH https://api.turbotrades.dev/api/admin/config/instantsell \
  -H "Content-Type: application/json" \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -d '{
    "cs2": {
      "payoutRate": 0.65
    },
    "rust": {
      "payoutRate": 0.55
    }
  }'
```

**Example: Disable instant sell for Rust**
```bash
curl -X PATCH https://api.turbotrades.dev/api/admin/config/instantsell \
  -H "Content-Type: application/json" \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -d '{
    "rust": {
      "enabled": false
    }
  }'
```

---

## 🚀 Initial Setup

### 1. Set API Key
```bash
# In your .env file
STEAM_APIS_KEY=your_api_key_here
```

Get API key from: https://steamapis.com/

### 2. Import Initial Prices (One-Time)
```bash
# Populates MarketPrice database
node import-market-prices.js
```

**Expected Output:**
```
📡 Fetching CS2 market data...
✅ Received 20,147 items from API
💾 Importing CS2 items to database...
✅ CS2 import complete: 20,147 inserted

📡 Fetching Rust market data...
✅ Received 9,823 items from API
💾 Importing Rust items to database...
✅ Rust import complete: 9,823 inserted

🎉 Total: 29,970 items imported
```

### 3. Configure Payout Rate
Use admin panel or API to set your desired payout percentage.

### 4. Start Server
```bash
pm2 start ecosystem.config.js --env production
```

Server will automatically:
- ✅ Update prices on startup
- ✅ Schedule hourly updates
- ✅ Keep prices fresh

---

## 📈 Price Update Logs

### Successful Update:
```
🔄 Starting price update for all games...

🔄 Updating MarketPrice reference database for CS2...
📡 Fetching market data from Steam API...
✅ Received 20,147 items from API
📦 Batch: 10,000 inserted, 10,147 updated
✅ MarketPrice update complete for CS2:
   📥 Inserted: 234
   🔄 Updated: 19,913
   ⏭️  Skipped: 0

🔄 Updating MarketPrice reference database for RUST...
✅ Received 9,823 items from API
✅ MarketPrice update complete for RUST:
   📥 Inserted: 89
   🔄 Updated: 9,734

✅ All price updates complete!
```

### View Logs:
```bash
pm2 logs turbotrades-backend --lines 100 | grep "price update"
```

---

## 🛠️ Manual Price Updates

### Update All Prices Now:
```bash
node update-prices-now.js
```

### Update Specific Game:
```bash
node update-prices-now.js cs2
node update-prices-now.js rust
```

### Check Price Coverage:
```bash
node check-prices.js
```

**Output:**
```
📊 Price Coverage Report

🎮 Counter-Strike 2:
   Active Items:  1,245
   With Prices:   1,198
   Coverage:      96.2%

🔧 Rust:
   Active Items:  387
   With Prices:   375
   Coverage:      96.9%
```

---

## 🔍 Troubleshooting

### Items Showing "Price unavailable" on Sell Page

**Cause:** MarketPrice database is empty or outdated

**Solution:**
```bash
# Import prices
node import-market-prices.js

# OR restart server (auto-updates on startup)
pm2 restart turbotrades-backend
```

### Prices Not Updating

**Check 1:** Verify API key
```bash
# Check if set
echo $STEAM_APIS_KEY

# Test API key
curl "https://api.steamapis.com/market/items/730?api_key=$STEAM_APIS_KEY" | head
```

**Check 2:** Check logs
```bash
pm2 logs turbotrades-backend --lines 200 | grep -E "price|update"
```

**Check 3:** Verify scheduler is running
```bash
# Should see this on startup:
⏰ Starting automatic price update scheduler...
🔄 Running initial price update on startup...
```

### Wrong Payout Rate Applied

**Check config:**
```bash
# Via API
curl https://api.turbotrades.dev/api/config/public | jq '.config.instantSell'
```

**Update config:**
```bash
# Via admin panel at /admin
# Or via API (requires admin auth)
```

---

## 📊 Database Queries

### Check MarketPrice Count:
```javascript
db.marketprices.countDocuments({ game: "cs2" })
db.marketprices.countDocuments({ game: "rust" })
```

### Find Item Price:
```javascript
db.marketprices.findOne({
  marketHashName: "AK-47 | Redline (Field-Tested)",
  game: "cs2"
})
```

### Most Expensive Items:
```javascript
db.marketprices.find({ game: "cs2" })
  .sort({ price: -1 })
  .limit(10)
```

### Last Update Time:
```javascript
db.marketprices.findOne({ game: "cs2" })
  .sort({ lastUpdated: -1 })
  .limit(1)
```

---

## 🎯 Best Practices

### Payout Rates:
- **Too High** (>80%): Site loses money
- **Too Low** (<40%): Users won't sell
- **Recommended**: 55-65% depending on competition

### Update Frequency:
- **Every Hour**: Good for active trading
- **Every 2-4 Hours**: Sufficient for most sites
- **Daily**: Only for low-volume sites

### Monitoring:
- Set up alerts for failed price updates
- Monitor price coverage percentage
- Track user complaints about prices

---

## 🔐 Security Notes

- ✅ API key stored in `.env` (never committed)
- ✅ Payout rate changes logged with admin username
- ✅ Rate limits on price update endpoints
- ✅ Validate prices before accepting trades
- ✅ Maximum item value limits prevent abuse

---

## 📝 Summary

| Feature | Status | Update Frequency |
|---------|--------|------------------|
| MarketPrice DB | ✅ Automatic | Every 1 hour |
| Item Prices | ✅ Automatic | Every 1 hour |
| Payout Rate | ⚙️ Admin Config | Manual |
| Initial Import | 🔧 Manual | One-time |
| Sell Page | ✅ Live | Real-time |

**Your instant sell page will now:**
- ✅ Show accurate prices from your database
- ✅ Apply your configured payout rate
- ✅ Update prices automatically every hour
- ✅ Allow per-game payout customization

**No more manual price updates needed!** 🎉