Skip to main content

BitMEX API & Account Security

  • Updated

Over the years, we have seen a large variety of ways users can lose control of their accounts with some of the more sophisticated account take-over techniques centred around vulnerabilities in the way that users store their API keys. Depending on the settings of your account and the permissions of the API key, most functions on an account can be performed, including withdrawing funds and the transfer of profits through manipulative trading practices.

If you are getting started on BitMEX, or if you are looking to refresh the security on your existing accounts, we hope that you’ll find this summary of our top tips helpful. 


Securing Your Environment

  • Use two-factor authentication everywhere (email, exchange accounts)
    • In order of preference: U2F, Yubikeys, TOTP auth
    • Do not use SMS authentication
  • Use a strong password on your computer
    • Use a password manager like 1Password, KeePass, LastPass
  • Encrypt your hard drive
    • Windows: BitLocker
    • MacOS: FileVault
    • Linux: LUKS/CryptFS
  • Encrypt your backups
  • Consider installing a hardware firewall on your network (IDS/IPS)
  • If on MacOS, consider a strong outgoing traffic filter, for example, Little Snitch.
  • If accessing your accounts on a public network, use a VPN provider


Structuring and configuring your accounts

  • Use testnet.bitmex.com first
    • Our Testnet environment provides the same features and functionality as the main bitmex.com environment. The same trading rules, account settings and restrictions from the main environment are replicated on our Testnet environment, but without using real funds. We highly recommend playing around with the following features to see how they interact with your program. 
      • https://testnet.bitmex.com/app/securityCentre - Account security
      • https://testnet.bitmex.com/app/apiKeys - Key configuration
      • https://testnet.bitmex.com/app/addresses - Withdrawal confirmation settings. Adding addresses to your address book allows for quicker transfers and withdrawals. 
      • Whitelisting  / Withdrawal Locking - You can configure your withdrawal settings to only allow withdrawals to a specified set of wallet addresses. Please contact support@bitmex.com and our support team will arrange this for you. This is especially important for corporates where there needs to be a segregation of duties between traders and those responsible for treasury management.
      • Account Linking - Linking allows users to create a group of accounts with shared ownership where funds can be instantly transferred within the group without incurring an on-chain network fee. There are limits to the number of accounts each user can have as well as other restrictions, but please contact support@bitmex.com and our team will sort this out for you.


Writing your software

  • Read the existing documentation for explanations of endpoints and rules
  • Be sure to add your credentials file to .gitignore. 
    • If you accidentally pushed your credentials to GitHub,  delete the API key as soon as possible using https://www.bitmex.com/app/apiKeys and check your account history.
    • This is another good reason to define a strict CIDR block (IP range) that your API key can be used from, so that it is harder to abuse if leaked.
  • Write tests. Use assertions within your code. Use a linter or typechecker when available.
    • Consider implementing independent risk limits and log, alert or shut down your trading application if those limits are breached for any reason. An independent codebase without shared source code is always better, as any risk system that shares code or data with your trading system could suffer from the same bugs that caused you to breach the limits in the first place.
    • On a crash or other major unexpected event, consider having your code cancel all open orders.


Buying or renting a server

  • We recommend starting a server in AWS eu-west-1 for the lowest latency connection to the exchange. We don’t offer co-location, so being in the same AWS zone is the best option if latency is important to your trading strategy. 
  • For most applications, a t3.nano or t3.micro will do. 
    • If you’re using burstable instances, closely monitor available CPU credits or enable “T3 Unlimited”. You may have significant latency problems if you run out of credits.
    • Larger instances have better network capacity. Consider this if you are ingesting significant volumes of data from many sources.


Locking down your server

  • Use SSH keys when connecting to your server and disable password authentication.
  • Install automatic security updates.
  • Install ufw (uncomplicated firewall) and only open the ports you need.
    • If you know your server  will only talk to BitMEX servers, you can significantly lock down outgoing ports. We occasionally change the IP addresses of our servers, so you’ll need to take this into consideration.
  • Set up email alerts for common actions on your server, such as ssh login, trading process restart and so on, so you have knowledge of what the server is doing at any time. Don’t forget to monitor your email.
  • Consider using a command logger to send all commands that are run on your server to an external source for auditing and surveillance purposes.
  • Consider using immutable containers for your application.


Generating API keys

  • Generate only one API Key per automated tool. If you have a number of systems using API keys, assign them one each.
  • Name your API Keys.
  • Give your API Keys the least permissions possible for your application. You should generate read-only keys for the purposes of external audits and/or third-party portfolio tracking software for example.
  • Specify a single IP address followed by /32 in the “CIDR” field to ensure your key can’t be used from any IP other than your server.
  • If you move servers, regenerate the API Key with a new strict CIDR block and a new name.
  • Do not share API keys between development machines and production machines.


Handling API keys and other secrets

  • Store the key/secret in a file on disk with strict permissions, readable only by the user that will run the software. Have your program read that file on start.
    • If using containers, use a volume mount.
  • Why not use environment variables?
    • Every dependency that your application uses can also access the environment.
    • Child processes spawned by your application can read the environment (e.g. curl, imagemagick, etc)
    • If your application crashes, it may log the environment for debugging purposes, which may expose your secrets.
    • Any other applications launched by the same user or by root can read these environment variables.
  • If you must use environment variables, consider baking an AES key into your application then encrypt/decrypt the secrets with that key. This isn’t 100% failsafe, but it raises the bar for exploitation.
  • Ideally use a secret manager like Vault.

 

What to do if you suspect a breach

If you suspect that your API keys or accounts have been compromised in any way, please reach out to our Support Team immediately. They will be able to lock your account, ensure your funds are safe and help investigate.

In addition, you should:

  • Delete or disable any suspected compromised API key(s)
  • Change your passwords
  • Check your account history

 

We hope that some of the suggestions above prove helpful for you and your team. If we have missed anything, or if you have any suggestions, please feel free to reach out to our support team or your client development representative and we will be happy to investigate.

Related articles

This website is operated by HDR Global Trading Limited, a company incorporated under the International Business Companies Act of 1994 of the Republic of Seychelles with a company number of 148707 and registered address at Global Gateway 8, Rue de la Perle, Providence Mahé, Seychelles (“HDR”). HDR wholly owns BitMEX, a Bitcoin-based trading platform.


Access to trading or holding positions on BitMEX is prohibited for any person or entity that is located, incorporated or otherwise established in, or a citizen or a resident of: (i) the United States of America, Québec (Canada), the Hong Kong Special Administrative Region of the People’s Republic of China, the Republic of Seychelles, Bermuda, Cuba, Crimea and Sevastopol, Iran, Syria, North Korea or Sudan; (ii) any state, country or other jurisdiction that is embargoed by the United States of America; or (iii) any other jurisdiction where the services offered by BitMEX are restricted (collectively “Restricted Jurisdictions”). If it is determined that any BitMEX user has given false representations as to their location, incorporation, establishment, citizenship or residence, or HDR detects a user is from a Restricted Jurisdiction as described above, HDR reserves the right to immediately close their accounts and liquidate any open positions. HDR may, in its sole discretion, implement controls to restrict access to the BitMEX trading platform in any of the Restricted Jurisdictions.