TurboTrades/API_ENDPOINTS.md

TurboTrades API Endpoints Reference

Complete list of all available API endpoints with examples.

---

Base URL

• Development: http://localhost:3000
• Frontend Proxy: http://localhost:5173/api (proxies to backend)

---

Authentication Endpoints

/auth/*

Method	Endpoint	Description	Auth Required
GET	/auth/steam	Initiate Steam login	No
GET	/auth/steam/return	Steam OAuth callback	No
GET	/auth/steam/test	Test Steam config	No
GET	/auth/me	Get current user	Yes (Access Token)
POST	/auth/refresh	Refresh access token	Yes (Refresh Token)
POST	/auth/logout	Logout user	Yes (Access Token)
GET	/auth/verify	Verify token validity	Yes (Access Token)
GET	/auth/decode-token	Decode JWT token (debug)	No

Example Usage:

# Login via Steam (opens browser)
curl http://localhost:3000/auth/steam

# Get current user (requires auth)
curl http://localhost:3000/auth/me \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Refresh token
curl -X POST http://localhost:3000/auth/refresh \
  -H "Cookie: refreshToken=YOUR_REFRESH_TOKEN"

---

User Endpoints

/user/*

Method	Endpoint	Description	Auth Required
GET	/user/profile	Get user profile	Yes
PATCH	/user/email	Update email address	Yes
GET	/user/verify-email/:token	Verify email	No
PATCH	/user/trade-url	Update Steam trade URL	Yes
GET	/user/balance	Get user balance	Yes
GET	/user/stats	Get user statistics	Yes
PATCH	/user/intercom	Update intercom ID	Yes
GET	/user/:steamId	Get public user profile	No

Example Usage:

# Get profile
curl http://localhost:3000/user/profile \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Update email
curl -X PATCH http://localhost:3000/user/email \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Update trade URL
curl -X PATCH http://localhost:3000/user/trade-url \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=123&token=abc"}'

---

Two-Factor Authentication (2FA) Endpoints

/user/2fa/*

Method	Endpoint	Description	Auth Required
POST	/user/2fa/setup	Generate QR code & secret	Yes
POST	/user/2fa/verify	Verify code & enable 2FA	Yes
POST	/user/2fa/disable	Disable 2FA	Yes

Example Usage:

# Setup 2FA (get QR code)
curl -X POST http://localhost:3000/user/2fa/setup \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Verify 2FA code
curl -X POST http://localhost:3000/user/2fa/verify \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "123456"}'

# Disable 2FA
curl -X POST http://localhost:3000/user/2fa/disable \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "123456"}'

---

Session Management Endpoints

/user/sessions/*

Method	Endpoint	Description	Auth Required
GET	/user/sessions	Get all active sessions	Yes
DELETE	/user/sessions/:sessionId	Revoke specific session	Yes
POST	/user/sessions/revoke-all	Revoke all other sessions	Yes

Example Usage:

# Get all sessions
curl http://localhost:3000/user/sessions \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Revoke specific session
curl -X DELETE http://localhost:3000/user/sessions/SESSION_ID \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Revoke all other sessions
curl -X POST http://localhost:3000/user/sessions/revoke-all \
  -H "Cookie: accessToken=YOUR_TOKEN"

---

Market Endpoints

/market/*

Method	Endpoint	Description	Auth Required
GET	/market/items	Get marketplace items	No
GET	/market/items/:id	Get item details	No
GET	/market/featured	Get featured items	No
GET	/market/recent-sales	Get recent sales	No
GET	/market/stats	Get market statistics	No
POST	/market/purchase/:id	Purchase an item	Yes

Example Usage:

# Get all items
curl http://localhost:3000/market/items

# Get items with filters
curl "http://localhost:3000/market/items?game=cs2&minPrice=10&maxPrice=100&limit=20"

# Get featured items
curl http://localhost:3000/market/featured

# Get item details
curl http://localhost:3000/market/items/ITEM_ID

# Purchase item
curl -X POST http://localhost:3000/market/purchase/ITEM_ID \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Get market stats
curl http://localhost:3000/market/stats

---

WebSocket Endpoint

/ws

Real-time updates via WebSocket.

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:3000/ws');

// Listen for messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Send ping
ws.send(JSON.stringify({ type: 'ping' }));

Events:

• listing_update - Item listing updated
• listing_removed - Item removed from market
• listing_added - New item added to market
• price_update - Item price changed
• market_update - Bulk market updates
• pong - Response to ping

---

Testing from Frontend

Using Axios (already configured):

import axios from '@/utils/axios'

// Get user profile
const response = await axios.get('/api/user/profile', {
  withCredentials: true
})

// Update email
await axios.patch('/api/user/email', {
  email: 'user@example.com'
}, {
  withCredentials: true
})

// Setup 2FA
const response = await axios.post('/api/user/2fa/setup', {}, {
  withCredentials: true
})

// Get sessions
const response = await axios.get('/api/user/sessions', {
  withCredentials: true
})

---

Common Issues & Solutions

1. "Unauthorized" Error

Cause: No access token provided or token expired.

Solution:

• Login via Steam first: http://localhost:3000/auth/steam
• Ensure cookies are being sent: withCredentials: true
• Check if token is expired (15 minutes lifetime)
• Use refresh token to get new access token

2. "Route not found"

Cause: Incorrect URL or route not registered.

Solution:

• Check the route prefix (/auth, /user, /market)
• Verify the HTTP method (GET, POST, PATCH, DELETE)
• Check backend logs for route registration

3. CORS Issues

Cause: Frontend and backend on different ports.

Solution:

• Ensure CORS_ORIGIN=http://localhost:5173 in .env
• Restart backend after changing .env
• Use frontend proxy: /api/* instead of direct backend URL

4. Sessions Not Working

Cause: Session model not properly imported or MongoDB issue.

Solution:

• Check MongoDB is running: mongod
• Verify Session model exists: models/Session.js
• Check backend logs for session creation errors
• Ensure TTL index is created on expiresAt field

---

Response Formats

Success Response:

{
  "success": true,
  "data": { ... }
}

Error Response:

{
  "error": "ErrorType",
  "message": "Human readable error message",
  "details": { ... }
}

---

Authentication Flow

1. User clicks "Login with Steam" → /auth/steam
2. Redirects to Steam OpenID
3. User authenticates on Steam
4. Steam redirects back → /auth/steam/return
5. Backend generates JWT tokens
6. Sets accessToken and refreshToken cookies
7. Redirects to frontend → http://localhost:5173/

---

Token Lifetimes

• Access Token: 15 minutes
• Refresh Token: 7 days
• Session TTL: 7 days (auto-deleted by MongoDB)

---

Frontend Routes

Route	Component	Auth Required
/	HomePage	No
/market	MarketPage	No
/item/:id	ItemDetailsPage	No
/profile	ProfilePage	Yes
/inventory	InventoryPage	Yes
/sell	SellPage	Yes
/transactions	TransactionsPage	Yes
/deposit	DepositPage	Yes
/withdraw	WithdrawPage	Yes
/admin	AdminPage	Yes (Admin only)
/faq	FAQPage	No
/support	SupportPage	No
/terms	TermsPage	No
/privacy	PrivacyPage	No

---

Quick Start Testing

1. Start MongoDB: mongod
2. Seed Database: npm run seed
3. Start Backend: npm run dev
4. Start Frontend: cd frontend && npm run dev
5. Login: Navigate to http://localhost:5173 and login with Steam
6. Test Routes: Use browser DevTools Network tab or curl commands above

---

Notes

• All timestamps are in UTC
• Prices are in USD
• Image URLs may be Steam CDN or placeholder
• WebSocket connections are optional
• Rate limiting: 100 requests per minute (development)