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": []} -
nullclears 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.sellis the normal sets the bot gives you for one TF2 key.sets.foil.prices.setsPerKey.tf2.sellis the same for foil sets, which have their own prices.sets.normal.prices.gemsPerSet.sellis the gems it asks for one set.sets.normal.prices.coinsPerSetprices a set in cryptocurrencies, as decimal strings.games.prices.keysPerGame.tf2.sellis the keys it asks for one game, andgames.priceByAppoverrides it for single games.gems.prices.gemsPerKey.tf2.sellis 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.
/v1/bot.pushAuthorizationBearer token · headerrequiredapplication/jsonclientBotPushRequestClientThe plugin or script sending the push. When it is missing, the User-Agent header names the client.
Show propertiesHide properties
namestringrequiredThe plugin or script, the same in every push it sends. Trimmed.
versionstringIts version, ideally semantic (2.4.1). Trimmed. The response says when it is below the minimum the directory supports for this client.
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 propertiesHide properties
BotPushRequestFeaturecommandsstring[] | nullThe 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.
featurestringrequiredbadgeAware: 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.
badgeAwarebuyAnybuyOnePerGamelevelQuotepickAppsstartedBadgesOnlysetSwapbuysCardsbuysBoostersbuysProfileItemswebOrderingsiteBalancegiftOrdersrestockAlertsgamesBotPushRequestGamesSteam games the bot sells or buys, as keys or gifts.
Show propertiesHide properties
priceByAppobjectPrices of single games, by app ID, which replace the flat price for those games. Replaces every stored override; {} clears them.
pricesBotPushRequestGamePricesOne flat price per game, whatever the game, by unit.
Show propertiesHide properties
gemsPerGameBotPushRequestRateGems per game. sell is the gems the bot asks for one game, buy is the gems it pays for one game.
Show propertiesHide 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.
sellnumber<double>The price when the bot sells to you, in the field's unit. 0 means it stopped selling.
keysPerGameBotPushRequestKeyRatesKeys or tickets per game. sell is the keys the bot asks for one game, buy is the keys it pays for one game.
Show propertiesHide properties
cs2BotPushRequestRateCS2 case keys.
hydraBotPushRequestRateCS Operation Hydra keys.
tf2BotPushRequestRateTeam Fortress 2 keys.
todBotPushRequestRateTour of Duty tickets.
stockobjectApp ID to copies in stock, keys and gifts counted together. Replaces the stored game stock; {} clears it.
gemsBotPushRequestGemsThe gem market: gems the bot holds and its gem prices.
Show propertiesHide properties
pricesBotPushRequestGemPricesGem prices, by unit.
Show propertiesHide properties
gemsPerKeyBotPushRequestKeyRatesGems 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.
isOnlinebooleanWhether the bot is accepting trades.
keysBotPushRequestKeysKeys and tickets the bot holds, which is what it can pay with when it buys.
Show propertiesHide properties
stockBotPushRequestKeyCountsKeys and tickets held, per currency. A currency you leave out keeps its count; 0 clears it.
Show propertiesHide properties
cs2integer<int32>CS2 case keys.
hydrainteger<int32>CS Operation Hydra keys.
tf2integer<int32>Team Fortress 2 keys.
todinteger<int32>Tour of Duty tickets.
paymentBotPushRequestPaymentThe Steam items the bot takes as each currency.
Show propertiesHide properties
cs2BotPushRequestPaymentItemsShow propertiesHide properties
itemsstring[] | nullrequiredSteam 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.
gemsBotPushRequestPaymentItemsShow propertiesHide properties
itemsstring[] | nullrequiredSteam 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.
hydraBotPushRequestPaymentItemsShow propertiesHide properties
itemsstring[] | nullrequiredSteam 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.
tf2BotPushRequestPaymentItemsShow propertiesHide properties
itemsstring[] | nullrequiredSteam 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.
todBotPushRequestPaymentItemsShow propertiesHide properties
itemsstring[] | nullrequiredSteam 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.
profileBotPushRequestProfileHow users reach the bot and who its stock is for.
Show propertiesHide properties
languagesobject | nullThe languages the bot answers in. null clears them.
Show propertiesHide properties
defaultstringThe language the bot uses until a user picks another. Must be in supported.
supportedstring[] | nullrequiredISO 639-1 codes, such as en or pt, at most 20. Case and repeats do not matter. An unknown code is a 400.
levelRangeobject | nullThe 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 propertiesHide properties
maxinteger<int32>requiredThe highest account level the bot is meant for. 0 means no upper limit.
mininteger<int32>requiredThe lowest account level the bot is meant for.
websitestringThe https page where users order from the bot. "" clears it. A bot without one shows its brand's website.
rulesobject | nullWhich users and trades the bot accepts. A rule you leave out keeps its stored value; null clears every rule.
Show propertiesHide properties
acceptsDonationsbooleanThe bot accepts trade offers where it only receives items.
acceptsLimitedAccountsbooleanThe bot accepts friend requests from limited Steam accounts, which never spent US$5 on Steam.
acceptsTradeBannedUsersbooleanThe bot accepts friend requests from users with a trade ban.
acceptsTradeHoldsbooleanThe bot trades with users whose trades Steam would put on hold.
acceptsVacBannedUsersbooleanThe bot accepts friend requests from users with a VAC ban.
setsBotPushRequestSetsCard sets: normal and foil stock and prices, and limits.
Show propertiesHide properties
foilBotPushRequestSetSideFoil sets, priced on their own.
Show propertiesHide properties
pricesBotPushRequestSetPricesSet prices, by unit.
Show propertiesHide properties
coinsPerSetBotPushRequestCoinRate[] | nullCoins per set, one entry per coin. A coin you leave out keeps its prices.
Show propertiesHide properties
BotPushRequestCoinRatebuystringCoins the bot pays for one set, as a decimal string. "0" stops buying for this coin.
coinstringrequiredTicker, such as btc, eth or ltc.
sellstringCoins the bot asks for one set, as a decimal string. "0" stops selling for this coin.
gemsPerSetBotPushRequestRateGems 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.
setsPerKeyBotPushRequestKeyRatesSets 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.
stockobjectApp ID to complete sets. Replaces the stored stock of this side: an app you leave out has none. {} clears it.
limitsBotPushRequestSetLimitsLimits on what the bot sells and holds.
Show propertiesHide properties
maxPerUserPerAppinteger<int32>Most sets of one app the bot sells to one user. 0 means no limit.
maxStockPerAppinteger<int32>Most sets of one app the bot holds when it buys. 0 means it does not say.
normalBotPushRequestSetSideNormal sets.
Show propertiesHide properties
pricesBotPushRequestSetPricesSet prices, by unit.
stockobjectApp ID to complete sets. Replaces the stored stock of this side: an app you leave out has none. {} clears it.
steamId64stringSteamID64 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.
OK
isClientOutdatedbooleanrequiredThe client's version is below the lowest the directory supports for this client. Update the plugin.
issuesBotPushResponseIssue[]requiredEverything in this push that was ignored or looks wrong, at most 100. None of it failed the push. Empty when all is well.
Show propertiesHide properties
BotPushResponseIssuecodestringrequiredWhat 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.
messagestringrequiredWhat is wrong and what to do about it, in English.
pathstringrequiredThe field the issue is about, as a path into the request body.
staleAtstring<date-time>requiredWhen the bot shows as stale if it pushes nothing more. Push again well before it.
storedBotPushResponseStoredrequiredWhat the directory now holds for the bot, after this push.
Show propertiesHide properties
gamesBotPushResponseStoredGamesrequiredShow propertiesHide properties
copiesinteger<int32>requiredCopies across all games.
titlesinteger<int32>requiredDistinct games in stock.
gemsinteger<int64>requiredGems the bot holds.
keysinteger<int64>requiredKeys and tickets the bot holds, every currency together.
setsBotPushResponseStoredSetsrequiredShow propertiesHide properties
appsinteger<int32>requiredDistinct apps with set stock.
foilinteger<int32>requiredComplete foil sets.
normalinteger<int32>requiredComplete normal sets.
Bad Request
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.
Unauthorized
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.
Forbidden
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.
Unprocessable Entity
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.
Too Many Requests
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.
Internal Server Error
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsErrorDetail[] | nullOptional list of individual error details
Show propertiesHide properties
ErrorDetaillocationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
messagestringError message text
valueanyThe value at the given location
instancestring<uri>A URI reference that identifies the specific occurrence of the problem.
statusinteger<int64>HTTP status code
titlestringA 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.