Auto-buying via API: key, limits, refunds

The public API covers the same things you do by hand: the catalogue, the stock, the balance and the orders. There is no separate subdomain such as api.boomly.ac — the base is relative, requests go to /api on the same domain. The documentation describing the endpoints lies on the site in the API section, and the playground works there too.

The playground is built as honestly as the format converter: the request goes straight from your browser, the key is not stored on the shop server. That lets you test a call before you start writing code.

The same API checks the stock before an order is placed. That is cheaper than placing a purchase and getting a failed delivery, even if support refunds the money manually afterwards: the time for a repeat order still comes out of the thirty-minute window.

It is more useful than it looks. The shape of the response is easier to see once with your own eyes than to reconstruct from the documentation: the parser is written for the real structure rather than for its description, and debugging starts from a working request instead of a guess.

The buyer issues the key and the secret in the account panel — there is no need to ask support for them. The secret is used only to sign a request, and the signature is not always required: it is needed only for those keys where it is switched on. This is a deliberate fork — a simple scenario can start without a signature, and for a production auto-purchase it can be switched on.

• The key is issued in the account panel and revoked in the same place.
• The secret is needed only for the signature; if the signature is not switched on for the key, it takes no part in the request.
• The playground on the site lets you send a request with the key without storing it on the server.

The key is the same kind of credential as the accounts themselves: it opens the balance and the orders. Keeping it in a shared repository is not worth it, and if it has leaked, issuing a new one in the panel and revoking the old one is simpler than dealing with the consequences.

The connection order therefore comes out step by step: first a request from the playground, then the same request from your own code without a signature, and only then the signature switched on for the production key. Every step is checked separately, and the place of an error is visible at once.

A position has two numbers in the catalogue response, and confusing them is expensive. The SKU is the public number of the product: the same one stands on the card on the site, it is quoted to support and a repeat purchase is made by it. The internal identifier is the service number of the record in the database.

The address of the card on the site is built from the SKU. If your script collects links to positions — to attach to a request or to keep for yourself — they have to be collected from the SKU. The internal number will lead to the same page, but already through a redirect, and it will stay as a needless link in your own database.

• The SKU is what you quote to support together with the order number.
• The SKU is permanent: restock alerts in the shop bot are subscribed by it.
• The internal number is useless in a conversation with support — it identifies a record, not a product.

The SKU is visible without the API as well: it stands on the position card and in the order, and it is exactly what support asks for. A purchase table assembled by SKUs reads the same way for a script and for the person who writes to the bot afterwards.

Hence the rule for monitoring: the key in your table has to be the SKU. The composition of the catalogue changes together with the stock — positions appear and leave — and the SKU stays the only stable way to refer to a particular product and compare yesterday's stock with today's.

There are two restrictions and they are counted independently: 120 requests per minute per endpoint and 60 requests per minute per key. The second limit is stricter than the first, and it is the one that sets the actual ceiling: however many different endpoints you poll, sixty requests per minute in total pass from one key.

Hence the practical consequence for anyone writing stock monitoring: polling the catalogue more often than once a second is pointless — you will hit the key limit before you get fresher data. It is more sensible to poll less often and to subscribe to restocks of the SKUs you need in the shop bot, where the notification arrives by itself.

• 120 requests per minute — per one address.
• 60 requests per minute — per one key, and this is the actual ceiling of the scenario.
• The limits are counted independently, so the smaller of the two is always the binding one.

Parallelising the problem will not work either: spreading requests across several endpoints runs into the same key limit. The ceiling is raised not by the number of threads but by the design of the polling — a rare full pass over the catalogue plus a pinpoint check of the SKUs you actually need.

One rule is worth knowing before you choose a channel: there are no automatic refunds anywhere, including API orders. If an order paid through the API from the balance is not fulfilled, contact support with the order number — we will check and refund you manually. The same applies on the site and in the bot, except that there the funds are simply not charged on a failure.

For a one-off purchase this is a detail. For a regular auto-purchase it is worth planning for in advance: a scenario where a script orders batches without a human has to notice a failed delivery itself and keep the order number — in no channel does the money come back without a request to support.

• There is no automatic refund for any payment, including payment from the balance via the API.
• The balance is charged immediately, so the delivery goes without waiting for a transfer to be confirmed.
• The balance is topped up by the same methods that pay for an order: USDT in seven networks, CryptoBot, Telegram Stars or roubles via SBP.

Here the channels do not differ: a failure is always handled by support manually — on a purchase via the API, on the site and in the bot alike. For a flow of orders this means a script working at night should keep the numbers of failed orders, so that in the morning there is something to write to support with.

Hand-over inside a script looks different from doing it by hand, but the rule is the same: right after the response, compare the number of delivered lines with the ordered volume, and the field composition with the contents mark of the position. The thirty minutes run the same way, whoever places the order.

A refund for a delivery that did not happen does not replace hand-over. It closes the case where the delivery did not happen at all, not the case where the position arrived and does not match its description. The second one is still settled inside the thirty-minute window and through support — with the order number and the SKU.