【教程】BitMEX API：轻松查询实时&历史市场数据，交易更精准！

BitMEX API 查询市场数据

BitMEX 提供了一套强大的 API，允许开发者获取实时的和历史的市场数据。 这篇文章将深入探讨如何使用 BitMEX API 查询市场数据，包括不同的 API 端点、请求参数、返回格式，以及实际的代码示例。

概述

BitMEX API 遵循 RESTful 架构原则，用户可以通过标准的 HTTP 请求与平台进行交互，从而访问并利用其提供的丰富功能。对于加密货币市场数据的查询和分析，以下几个 API 端点至关重要，并且将在后续的内容中重点介绍：

• GET /api/v1/trade : 此端点用于检索历史交易数据。用户可以指定时间范围，并选择按照时间升序（旧到新）或降序（新到旧）排列返回的交易记录。返回的数据通常包含成交价格、成交数量、交易时间戳以及买卖方向等关键信息，这些信息对于趋势分析和回测至关重要。
• GET /api/v1/trade/bucketed : 此端点提供聚合后的交易数据，通常被称为 OHLC（Open, High, Low, Close）数据，即开盘价、最高价、最低价和收盘价。该端点允许用户指定不同的时间间隔，如 1 分钟、5 分钟、1 小时、1 天等，以获取不同粒度的市场数据。这些聚合数据广泛应用于技术分析，例如K线图的绘制和各种技术指标的计算。用户可以通过参数设置来获取特定时间段内的 OHLC 数据，进行深度分析。
• GET /api/v1/orderBook/L2 : 此端点用于获取 Level 2 订单簿数据，也称为深度数据。Level 2 订单簿显示了市场上多个买入和卖出订单的价格和数量，提供了比 Level 1 数据（仅显示最佳买入价和卖出价）更详细的市场供需信息。通过分析 Level 2 订单簿，交易者可以了解市场的流动性分布、潜在的支撑位和阻力位，以及其他交易者可能的交易意图，从而制定更明智的交易策略。需要注意的是，频繁请求 Level 2 数据可能会对 API 的使用频率产生影响，因此需要合理控制请求频率。
• GET /api/v1/instrument : 此端点用于获取特定合约的详细信息。这些信息包括但不限于保证金要求（用于计算开仓所需的资金）、交易手续费（影响交易成本）、最小委托量（限制单笔交易的最小数量）等。用户可以查询特定合约的代码，以获取与其相关的各种参数和规则。掌握这些信息对于风险管理和成本控制至关重要。
• GET /api/v1/instrument/active : 此端点用于获取当前活跃合约的信息。活跃合约是指当前正在交易的合约，通常是成交量最大的合约。通过此端点，用户可以快速了解当前市场关注的焦点，并获取相关合约的详细信息，例如合约代码、结算时间、以及其他重要参数。这对于及时调整交易策略至关重要，尤其是在合约到期或市场发生重大变化时。

API 认证

虽然BitMEX提供部分公开市场数据，允许用户在无需API密钥的情况下访问，但这通常仅限于有限的数据类型和较低的访问频率。为了满足更高级的数据需求，例如高频交易、自动化策略执行以及访问更全面的历史数据，强烈建议注册一个BitMEX账户并申请API密钥。API密钥是访问受保护API端点的必要凭证，它确保了您的身份验证和授权，同时防止未经授权的访问。

一个API密钥由两个关键部分组成： apiKey 和 apiSecret 。 apiKey 是公开的密钥标识符，用于识别您的账户。 apiSecret 是一个私密的密钥，必须严格保密，类似于密码。泄漏 apiSecret 可能导致您的账户被盗用，因此务必将其安全存储，并避免在不安全的环境中共享。

当您使用需要身份验证的BitMEX API端点时，您需要在HTTP请求头中包含认证信息。这通常涉及使用 apiKey 和 apiSecret 对请求进行签名。签名的过程会根据所使用的编程语言和库而有所不同，但通常涉及到将请求参数、时间戳和 apiSecret 组合在一起，然后使用哈希算法（如HMAC-SHA256）生成一个唯一的签名。

