iDefineHD/TurboTrades
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
TurboTrades/TRADE_WORKFLOW.md

11 KiB
Raw Permalink Blame History

TurboTrades - Steam Trade Workflow Documentation

Overview

This document explains the complete workflow for selling items through Steam trade offers with real-time WebSocket updates and verification codes.

Architecture

User (Frontend) <--WebSocket--> Backend <--> Steam Bot Manager <--> Steam API
                                    |
                                    v
                                 Database
                                (Trades, Users, Transactions)

Complete Trade Flow

1. User Initiates Sale (Frontend)

File: frontend/src/views/SellPage.vue

  1. User logs in and navigates to /sell
  2. Frontend fetches user's Steam inventory via /api/inventory/steam
  3. Items are displayed with market prices (pre-fetched from database)
  4. User selects items to sell
  5. User clicks "Sell Selected Items"
  6. Frontend makes POST request to /api/inventory/sell with: 
    {
  "tradeUrl": "user's Steam trade URL",
  "items": [
    {
      "assetid": "123456789",
      "appid": 730,
      "contextid": "2",
      "name": "AK-47 | Redline (Field-Tested)",
      "price": 25.50,
      "image": "url",
      "wear": "ft",
      "rarity": "classified"
    }
  ]
}

2. Backend Creates Trade Offer

File: routes/inventory.js - POST /api/inventory/sell

  1. Validates user authentication and trade URL
  2. Calculates total value of items
  3. Calls botManager.createTradeOffer() with:
    • User's trade URL
    • Items to receive (assetid, appid, contextid)
    • User ID (for WebSocket notifications)
  4. Bot manager selects best available bot (least busy)
  5. Bot manager generates 6-character verification code
  6. Bot creates Steam trade offer with verification code in message

3. Trade Offer Created

File: services/steamBot.js - SteamBotInstance.createTradeOffer()

  1. Bot sends trade offer to Steam

  2. Bot confirms trade offer with 2FA (identity_secret)

  3. Trade record saved to database with status: pending

  4. WebSocket notifications sent to user:

    WebSocket Events Sent:

    • trade_creating - Trade is being created
    • trade_sent - Trade offer sent to Steam
    • trade_confirmed - Trade confirmed with 2FA
    • trade_created - Complete trade details

  5. Response sent to frontend with:

    {
  "success": true,
  "trade": {
    "tradeId": "db_record_id",
    "offerId": "steam_offer_id",
    "verificationCode": "A3X9K2",
    "itemCount": 3,
    "totalValue": 75.50,
    "status": "pending",
    "botId": "bot1"
  }
}

4. User Views Verification Code

