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:

// Runs immediately when server starts
pricingService.updateAllPrices()
  → Updates MarketPrice database (CS2 + Rust)
  → Updates Item prices (marketplace listings)

Every Hour:

// 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:

{
  "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

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

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

# In your .env file
STEAM_APIS_KEY=your_api_key_here

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

2. Import Initial Prices (One-Time)

# 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

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:

pm2 logs turbotrades-backend --lines 100 | grep "price update"

---

🛠️ Manual Price Updates

Update All Prices Now:

node update-prices-now.js

Update Specific Game:

node update-prices-now.js cs2
node update-prices-now.js rust

Check Price Coverage:

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:

# 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

# 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

pm2 logs turbotrades-backend --lines 200 | grep -E "price|update"

Check 3: Verify scheduler is running

# Should see this on startup:
⏰ Starting automatic price update scheduler...
🔄 Running initial price update on startup...

Wrong Payout Rate Applied

Check config:

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

Update config:

# Via admin panel at /admin
# Or via API (requires admin auth)

---

📊 Database Queries

Check MarketPrice Count:

db.marketprices.countDocuments({ game: "cs2" })
db.marketprices.countDocuments({ game: "rust" })

Find Item Price:

db.marketprices.findOne({
  marketHashName: "AK-47 | Redline (Field-Tested)",
  game: "cs2"
})

Most Expensive Items:

db.marketprices.find({ game: "cs2" })
  .sort({ price: -1 })
  .limit(10)

Last Update Time:

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! 🎉