将生成的签名作为请求头的一部分发送给BitMEX服务器，服务器会验证签名的有效性，并根据 apiKey 授予相应的访问权限。请注意，签名算法的细节和请求头的格式可能会因API端点和BitMEX API版本而异。有关详细的认证过程、代码示例以及安全最佳实践，请务必参考BitMEX官方API文档，确保您的API集成安全可靠。BitMEX官方文档通常提供各种编程语言的示例代码，如Python、JavaScript等，方便开发者快速上手。

查询交易数据 ( /api/v1/trade )

GET /api/v1/trade 端点提供了一种检索特定合约历史交易信息的途径。通过该接口，用户可以获取一段时间内发生的成交记录，用于分析市场趋势、评估交易策略的有效性，或进行数据回测。该接口返回的数据包括成交价格、成交数量、成交时间等关键信息，有助于更全面地了解市场动态。

通过该接口，您可以获取特定交易对的历史成交数据。返回数据通常包含以下字段：成交时间（timestamp）、成交价格（price）、成交数量（quantity）、买卖方向（side，如 buy 或 sell）等。这些信息对于技术分析、量化交易策略的回测以及市场深度评估至关重要。

用户可以利用各种参数来过滤和排序交易数据。常见的参数包括：

• symbol : 指定要查询的合约代码，例如 "BTCUSDT"。
• limit : 限制返回的交易记录数量。默认值和最大值通常存在限制，例如默认为 500 条，最大不超过 1000 条。
• fromId : 从指定的交易 ID 开始查询，用于分页获取大量数据。
• startTime 和 endTime : 指定查询的时间范围，允许用户获取特定时间段内的交易数据。

在使用该接口时，请务必注意频率限制，避免对服务器造成过大的压力。同时，合理设置查询参数，可以更高效地获取所需的数据。例如，通过指定 startTime 和 endTime ，可以只获取特定时间段内的交易记录，从而减少数据传输量和处理时间。

请求参数：

• symbol (必选): 合约代码，用于指定交易的合约。例如， XBTUSD 代表比特币/美元的永续合约。请务必提供有效的合约代码，否则API将无法正确返回数据。支持的合约代码列表可在交易所的官方文档中找到。
• count (可选): 返回的记录数量，控制API响应中包含的数据条目数。默认值为 100，最大值为 500。如果未指定此参数，API将返回100条记录。若需获取更多数据，请根据API限制调整此参数，并考虑分页请求。
• start (可选): 起始记录的偏移量，允许您从指定位置开始检索数据。例如，如果设置 start 为 100，API将跳过前100条记录，并从第101条记录开始返回数据。此参数常用于分页，以便逐步获取大量历史数据。
• reverse (可选): 是否按时间倒序排列。默认为 false (按时间顺序，即从旧到新)。如果设置为 true ，则API将按时间倒序排列记录，即从最新到最旧。这对于快速获取最近的交易记录非常有用。
• startTime (可选): 查询的起始时间 (ISO8601 格式)。用于指定要检索的交易记录的起始时间。时间格式必须符合 ISO8601 标准，例如 2023-10-26T00:00:00Z 。此参数与 endTime 结合使用，可以精确地筛选出指定时间范围内的交易记录。
• endTime (可选): 查询的结束时间 (ISO8601 格式)。用于指定要检索的交易记录的结束时间。时间格式同样必须符合 ISO8601 标准，例如 2023-10-27T00:00:00Z 。请确保 endTime 晚于 startTime ，以避免API返回错误或空数据。
• partial (可选): 如果为 true ，返回未完成的交易（即仍在挂单簿上的订单）。默认为 false ，仅返回已成交的交易记录。设置为 true 可以用于监控订单的执行情况，但请注意，未完成的交易可能会发生变化或被取消。

返回格式：

返回一个 JSON 数组，每个元素代表一笔独立成交的交易记录。该数组能够提供关于市场交易活动的详细信息，以便进行数据分析和策略制定。每个交易对象包含以下字段，务必注意数据类型和单位，避免解析错误：

