Trades API

Query your trade history with flexible filtering and pagination.

Base path: /api/trades

Get Trade History

GET /api/trades

Returns your trade history with optional filtering by date range, custom IDs, or trade IDs. Supports pagination.

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	ISO date string for start of range
end_date	string	No	ISO date string for end of range
trade_ids	string	No	Comma-separated list of trade IDs (UUIDs)
steam_trade_ids	string	No	Comma-separated list of Steam full trade IDs
steam_trade_offer_ids	string	No	Comma-separated list of Steam tradeoffer IDs
custom_ids	string	No	Comma-separated list of custom IDs
limit	number	No	Results per page. Default: 50, max: 2000
offset	number	No	Number of results to skip. Default: 0

cURL

curl -X GET "https://market.vpsbot.io/api/trades?limit=10&offset=0&start_date=2024-01-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

Node.js

const { data } = await client.get('/trades', {
  params: {
    limit: 10,
    offset: 0,
    start_date: '2024-01-01T00:00:00Z'
  }
});

Example Response

{
  "success": true,
  "data": {
    "trades": [
      {
        "trade_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "custom_id": "order-001",
        "summary": "Accepted",
        "processed_trade": {
          "market": "market-vpsbot",
          "trade_id": "4012345678_76561198012345678",
          "tradeoffer_id": "5234567890",
          "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "partner_id": "https://steamcommunity.com/tradeoffer/new/?partner=XXXXX&token=YYYYY",
          "items_to_give": [],
          "items_to_receive": [
            {
              "appid": 730,
              "contextid": "2",
              "assetid": "30000000001",
              "market_hash_name": "AK-47 | Redline (Field-Tested)",
              "amount": "1"
            }
          ],
          "status": 3,
          "game_id": 730,
          "settlement": "2026-01-22T10:05:00Z"
        },
        "selected_bot": {
          "steamid64": "76561198000000001",
          "avatar": "https://avatars.steamstatic.com/...",
          "profile_name": "VPSBot #5"
        },
        "status": "accepted",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:05:00Z",
        "error": null
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

---

Filtering Examples

By Date Range

GET /api/trades?start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z

By Custom IDs

GET /api/trades?custom_ids=order-001,order-002,order-003

By Trade IDs

GET /api/trades?trade_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901

By Steam Tradeoffer IDs

GET /api/trades?steam_trade_offer_ids=5234567890,5234567891

By Steam Full Trade IDs

GET /api/trades?steam_trade_ids=4012345678_76561198012345678

Pagination

# Page 1 (first 50 results)
GET /api/trades?limit=50&offset=0

# Page 2 (next 50 results)
GET /api/trades?limit=50&offset=50

---

Trade Object Schema (TradeData)

Field	Type	Description
trade_id	string	Internal trade identifier (UUID)
custom_id	string | null	Your custom reference ID
summary	string	Business-level status (see Trade Summary)
status	string	IMT status (see Trade Statuses)
created_at	string | null	ISO timestamp of trade creation
updated_at	string | null	ISO timestamp of last update
error	string | null	Error description if trade failed
processed_trade	object	Processed trade details (see below)
selected_bot	object	Bot that handled the trade
selected_bot.steamid64	string	Bot's Steam ID
selected_bot.avatar	string	Bot's avatar URL
selected_bot.profile_name	string	Bot's display name

ProcessedTrade Object

Field	Type	Description
market	string	Always "market-vpsbot"
trade_id	string	Steam full trade ID
tradeoffer_id	string	Steam trade offer ID
request_id	string	Market trade UUID (same as top-level trade_id)
partner_id	string	Steam trade offer URL
items_to_give	array	Items given (always empty for sell trades)
items_to_receive	array	Items received in the trade
status	number	Numeric Steam trade status
game_id	number	Game ID (730, 570, 252490, 440)
settlement	string | null	ISO timestamp of when Steam settles the trade (CS2 only)

Trade Item Schema (items_to_receive)

Field	Type	Description
appid	number	Game ID
contextid	string	Steam context ID (always "2")
assetid	string	Steam asset ID
market_hash_name	string	Item market hash name
amount	string	Always "1"

Trade Statuses

Status	Description
processing	Trade is being processed (initial status)
accepted	Trade accepted, funds frozen pending settlement (CS2 only)
completed	Trade completed successfully
declined	Trade declined (buyer-side failure)
cancelled	Trade cancelled (seller-side failure)
rolled_back_by_user	Trade rolled back by the user
rolled_back_by_bot	Trade rolled back by the bot

Game-Specific Flow

The trade flow depends on the game's balance strategy:

Game	Strategy	Flow
CS2 (730)	FREEZE_BALANCE	processing → accepted → completed (funds held in frozen balance until settlement)
Dota 2 (570)	BALANCE	processing → completed (funds credited directly)
TF2 (440)	BALANCE	processing → completed (funds credited directly)
Rust (252490)	BALANCE	processing → completed (funds credited directly)

For BALANCE games (Dota 2, TF2, Rust), items are irreversible once accepted — the trade skips accepted and goes directly to completed with funds credited to the seller's main balance.

Trade Summary

The summary field is a business-level status derived from the Steam trade status and rollback side.

Summary	Description
InProgress	Trade is active, awaiting confirmation, or in escrow
Accepted	Trade was accepted successfully
CanceledByBuyer	Trade was canceled by the buyer
DeclinedBySeller	Trade was declined by the seller
RolledBackByBuyer	Trade was rolled back by the buyer
RolledBackBySeller	Trade was rolled back by the seller
Failed	Trade failed (invalid, expired, missing items, etc.)

Error Field

When the trade status is declined or cancelled, the error field contains a free-form string describing the failure reason.