TurboTrades/STEAM_API_SETUP.md

# Steam API Setup Guide

This guide will help you set up the Steam API integration for fetching user inventories.

## Prerequisites

- Steam account with API access
- TurboTrades backend configured and running

## Step 1: Get Your Steam API Key

1. **Visit the Steam Web API Key page:**
   - Go to: https://steamcommunity.com/dev/apikey

2. **Register for a Steam Web API Key:**
   - You'll need to be logged into Steam
   - Domain Name: Enter your domain (for development, use `localhost` or `127.0.0.1`)
   - Agree to the Steam Web API Terms of Use
   - Click "Register"

3. **Copy your API Key:**
   - Once registered, you'll see your API key
   - Copy this key - you'll need it in the next step
   - **Keep this key secret!** Never commit it to version control

## Step 2: Alternative - Use SteamAPIs.com

Since the direct Steam API can be rate-limited and unreliable, we're using **SteamAPIs.com** which provides a more reliable wrapper.

1. **Get a SteamAPIs Key:**
   - Go to: https://steamapis.com/
   - Sign up for a free account
   - Navigate to your dashboard to get your API key
   - Free tier includes: 100,000 requests/month

2. **Why SteamAPIs.com?**
   - More reliable than direct Steam API
   - Better rate limits
   - Automatic retry logic
   - Cached responses for better performance
   - Handles Steam API downtime gracefully

## Step 3: Add API Key to Environment Variables

1. **Open your `.env` file** in the TurboTrades root directory

2. **Add the Steam API key:**

```env
# Steam API Configuration
STEAM_API_KEY=your_steamapis_key_here
```

3. **Example `.env` file:**

```env
# Server Configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/turbotrades

# Steam OpenID
STEAM_RETURN_URL=http://localhost:3000/auth/steam/return
STEAM_REALM=http://localhost:3000

# Steam API (for inventory fetching)
STEAM_API_KEY=abc123xyz456def789ghi012

# JWT Secrets
JWT_ACCESS_SECRET=your-access-secret-key-here
JWT_REFRESH_SECRET=your-refresh-secret-key-here

# Session
SESSION_SECRET=your-session-secret-here

# CORS
CORS_ORIGIN=http://localhost:5173
```

## Step 4: Restart the Backend

After adding the API key, restart your backend server:

```bash
# Stop the current server (Ctrl+C)
# Then restart:
npm run dev
```

## Step 5: Test the Integration

1. **Make sure you're logged in** via Steam on the frontend

2. **Navigate to the Sell page:** `http://localhost:5173/sell`

3. **Check the browser console** for any errors

4. **Backend logs** should show:
```
🎮 Fetching CS2 inventory for Steam ID: 76561198xxxxx
📡 Calling: https://api.steamapis.com/steam/inventory/76561198xxxxx/730/2
✅ Found XX marketable items in inventory
```

## Troubleshooting

### Error: "STEAM_API_KEY not configured"

**Solution:** Make sure you've added `STEAM_API_KEY` to your `.env` file and restarted the server.

### Error: "Steam API authentication failed"

**Solution:** 
- Verify your API key is correct
- Check if your SteamAPIs.com account is active
- Ensure you haven't exceeded your rate limit

### Error: "Steam inventory is private"

**Solution:** 
- Open Steam client
- Go to Profile → Edit Profile → Privacy Settings
- Set "Game details" and "Inventory" to **Public**

### Error: "Steam profile not found"

**Solution:**
- Verify the Steam ID is correct
- Make sure the user has logged in via Steam OpenID
- Check that `request.user.steamId` is being populated correctly

### Rate Limiting Issues

If you're hitting rate limits:

1. **Upgrade SteamAPIs.com plan:**
   - Free: 100,000 requests/month
   - Paid plans: Higher limits

2. **Implement caching:**
   - Cache inventory responses for 5-10 minutes
   - Store frequently accessed data in Redis

3. **Use direct Steam API as fallback:**
   - Only for development/testing
   - Not recommended for production

## API Endpoints

### Fetch Inventory

```http
GET /api/inventory/steam?game=cs2
GET /api/inventory/steam?game=rust

Headers:
  Cookie: accessToken=your_jwt_token
```

**Response:**
```json
{
  "success": true,
  "items": [
    {
      "assetid": "123456789",
      "name": "AK-47 | Redline (Field-Tested)",
      "image": "https://community.cloudflare.steamstatic.com/economy/image/...",
      "wear": "ft",
      "wearName": "Field-Tested",
      "rarity": "Rarity_Rare",
      "category": "weapon_ak47",
      "marketable": true,
      "tradable": true,
      "statTrak": false,
      "souvenir": false
    }
  ],
  "total": 42
}
```

### Price Items

```http
POST /api/inventory/price

Headers:
  Cookie: accessToken=your_jwt_token
  Content-Type: application/json

Body:
{
  "items": [
    {
      "name": "AK-47 | Redline (Field-Tested)",
      "assetid": "123456789",
      "wear": "ft"
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "items": [
    {
      "name": "AK-47 | Redline (Field-Tested)",
      "assetid": "123456789",
      "wear": "ft",
      "estimatedPrice": 42.50,
      "currency": "USD"
    }
  ]
}
```

### Sell Items

```http
POST /api/inventory/sell

Headers:
  Cookie: accessToken=your_jwt_token
  Content-Type: application/json

Body:
{
  "items": [
    {
      "assetid": "123456789",
      "name": "AK-47 | Redline (Field-Tested)",
      "price": 42.50,
      "image": "https://...",
      "wear": "ft",
      "rarity": "Rarity_Rare",
      "category": "weapon_ak47",
      "statTrak": false,
      "souvenir": false
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "message": "Successfully sold 1 item for $42.50",
  "itemsListed": 1,
  "totalEarned": 42.50,
  "newBalance": 142.50
}
```

## Security Best Practices

1. **Never commit API keys to Git:**
   - Add `.env` to `.gitignore`
   - Use environment variables only

2. **Rotate keys regularly:**
   - Change your API key every 3-6 months
   - Immediately rotate if compromised

3. **Use rate limiting:**
   - Implement request throttling
   - Cache inventory responses

4. **Validate user permissions:**
   - Always authenticate requests
   - Verify user owns the Steam account

5. **Monitor API usage:**
   - Track API calls in logs
   - Set up alerts for unusual activity
   - Monitor SteamAPIs.com dashboard

## Additional Resources

- **Steam Web API Documentation:** https://developer.valvesoftware.com/wiki/Steam_Web_API
- **SteamAPIs Documentation:** https://steamapis.com/docs
- **Steam Inventory Service:** https://steamcommunity.com/dev
- **Steam API Key Management:** https://steamcommunity.com/dev/apikey

## Support

If you encounter any issues:

1. Check the backend logs for detailed error messages
2. Verify your API key is valid
3. Ensure Steam inventory is public
4. Check SteamAPIs.com service status
5. Review the troubleshooting section above

---

**Last Updated:** 2024
**Maintainer:** TurboTrades Development Team