• timestamp : 交易时间，采用 ISO8601 标准格式（例如： 2023-10-27T10:00:00.000Z ）。 此时间戳精确到毫秒级别，并且使用 UTC 时间，务必进行时区转换以适应本地时间。该字段是理解市场交易节奏的关键。
• symbol : 合约代码，代表具体交易的交易对或合约类型（例如： BTCUSDT ， ETHUSD_PERP ）。该字段是识别交易标的物的基础。不同交易所和交易平台可能使用不同的合约代码命名规则，请务必参考相关API文档。
• side : 交易方向，表明交易是买入 ( Buy ) 还是卖出 ( Sell )。 Buy 表示主动买入，推动价格上涨的可能性较高； Sell 表示主动卖出，推动价格下跌的可能性较高。该字段用于判断市场情绪和交易压力。
• size : 交易数量，代表交易的合约数量或币的数量，取决于具体的交易对和合约类型。 需要结合 symbol 字段来理解具体的数量单位。该字段是评估交易规模的重要指标。
• price : 交易价格，代表该笔交易的成交价格。 该价格是市场供需关系的直接体现，也是技术分析的基础数据。
• tickDirection : 价格变动方向，指示该笔交易相对于上一笔交易的价格变动情况。 可能的值包括： PlusTick (价格上涨), ZeroPlusTick (价格不变但属于上涨序列), MinusTick (价格下跌), ZeroMinusTick (价格不变但属于下跌序列)。该字段能够帮助判断微观层面的市场动向和价格趋势。
• trdMatchID : 交易 ID，唯一标识该笔交易的字符串。 该ID用于追踪特定的交易，在排查问题或进行交易审计时非常有用。
• grossValue : 交易的总价值，通常以计价货币（例如：USDT）表示。 该字段是评估交易金额大小的重要指标，也是计算交易手续费的基础。
• homeNotional : 以基础货币计价的交易价值。例如，对于 BTCUSDT 交易对，基础货币是 BTC。 该字段表示交易中涉及的 BTC 的数量。
• foreignNotional : 以外币计价的交易价值。例如，对于 BTCUSDT 交易对，外币是 USDT。 该字段表示交易中涉及的 USDT 的数量。 这两个 notional 字段对于理解跨币种交易和计算损益至关重要。

示例 (使用 Python):

本示例展示如何使用 Python 编程语言，通过 HTTP 请求从 BitMEX 交易所的 API 获取最新的交易数据。我们将使用 requests 库发送 GET 请求，并使用 库解析返回的 JSON 数据。

你需要确保安装了 requests 库。可以使用 pip 进行安装： pip install requests 。 同时需要导入库，虽然多数python版本已经内置，但显式导入可以避免潜在的依赖问题。

import requests
import  

接下来，我们定义 API 的 URL 和请求参数。 url 变量指定了 BitMEX 交易 API 的端点， params 字典包含了查询参数。其中， symbol 指定了交易对（例如 XBTUSD，即比特币/美元永续合约）， count 指定了要获取的交易记录的数量。 请注意，BitMEX API 可能需要身份验证，具体取决于你要访问的端点和数据。 如果需要身份验证，则需要添加相应的标头和签名。

url = "https://www.bitmex.com/api/v1/trade"
params = {
    'symbol': 'XBTUSD',
    'count': 10
}

现在，我们使用 requests.get() 方法发送 GET 请求，并将 URL 和参数传递给该方法。服务器将返回一个响应对象，其中包含响应的状态码、标头和内容。

response = requests.get(url, params=params)

我们需要检查响应状态码以确保请求成功。如果状态码为 200，表示请求已成功处理。然后，我们使用 .loads() 方法将响应内容（JSON 字符串）解析为 Python 字典列表。 接下来，我们遍历交易记录列表，并提取每个交易记录的时间戳、价格、数量和方向。 请注意，从API返回的数据通常是时间戳字符串，根据实际需要可能要将其转换为 datetime 对象以便进行更复杂的处理或格式化显示。 方向（side）字段通常表示买入或卖出，具体值取决于交易所的 API 定义。

if response.status_code == 200:
    trades = .loads(response.text)
    for trade in trades:
        print(f"时间: {trade['timestamp']}, 价格: {trade['price']}, 数量: {trade['size']}, 方向: {trade['side']}")
