Market VPSBot API Documentation

Welcome to the official documentation for the Market VPSBot API. This API allows you to programmatically browse items, execute purchases, track trades, and manage your wallet on market.vpsbot.io.

Base URL

All API requests use the base URL:

https://market.vpsbot.io/api

Getting Started

Before using the API, you'll need to:

1. Get your API key for authentication
2. Understand the available endpoints and their parameters
3. Implement the API using the provided code examples

API Overview

Items API

Browse and purchase items on the marketplace:

• List all items for sale with optional game filtering
• Search items by market hash name or market ID
• Buy items directly by asset ID or by name
• Check item availability before purchasing
• View recently sold items

Trades API

Track your trade history:

• Filter trades by date range, custom IDs, or trade IDs
• Paginate through large result sets
• Monitor trade statuses and errors

Wallet API

Manage your project wallet:

• Check current available balance
• View frozen (held) balance

Deprecated API Backward Compatibility

For users migrating from the deprecated API, we provide a fully backward-compatible API layer:

• Items (Deprecated API) — Same request/response format as the deprecated API
• Trades (Deprecated API) — Trade history in deprecated API format
• Wallet (Deprecated API) — Balance in deprecated API format

Response Format

Every native API response uses the same envelope:

Field	Type	Present	Description
success	boolean	Always	true when the request did what you asked, false otherwise
code	string	When success is false	Machine-readable error code. Branch on this field
error	string	When success is false	Human-readable description, for display and logs. Do not parse it
data	object | array	On success when the endpoint returns a result, and on a validation error	The result of the call (its shape is documented per endpoint). On a validation error — the list of invalid fields

A successful response has no code:

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

Other formats

The Deprecated API Backward Compatibility layer keeps the deprecated API format. Everything below applies to the rest of the API.

Business Refusal — HTTP 200

The request is valid, but it cannot be carried out: the item is already sold, the price changed, the balance is too low, and so on. The action does not go through, and your balance is left as it was. The response is HTTP 200 with success: false, a machine-readable code and a human-readable error:

{
  "success": false,
  "code": "price_changed",
  "error": "Price mismatch: listing price does not match the offered price"
}

Each endpoint lists its business codes: purchases, hold purchases, hold cancel and withdraw, purchase cancel, sell trades. The one exception is purchase cancel: its refusals keep their documented HTTP statuses (404 / 409).

Validation Error — HTTP 400

The request body or query is invalid: a field is missing or has a wrong type or value, or none of the alternative fields was sent. The response is HTTP 400 with code: "validation_failed", and data lists the invalid fields. A body that is not a JSON object answers invalid_payload instead, see Common Codes:

{
  "success": false,
  "code": "validation_failed",
  "error": "Validation error",
  "data": [
    {
      "field": "trade_url",
      "code": "required",
      "message": "must have required property 'trade_url'"
    }
  ]
}

Field	Type	Description
data[].field	string	Path to the invalid field: trade_url, a nested a.b, an array element items[0].price
data[].code	string	What is wrong with the field (see below)
data[].message	string	Human-readable explanation

Field code	Meaning
required	The field is missing
required_without_all	None of several alternative fields was sent; every alternative is listed
required_without	Neither of two alternative fields was sent; both are listed
type	The value has the wrong type
oneof	The value is not one of the allowed values
min / max	The number, string length or array size is below the minimum / above the maximum
gt	The number must be greater than the limit
pattern	The string does not match the expected pattern
uuid, date-time, uri, …	The string is not in the named format

New field codes may be added; treat an unfamiliar one as an invalid value.

System Failure — HTTP 500

The server could not process the request:

{
  "success": false,
  "code": "internal_error",
  "error": "Internal server error"
}

Retry later. If the failure persists, contact support.

Common Codes

These error codes can come from any endpoint. Business codes are listed on each endpoint's page.

code	HTTP	Meaning
validation_failed	400	The request is invalid; data lists the invalid fields
invalid_payload	400	The body of an endpoint that takes one is missing or is not a JSON object: it is empty, malformed JSON, an array, a string, a number or null. The same code answers a body sent with an unsupported Content-Type and a body that is too large. No data
unauthorized	401	The API key is missing or invalid. For API key management: the session is missing or has expired. See Access Control
forbidden	403	The call is not allowed with these credentials: the account does not have the project role, or an API key was used to create or delete API keys. See Access Control
not_found	404	The resource or the URL does not exist. An unsupported HTTP method on an existing path answers the same way
conflict	409	The request conflicts with the current state of the resource
rate_limited	429	Too many requests, see Rate Limits
internal_error	5xx	The server failed to process the request

Handling Responses

Check success, then branch on code

1. Check success first. A successful response has no code.
2. When it is false, branch on code — not on the error text, and not on the HTTP status alone: a business refusal answers HTTP 200.
3. Treat an unknown code as a generic failure: new codes may be added.

With axios's default settings, HTTP 4xx / 5xx responses throw (the envelope is in err.response.data), while a business refusal resolves like a success. Check success on every response:

const { data } = await client.post('/items/buy', {
  asset_id: '30000000001',
  game_id: 730,
  trade_url: 'https://steamcommunity.com/tradeoffer/new/?partner=XXXXX&token=YYYYY',
  price: 1245,
  custom_id: 'order-001'
});

if (!data.success) {
  switch (data.code) {
    case 'price_changed':
      // refresh the price and retry
      break;
    case 'insufficient_balance':
      // top up the balance
      break;
    default:
      throw new Error(`Purchase refused: ${data.code} (${data.error})`);
  }
}

Rate Limits

Some endpoints are rate-limited per user. When rate-limited, responses include headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Remaining requests in current window

Exceeding the rate limit returns HTTP 429 Too Many Requests.

Support

If you encounter any issues or have questions, contact our support team via Telegram.