Rate Limiter¶

Most exchanges impose certain limits on the number of requests sent per unit of time. There can be different levels of aggregation.

The downside from reaching these limits can typically range from warning, to temporary ban or even outright ban.

The gateways allow you to configure rate-limiters to protect you from bad things happening, including being banned by the exchange.

There gateway config can include something like that

[rate_limits]

  [rate_limits.global]
    type = "ORDER_ACTION"
    aggregate = true
    request_limit = 100
    monitor_period = "10s"
    ban_period = "5m"

  [rate_limits.A1]
    type = "CREATE_ORDER"
    accounts = "A.*"
    request_limit = 30
    monitor_period = "1s"
    ban_period = "5m"

  [rate_limits.market_maker]
    type = "CREATE_ORDER"
    users = [ "trader" ]
    request_limit = 20
    monitor_period = "200ms"
    ban_period = "5m"
    high_water_mark = 15
    low_water_mark = 10

This briefly describes the purpose of each configuration

Name	Comments
`global`	Includes all order action (create, modify, cancel, …). Is managed at an aggregate level, i.e. for all accounts and all users. Allows up to 100 requests over a sliding window spanning 10 seconds. If the rate-limiter is triggered, all users will be banned for 5 minutes.
`A1`	Includes only order creation requests, i.e. not modify, cancel, … Is applied to each account matching the `A.*` regex pattern. Allows up to 30 requests over a sliding window spanning 1 second. If the rate-limiter is triggered, all users will be banned from trading the specific account for a period of 5 minutes.
`market_maker`	Includes only order creation requests, i.e. not modify, cancel, … Is applied to the user named `trader`. Allows up to 20 requests over a sliding window spanning 200 milliseconds. If the rate-limiter is triggered, the user will be banned from trading for a period of 5 minutes.

The key is to understand the following

The field named aggregate is used distinguish between “for all” (true) or “for each” (false).
The fields accounts and users can be single values or lists of regex patterns to match.

Clients will generally be able to track the status of each rate-limiter through the RateLimitTrigger events.

The RateLimitTrigger has two (sorted) members used to identify what is affected: users and accounts. The conventions are:

Both empty = every connected client
Either non-empty = those clients matching on name or account being traded

Furthermore, the OrderAck event may indicate reject with additional information through the Error::REQUEST_RATE_LIMIT_REACHED error code.

It is also possible to more pro-actively use the RateLimitTrigger by specifying the high_water_mark and low_water_mark fields.

These are the possible events

`buffer_capacity`	Comments
`HIGH_WATER_MARK`	The ban will be triggered if you instantly send `remaining_requests`. A likely reaction could be for a strategy to enter a cool-down mode.
`LOW_WATER_MARK`	The ban will be triggered if you instantly send `remaining_requests`. A likely recation could be for a strategy to resume normal operation by leaving the cool-down mode.
`FULL`	The ban has been triggered and no further requests will be allowed until after `ban_expires`. Sending any further requests, before the ban has been lifted, will simply extend the ban. The strategy should therefore refrain from sending any new requests during the ban period.