else:
    print(f"请求失败: {response.status_code}")

如果响应状态码不是 200，表示请求失败。我们打印错误消息，其中包含响应状态码，以便进行故障排除。

查询聚合交易数据 (OHLC) ( /api/v1/trade/bucketed )

GET /api/v1/trade/bucketed 端点提供对聚合交易数据的访问，这些数据经过预处理，并按照指定的时间间隔进行分组。 这种类型的数据通常用于构建金融市场的 K 线图，也称为 OHLC (Open, High, Low, Close) 图表。 通过该端点，用户可以检索指定交易对在特定时间范围内的开盘价、最高价、最低价和收盘价，以及交易量等信息。

此端点允许灵活地配置数据聚合的方式，例如可以通过参数指定时间桶的大小 (bucket size)，常见的桶大小包括分钟、小时、天等。 聚合交易数据对于技术分析至关重要，可以帮助交易者识别趋势、支撑位和阻力位，并制定交易策略。 返回的数据通常包含时间戳、开盘价、最高价、最低价、收盘价、交易量和成交笔数等字段。

利用此端点，开发者可以构建各种金融分析工具和应用程序，例如实时价格监控仪表盘、历史数据分析平台和自动化交易系统。 正确理解和使用 /api/v1/trade/bucketed 端点对于有效地分析加密货币市场至关重要。

请求参数：

• symbol (必选): 合约代码，用于指定要查询的交易品种。例如， XBTUSD 代表比特币兑美元永续合约。务必提供有效的合约代码，否则无法获取数据。不同的交易所可能有不同的合约代码命名规则，请参考对应交易所的API文档。
• count (可选): 返回的K线数据记录数量。默认值为 100，允许的最大值为 500。请求较多的数据量可能会增加服务器的响应时间。开发者应根据实际需求合理设置 count 值。
• start (可选): 起始记录的偏移量，用于分页查询。例如， start=100 表示从第 101 条记录开始返回数据。偏移量从 0 开始计数。结合 count 参数可以实现对大量历史数据的分批获取。
• reverse (可选): 是否按时间倒序排列返回的数据。默认为 false (按时间顺序，即时间由早到晚)。设置为 true 将按时间由晚到早的顺序返回数据。倒序排列在某些场景下可以更方便地处理最新数据。
• startTime (可选): 查询数据的起始时间，采用 ISO8601 格式表示。例如， 2023-10-26T00:00:00Z 。只返回指定时间之后的数据。如果未指定，则从最早的可用数据开始返回，但会受 count 参数限制。
• endTime (可选): 查询数据的结束时间，同样采用 ISO8601 格式表示。例如， 2023-10-27T00:00:00Z 。只返回指定时间之前的数据。如果未指定，则返回到最新的可用数据，但会受 count 参数限制。
• binSize (必选): 时间间隔，也称为 K 线周期。指定返回数据的聚合粒度。常见的取值包括： 1m (1 分钟), 5m (5 分钟), 1h (1 小时), 1d (1 天)。选择合适的时间间隔取决于分析的时间范围和精度要求。更小的时间间隔提供更精细的数据，但也会产生更多的数据点。
• partial (可选): 如果设置为 true ，则返回未完成的当前 K 线数据。默认为 false ，只返回已完成的 K 线。未完成的 K 线可能包含当前正在发生的交易数据，因此其数值可能会不断变化。
• use MillisecondTime (可选): 如果设置为 true ，则返回的 K 线时间戳将是毫秒级的时间戳。默认为 false ，返回的是秒级时间戳。毫秒级时间戳提供更高的精度，在需要精确时间分析的场景下非常有用。

返回格式：

接口返回一个 JSON 数组，数组中的每个元素代表特定时间间隔内的聚合数据。 这种聚合方式旨在提供一段时间内加密货币交易活动的概览，便于分析和可视化。 每个聚合数据对象都包含以下详细字段，方便用户进行深度分析和量化交易策略的制定：

