system now uses seperate pricing.

PRICING_SYSTEM_COMPLETE.md

@@ -0,0 +1,395 @@
+# 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!** 🎉