File: frontend/src/views/SellPage.vue

  1. Toast notification shows verification code (doesn't auto-dismiss)
  2. User receives WebSocket message with trade details
  3. User opens Steam client/mobile app
  4. User sees trade offer from TurboTrades bot

5. User Verifies and Accepts Trade

Steam Side:

  1. User checks trade offer message for verification code
  2. User compares code in Steam with code shown on website
  3. If codes match, user accepts trade
  4. If codes don't match, user declines (security protection)

6. Bot Detects Trade Acceptance

File: services/steamBot.js - _handleOfferStateChange()

When Steam trade state changes to Accepted (state 3):

  1. Bot emits tradeAccepted event
  2. Event includes offer details and trade data

7. Backend Processes Completed Trade

File: index.js - Trade event listener

botManager.on('tradeAccepted', async (offer, tradeData) => {
  // 1. Find trade record in database
  // 2. Find user record
  // 3. Credit user balance with trade value
  // 4. Update trade status to 'completed'
  // 5. Create transaction record (type: 'sale')
  // 6. Send WebSocket notifications
});

WebSocket Events Sent:

  • trade_accepted - Trade was accepted on Steam
  • trade_completed - Balance credited successfully
  • balance_update - User's new balance

8. User Receives Funds

  1. User balance updated in database
  2. Transaction record created for audit trail
  3. WebSocket notifications update frontend in real-time
  4. Toast notification shows credited amount
  5. User can spend balance on marketplace

WebSocket Events Reference

Events Sent to User During Trade

Event Trigger Data
trade_creating Bot starting to create offer verificationCode, itemCount, botId
trade_sent Offer sent to Steam offerId, verificationCode, status
trade_confirmed Offer confirmed with 2FA offerId, verificationCode
trade_created Complete - offer ready tradeId, offerId, verificationCode, totalValue
trade_accepted User accepted on Steam offerId, verificationCode, itemCount
trade_completed Balance credited tradeId, amount, newBalance
balance_update Balance changed balance, change, reason
trade_declined User declined on Steam offerId, tradeId
trade_expired Offer expired (15 days) offerId, tradeId
trade_canceled User/bot canceled offerId, tradeId
trade_error Error occurred error, verificationCode

WebSocket Message Format

{
  "type": "trade_completed",
  "data": {
    "tradeId": "507f1f77bcf86cd799439011",
    "offerId": "5847362918",
    "amount": 75.50,
    "newBalance": 125.75,
    "itemCount": 3,
    "timestamp": 1704067200000
  }
}

Database Models

Trade Model

File: models/Trade.js

{
  offerId: String,        // Steam trade offer ID
  botId: String,          // Bot that created the offer
  user: ObjectId,         // User reference
  items: [{               // Items in trade
    assetid: String,
    name: String,
    price: Number,
    image: String
  }],
  totalValue: Number,     // Total value of items
  verificationCode: String, // 6-char code
  status: String,         // pending, completed, declined, expired, cancelled
  type: String,           // sell, buy
  createdAt: Date,
  completedAt: Date
}

Transaction Model

File: models/Transaction.js

{
  user: ObjectId,
  type: String,           // sale, deposit, withdrawal, purchase
  amount: Number,
  description: String,
  status: String,         // completed, pending, failed
  metadata: {
    tradeId: ObjectId,
    offerId: String,
    botId: String,
    verificationCode: String
  }
}

Security Features

Verification Codes

  • Purpose: Prevent phishing and fake trade offers
  • Format: 6 alphanumeric characters (no ambiguous chars: O, 0, I, l, 1)
  • Display: Shown on website and in Steam trade message
  • Validation: User must verify codes match before accepting

Trade URL Privacy

  • Trade URLs stored encrypted in database
  • Only sent to bot manager, never exposed to frontend
  • Required for creating trade offers

Bot Security

  • Each bot uses separate Steam account
  • Proxies supported for IP distribution
  • 2FA required (shared_secret, identity_secret)
  • Rate limiting on trade creation
  • Health monitoring and auto-failover

API Endpoints

POST /api/inventory/sell

Create a new trade offer to sell items.

Request:

{
  "tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=XXX&token=YYY",
  "items": [
    {
      "assetid": "123456789",
      "appid": 730,
      "contextid": "2",
      "name": "Item Name",
      "price": 10.50
    }
  ]
}

Response:

{
  "success": true,
  "trade": {
    "tradeId": "db_id",
    "offerId": "steam_id",
    "verificationCode": "A3X9K2",
    "itemCount": 1,
    "totalValue": 10.50,
    "status": "pending"
  }
}

GET /api/inventory/trades

Get user's trade history.

Response:

{
  "success": true,
  "trades": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "offerId": "5847362918",
      "status": "completed",
      "totalValue": 75.50,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

GET /api/inventory/trade/:tradeId

Get specific trade details.

POST /api/inventory/trade/:tradeId/cancel

Cancel a pending trade offer.

Bot Configuration

Config File Format

File: config/steam-bots.json

[
  {
    "username": "turbotrades_bot1",
    "password": "your_password",
    "sharedSecret": "your_shared_secret",
    "identitySecret": "your_identity_secret",
    "steamApiKey": "your_steam_api_key",
    "proxy": {
      "type": "socks5",
      "host": "proxy.example.com",
      "port": 1080,
      "username": "proxy_user",
      "password": "proxy_pass"
    }
  }
]

Environment Variables

# Auto-start bots on server startup
STEAM_BOT_AUTO_START=true

# Steam API key for inventory fetching
STEAM_APIS_KEY=your_api_key

Error Handling

Trade Creation Errors

Error Cause Solution
No bots available All bots offline/busy Wait or add more bots
Trade URL is required User hasn't set trade URL Redirect to profile settings
Bot not ready Bot not logged in Check bot status, restart if needed
Invalid trade URL Malformed URL User must update trade URL

Trade State Errors

  • Declined: User declined offer - notify user, can retry
  • Expired: 15 days passed - notify user, items returned to user
  • Canceled: Bot/user canceled - update status, no funds credited
  • Invalid: Steam error - log error, notify admin

Monitoring & Logging

Bot Health Checks

botManager.getAllBotsHealth();
// Returns health status for all bots

Trade Statistics

botManager.getStats();
// Returns total trades, active trades, errors, etc.

Database Indexes

  • Trade.offerId - Fast lookup by Steam offer ID
  • Trade.user + Trade.status - User's pending trades
  • Transaction.user + Transaction.createdAt - Transaction history

Testing

Test Sell Flow

  1. Set up test bot with Steam account
  2. Configure bot credentials in config/steam-bots.json
  3. Start backend with STEAM_BOT_AUTO_START=true
  4. Set trade URL in profile
  5. Navigate to /sell page
  6. Select items and click sell
  7. Check verification code matches
  8. Accept trade in Steam
  9. Verify balance credited

Mock Testing (No Real Trades)

For development without real Steam bots:

  • Comment out bot initialization
  • Create mock trade records directly
  • Test WebSocket notifications
  • Test UI with fake verification codes

Troubleshooting

Trade Not Creating

  1. Check bot status: GET /api/admin/bots/health
  2. Verify Steam API key is valid
  3. Check bot login credentials
  4. Review bot error logs
  5. Ensure identity_secret is correct

Trade Created But Not Accepted

  1. Verify user has mobile authenticator
  2. Check if items are still tradable
  3. Verify verification codes match
  4. Check Steam trade restrictions (7-day holds)

Balance Not Credited

  1. Check trade status in database
  2. Review server logs for tradeAccepted event
  3. Verify transaction was created
  4. Check for any database errors

Future Enhancements

  • Queue system (Bull/Redis) for high-volume trades
  • Trade status page with live updates
  • Mobile notifications when trade is ready
  • Automatic retry on trade failure
  • Multi-region bot distribution
  • Trade escrow handling for new devices
  • Price history tracking per trade
  • CSV export of trade history
  • Admin dashboard for trade monitoring
Reference in New Issue View Git Blame Copy Permalink