• timestamp : 时间戳，采用 ISO8601 格式表示。 精确记录数据聚合的时间点，保证时间序列分析的准确性。 例如："2023-10-27T10:00:00Z" 表示 UTC 时间 2023 年 10 月 27 日 10 点整。
• symbol : 合约代码，唯一标识交易的加密货币合约。 明确指定数据所属的交易对，例如 "BTCUSD" 代表比特币兑美元的永续合约。
• open : 开盘价，指定时间间隔内第一笔交易的价格。 是计算价格波动和趋势的基础数据。
• high : 最高价，指定时间间隔内达到的最高交易价格。 用于评估价格上限和潜在的阻力位。
• low : 最低价，指定时间间隔内达到的最低交易价格。 用于评估价格下限和潜在的支撑位。
• close : 收盘价，指定时间间隔内最后一笔交易的价格。 通常被认为是该时间段内的代表性价格。
• trades : 交易数量，指定时间间隔内发生的交易总次数。 反映了市场活跃度。
• volume : 成交量 (以基础货币计价)，指定时间间隔内交易的基础货币总量。 例如，如果交易对是 BTCUSD，成交量将以 BTC 计价，表示交易的比特币数量。
• vwap : 成交量加权平均价 (Volume Weighted Average Price)，通过将每笔交易的价格乘以其交易量，然后将所有这些值加总，最后除以总交易量计算得出。 VWAP 提供了该时间段内交易的平均价格，更准确地反映了市场价格。
• lastSize : 上一次交易量，指在当前聚合时间段内最后一次成交的交易数量。 有助于识别近期市场活动的规模。
• turnover : 成交额 (以外币计价)，指定时间间隔内交易的总价值，以外币计价。 例如，如果交易对是 BTCUSD，成交额将以 USD 计价，表示交易的总美元价值。
• homeNotional : 以基础货币计价的交易价值，与成交量类似，但明确表示以基础货币计价的名义价值。 用于分析以基础货币衡量的交易规模。
• foreignNotional : 以外币计价的交易价值，与成交额类似，但明确表示以外币计价的名义价值。 用于分析以外币衡量的交易规模。

示例 (使用 Python):

本示例演示了如何使用 Python 从加密货币交易所获取 OHLC (开盘价、最高价、最低价、收盘价) 数据。它使用 requests 库发送 HTTP 请求，并使用 库解析响应。

需要导入 requests 和 库：

import requests
import 

然后，定义 API 的 URL 和请求参数。以下代码示例针对 BitMEX 交易所，获取 XBTUSD 交易对的 1 分钟 OHLC 数据，数量为 10 条：

url = "https://www.bitmex.com/api/v1/trade/bucketed"
params = {
    'symbol': 'XBTUSD',
    'binSize': '1m',
    'count': 10
}

接下来，使用 requests.get() 方法发送 GET 请求，并将参数传递给 params 参数：

response = requests.get(url, params=params)

现在，检查响应状态码。如果状态码为 200，表示请求成功。然后，可以使用 response.text 属性获取响应内容，并使用 .loads() 方法将其解析为 JSON 对象：

if response.status_code == 200:
    ohlc_data = .loads(response.text)
    for data in ohlc_data:
        print(f"时间: {data['timestamp']}, 开盘价: {data['open']}, 最高价: {data['high']}, 最低价: {data['low']}, 收盘价: {data['close']}")
else:
    print(f"请求失败: {response.status_code}")

在循环中，可以访问每个 OHLC 数据点的 timestamp (时间戳), open (开盘价), high (最高价), low (最低价) 和 close (收盘价) 属性，并将其打印到控制台。如果请求失败，将打印相应的错误消息和状态码。

注意：不同的交易所 API 接口和参数可能会有所不同，请根据实际情况进行调整。 需要处理潜在的异常情况，例如网络连接错误、API 速率限制等。可以添加错误处理机制，例如使用 try-except 块来捕获异常。

查询订单簿数据 ( /api/v1/orderBook/L2 )

GET /api/v1/orderBook/L2 端点提供对指定交易对的 Level 2 订单簿数据的访问。 订单簿是市场中所有未成交买单和卖单的集合，按价格排序，反映了市场的买卖意愿和流动性状况。Level 2 订单簿提供比 Level 1 更精细的市场深度信息，包含多个价格级别的买单和卖单数量，允许交易者更全面地评估市场供需关系。

