Skip to content
SteamSets
Esc
↑↓navigate↵open⌘Jpreview

Push a bot's status, prices, stock and features

Reports a bot’s status, profile, rules, prices, stock and features, and answers what is now stored, what in the push was ignored or looks wrong, and when the bot goes stale.

Pushing is free: it uses no daily units. Authenticate with a bot key, or with your account key and steamId64. Push at least every 30 minutes: a bot silent for 45 minutes shows as stale, and after a day it is hidden.

Patch rules

Every field is optional.

  • A field you leave out keeps its stored value, down to each price side, count and rule. This changes the TF2 sell price of normal sets and nothing else:

    {"sets": {"normal": {"prices": {"setsPerKey": {"tf2": {"sell": 12}}}}}}
  • 0 removes a price side or a count. This stops buying normal sets for TF2 keys:

    {"sets": {"normal": {"prices": {"setsPerKey": {"tf2": {"buy": 0}}}}}}
  • A stock you send replaces the stored stock of that side. This leaves the bot with 3 normal sets of app 440 and keeps its foil stock:

    {"sets": {"normal": {"stock": {"440": 3}}}}
  • {} clears a stock or a map, and [] clears a list. This empties the game stock, drops every per-game price and clears the chat commands:

    {"games": {"stock": {}, "priceByApp": {}}, "commands": []}
  • null clears an object. This clears the languages, the level range and every rule:

    {"profile": {"languages": null, "levelRange": null}, "rules": null}

Prices

Every price is named after its unit, and sell and buy are from the bot’s side.

  • sets.normal.prices.setsPerKey.tf2.sell is the normal sets the bot gives you for one TF2 key.
  • sets.foil.prices.setsPerKey.tf2.sell is the same for foil sets, which have their own prices.
  • sets.normal.prices.gemsPerSet.sell is the gems it asks for one set.
  • sets.normal.prices.coinsPerSet prices a set in cryptocurrencies, as decimal strings.
  • games.prices.keysPerGame.tf2.sell is the keys it asks for one game, and games.priceByApp overrides it for single games.
  • gems.prices.gemsPerKey.tf2.sell is the gems the bot gives you for one TF2 key.

A bot buys what it quotes a buy price for. There is no separate field that says a bot takes supply, and no bot type to send: the directory reads what a bot does from its stock and prices.

{
  "sets": {
    "normal": {"stock": {"440": 3}, "prices": {"setsPerKey": {"tf2": {"sell": 12, "buy": 14}}}},
    "foil": {"stock": {"730": 1}, "prices": {"setsPerKey": {"tf2": {"sell": 0.5}}}},
    "limits": {"maxPerUserPerApp": 5, "maxStockPerApp": 10}
  },
  "games": {"stock": {"730": 2}, "priceByApp": {"730": {"keysPerGame": {"tf2": {"sell": 4}}}}}
}

Sale and event sets need nothing special: send them as app IDs in the normal stock.

Profile and rules

profile says how users reach the bot: its website, the ISO 639-1 languages it answers in (default must be in supported), and the account levels its stock is meant for. rules says which users and trades it accepts. The calculator leaves out a bot whose rules turn the signed-in user away for a VAC or trade ban.

{
  "profile": {
    "website": "https://example.com/order",
    "languages": {"supported": ["en", "pt"], "default": "en"},
    "levelRange": {"min": 1, "max": 200}
  },
  "rules": {"acceptsTradeHolds": false, "acceptsVacBannedUsers": true}
}

Payment, commands and features

payment lists the Steam items, by market hash name, that count as each currency. Items for a currency the bot quotes no price in are kept and reported as paymentWithoutPrice. commands is every chat command the bot answers. Each feature can name the commands that use it; neither list is checked against the other.

{
  "payment": {"tf2": {"items": ["Mann Co. Supply Crate Key"]}, "gems": {"items": ["Sack of Gems", "Gems"]}},
  "commands": ["!help", "!prices", "!buytf", "!check"],
  "features": [{"feature": "badgeAware", "commands": ["!check", "!buytf"]}]
}

Client

A push without client is named by its User-Agent (name/version). Send client so staff can tell your plugin’s versions apart.

POST/v1/bot.push
Authorization
AuthorizationBearer token · headerrequired
Request body
requiredapplication/json
clientBotPushRequestClient

