Bitmex Getting Started: Account, Keys, First Request (2026)

Getting started overview

Integrating with the Bitmex API involves a sequence of steps designed to secure your account and enable programmatic interaction with the exchange. This guide outlines the essential procedures for setting up your Bitmex account, generating the necessary API credentials, and making an initial authenticated request. The Bitmex platform provides both REST and WebSocket APIs for various trading and data retrieval purposes, supporting automated strategies and real-time market monitoring.

Before initiating API calls, users are typically required to complete an account registration process and satisfy any applicable identity verification requirements. This ensures compliance with regulatory standards and secures user assets. Once an account is established, API keys can be generated within the user's account settings, providing the authentication tokens needed to sign API requests. Understanding the authentication mechanism, which often involves HMAC-SHA256 signing, is crucial for successful API integration.

This section provides a high-level overview of the process:

1. Account Creation and Verification: Register for a Bitmex account and complete any required Know Your Customer (KYC) procedures.
2. API Key Generation: Create API keys (API Key ID and API Secret) within your Bitmex account settings.
3. Authentication: Understand how to sign requests using your API keys for secure communication.
4. First Request: Execute a simple API call to verify connectivity and authentication.

The following table summarizes the initial steps:

Create an account and get keys

To begin using the Bitmex API, the first step is to create a user account on the Bitmex platform. This process typically involves providing an email address, setting a password, and agreeing to the terms of service. Following initial registration, Bitmex, like many regulated financial platforms, requires users to complete identity verification, often referred to as Know Your Customer (KYC) procedures. This usually involves submitting identification documents and proof of address. The specifics of these requirements can be found on the Bitmex official website.

Once your account is set up and verified, you can proceed to generate API keys. API keys are essential for authenticating your programmatic requests to the Bitmex API. Bitmex provides a dedicated section within your account settings for creating and managing these keys. Each API key pair consists of an API Key ID and an API Secret. The API Key ID is a public identifier, while the API Secret is a cryptographic key that must be kept confidential, similar to a password. It is used to sign your requests, proving their authenticity.

To generate API keys:

1. Log in to your Bitmex account.
2. Navigate to the "API Keys" section, typically found under your account profile or settings.
3. Click on a button or link to "Create New API Key" or similar.
4. You may be prompted to set permissions for the new key. It is recommended to grant only the minimum necessary permissions for your intended use case to enhance security. For initial testing, read-only permissions are often sufficient.
5. After creation, the API Key ID and API Secret will be displayed. Crucially, the API Secret is usually shown only once upon creation. Copy and store it securely immediately. If lost, you will need to generate a new key pair.
6. For security best practices in general API usage, consider storing API keys in environment variables or a secure vault rather than hardcoding them directly into your application code. This practice is outlined in security guidelines for web applications, such as those provided by Google Cloud's API key security documentation.

Your first request

After successfully generating your API keys, the next step is to make your first authenticated request to the Bitmex API. This verifies that your keys are correctly set up and that your authentication mechanism is functioning as expected. Bitmex's REST API requires requests to be signed using an HMAC-SHA256 algorithm. The signature is generated from a combination of the HTTP method, request path, expiration timestamp, and request body (if applicable), all hashed with your API Secret. This signature, along with your API Key ID and the expiration timestamp, is then included in the request headers.

A common first request is to fetch your account's wallet balance or a public endpoint that requires no authentication but can be used with signed requests to test the signing mechanism. For simplicity, let's consider a basic GET request to retrieve user wallet information, which requires authentication. The Bitmex API documentation provides detailed examples and specifications for constructing these requests, particularly in the authentication section of their REST API introduction.

Here's a conceptual outline for a Python example using the requests library, demonstrating how to construct and sign a request for /api/v1/user/wallet:

import hashlib
import hmac
import time
import requests
import urllib.parse

# Replace with your actual API Key and Secret
API_KEY = "YOUR_API_KEY_ID"
API_SECRET = "YOUR_API_SECRET"
BASE_URL = "https://www.bitmex.com/api/v1" # Use testnet for testing: https://testnet.bitmex.com/api/v1