通过此端点，用户可以实时查询指定交易对的订单簿快照。订单簿数据包含买单（Bid）和卖单（Ask）两个部分，每个部分都包含多个按价格排序的订单，每个订单对应特定的价格和数量。 请求参数需要指定交易对，例如 BTC/USD, ETH/BTC 等。返回的数据会包含指定深度的买单和卖单信息，通常会限制返回的订单数量，以控制数据传输量和响应时间。

使用 GET /api/v1/orderBook/L2 端点可以帮助交易者进行以下操作：

• 评估市场深度： 通过观察订单簿的买单和卖单分布，了解市场在不同价格水平的支撑和阻力。
• 发现潜在交易机会： 订单簿中的大额订单可能预示着潜在的价格变动方向。
• 优化交易策略： 根据订单簿数据调整交易策略，例如利用订单簿中的挂单信息进行套利或做市。
• 风险管理： 通过分析订单簿的流动性，评估交易的滑点风险。

请注意，订单簿数据是动态变化的，需要定期刷新才能保持数据的准确性。高频交易者通常会使用 WebSocket 等实时推送技术来获取最新的订单簿数据。不同交易所的订单簿数据格式可能略有差异，需要根据具体交易所的 API 文档进行解析。

请求参数：

• symbol (必选): 合约代码，指定需要查询订单簿的交易对。必须提供有效的合约代码，例如 XBTUSD 代表比特币兑美元的永续合约。不同的交易所和交易平台可能使用不同的合约代码表示相同的交易对，务必参考交易所的官方文档确认。请注意，提供的 symbol 必须存在于交易所中，否则将返回错误。
• depth (可选): 返回的订单簿深度，决定了返回多少层买单和卖单数据。该参数是一个整数，表示订单簿中显示的最佳买卖单数量。默认为 25，意味着将返回最佳的 25 个买单和 25 个卖单。 增加 depth 的值可以获得更全面的市场深度信息，但同时也会增加数据传输量和处理时间。减少 depth 的值可以减少数据量，但可能会错过一些市场信息。交易所通常会对 depth 的最大值进行限制，超过限制值将返回错误。请参考具体交易所的API文档确定可接受的 depth 范围。

返回格式：

API 将返回一个 JSON 数组，该数组的每一个元素代表着订单簿中的一个独立条目。每个订单簿条目对象，如同订单簿上的一个快照，都精细地包含了以下关键字段，以供投资者参考：

• symbol : 合约代码 。这是交易标的的唯一标识符，例如 'BTCUSDT'，明确指明了交易的币种和计价货币。
• id : 订单簿 ID 。一个独特的数字标识符，用于区分订单簿中的每一个条目，方便追踪和管理。
• side : 订单簿方向 ( Buy 或 Sell ) 。清晰地表明了该订单条目是买单（ Buy ）还是卖单（ Sell ），代表了市场参与者的意图。
• size : 订单数量 。代表订单的规模，即买入或卖出的合约单位数量。例如，如果 symbol 是 'BTCUSDT'， size 为 1，则表示 1 个比特币的订单。
• price : 订单价格 。这是该订单的执行价格，单位通常是计价货币，例如 USDT。 订单价格反映了市场参与者愿意买入或卖出该合约的价格水平。

示例 (使用 Python):

此示例演示如何使用 Python 从 BitMEX 获取 XBTUSD 交易对的深度为 5 的订单簿数据。需要安装 requests 库。

import requests

导入 requests 库，用于发送 HTTP 请求。

url = "https://www.bitmex.com/api/v1/orderBook/L2"

定义 BitMEX API 的订单簿端点 URL。 /orderBook/L2 端点提供分层订单簿数据，其中 L2 表示第二级深度。

params = { 'symbol': 'XBTUSD', 'depth': 5 }

定义请求参数。 symbol 参数指定要查询的交易对 (XBTUSD，即比特币/美元)。 depth 参数指定返回的订单簿深度，这里设置为 5，表示返回买单和卖单前五层的价格和数量。

response = requests.get(url, params=params)

使用 requests.get() 方法发送 GET 请求到指定的 URL，并将定义的参数传递给 params 参数。请求的结果存储在 response 对象中。

