Over the past 6 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. 

  1. Securing Your Environment
  2. Structuring and configuring your accounts
  3. Writing your software
  4. Buying or renting a server
  5. Generating API keys
  6. Handling API keys and other secrets
  7. What to do if you suspect a breach

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.