API Rate Limiting Control
Exchanges limit how often their API may be called. Going over the limit gets requests rejected at best and the account temporarily banned at worst. With exchange.IO("rate", ...) or exchange.IO("quota", ...) you can cap the call frequency of standard functions locally on the docker: a call that exceeds the limit is never sent.
javascript
exchange.IO("rate" | "quota", name, count, window[, "delay"])
Two modes
- rate (token bucket): the bucket capacity defaults to
count. It starts full and refills at a steady "count per window"; each call takes one token. Short bursts are allowed, while the long-run average never exceeds "count per window". Writingcountas"10/5"means 10 refills per window with a bucket capacity of 5, which limits bursts. - quota (fixed window): at most
countcalls per window; the counter resets when the next window starts. Windows are aligned to the Unix epoch:1sto whole seconds,1mto whole minutes,1hto whole hours,1dto UTC midnight (08:00 Beijing time). For example, counting that starts at 12:00:00.900 is already in a new window at 12:00:01.000.
Use quota with a window matching the exchange's counting period when you must guarantee "no more than N calls in any of the exchange's periods"; use rate when you only need to control the average frequency.
Parameters
For the parameter syntax (several function names separated by commas, the * fallback rule, "count/burst" in rate mode, window durations and daily resets with @HHMM, the delay action, deleting rules) see exchange.IO("rate", ...) in the exchange.IO category of the syntax manual.
Function names that can be limited
| Category | Names |
|---|---|
| Market data | GetTicker, GetTickers, GetDepth, GetTrades, GetRecords, GetMarkets, GetFundings |
| Account | GetAccount, GetAssets, GetPositions, SetMarginLevel |
| Trading | CreateOrder (Buy and Sell count here too), CancelOrder, ModifyOrder |
| Order queries | GetOrder, GetOrders, GetHistoryOrders |
| Conditional orders | CreateConditionOrder, ModifyConditionOrder, CancelConditionOrder |
| Conditional order queries | GetConditionOrder, GetConditionOrders, GetHistoryConditionOrders |
| Custom requests | IO/api: limits only exchange.IO("api", ...), other exchange.IO() commands are unaffected |
GetAccountandGetAssetsare the same underlying request; a rule under either name applies to both functions.- Calls made concurrently through
exchange.Go()are counted under the function actually called.
Scope of rules
- Rules are set per exchange object: a rule on
exchanges[0]does not affectexchanges[1]. - Rules last for the current run only. Set them again after the live trading restarts, usually at the beginning of
main(). - Setting the same name again replaces its rule; an empty name (
exchange.IO("rate", "")) clears all rules of that exchange object. - Each call is counted under one rule only: a function with its own rule is no longer counted under
*, so*cannot be used as a "total quota for all calls" stacked on top of specific rules.
When the limit is exceeded
With the default action, a call over the limit sends no request and is treated as a failed call (JavaScript returns null, Python returns None, Rust returns Err). The error message looks like:
text
rate limit exceeded: GetTicker 10/1s
quota limit exceeded: GetTicker 10/1m
quota limit exceeded: GetRecords 2000/day (resets at 0800)
With the delay action the call blocks until a call is available, so the time recorded in the log is the time after the wait. With a rule that resets daily, delay may wait until the next day; use it with care.
Examples
-
Default action: calls over the limit fail.
javascriptfunction main() { // GetTicker at most 5 calls per second on average (token bucket, capacity 5) exchange.IO("rate", "GetTicker", 5, "1s") for (var i = 0; i < 10; i++) { var ticker = exchange.GetTicker("BTC_USDT") if (ticker) { Log("call", i + 1, "succeeded:", ticker.Last) } else { // a call over the limit sends no request and returns null Log("call", i + 1, "rate limited:", GetLastError()) } } }pythondef main(): # GetTicker at most 5 calls per second on average (token bucket, capacity 5) exchange.IO("rate", "GetTicker", 5, "1s") for i in range(10): ticker = exchange.GetTicker("BTC_USDT") if ticker: Log("call", i + 1, "succeeded:", ticker["Last"]) else: # a call over the limit sends no request and returns None Log("call", i + 1, "rate limited:", GetLastError())rustfn main() { // GetTicker at most 5 calls per second on average (token bucket, capacity 5) let _ = exchange.IO(("rate", "GetTicker", 5, "1s")); for i in 0..10 { match exchange.GetTicker("BTC_USDT") { Ok(ticker) => Log!("call", i + 1, "succeeded:", ticker.Last), // a call over the limit sends no request and returns Err Err(e) => Log!("call", i + 1, "rate limited:", e), } } } -
Rules grouped after the exchange's own limits: market data and trading each share one rule, trading calls wait instead of failing, and every other function falls back to
*.javascriptfunction main() { // market data: GetTicker and GetDepth together 20 calls/s on average exchange.IO("rate", "GetTicker,GetDepth", 20, "1s") // trading: orders (incl. Buy/Sell) and cancels together 5/s; wait when over exchange.IO("rate", "CreateOrder,CancelOrder", 5, "1s", "delay") // fallback: other functions (GetAccount, GetPositions...) 60/min, aligned to minutes exchange.IO("quota", "*", 60, "1m") while (true) { var ticker = exchange.GetTicker("BTC_USDT") var depth = exchange.GetDepth("BTC_USDT") if (ticker && depth) { Log("last:", ticker.Last, "best bid:", depth.Bids[0].Price) } Sleep(1000) } }pythondef main(): # market data: GetTicker and GetDepth together 20 calls/s on average exchange.IO("rate", "GetTicker,GetDepth", 20, "1s") # trading: orders (incl. Buy/Sell) and cancels together 5/s; wait when over exchange.IO("rate", "CreateOrder,CancelOrder", 5, "1s", "delay") # fallback: other functions (GetAccount, GetPositions...) 60/min, aligned to minutes exchange.IO("quota", "*", 60, "1m") while True: ticker = exchange.GetTicker("BTC_USDT") depth = exchange.GetDepth("BTC_USDT") if ticker and depth: Log("last:", ticker["Last"], "best bid:", depth["Bids"][0]["Price"]) Sleep(1000)rustfn main() { // market data: GetTicker and GetDepth together 20 calls/s on average let _ = exchange.IO(("rate", "GetTicker,GetDepth", 20, "1s")); // trading: orders (incl. Buy/Sell) and cancels together 5/s; wait when over let _ = exchange.IO(("rate", "CreateOrder,CancelOrder", 5, "1s", "delay")); // fallback: other functions (GetAccount, GetPositions...) 60/min, aligned to minutes let _ = exchange.IO(("quota", "*", 60, "1m")); loop { let (t, d) = (exchange.GetTicker("BTC_USDT"), exchange.GetDepth("BTC_USDT")); if let (Ok(ticker), Ok(depth)) = (t, d) { Log!("last:", ticker.Last, "best bid:", depth.Bids[0].Price); } Sleep(1000); } } -
Burst capacity, daily quota, and deleting rules.
javascriptfunction main() { // 10 calls per second on average, but at most 2 in a burst exchange.IO("rate", "GetDepth", "10/2", "1s") // resets every day at 08:00 Beijing time, at most 2000 calls per day exchange.IO("quota", "GetRecords", 2000, "@0800") // units can be combined: at most 100 calls every 1 hour 30 minutes exchange.IO("rate", "GetOrders", 100, "1h30m") // count 0: delete the rule for GetOrders exchange.IO("rate", "GetOrders", 0) // empty name: clear all rules of this exchange object exchange.IO("rate", "") }pythondef main(): # 10 calls per second on average, but at most 2 in a burst exchange.IO("rate", "GetDepth", "10/2", "1s") # resets every day at 08:00 Beijing time, at most 2000 calls per day exchange.IO("quota", "GetRecords", 2000, "@0800") # units can be combined: at most 100 calls every 1 hour 30 minutes exchange.IO("rate", "GetOrders", 100, "1h30m") # count 0: delete the rule for GetOrders exchange.IO("rate", "GetOrders", 0) # empty name: clear all rules of this exchange object exchange.IO("rate", "")rustfn main() { // 10 calls per second on average, but at most 2 in a burst let _ = exchange.IO(("rate", "GetDepth", "10/2", "1s")); // resets every day at 08:00 Beijing time, at most 2000 calls per day let _ = exchange.IO(("quota", "GetRecords", 2000, "@0800")); // units can be combined: at most 100 calls every 1 hour 30 minutes let _ = exchange.IO(("rate", "GetOrders", 100, "1h30m")); // count 0: delete the rule for GetOrders let _ = exchange.IO(("rate", "GetOrders", 0)); // empty name: clear all rules of this exchange object let _ = exchange.IO(("rate", "")); }
See Also