The plugin or script sending the push. When it is missing, the User-Agent header names the client.

Show properties
namestringrequired

The plugin or script, the same in every push it sends. Trimmed.

max length 64
versionstring

Its version, ideally semantic (2.4.1). Trimmed. The response says when it is below the minimum the directory supports for this client.

max length 32
commandsstring[]

Every chat command the bot answers, as free text, at most 50 of up to 32 characters. Replaces the stored list; [] clears it.

featuresBotPushRequestFeature[]

Everything the bot does that its prices and stock cannot show. Replaces the stored list; [] clears it. Currencies, buying, foil, gems, games, event sets, languages and limits are not features: the directory reads them from the rest of the push.

Show properties
Array of BotPushRequestFeature
commandsstring[] | null

The chat commands that use the feature, as free text, at most 5 of up to 32 characters. Leave it out when the feature has none.

featurestringrequired

badgeAware: the default buy never sends a set for a badge you have already maxed or cannot craft further (judged by your badges, not your inventory). buyAny: you can buy sets whatever your badges, including ones you have already crafted. buyOnePerGame: you can ask for at most one set per game. levelQuote: given a target level, the bot or site tells you how many sets that takes and what it costs. pickApps: you can choose which apps' sets you get. startedBadgesOnly: you can limit an order to badges you have already started. setSwap: the bot swaps your duplicate sets or cards for ones you can craft, with no currency involved. buysCards: the bot buys loose cards, not only complete sets. buysBoosters: the bot buys booster packs. buysProfileItems: the bot buys backgrounds or emoticons. webOrdering: you can order on a website instead of in Steam chat. siteBalance: you can hold a prepaid balance with the service, and failed trades are refunded to it. giftOrders: you can pay for sets delivered to another Steam account. restockAlerts: the bot messages you when new stock arrives, if you opt in.

Allowed:badgeAwarebuyAnybuyOnePerGamelevelQuotepickAppsstartedBadgesOnlysetSwapbuysCardsbuysBoostersbuysProfileItemswebOrderingsiteBalancegiftOrdersrestockAlerts
gamesBotPushRequestGames

Steam games the bot sells or buys, as keys or gifts.

Show properties
priceByAppobject

Prices of single games, by app ID, which replace the flat price for those games. Replaces every stored override; {} clears them.

pricesBotPushRequestGamePrices

One flat price per game, whatever the game, by unit.

Show properties
gemsPerGameBotPushRequestRate

Gems per game. sell is the gems the bot asks for one game, buy is the gems it pays for one game.

Show properties
buynumber<double>

The price when the bot buys from you, in the field's unit. 0 means it stopped buying. Sending a buy price is how a bot says it buys.

min 0
sellnumber<double>

The price when the bot sells to you, in the field's unit. 0 means it stopped selling.

min 0
keysPerGameBotPushRequestKeyRates

Keys or tickets per game. sell is the keys the bot asks for one game, buy is the keys it pays for one game.

Show properties
cs2BotPushRequestRate

CS2 case keys.

hydraBotPushRequestRate

CS Operation Hydra keys.

tf2BotPushRequestRate

Team Fortress 2 keys.

todBotPushRequestRate

Tour of Duty tickets.

stockobject

App ID to copies in stock, keys and gifts counted together. Replaces the stored game stock; {} clears it.

gemsBotPushRequestGems

The gem market: gems the bot holds and its gem prices.

Show properties
pricesBotPushRequestGemPrices

Gem prices, by unit.

Show properties
gemsPerKeyBotPushRequestKeyRates

Gems per key or ticket. sell is the gems the bot gives you for one key, buy is the gems it takes from you for one key, so a bot that makes money has sell below buy.

stockinteger<int64>

Gems the bot holds. 0 clears it.

min 0
isOnlineboolean

Whether the bot is accepting trades.

keysBotPushRequestKeys

Keys and tickets the bot holds, which is what it can pay with when it buys.

Show properties
stockBotPushRequestKeyCounts

Keys and tickets held, per currency. A currency you leave out keeps its count; 0 clears it.

Show properties
cs2integer<int32>

CS2 case keys.

min 0
hydrainteger<int32>

