TurboTrades/TRADE_SETUP.md

# Trade System Setup Guide

## Quick Start (Development Mode - No Steam Bots Required)

For testing the trade system without real Steam bots:

### 1. Enable Bypass Mode

Add to your `.env` file:

```bash
NODE_ENV=development
BYPASS_BOT_REQUIREMENT=true
```

### 2. Restart Backend

```bash
npm run dev
```

### 3. Test the Flow

1. Go to `/sell` page
2. Select items to sell
3. Click "Sell Selected Items"
4. You'll get a mock trade with verification code
5. **To complete the trade and credit balance:**
   ```bash
   # Get the trade ID from the response, then:
   curl -X POST http://localhost:3000/api/inventory/trade/TRADE_ID/complete \
     -H "Cookie: accessToken=YOUR_TOKEN"
   ```
   Or use the frontend to call: `POST /api/inventory/trade/:tradeId/complete`

### 4. Check Balance

Your balance should be credited automatically!

---

## Production Setup (With Real Steam Bots)

### Prerequisites

You need:
- ✅ Steam account(s) for bots
- ✅ Steam Mobile Authenticator enabled on each bot account
- ✅ `shared_secret` and `identity_secret` for each bot
- ✅ Steam API Key ([get one here](https://steamcommunity.com/dev/apikey))
- ⚠️ Optional: SOCKS5/HTTP proxies (recommended for multiple bots)

### Step 1: Extract Bot Secrets

#### Using [SDA (Steam Desktop Authenticator)](https://github.com/Jessecar96/SteamDesktopAuthenticator):

1. Install SDA on your computer
2. Add your bot account to SDA
3. Navigate to SDA's data folder:
   - Windows: `%APPDATA%\SteamDesktopAuthenticator`
   - Linux: `~/.config/SteamDesktopAuthenticator`
4. Open `maFiles/<steamid>.maFile`
5. Copy `shared_secret` and `identity_secret`

#### Using [steam-totp](https://www.npmjs.com/package/steam-totp):

```javascript
// If you have your Steam Guard secret:
import SteamTotp from 'steam-totp';
const code = SteamTotp.generateAuthCode('YOUR_SHARED_SECRET');
```

### Step 2: Create Bot Configuration

Create `config/steam-bots.json`:

```json
[
  {
    "username": "turbotrades_bot1",
    "password": "your_steam_password",
    "sharedSecret": "abcd1234efgh5678ijkl==",
    "identitySecret": "wxyz9876vuts5432pqrs==",
    "steamApiKey": "YOUR_STEAM_API_KEY",
    "pollInterval": 30000,
    "tradeTimeout": 600000,
    "proxy": {
      "type": "socks5",
      "host": "proxy.example.com",
      "port": 1080,
      "username": "proxy_user",
      "password": "proxy_password"
    }
  }
]
```

**Notes:**
- `proxy` is optional but recommended for multiple bots
- `pollInterval`: How often to check for trade updates (ms)
- `tradeTimeout`: How long before trade auto-cancels (ms)

### Step 3: Enable Auto-Start

Add to `.env`:

```bash
STEAM_BOT_AUTO_START=true
```

### Step 4: Start Backend

```bash
npm run dev
```

You should see:
```
🤖 Auto-starting Steam bots...
✅ Bot turbotrades_bot1 ready
✅ 1/1 bots initialized successfully
```

### Step 5: Test Trade Flow

1. Set your trade URL in profile (`/profile`)
2. Go to sell page (`/sell`)
3. Select items
4. Create trade offer
5. Check Steam for trade offer
6. Verify code matches
7. Accept trade in Steam
8. Balance credited automatically!

---

## Manual Bot Initialization (Alternative)

If you don't want auto-start, you can initialize bots via API:

```javascript
// In your code or via admin endpoint
import { getSteamBotManager } from './services/steamBot.js';

const botManager = getSteamBotManager();

const botsConfig = [
  {
    username: "bot1",
    password: "pass",
    sharedSecret: "secret",
    identitySecret: "secret"
  }
];

await botManager.initialize(botsConfig);
```

---

## Environment Variables Reference

```bash
# Development Mode (bypass bots)
NODE_ENV=development
BYPASS_BOT_REQUIREMENT=true

# Production Mode (real bots)
NODE_ENV=production
STEAM_BOT_AUTO_START=true
STEAM_APIS_KEY=your_steam_api_key

# Optional
ENABLE_PRICE_UPDATES=true
```

---

## Verification Codes

- **Format**: 6 alphanumeric characters (e.g., `A3X9K2`)
- **Purpose**: Prevent phishing attacks
- **How it works**:
  1. Code shown on website
  2. Code included in Steam trade message
  3. User must verify codes match before accepting

---

## WebSocket Events (Real-time Updates)

Your frontend will receive these events:

- `trade_creating` - Trade is being created
- `trade_sent` - Trade sent to Steam
- `trade_confirmed` - Trade confirmed with 2FA
- `trade_created` - Trade ready (includes verification code)
- `trade_accepted` - User accepted on Steam
- `trade_completed` - Balance credited
- `balance_update` - Balance changed
- `trade_declined` - User declined
- `trade_expired` - Trade expired
- `trade_canceled` - Trade canceled

---

## Monitoring

### Check Bot Health

```bash
# Via admin endpoint (requires admin role)
curl http://localhost:3000/api/admin/bots/health
```

### Check Bot Stats

```javascript
import { getSteamBotManager } from './services/steamBot.js';

const botManager = getSteamBotManager();
const stats = botManager.getStats();

console.log(stats);
// {
//   totalBots: 2,
//   healthyBots: 2,
//   totalTrades: 15,
//   totalActiveTrades: 3,
//   totalErrors: 0
// }
```

### View Trade History

```bash
curl http://localhost:3000/api/inventory/trades \
  -H "Cookie: accessToken=YOUR_TOKEN"
```

---

## Troubleshooting

### "Trade system unavailable"

**Cause**: Bots not initialized

**Solution**:
- Development: Set `BYPASS_BOT_REQUIREMENT=true`
- Production: Check bot config and set `STEAM_BOT_AUTO_START=true`

### "Bot login failed"

**Causes**:
- Wrong username/password
- Wrong shared_secret
- Steam Guard not enabled
- Account locked/banned

**Solution**:
1. Verify credentials
2. Test login manually via Steam client
3. Check bot account is not limited (spent $5+ on Steam)

### "Confirmation failed"

**Cause**: Wrong `identity_secret`

**Solution**:
- Double-check identity_secret from SDA maFile
- Ensure mobile auth is enabled

### Trade created but not appearing in Steam

**Causes**:
- User's trade URL is incorrect
- User's inventory is private
- Items became untradable

**Solution**:
1. Verify trade URL format
2. Make inventory public
3. Check item trade restrictions

### Balance not credited after accepting trade

**Causes**:
- Backend event listener not working
- Database error
- WebSocket disconnected

**Solution**:
1. Check backend logs for `tradeAccepted` event
2. Check Trade status in database
3. Manually complete via: `POST /api/inventory/trade/:tradeId/complete` (dev only)

---

## Security Best Practices

1. ✅ **Never expose bot credentials** - Store in secure config, not in code
2. ✅ **Use proxies** - Distribute bot IPs to avoid rate limits
3. ✅ **Monitor bot health** - Set up alerts for bot failures
4. ✅ **Verification codes** - Always show and require verification
5. ✅ **Rate limiting** - Limit trades per user per hour
6. ✅ **Escrow handling** - Warn users about 7-day trade holds
7. ✅ **Audit logs** - Log all trade events for debugging

---

## API Endpoints Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/inventory/sell` | Create trade offer |
| GET | `/api/inventory/trades` | Get trade history |
| GET | `/api/inventory/trade/:id` | Get trade details |
| POST | `/api/inventory/trade/:id/cancel` | Cancel pending trade |
| POST | `/api/inventory/trade/:id/complete` | Complete trade (dev only) |

---

## Need Help?

- 📖 Read `TRADE_WORKFLOW.md` for detailed flow documentation
- 🤖 Read `STEAM_BOT_SETUP.md` for bot setup details
- 🔧 Check logs in backend console
- 💬 Check WebSocket messages in browser dev tools