if response.status_code == 200: order_book = response.() for entry in order_book: print(f"方向: {entry['side']}, 价格: {entry['price']}, 数量: {entry['size']}") else: print(f"请求失败: {response.status_code}")

检查 HTTP 响应状态码。如果状态码为 200，表示请求成功。然后，使用 response.() 方法将响应内容解析为 JSON 格式的 Python 字典或列表，并将其存储在 order_book 变量中。

循环遍历 order_book 列表中的每个条目，每个条目代表订单簿中的一个层级。对于每个条目，打印方向 ( side ，买单或卖单)，价格 ( price ) 和数量 ( size )。

如果响应状态码不是 200，则打印一个错误消息，指示请求失败，并显示 HTTP 状态码。

查询合约信息 ( /api/v1/instrument )

GET /api/v1/instrument 端点允许开发者和交易者获取指定合约的详细信息。 这些信息对于制定交易策略、评估风险以及了解市场微观结构至关重要。 通过此端点，可以检索的关键数据包括：

• 保证金要求: 不同杠杆倍数下的初始保证金和维持保证金比例，用于计算开仓所需的资金量以及维持仓位的最低保证金水平。
• 交易手续费: 该合约的 maker (挂单) 和 taker (吃单) 手续费率，直接影响交易成本和盈利能力。
• 最小委托量: 允许的最小交易数量或合约数量，防止微小订单干扰市场。
• 合约类型: 区分永续合约、交割合约等不同类型的合约，了解其结算机制和到期规则。
• 计价货币和结算货币: 明确合约的交易标的和结算货币，方便资金管理和损益计算。
• 合约乘数: 每个合约代表的标的资产数量，影响盈亏计算。
• 价格精度和数量精度: 允许的价格和数量最小变动单位，影响挂单策略和风险控制。

正确理解和利用通过 /api/v1/instrument 端点获取的信息，有助于优化交易决策，降低交易风险，并更全面地了解市场动态。

请求参数：

• symbol (可选): 合约代码，用于指定需要查询的合约信息。例如， XBTUSD 代表比特币兑美元的永续合约。如果不提供此参数，API 将返回交易所支持的所有合约信息列表，可能包含现货、永续合约、交割合约等多种类型。务必注意，合约代码区分大小写，且必须是交易所支持的有效代码。使用此参数可以精确查找特定合约，提高查询效率。
• filter (可选): JSON 格式的过滤器，允许用户根据特定的合约属性进行筛选。这提供了一种高级查询机制，可以根据合约的特定特征缩小查询范围。

  示例：

  例如，可以使用 {"quoteCurrency": "USD", "underlying": "BTC"} 过滤出所有以美元计价，并以比特币为标的资产的合约。也可以使用 {"settlCurrency": "XBT"} 筛选出结算货币为比特币的所有合约，这在多币种结算的交易所中特别有用。 filter 参数的灵活性极高，可以组合多个条件进行筛选，例如 {"typ": "FFWCSX", "expiry": "2023-12-29"} 可以筛选出特定类型的金融工具和到期日的合约。

  注意事项：

  • filter 参数的值必须是有效的 JSON 字符串。
  • 支持的过滤字段取决于交易所的具体实现。常见的字段包括 typ (合约类型，例如永续合约、交割合约)、 quoteCurrency (报价货币)、 underlying (标的资产)、 settlCurrency (结算货币)、 expiry (到期日) 等。
  • 如果提供的 filter 条件不正确或不被支持，API 可能会返回错误，或者返回的结果不符合预期。请参考交易所的API文档以获取支持的过滤字段和取值的详细信息。

返回格式：

返回一个 JSON 数组，每个元素代表一个合约的详细信息。该数组中的每个 JSON 对象都将包含特定合约的各种属性，例如合约代码（symbol）、底层资产、结算货币、到期日期、杠杆率、以及交易和结算相关的详细参数。这些信息对于评估合约的风险、收益和适用性至关重要。 详细字段的含义和取值范围，请务必参考 BitMEX 官方API文档，确保能够正确解析和使用返回的数据。文档中会详细说明每个字段的类型、单位、以及可能出现的特殊情况，避免因理解偏差导致的交易错误或者数据分析偏差。请注意，BitMEX可能会不定期更新API文档，因此强烈建议定期查阅最新版本，以保持数据的准确性和API调用的兼容性。

