Bot API Documentation (v1)

Overview

This API allows verified bot owners to programmatically update their bot's information displayed on SteamTradeBots.com. By sending regular updates, you ensure users see your bot's current status, exchange rates, and stock levels accurately.

Authentication

All API requests must be authenticated using an **API Key** specific to each bot. You can find the unique API Key for each of your verified bots on your Bot Owner Dashboard (Click the icon).

Include the API key as a query parameter in the request URL:

?api_key=YOUR_BOT_API_KEY_HERE

For example, if the endpoint is https://steamtradebots.com/api/v1/bot/update.php, your request URL would look like:

https://steamtradebots.com/api/v1/bot/update.php?api_key=YOUR_BOT_API_KEY_HERE

Important: Keep your API Key confidential. While sending it in the URL is functional for this API version, be mindful of server logs and potential exposure if URLs are shared.

Rate Limiting

• Limit: 10 requests per bot per 5-minute window (subject to change).
• Recommendation: Update only when data changes. Check the Retry-After header in 429 Too Many Requests responses.

Update Bot Data

POST https://steamtradebots.com/api/v1/bot/update.php?api_key=YOUR_BOT_API_KEY_HERE

Description

Updates various data points for the bot associated with the provided API Key. Send only the fields you wish to update in the JSON request body.

Request Body (application/json)

A JSON object containing the fields you want to update.

{
  "status": "online",
  "buy_sets_csgo": 25,
  "sell_sets_csgo": 27,
  "buy_sets_hydra": 15,
  "sell_sets_hydra": 16,
  "buy_sets_tod": 1,
  "sell_sets_tod": 2,
  "stock_gems": 2550000,
  "stock_keys_hydra": 10,
  "stock_tickets_tod": 25,
  "stock_badge_appids": [730, 570],
  "last_update_timestamp": 1748771273
  // ... include other fields to update ...
}

Field Descriptions

Example Request (curl)

curl -X POST "https://steamtradebots.com/api/v1/bot/update.php?api_key=YOUR_BOT_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "status": "online",
  "buy_sets_hydra": 15,
  "sell_sets_hydra": 16,
  "stock_sets": 200,
  "stock_unique_sets": 15,
  "stock_badge_appids": [730, 440, 570],
  "stock_badges": { 
    "730": 100, 
    "440": 50, 
    "570": 50 
  },
  "last_update_timestamp": 1748771273
}'

Responses

• 200 OK Success:

  { "success": true, "message": "Bot data updated successfully." }

• 400 Bad Request Invalid Data:

  { "success": false, "message": "Invalid data provided. Please check the errors field for details.", "errors": { "buy_sets_hydra": "'buy_sets_hydra' must be a number..." } }

• 401 Unauthorized Invalid/Missing Key:

  { "success": false, "message": "Authentication failed. API key missing from URL." }

• 403 Forbidden Invalid Key/Bot Status:

  { "success": false, "message": "Authentication failed or bot is inactive/unverified." }

• 405 Method Not Allowed Incorrect HTTP Method:

  { "success": false, "message": "Invalid request method. Only POST (and OPTIONS for preflight) is allowed." }

• 429 Too Many Requests Rate Limit:

  { "success": false, "message": "Rate limit exceeded. Please try again later.", "errors": {"retry_after_seconds": 60} }

• 500 Internal Server Error Server Issue:

  { "success": false, "message": "An internal server error occurred. Please check server logs." }

Notes

• Requires a valid Bot API Key with update permissions.
• Only include fields you want to update in the JSON body.
• Rate values can be integers or decimals. Stock values should generally be non-negative integers.
• For rates_badges, the key should be the Badge ID (numeric string or integer). The value for rates is a "Buy/Sell" string (Gems per Badge).
• For stock_badges, the key should be the Game AppID. The value is the quantity of sets for that game.
• The stock_badge_appids field should be an array of numerical Steam AppIDs for which the bot has sets.
• The API automatically updates the bot's updated_at timestamp and potentially status_last_update on the site.
• A successful update may clear any "missing data" flags on the site for your bot.

Code Examples

Example implementations for sending updates.

PHP (using cURL)

<?php

$botApiKey = 'YOUR_BOT_API_KEY_HERE'; // Replace with your actual API key
// Construct the URL with the API key as a query parameter
$apiUrl = 'https://steamtradebots.com/api/v1/bot/update.php?api_key=' . urlencode($botApiKey);

$data = [
    'status' => 'online',
    'buy_sets_csgo' => 25,
    'sell_sets_csgo' => 27,
    'stock_sets' => 150,
    'stock_unique_sets' => 3,
    'stock_badge_appids' => [730, 440, 570],
    'stock_badges' => [ // Example for stock_badges
        "730" => 75, // 75 CS:GO sets
        "440" => 50, // 50 TF2 sets
        "570" => 25  // 25 Dota 2 sets
    ],
    'last_update_timestamp' => time()
];

$jsonData = json_encode($data);

$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); // Or CURLOPT_POST, true
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
    // No Authorization header needed if API key is in URL
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch); 

curl_close($ch);

if ($curlError) { 
    echo "cURL Error: " . $curlError;
} else {
    echo "HTTP Status Code: " . $httpCode . "\n";
    echo "Response Body: " . $response . "\n";
    $responseData = json_decode($response, true);
    if ($responseData && isset($responseData['success'])) {
        if ($responseData['success']) {
            echo "Update successful: " . $responseData['message'] . "\n";
        } else {
            echo "Update failed: " . $responseData['message'] . "\n";
            if (isset($responseData['errors'])) {
                print_r($responseData['errors']);
            }
        }
    }
}
?>

Python (using `requests`)

import requests
import json
import time

bot_api_key = 'YOUR_BOT_API_KEY_HERE'
# Construct the URL with the API key as a query parameter
api_url_base = 'https://steamtradebots.com/api/v1/bot/update.php'
api_url = f"{api_url_base}?api_key={bot_api_key}"

data = {
    'status': 'online',
    'buy_sets_csgo': 25,
    'sell_sets_csgo': 27,
    'stock_sets': 150,
    'stock_unique_sets': 3,
    'stock_badge_appids': [730, 440, 570],
    'stock_badges': { # Example for stock_badges
        "730": 75, # 75 CS:GO sets
        "440": 50, # 50 TF2 sets
        "570": 25  # 25 Dota 2 sets
    },
    'last_update_timestamp': int(time.time())
}

# Headers no longer need Authorization if key is in URL
headers = {
    'Content-Type': 'application/json'
}

try:
    response = requests.post(api_url, headers=headers, json=data, timeout=10)
    print(f"HTTP Status Code: {response.status_code}")
    print(f"Raw Response Body: {response.text}") 

    response.raise_for_status() 
    
    response_data = response.json()
    print(f"Parsed Response Body: {response_data}")
    if response_data.get('success'):
        print(f"Update successful: {response_data.get('message')}")
    else:
        print(f"Update failed: {response_data.get('message')}")
        if response_data.get('errors'):
            print(f"Errors: {response_data.get('errors')}")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")  
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}") 
except json.JSONDecodeError:
    print(f"Failed to decode JSON response. Raw response was: {response.text}")