CS Operation Hydra keys.

min 0
tf2integer<int32>

Team Fortress 2 keys.

min 0
todinteger<int32>

Tour of Duty tickets.

min 0
paymentBotPushRequestPayment

The Steam items the bot takes as each currency.

Show properties
cs2BotPushRequestPaymentItems
Show properties
itemsstring[] | nullrequired

Steam market hash names that count as this currency, at most 20 of up to 128 characters. Replaces the stored list for this currency; [] clears it.

gemsBotPushRequestPaymentItems
Show properties
itemsstring[] | nullrequired

Steam market hash names that count as this currency, at most 20 of up to 128 characters. Replaces the stored list for this currency; [] clears it.

hydraBotPushRequestPaymentItems
Show properties
itemsstring[] | nullrequired

Steam market hash names that count as this currency, at most 20 of up to 128 characters. Replaces the stored list for this currency; [] clears it.

tf2BotPushRequestPaymentItems
Show properties
itemsstring[] | nullrequired

Steam market hash names that count as this currency, at most 20 of up to 128 characters. Replaces the stored list for this currency; [] clears it.

todBotPushRequestPaymentItems
Show properties
itemsstring[] | nullrequired

Steam market hash names that count as this currency, at most 20 of up to 128 characters. Replaces the stored list for this currency; [] clears it.

profileBotPushRequestProfile

How users reach the bot and who its stock is for.

Show properties
languagesobject | null

The languages the bot answers in. null clears them.

Show properties
defaultstring

The language the bot uses until a user picks another. Must be in supported.

supportedstring[] | nullrequired

ISO 639-1 codes, such as en or pt, at most 20. Case and repeats do not matter. An unknown code is a 400.

levelRangeobject | null

The account levels this bot's stock is meant for, as brands split rarer sets across bots by level tier. null clears it. A range whose min is above its max is ignored and reported as an issue.

Show properties
maxinteger<int32>required

The highest account level the bot is meant for. 0 means no upper limit.

min 0
mininteger<int32>required

The lowest account level the bot is meant for.

min 0
websitestring

The https page where users order from the bot. "" clears it. A bot without one shows its brand's website.

max length 255
rulesobject | null

Which users and trades the bot accepts. A rule you leave out keeps its stored value; null clears every rule.

Show properties
acceptsDonationsboolean

The bot accepts trade offers where it only receives items.

acceptsLimitedAccountsboolean

The bot accepts friend requests from limited Steam accounts, which never spent US$5 on Steam.

acceptsTradeBannedUsersboolean

The bot accepts friend requests from users with a trade ban.

acceptsTradeHoldsboolean

The bot trades with users whose trades Steam would put on hold.

acceptsVacBannedUsersboolean

The bot accepts friend requests from users with a VAC ban.

setsBotPushRequestSets

Card sets: normal and foil stock and prices, and limits.

Show properties
foilBotPushRequestSetSide

Foil sets, priced on their own.

Show properties
pricesBotPushRequestSetPrices

Set prices, by unit.

Show properties
coinsPerSetBotPushRequestCoinRate[] | null

Coins per set, one entry per coin. A coin you leave out keeps its prices.

Show properties
Array of BotPushRequestCoinRate
buystring

Coins the bot pays for one set, as a decimal string. "0" stops buying for this coin.

coinstringrequired

Ticker, such as btc, eth or ltc.

sellstring

Coins the bot asks for one set, as a decimal string. "0" stops selling for this coin.

gemsPerSetBotPushRequestRate

Gems per set. sell is the gems the bot asks for one set, buy is the gems it pays for one set, so a bot that makes money has sell above buy.

setsPerKeyBotPushRequestKeyRates

Sets per key or ticket. sell is the sets the bot gives you for one key, buy is the sets it takes from you for one key, so a bot that makes money has sell below buy.

stockobject

App ID to complete sets. Replaces the stored stock of this side: an app you leave out has none. {} clears it.

limitsBotPushRequestSetLimits

Limits on what the bot sells and holds.

Show properties
maxPerUserPerAppinteger<int32>

Most sets of one app the bot sells to one user. 0 means no limit.

min 0
maxStockPerAppinteger<int32>

Most sets of one app the bot holds when it buys. 0 means it does not say.