查询活跃合约 ( /api/v1/instrument/active )

GET /api/v1/instrument/active 端点允许用户检索当前交易平台上处于活跃状态的合约列表。此接口设计简洁，无需任何请求参数，直接调用即可获取最新的活跃合约数据。

该接口返回的信息通常包括合约代码（instrument code）、合约类型（合约是永续合约、交割合约还是其他类型）、标的资产（例如BTC、ETH等）、以及其他与合约相关的关键参数。开发者可以利用此端点获取的动态信息，进行交易策略的调整和风险管理。

由于活跃合约列表会随着市场变化而更新，因此建议定期调用此接口，以确保获取最新的合约信息。频繁调用可能受到API平台的流量限制，请注意API的使用规范。

返回格式：

接口将返回一个 JSON 数组，其中每个 JSON 对象代表一个合约的详细信息。该数组的每个元素都对应一个可交易或已下线的合约，方便用户全面了解市场上的合约情况。

JSON 数组中的每个元素（即每个合约对象）所包含的字段，与 /api/v1/instrument 接口返回的字段定义完全相同。这意味着用户可以参考 /api/v1/instrument 接口的文档，了解每个字段的具体含义、数据类型和取值范围，从而更好地解析和利用返回的合约信息。

这些字段通常包括但不限于：合约代码、合约名称、合约类型（例如：永续合约、交割合约）、标的资产、报价货币、合约乘数、最小价格变动单位、最大杠杆倍数、手续费率、合约状态（例如：交易中、已下线）、创建时间、修改时间等。通过这些详细字段，用户可以全面了解合约的各项参数和状态，为交易决策提供充分的数据支持。

错误处理

BitMEX API 使用标准的 HTTP 状态码来明确指示每个请求的处理结果。客户端应用程序应始终检查这些状态码，以便妥善处理各种情况。

• 200 OK : 表示请求已成功处理并返回期望的结果。这是最理想的情况，表明API服务器已成功接收、处理并响应了您的请求。
• 400 Bad Request : 指示客户端发送的请求存在问题。这通常意味着请求参数无效、格式不正确或缺少必需的参数。请仔细检查请求的结构和数据类型，确保符合API文档的要求。常见的错误包括参数类型错误、参数范围超出限制、以及JSON格式错误等。
• 401 Unauthorized : 表明客户端未能通过身份验证。这通常是因为提供的API密钥无效、已过期或没有足够的权限访问所请求的资源。请检查您的API密钥是否正确配置，并确认您拥有执行此操作所需的权限。
• 429 Too Many Requests : 指示客户端已超过API的请求频率限制。为了保护服务器的稳定性和可用性，BitMEX API对每个客户端的请求频率进行了限制。当您在短时间内发送过多的请求时，服务器将返回此错误。建议实施速率限制策略，例如使用队列或延迟函数，以避免超过请求频率限制。
• 500 Internal Server Error : 表明服务器在处理请求时遇到了内部错误。这通常是由于服务器端的代码错误或配置问题引起的。如果遇到此错误，请稍后重试该请求。如果问题持续存在，请联系BitMEX技术支持以获得帮助。

在开发与BitMEX API交互的应用程序时，必须编写健壮的错误处理代码，以应对各种可能的错误情况。处理HTTP状态码是至关重要的，例如捕获 400 、 401 、 429 和 500 等错误，并采取适当的措施，例如重试请求、向用户显示错误消息或记录错误日志。BitMEX API具有明确的请求频率限制，旨在防止滥用和确保所有用户的公平访问。当遇到 429 错误时，最佳实践是采用指数退避算法。该算法通过逐渐增加重试请求之间的时间间隔，来避免对服务器造成过大的压力。例如，第一次重试延迟1秒，第二次延迟2秒，第三次延迟4秒，依此类推。这种策略有助于平滑请求流量，并最大限度地减少因超过请求频率限制而导致的错误。