Using the BitMEX REST API

For working code and examples, please see our HTTP Connectors on GitHub.

If you are logged in, you may access the API Key Management interface.

For a list of endpoints and return types, view the REST documentation in the API Explorer.

Specification and Clients

The BitMEX API conforms to the Swagger spec for REST endpoints. Any Swagger-compatible client can connect to the BitMEX API and execute commands.

An updated list of available clients is listed here.

Examples of basic communication to our API are in our api-connectors repository.

Note that all Bitcoin quantities are returned in Satoshis: 1 XBt (Satoshi) = 0.00000001 XBT (Bitcoin), all Tether quantities are returned in USDt: 1 USDt = 0.000001 USDT and all Ethereum are returned in gwei: 1 gwei = 0.000000001 ETH.

For other currencies, please refer to our Asset API where the relationship is represented by the scale parameter.

Authentication

To access private endpoints, a permanent API key is required.

Details about authentication via API Key are available via a separate document.

Limits

Request Rate Limits

Requests to our REST API are rate limited by one or more limiters in a layered approach. The limiters implement a Token Bucket mechanism and tokens are continuously refilled.

Currently, there are two limiters in place:

1. 120 requests per minute on all routes (reduced to 30 when unauthenticated)
2. 10 requests per second on certain routes (see below)

Please be very careful about the number of errors your tools throw. If a large number of 4xx or 5xx responses are delivered in a short period of time, your IP address may be banned for an hour. Multiple bans in a short time will result in a weeklong ban.

Viewing Your Request Rate Limit

On each request to the API, these headers are returned:

"x-ratelimit-limit": 120
"x-ratelimit-remaining": 118
"x-ratelimit-reset": 1489791662

Use these headers to determine your current limit and remaining requests. At the UNIX timestamp designated by x-ratelimit-reset, you will have enough requests left to retry your current request. If you have not exceeded your limit, this value is always the current timestamp.

If you are limited, you will receive a 429 response and an additional header, retry-after, that indicates the number of seconds you should pause before retrying.

Second Layer Rate Limits

In addition to the first layer of rate limiting, some routes have an additional limiter that limits requests to a rate of 10 requests per second. This limit is shared across the following routes:

• POST /api/v1/order
• PUT /api/v1/order
• DELETE /api/v1/order
• DELETE /api/v1/order/all
• POST /api/v1/position/isolate
• POST /api/v1/position/leverage
• POST /api/v1/position/transferMargin

On each request to these routes, the x-ratelimit-remaining-1s header will be returned with the first layer rate limit headers.

When exceeding this limit, the value for the x-ratelimit-remaining-1s header will be 0 and you will receive a 429 response along with the retry-after header.

Increasing Your Request Rate Limit

If you are running up against our limits and believe that you have a legitimate need, please Contact Support to discuss upgrading your access limits.

Before increasing your rate limits, we require that your programs at least:

• Use the WebSocket feeds to avoid polling data.
• Use our bulk cancel features to reduce load on the system.
  • Bulk cancels, regardless of count, always only count as one request.

When emailing us about a rate limit increase, please include:

• Your application’s purpose and intended growth
• Your desired rate limit
• Acknowledgement that your program is using the API efficiently, as mentioned above.

Rate Limit Reductions

Rate limits may be reduced on individual accounts if an account is involved with malicious behaviour.

Order Count Limits

To keep an orderly market, BitMEX imposes limits on the number of open orders per account. These limits are:

1. Maximum 200 open orders per symbol per account;
2. Maximum 10 stop orders per symbol per account;

When placing a new order that causes these caps to be exceeded, it will be rejected with the message “Too many [open|stop] orders”.

Order Minimum Size Limits

We intentionally set the contract sizes of BitMEX products at low values to encourage traders both large and small to trade on BitMEX. However, some traders abuse this and spam the orderbook or trade feed with many small orders.

Accounts with too many open orders with a gross value less than 0.0001 XBT each will be labeled as a Spam Account.

If you are marked as a Spam Account:

• Orders below 0.0001 XBT in value will automatically become hidden orders.
• Hidden orders do not show in the orderbook and always pay the taker fee.
• Post-Only spam orders will be Rejected instead of being hidden.
• Too many spam orders may be grounds to temporarily ban an account from trading.
• Spam Account designations are re-evaluated and lifted automatically every 24 hours if user behavior has changed.

WebSocket Limits

WebSocket Limits are documented on the WebSocket API page.

Behaviour

BitMEX monitors the behaviour of accounts on the platform, including those using the API.

Trading Rules

BitMEX enforces certain trading rules on the platform to discourage inefficient or undesirable behaviours. Please view our Trading Rules documentation for more details.

Efficiency

Accounts that consistently make a disproportionate number of order-management API requests per notional of XBT executed place unnecessary load on the system and may be banned. For example, if your account is making thousands of new/amend/cancel order API requests each day, yet not trading at all, your account may be banned.

To help keep your trading activity efficient, you may:

• Switch off the automated system that is using the API.
• Increase traded volume, by tightening your quotes or crossing the spread if necessary.
• Reduce the number of requests made.

HTTP Keep-Alive

BitMEX does not support placing or canceling orders via WebSocket, only via HTTP.

Our servers support HTTP Keep-Alive and cache SSL sessions. If you keep a connection alive, you will get websocket-like latency, obviating the need to use the websocket for transactional communication.

Our Keep-Alive timeout is 90 seconds.

Overload

To help improve responsiveness during high-load periods, the BitMEX trading engine will begin load-shedding when requests reach a critical queue depth. When this happens, you will quickly receive a 503 status code with the JSON payload {"error": {"message": "The system is currently overloaded. Please try again later.", "name": "HTTPError"}}. The request will not have reached the engine, and you should retry after at least 500 milliseconds.

Learn more about how this mechanism works by visiting the load shedding reference page. We will keep clients updated as we improve peak capacity on the trading engine.

Filtering

Many table endpoints take a filter parameter. This is expected to be JSON. For example, the filter query {"side":"Buy"} can be url-encoded and sent to the trade endpoint (click to run).

Most values can only be filtered by simple equality. Timestamps, which are all UTC, can be queried in many ways:

Timestamp Filters

The following fields can be passed in the "filter" param as JSON key/value pairs:

Key	Description	Example	Example Description
"startTime"	Start timestamp.	"2014-12-26 11:00"	On or after 11:00am on 26 December 2014.
"endTime"	End timestamp.	"2014-12-26 13:00"	On or before 1:00pm on 26 December 2014.
"timestamp"	Exact timestamp.	"2014-12-26 12:00"	Exactly noon on 26 December 2014.
"timestamp.date"	Exact day.	"2014-12-26"	The entire day of 26 December 2014.
"timestamp.month"	Exact month.	"2014-12"	The entire month of December 2014.
"timestamp.year"	Exact year.	2014	The entire year of 2014.
"timestamp.mm"	Month of year.	12	December of each year.
"timestamp.dd"	Day of month.	26	26th of each month.
"timestamp.ww"	Day of week.	6	Friday of each week. 0 = Sat, 1 = Sun
"timestamp.time"	Exact time.	"12:00:00.000"	Exactly noon of each day.
"timestamp.second"	Exact second.	"12:00:00"	The entire second from noon of each day.
"timestamp.minute"	Exact minute.	"12:00"	The entire minute from noon of each day.
"timestamp.hh"	Hour of day.	12	12th hour of each day. (i.e. noon)
"timestamp.uu"	Minute of hour.	30	30th minute of each hour.
"timestamp.ss"	Second of minute.	15	15th second of each minute.

For example, the .BVOL7D index is calculated and published on the trade feed every 5 minutes. To filter to just noon on Fridays, send the payload:

{"symbol": ".BVOL7D", "filter": {"timestamp.time":"12:00", "timestamp.ww":6}}

(Click to run)

OrderBookL2

This section has been relocated.