min 0
normalBotPushRequestSetSide

Normal sets.

Show properties
pricesBotPushRequestSetPrices

Set prices, by unit.

stockobject

App ID to complete sets. Replaces the stored stock of this side: an app you leave out has none. {} clears it.

steamId64string

SteamID64 of the bot this push is for. Required with your account key, which pushes for every bot you own. Optional with a bot key, and then it must be that bot's.

Responses
200

OK

isClientOutdatedbooleanrequired

The client's version is below the lowest the directory supports for this client. Update the plugin.

issuesBotPushResponseIssue[]required

Everything in this push that was ignored or looks wrong, at most 100. None of it failed the push. Empty when all is well.

Show properties
Array of BotPushResponseIssue
codestringrequired

What kind of issue it is: unknownApp, foilWithoutBadge, rateSidesSwapped, rateInverted, levelRangeInvalid, paymentWithoutPrice, fieldIgnored or clientMissing. New codes can appear, so treat an unknown one as a warning.

messagestringrequired

What is wrong and what to do about it, in English.

pathstringrequired

The field the issue is about, as a path into the request body.

staleAtstring<date-time>required

When the bot shows as stale if it pushes nothing more. Push again well before it.

storedBotPushResponseStoredrequired

What the directory now holds for the bot, after this push.

Show properties
gamesBotPushResponseStoredGamesrequired
Show properties
copiesinteger<int32>required

Copies across all games.

min 0
titlesinteger<int32>required

Distinct games in stock.

min 0
gemsinteger<int64>required

Gems the bot holds.

min 0
keysinteger<int64>required

Keys and tickets the bot holds, every currency together.

min 0
setsBotPushResponseStoredSetsrequired
Show properties
appsinteger<int32>required

Distinct apps with set stock.

min 0
foilinteger<int32>required

Complete foil sets.

min 0
normalinteger<int32>required

Complete normal sets.

min 0
400

Bad Request

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
401

Unauthorized

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
403

Forbidden

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
422

Unprocessable Entity

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
429

Too Many Requests

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
500

Internal Server Error

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties
Array of ErrorDetail
locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.steamsets.com/v1/bot.push' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client": {
    "name": "Steam-levelup-BOT",
    "version": "2.4.1"
  },
  "commands": [
    "!help",
    "!prices",
    "!buytf",
    "!check"
  ],
  "features": [
    {
      "commands": [
        "!check",
        "!buytf"
      ],
      "feature": "badgeAware"
    }
  ],
  "games": {
    "prices": {
      "keysPerGame": {
        "tf2": {
          "sell": 1.5
        }
      }
    },
    "stock": {
      "730": 2
    }
  },
  "gems": {
    "prices": {
      "gemsPerKey": {
        "tf2": {
          "buy": 3600,
          "sell": 3400
        }
      }
    },
    "stock": 100000
  },
  "isOnline": true,
  "keys": {
    "stock": {
      "tf2": 10,
      "tod": 0
    }
  },
  "payment": {
    "tf2": {
      "items": [
        "Mann Co. Supply Crate Key"
      ]
    }
  },
  "profile": {
    "languages": {
      "default": "en",
      "supported": [
        "en",
        "pt"
      ]
    },
    "levelRange": {
      "max": 200,
      "min": 1
    },
    "website": "https://example.com/order"
  },
  "rules": {
    "acceptsTradeHolds": false,
    "acceptsVacBannedUsers": true
  },
  "sets": {
    "limits": {
      "maxPerUserPerApp": 5
    },
    "normal": {
      "prices": {
        "setsPerKey": {
          "tf2": {
            "buy": 14,
            "sell": 12
          }
        }
      },
      "stock": {
        "440": 3
      }
    }
  },
  "steamId64": "76561199756787903"
}'
Response
{
  "isClientOutdated": true,
  "issues": [
    {
      "code": "foilWithoutBadge",
      "message": "string",
      "path": "sets.foil.stock.440"
    }
  ],
  "staleAt": "2019-08-24T14:15:22Z",
  "stored": {
    "games": {
      "copies": 0,
      "titles": 0
    },
    "gems": 0,
    "keys": 0,
    "sets": {
      "apps": 0,
      "foil": 0,
      "normal": 0
    }
  }
}