def generate_signature(api_secret, verb, url, nonce, data):
    """Generates an API signature for Bitmex requests."""
    parsed_url = urllib.parse.urlparse(url)
    path = parsed_url.path
    if parsed_url.query:
        path = path + '?' + parsed_url.query

    if isinstance(data, (bytes, bytearray)):
        data = data.decode('utf-8')

    message = verb + path + str(nonce) + data
    signature = hmac.new(api_secret.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()
    return signature

# Example: Get User Wallet Summary
endpoint = "/user/wallet"
method = "GET"
expires = int(time.time()) + 60  # Request expires in 60 seconds

# For GET requests, data is an empty string
data = ""

signature = generate_signature(API_SECRET, method, endpoint, expires, data)

headers = {
    "api-expires": str(expires),
    "api-key": API_KEY,
    "api-signature": signature,
    "Content-Type": "application/json" # Even for GET, Bitmex often expects this header
}

try:
    response = requests.request(method, BASE_URL + endpoint, headers=headers, data=data)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    print("Response Status Code:", response.status_code)
    print("Response Body:", response.json())
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
    print(f"Response body: {err.response.text}")
except Exception as err:
    print(f"An error occurred: {err}")

Replace YOUR_API_KEY_ID and YOUR_API_SECRET with your actual keys. For initial testing, it is highly recommended to use the Bitmex Testnet to avoid risking real funds. The API endpoint for Testnet is https://testnet.bitmex.com/api/v1.

Common next steps

After successfully making your first authenticated API call to Bitmex, you can explore a range of functionalities to build out your trading application or data integration. The Bitmex API is comprehensive, supporting various aspects of cryptocurrency derivatives trading.

• Real-time Market Data (WebSockets): For applications requiring immediate updates on price changes, order book depth, and trade executions, integrating with the Bitmex WebSocket API is crucial. WebSockets provide a persistent, full-duplex communication channel, reducing latency compared to repeated REST API polling.
• Order Management: Programmatically place, modify, and cancel orders. This includes various order types such as limit, market, stop-market, and take-profit orders. Understanding the parameters for each order type, as detailed in the Bitmex REST API order endpoints, is essential for precise trading strategies.
• Account and Position Management: Access detailed information about your account, including current open positions, margin details, and historical trades. This allows for monitoring your portfolio and managing risk effectively.
• Error Handling and Rate Limits: Implement robust error handling in your code to gracefully manage API responses, including understanding HTTP status codes and specific error messages. Be aware of Bitmex's API rate limits to avoid being temporarily blocked. The documentation usually specifies these limits and recommended practices for managing them.
• Security Enhancements: Beyond basic API key management, consider implementing additional security measures, such as IP whitelisting for your API keys, if supported by Bitmex, and regularly rotating your API keys. General best practices for API security are critical, as highlighted by resources such as the Twilio API security guide, which emphasizes protecting credentials and validating inputs.
• Local Development and Testing: Continue to use the Bitmex Testnet for developing and testing new features or strategies without risking real capital. This environment mirrors the production API but operates with simulated funds.
• Leveraging Official Libraries: While Bitmex does not provide official SDKs, the community has developed various client libraries in different programming languages. While using third-party libraries, always review their source code for security and accuracy before integrating them into production systems.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some frequent problems and their solutions when interacting with the Bitmex API:

• Incorrect API Key or Secret: Double-check that you have copied the API Key ID and API Secret precisely. Remember that the API Secret is only shown once upon creation. If you suspect it's incorrect or lost, generate a new key pair.
• Signature Mismatch (401 Unauthorized): This is one of the most common issues. The HMAC-SHA256 signature calculation is sensitive to every detail.
• Timestamp (api-expires): Ensure your local system time is synchronized with network time (NTP). A significant time difference between your system and the Bitmex server will cause the signature to be invalid. The expiration timestamp must be in the future relative to the Bitmex server's time.
• Message String Construction: Verify the exact concatenation of verb + path + expires + data. The path should include any query parameters, and data should be the raw JSON body string for POST/PUT requests, or an empty string for GET requests.
• Encoding: Ensure that both the API Secret and the message string are correctly encoded (e.g., UTF-8) before being passed to the HMAC-SHA256 function.
• Case Sensitivity: API keys and secrets are case-sensitive.
• Incorrect Endpoint or Method (404 Not Found, 405 Method Not Allowed): Verify that the endpoint path (e.g., /api/v1/user/wallet) and HTTP method (GET, POST, PUT, DELETE) exactly match the Bitmex API documentation.
• Missing or Incorrect Headers: Ensure all required headers (api-key, api-expires, api-signature, Content-Type for requests with a body) are present and correctly formatted. The Content-Type header should typically be application/json for requests with a JSON body.
• Rate Limit Exceeded (429 Too Many Requests): If you send too many requests in a short period, Bitmex will temporarily block your IP. Implement exponential backoff or ensure your request frequency adheres to Bitmex's rate limit policies.
• Using Production Keys on Testnet or vice-versa: Ensure you are using the correct base URL (https://www.bitmex.com/api/v1 for production, https://testnet.bitmex.com/api/v1 for testnet) for the API keys you generated. Keys are environment-specific.
• Network Issues: Check your internet connection or any firewall settings that might be blocking outbound requests.
• Empty Response or Unexpected Data: If the request seems to go through but returns no data or unexpected data, check the endpoint and parameters. Some endpoints require specific query parameters to return relevant information.

When troubleshooting, use detailed logging to print out the full request (method, URL, headers, body) and the exact response (status code, headers, body). This can help pinpoint discrepancies in your request construction compared to what the Bitmex API expects.