Bybit API就像探险：新手到高手的跃迁指南

2025-03-16 02:12:47 生态阅读 130

Bybit 交易所 API 接口文档详解

本文档旨在详细解读 Bybit 交易所的 API 接口，帮助开发者快速上手并高效地进行程序化交易、数据分析等操作。 Bybit API 提供了一系列功能强大的接口，涵盖行情查询、交易下单、账户管理等多个方面，允许用户安全、可靠地访问 Bybit 交易所的各项服务。

1. 概述

Bybit API 提供了两种主要的访问方式：REST API 和 WebSocket API，它们在设计和应用场景上各有侧重，开发者可以根据具体的业务需求进行选择。

REST API: REST API 采用传统的请求-响应模型，客户端发起请求，服务器返回响应。这种方式特别适合于执行需要明确响应的操作，例如获取历史交易数据、查询账户余额、提交或取消订单等。REST API 的优势在于其简单性和易用性，开发者可以使用标准的 HTTP 方法（GET, POST, PUT, DELETE）与 Bybit 服务器进行交互。REST API 通常支持身份验证和授权机制，确保交易的安全性。
WebSocket API: WebSocket API 则是一种基于双向通信协议的实时数据推送服务。服务器可以主动向客户端推送数据，而无需客户端频繁发起请求。这种方式非常适合于需要实时更新的场景，例如接收实时行情数据（如价格变动、交易量）、订阅账户信息（如余额变动、订单状态更新）。使用 WebSocket API 可以显著降低延迟，并减少服务器的负载，提高应用的响应速度。 Bybit WebSocket API 通常提供多种订阅频道，允许开发者根据自身需求选择需要接收的数据类型。

建议开发者同时掌握 REST API 和 WebSocket API 的使用方法。通过结合两种 API 的优势，可以构建出功能更加完善、性能更优越的应用程序。例如，可以使用 REST API 进行订单管理和账户查询，同时使用 WebSocket API 接收实时行情数据，从而实现自动交易策略或实时监控应用。开发者在使用 API 时，应仔细阅读 Bybit 官方文档，了解 API 的具体参数、返回值格式和使用限制，以确保应用的稳定性和安全性。还应关注 API 的更新和变更，及时调整代码以适应新的版本。

1.1 认证方式

Bybit API 采用 API 密钥认证机制，确保交易的安全性和用户身份的唯一性。用户必须在其 Bybit 账户中生成 API 密钥，并采取一切必要措施来保护这些密钥的安全，避免泄露。API 密钥由两部分组成： API Key (公钥) 和 API Secret (私钥)。 API Key 用于标识用户身份，而 API Secret 则用于对 API 请求进行签名，验证请求的合法性。

在发起 API 请求时，必须将 API Key 嵌入到请求头部（Header）中，以便 Bybit 服务器能够识别发送请求的用户。更重要的是，所有请求参数都需要使用 API Secret 进行加密签名。该签名过程涉及使用特定的哈希算法（例如 HMAC-SHA256）基于请求参数和 API Secret 生成一个唯一的签名字符串。Bybit 服务器会使用相同的算法和存储的 API Secret 重新计算签名，并将其与请求中提供的签名进行比较。只有当两个签名匹配时，请求才会被认为是有效的，并被服务器处理。此签名机制能够有效防止中间人攻击和数据篡改，确保交易数据的完整性和安全性。若签名验证失败，服务器将拒绝该请求。

1.2 速率限制

为了保障 Bybit API 服务的稳定性和公平性，防止恶意请求对系统造成过载，Bybit 实施了速率限制机制。该机制旨在控制每个 API 密钥在特定时间段内可以发送的请求数量。

速率限制的具体数值会根据不同的 API 接口、用户等级以及市场状况而有所不同。例如，交易相关的接口通常会有比行情查询接口更严格的速率限制。用户等级越高，通常可以享受更高的速率限制。

开发者可以通过查看 API 响应头中的以下字段来实时了解当前的速率限制情况，并据此调整请求策略，避免触发速率限制:

X-RateLimit-Limit : 表示在当前时间窗口内允许的最大请求数量。
X-RateLimit-Remaining : 表示在当前时间窗口内剩余的可用请求数量。
X-RateLimit-Reset : 表示速率限制重置的时间戳（通常是 Unix 时间戳），表明下一个时间窗口何时开始。

超出速率限制的请求将会被服务器拒绝，并返回相应的错误代码 (通常是 429 Too Many Requests )。开发者应妥善处理此类错误，例如，实施重试机制，并根据 X-RateLimit-Reset 字段计算等待时间，避免短时间内再次触发速率限制。

为了更有效地管理 API 请求，建议开发者采用以下策略：

批量请求：尽可能将多个相关的请求合并成一个请求。
缓存数据：对于不频繁变化的数据，可以考虑在本地缓存，减少对 API 的请求次数。
合理安排请求时间：避免在短时间内发送大量请求。
使用 WebSocket：对于需要实时更新的数据，可以考虑使用 WebSocket 接口，减少轮询请求。

1.3 错误处理

当与 Bybit API 的交互出现问题时，服务器会返回一个 JSON 格式的响应，其中包含了指示错误类型的错误码以及对错误的详细描述信息。开发者应构建健壮的错误处理机制，以便识别并妥善处理这些错误，从而保证应用程序的稳定性和可靠性。

错误的发生可能源于多种原因，例如客户端的无效请求或服务器端的内部问题。针对不同类型的错误采取适当的措施至关重要。常见的 Bybit API 错误码包括：

10001 : 请求参数错误。这意味着客户端发送的 API 请求中包含了不正确、缺失或格式错误的参数。开发者应仔细检查请求参数，确保其符合 API 文档的规范。常见的错误包括参数类型错误、缺少必选参数、参数值超出范围等。
10002 : API 密钥无效。API 密钥用于验证客户端身份。此错误表明提供的 API 密钥无效或已被禁用。开发者应检查 API 密钥是否正确配置，并确保密钥处于激活状态。如果密钥丢失或泄露，应立即更换。
10003 : 签名验证失败。Bybit API 使用签名机制来确保请求的完整性和安全性。此错误表明请求的签名与服务器计算的签名不匹配。开发者应仔细检查签名算法的实现，确保使用正确的密钥和参数进行签名。时间戳不一致也可能导致签名验证失败，需要同步客户端和服务器的时间。
10004 : 余额不足。在进行交易或下单操作时，此错误表明账户余额不足以完成操作。开发者应检查账户余额，并确保有足够的资金用于交易。可以考虑增加账户余额或调整交易策略。
10005 : 订单不存在。此错误表明请求查询的订单不存在。开发者应检查订单 ID 是否正确，并确保订单已成功创建。订单可能已被取消或成交。
500 : 服务器内部错误。这通常表明 Bybit 服务器遇到了未知的内部问题。开发者应稍后重试请求，并关注 Bybit 的官方公告，以了解是否有服务器维护或故障。如果问题持续存在，应联系 Bybit 技术支持。

除了上述常见的错误码，Bybit API 还会返回其他错误码，开发者应参考 Bybit API 的官方文档，了解所有可能的错误码及其含义。在处理错误时，除了检查错误码之外，还应注意错误信息，错误信息通常提供了更详细的错误描述，有助于开发者定位问题。良好的错误处理机制应包括记录错误日志、通知用户、重试请求等功能，以提高应用程序的健壮性和用户体验。

2. REST API 接口详解

本节将深入探讨常用的 REST API 接口，详细介绍每个接口的功能、请求参数、请求方式（如 GET、POST、PUT、DELETE 等）、以及响应格式。我们将涵盖身份验证、数据获取、交易提交等关键操作涉及的 API 接口，并提供具体示例，帮助开发者更好地理解和使用。

2.1 账户信息查询接口

该接口用于查询指定账户的余额、交易历史、持仓信息等。

功能： 获取用户账户相关的详细信息。

请求方式： GET

请求参数：

account_id (必选): 账户ID，用于标识要查询的账户。
currency (可选): 指定查询的币种，如 BTC、ETH。如果未指定，则返回所有币种的信息。

响应格式： JSON


{
  "account_id": "1234567890",
  "currency": "BTC",
  "balance": "1.5",
  "available": "1.0",
  "frozen": "0.5",
  "transactions": [
    {
      "transaction_id": "tx123",
      "type": "deposit",
      "amount": "0.5",
      "timestamp": "1678886400"
    },
    {
      "transaction_id": "tx456",
      "type": "trade",
      "amount": "-0.2",
      "timestamp": "1678890000"
    }
  ]
}

2.2 交易提交接口

该接口用于提交买入或卖出交易订单。

功能： 提交交易订单到交易平台。

请求方式： POST

请求参数：

symbol (必选): 交易对，如 BTC/USD。
side (必选): 交易方向，"buy" (买入) 或 "sell" (卖出)。
type (必选): 订单类型，"market" (市价单) 或 "limit" (限价单)。
quantity (必选): 交易数量。
price (可选): 限价单的价格，当 type 为 "limit" 时必选。

响应格式： JSON


{
  "order_id": "order789",
  "status": "pending",
  "symbol": "BTC/USD",
  "side": "buy",
  "type": "limit",
  "quantity": "0.1",
  "price": "25000"
}

2.3 市场数据查询接口

该接口用于查询市场行情数据，如最新价格、成交量、深度等。

功能： 获取市场行情数据。

请求方式： GET

请求参数：

symbol (必选): 交易对，如 BTC/USD。

响应格式： JSON


{
  "symbol": "BTC/USD",
  "last_price": "25500",
  "volume": "1000",
  "bid": "25499",
  "ask": "25501",
  "timestamp": "1678893600"
}

2.4 订单状态查询接口

该接口用于查询指定订单的当前状态。状态可能包括：待成交、部分成交、完全成交、已取消等。

功能： 查询订单状态。

请求方式： GET

请求参数：

order_id (必选): 订单ID，用于标识要查询的订单。

响应格式： JSON


{
  "order_id": "order789",
  "status": "filled",
  "filled_quantity": "0.1",
  "average_price": "25000",
  "timestamp": "1678897200"
}

2.5 WebSocket API补充

除了REST API，很多交易所还提供WebSocket API，用于实时推送市场数据和订单状态更新。 WebSocket API能够提供更低延迟的数据流，适合高频交易和实时监控。

需要注意的是，以上仅为部分常用的 REST API 接口示例。实际的 API 接口会因交易所或平台的不同而有所差异，开发者应参考具体的 API 文档进行开发。进行API调用时，务必注意API的使用频率限制，避免触发限流机制。

2.1 获取服务器时间

接口描述: 获取Bybit服务器的当前时间戳，精度包含秒和纳秒，可用于同步客户端时间或进行时间相关逻辑处理。
接口地址: /v3/public/time
请求方式: GET
请求参数: 无 (该接口无需任何请求参数)
响应格式: JSON

响应示例:


{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
        "timesecond": "1678886400",
        "timenano": "1678886400123456789"
    },
    "retExtInfo": {},
    "time": 1678886400123
}

字段说明:

retCode : 返回码， 0 表示成功。
retMsg : 返回信息， "OK" 表示请求成功。
result : 返回结果对象，包含服务器时间信息。
- time second : 服务器时间的秒级时间戳，Unix时间戳，例如： "1678886400" 。
- time_nano : 服务器时间的纳秒级时间戳，例如： "1678886400123456789" 。用于更高精度的时间同步。
retExtInfo : 扩展信息，当前通常为空对象 {} 。
time : 服务器时间的毫秒级时间戳，例如： 1678886400123 。为了兼容性，仍然提供毫秒级时间戳。

使用场景:

该接口主要用于获取 Bybit 服务器的当前时间，特别适用于以下场景：

时间同步: 客户端可以使用该接口返回的时间戳校准本地时间，确保与服务器时间一致，避免因时间偏差导致的问题。
交易策略: 在编写交易策略时，可能需要依赖服务器时间进行判断和决策，例如在特定时间执行交易，或者根据时间窗口计算指标。
数据分析: 在分析历史数据时，可以使用该接口返回的时间戳作为参考，确保数据的时间准确性。
风控系统: 风控系统可以利用服务器时间进行风险控制，例如限制特定时间段内的交易行为。

注意事项:

频繁调用该接口可能会增加服务器压力，建议合理控制调用频率。
不同的编程语言处理时间戳的方式可能不同，请根据实际情况进行转换。

2.2 获取交易对信息

接口地址: /v3/public/instruments-info
请求方式: GET
描述: 此接口用于检索特定或所有交易对的详细参数和配置信息，对于了解交易规则至关重要。
请求参数:
- symbol : (必选) 交易对标识符，指定要查询的交易对，例如 BTCUSDT 。如果不提供该参数，将返回所有交易对的信息。
响应格式: JSON

响应示例:


{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
        "category": "linear",
        "list": [
            {
                "symbol": "BTCUSDT",
                "contractType": "LinearPerpetual",
                "status": "Trading",
                "baseCoin": "BTC",
                "quoteCoin": "USDT",
                "launchTime": "1579036800000",
                "deliveryTime": "",
                "deliveryFeeRate": "",
                "priceScale": "1",
                "leverageFilter": {
                    "minLeverage": "1",
                    "maxLeverage": "100",
                    "leverageStep": "0.01"
                },
                "priceFilter": {
                    "minPrice": "0.5",
                    "maxPrice": "999999",
                    "tickSize": "0.5"
                },
                "lotSizeFilter": {
                    "maxTradingQty": "100",
                    "minTradingQty": "0.001",
                    "qtyStep": "0.001"
                }
            }
        ]
    },
    "retExtInfo": {},
    "time": 1678886400123
}

响应字段说明:
- retCode : 返回代码， 0 表示成功。
- retMsg : 返回消息，例如 "OK"。
- result : 包含实际数据的对象。
- category : 产品类型，例如 "linear"（线性合约）。
- list : 包含交易对信息的数组，每个元素代表一个交易对。
- symbol : 交易对名称，例如 "BTCUSDT"。
- contractType : 合约类型，例如 "LinearPerpetual"（线性永续合约）。
- status : 交易对状态，例如 "Trading"（交易中）。
- baseCoin : 基础货币，例如 "BTC"。
- quoteCoin : 报价货币，例如 "USDT"。
- launchTime : 上线时间，Unix 时间戳（毫秒）。
- deliveryTime : 交割时间，仅适用于交割合约。
- deliveryFeeRate : 交割手续费率，仅适用于交割合约。
- priceScale : 价格精度，表示价格的小数位数。
- leverageFilter : 杠杆过滤信息。
  - minLeverage : 最小杠杆倍数。
  - maxLeverage : 最大杠杆倍数。
  - leverageStep : 杠杆步进。
- priceFilter : 价格过滤信息。
  - minPrice : 最小价格。
  - maxPrice : 最大价格。
  - tickSize : 最小价格变动单位。
- lotSizeFilter : 交易数量过滤信息。
  - maxTradingQty : 最大交易数量。
  - minTradingQty : 最小交易数量。
  - qtyStep : 交易数量步进。
- retExtInfo : 扩展信息，通常为空对象。
- time : 服务器时间，Unix 时间戳（毫秒）。

该接口提供关于特定交易对的关键信息，包括其交易状态、合约类型、以及重要的交易限制，如最小/最大交易数量、价格精度和可用的杠杆范围。开发者可以利用这些信息来构建交易策略，执行风险管理，并向用户展示准确的市场数据。 launchTime 字段提供了关于该交易对在交易所上线时间的关键信息，帮助用户了解市场历史。 priceScale 字段对于精确计算利润和损失至关重要。

2.3 下单

接口地址: /v3/private/order/create
请求方式: POST
请求参数:

symbol : (必选) 交易对，用于指定交易的市场。例如， BTCUSDT 表示比特币兑美元的交易对。务必使用交易所支持的交易对代码。
side : (必选) 买卖方向，指定是买入还是卖出。 Buy 表示买入，也称为做多； Sell 表示卖出，也称为做空。
orderType : (必选) 订单类型，定义订单的执行方式。 Market 表示市价单，以当前市场最优价格立即成交； Limit 表示限价单，需要指定价格，只有当市场价格达到指定价格时才成交。
qty : (必选) 数量，表示交易的合约数量。数量必须是正整数，且符合交易所规定的最小交易单位。
price : (可选) 价格，仅当 orderType 为 Limit (限价单) 时需要提供。指定希望成交的价格。
timeInForce : (可选) 有效时间，定义订单的有效时长，决定订单在多长时间内有效。 GTC (Good-Til-Cancel) 表示一直有效，直到订单被完全成交或手动取消； IOC (Immediate-Or-Cancel) 表示立即成交，否则取消； FOK (Fill-Or-Kill) 表示必须全部立即成交，否则取消。如果不提供，通常默认为 GTC 。
reduceOnly : (可选) 是否只平仓，用于控制订单是否只允许减少仓位。 true 表示只允许平仓，不允许开新仓； false 表示允许开新仓。默认为 false 。这个参数通常用于交易永续合约或期货合约。
closeOnTrigger : (可选) 是否触发时平仓，用于条件单。 true 表示当止盈/止损被触发时，自动平掉所有仓位。 false 表示仅仅执行止盈/止损单。默认为 false 。
takeProfit : (可选) 止盈价格，当市场价格达到指定价格时，自动平仓以锁定利润。必须大于当前市场价格（对于做多）或小于当前市场价格（对于做空）。
stopLoss : (可选) 止损价格，当市场价格达到指定价格时，自动平仓以限制损失。必须小于当前市场价格（对于做多）或大于当前市场价格（对于做空）。

响应格式:

{ "retCode": 0, "retMsg": "OK", "result": { "orderId": "1234567890abcdef", "orderLinkId": "" }, "retExtInfo": {}, "time": 1678886400123 }

该接口用于提交订单到交易平台。调用此接口需要根据实际交易需求设置不同的参数，包括交易对、买卖方向、订单类型和数量等。正确配置这些参数对于成功提交订单至关重要。 retCode 为0表示成功， orderId 是交易所生成的唯一订单ID， orderLinkId 是用户自定义的订单ID，可用于关联和追踪订单。

2.4 撤单

接口地址: /v3/private/order/cancel
请求方式: POST
描述: 撤销指定的挂单请求。
请求参数:
- symbol : (必选) 交易对，指定需要撤销订单的交易市场。例如， BTCUSDT 表示比特币兑美元交易对。
- orderId : (可选) 交易所订单 ID，用于唯一标识要撤销的订单。如果提供此参数，则优先使用此参数进行撤单。请注意，订单 ID 由交易所生成。
- orderLinkId : (可选) 客户端自定义订单 ID。允许用户自定义订单 ID，方便追踪订单状态。如果未提供 orderId ，系统将尝试使用此参数查找并撤销相应的订单。

请求示例:

以下是一个使用 orderId 撤单的示例请求：

POST /v3/private/order/cancel
{
  "symbol": "BTCUSDT",
  "orderId": "1234567890abcdef"
}

以下是一个使用 orderLinkId 撤单的示例请求：

POST /v3/private/order/cancel
{
  "symbol": "BTCUSDT",
  "orderLinkId": "your_custom_order_id"
}

响应格式:

以下是成功的撤单请求的响应示例：

{
  "retCode": 0,
  "retMsg": "OK",
  "result": {
    "orderId": "1234567890abcdef"
  },
  "retExtInfo": {},
  "time": 1678886400123
}

响应字段:
- retCode : 返回代码。 0 表示成功。
- retMsg : 返回消息。 OK 表示操作成功。
- result : 包含操作结果的对象。
  - orderId : 被撤销的订单的交易所订单 ID。
- retExtInfo : 扩展信息，通常为空对象 {} 。
- time : 服务器时间戳，表示处理请求的时间。
注意事项:
- 如果同时提供 orderId 和 orderLinkId ，系统将优先使用 orderId 进行撤单。
- 如果指定的订单不存在或已成交/撤销，撤单请求可能会失败，并返回相应的错误代码。请检查 retCode 和 retMsg 以确定撤单请求是否成功。
- 高频交易或网络拥堵情况下，可能会出现撤单延迟。

该接口用于撤销指定订单。可以通过 orderId 或 orderLinkId 指定要撤销的订单。

2.5 获取订单列表

接口地址: /v3/private/order/list
请求方式: GET
描述: 该接口用于查询用户的历史订单或当前挂单。通过不同的参数组合，可以精确筛选所需订单信息，并支持分页查询，方便大量订单数据的管理。
请求参数:
- symbol : (可选) 交易对，指定要查询的交易对，例如 BTCUSDT 。如果未提供，则返回所有交易对的订单。
- orderId : (可选) 订单 ID，通过订单ID精确查询特定订单。如果提供了此参数，将忽略其他过滤条件，直接返回该订单的信息（如果存在）。
- orderLinkId : (可选) 客户端订单 ID，通常由客户端生成并用于标识订单。允许使用客户端自定义的ID进行查询。
- orderStatus : (可选) 订单状态，筛选特定状态的订单。有效值包括 New (新订单), PartiallyFilled (部分成交), Filled (完全成交), Canceled (已取消), Rejected (已拒绝), PendingCancel (等待取消)。
- limit : (可选) 返回数量上限，指定单次请求返回的订单数量。默认为 20，最大值为 100。超出范围的值将被截断到允许的最大值。
- cursor : (可选) 分页游标，用于分页查询。第一次请求时无需提供，后续请求可以使用前一次响应中返回的 cursor 值，从而获取下一页的数据。
- 时间范围参数 : (可选，高级) 可以添加起始时间和结束时间参数，进一步筛选特定时间段内的订单。例如, startTime 和 endTime ，通常以 Unix 时间戳（毫秒）表示。
请求频率限制: 需要注意该接口的请求频率限制，过频繁的请求可能会被限制访问。建议合理设置请求间隔，并使用分页查询避免一次性请求过多数据。
响应格式:

示例响应：


{
  "retCode": 0,
  "retMsg": "OK",
  "result": {
    "cursor": "abcdef1234567890",
    "result": [
      {
        "symbol": "BTCUSDT",
        "orderId": "1234567890abcdef",
        "orderLinkId": "",
        "side": "Buy",
        "orderType": "Limit",
        "price": "10000",
        "qty": "0.01",
        "orderStatus": "New",
        "timeInForce": "GTC",
        "createdAt": "1678886400123",
        "updatedAt": "1678886400123",
        "reduceOnly": false,
        "closeOnTrigger": false,
        "leavesQty": "0.01",
        "cumExecQty": "0",
        "cumExecValue": "0",
        "cumExecFee": "0",
        "lastPriceOnCreated": "0",
        "rejectReason": ""
      }
    ]
  },
  "retExtInfo": {},
  "time": 1678886400123
}

字段解释:

retCode : 返回码， 0 表示成功，其他值表示失败。
retMsg : 返回信息，描述请求结果。
result.cursor : 分页游标，用于获取下一页的数据。
result.result : 订单列表，包含多个订单对象。
symbol : 交易对。
orderId : 订单 ID。
orderLinkId : 客户端订单 ID。
side : 订单方向， Buy (买入) 或 Sell (卖出)。
orderType : 订单类型， Limit (限价单), Market (市价单)。
price : 订单价格。
qty : 订单数量。
orderStatus : 订单状态。
timeInForce : 有效时间， GTC (Good Till Cancelled，撤销前有效), IOC (Immediate Or Cancel，立即成交否则取消), FOK (Fill Or Kill，完全成交否则取消)。
createdAt : 订单创建时间（Unix 时间戳，毫秒）。
updatedAt : 订单更新时间（Unix 时间戳，毫秒）。
reduceOnly : 是否为只减仓订单 (仅适用于衍生品)。
closeOnTrigger : 是否以触发价平仓 (仅适用于条件单)。
leavesQty : 剩余未成交的数量。
cumExecQty : 累计成交的数量。
cumExecValue : 累计成交的价值。
cumExecFee : 累计成交的手续费。
lastPriceOnCreated : 创建时的最后价格。
rejectReason : 订单被拒绝的原因 (如果订单被拒绝)。

该接口用于获取订单列表，可以根据不同的条件进行筛选和分页。合理利用这些参数，可以构建出灵活的订单查询功能，方便用户进行订单管理和分析。

2.6 获取持仓信息

接口地址: /v3/private/position/list
请求方式: GET
请求参数:
- symbol : (可选) 交易对，指定需要查询的交易对，例如 BTCUSDT 。如果不提供此参数，则返回所有交易对的持仓信息。交易对必须是交易所支持的有效交易对。
响应格式:

以下是一个成功响应的示例，展示了接口返回的数据结构。 retCode 为 0 表示请求成功。 result 字段包含了持仓信息列表。

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
        "list": [
            {
                "symbol": "BTCUSDT",
                "size": "0.01",
                "side": "Buy",
                "entryPrice": "20000",
                "liqPrice": "19000",
                "leverage": "10",
                "pnl": "0.0005",
                "unrealizedPnl": "0.0002",
                "markPrice": "20002",
                "positionValue": "200"
            }
        ]
    },
    "retExtInfo": {},
    "time": 1678886400123
}

该接口用于查询用户的持仓信息。通过此接口，可以获取关于特定交易对或所有交易对的详细持仓数据，包括但不限于：

symbol : 交易对，例如 BTCUSDT 。
size : 持仓数量，表示当前持有的合约数量。
side : 持仓方向， Buy 表示多仓 (做多)， Sell 表示空仓 (做空)。
entryPrice : 平均持仓价格，也称为开仓均价。
liqPrice : 预估强平价格，当市场价格达到或超过该价格时，持仓可能被强制平仓。
leverage : 杠杆倍数，表示用户使用的杠杆比例。
pnl : 已实现盈亏，指已经平仓部分的盈亏。
unrealizedPnl : 未实现盈亏，指当前持仓的盈亏，根据标记价格计算。
markPrice : 标记价格，用于计算未实现盈亏和强平价格。
positionValue : 持仓价值，以当前标记价格计算的持仓总价值。

请注意，强平价格 liqPrice 仅为预估值，实际强平价格可能受到市场波动、流动性等因素的影响。用户应密切关注市场动态，合理控制仓位和风险。

3. WebSocket API 接口详解

Bybit WebSocket API 提供实时、低延迟的数据推送服务，它允许用户通过建立持久的双向通信连接，实时订阅并接收来自Bybit交易所的各种市场数据和个人账户信息。相比传统的REST API轮询方式，WebSocket API可以显著降低延迟，提高数据获取效率，尤其适用于高频交易和算法交易。

通过WebSocket API，用户可以订阅的市场数据包括：

实时价格数据： 最新成交价、买一价、卖一价等。
深度行情数据： 订单簿的实时变化，包括买单和卖单的价格和数量。
K线数据： 不同时间周期的K线图数据，例如1分钟、5分钟、1小时等。
交易数据： 最新成交的交易记录，包括成交价格、数量和方向。
指数数据： Bybit平台的各类指数数据。
合约信息： 合约的详细信息，例如合约乘数、最小价格变动单位等。

用户还可以订阅账户相关的实时信息，包括：

仓位信息： 实时仓位数据，包括持仓数量、平均开仓价格、盈亏等。
订单信息： 订单状态的实时更新，包括订单创建、成交、取消等。
资金信息： 账户余额、可用保证金、已用保证金等。

使用Bybit WebSocket API，开发者可以构建各种实时应用，例如：

自动化交易系统： 根据实时市场数据自动执行交易策略。
风险管理系统： 实时监控账户风险，及时发出预警。
数据分析平台： 对实时市场数据进行分析和可视化。

通过有效地利用WebSocket API，用户可以及时掌握市场动态，优化交易策略，从而提高交易效率和盈利能力。

3.1 连接地址

访问Bybit实时数据流，您需要建立WebSocket连接。Bybit提供主网和测试网两种环境，方便开发者进行实盘交易和模拟测试。

主网:
wss://stream.bybit.com/realtime

主网连接用于访问真实的Bybit交易数据。请确保您的应用程序已准备好处理实盘交易数据，并已充分理解Bybit的交易规则和API文档。
测试网:
wss://stream-testnet.bybit.com/realtime

测试网连接提供了一个模拟交易环境，允许您在不冒真实资金风险的情况下测试您的策略和应用程序。建议在将应用程序部署到主网之前，先在测试网上进行充分的测试。

请注意，测试网的数据与主网的数据是独立的，测试网上的交易不会影响主网上的市场。

在建立WebSocket连接时，请确保您的客户端支持WSS协议（WebSocket Secure），该协议使用TLS/SSL加密来保护数据传输的安全性。连接建立后，您可以通过发送订阅消息来接收特定交易对或主题的实时数据。

请参考Bybit官方API文档，了解更多关于WebSocket连接和订阅消息的详细信息。

3.2 认证

与服务器建立 WebSocket 连接后，客户端需要发送认证消息来验证身份，确保通信安全并获得访问权限。认证消息采用 JSON 格式，需严格按照规范构造，否则可能导致认证失败。

认证消息的 JSON 格式如下：

{
  "op": "auth",
  "args": [
    "YOUR_API_KEY",
    "TIMESTAMP",
    "SIGNATURE"
  ]
}

其中，各字段的含义和构造方式如下：

YOUR_API_KEY : 您的 API Key，用于唯一标识您的账户。请务必妥善保管，避免泄露。API Key 通常在您的账户管理页面生成和管理。
TIMESTAMP : 当前时间戳，表示发送认证消息时的 Unix 时间，精确到秒级。您可以使用编程语言提供的函数 (例如 Python 的 time.time() ) 获取当前时间戳。时间戳的目的是防止重放攻击，服务器会验证时间戳的有效性，例如，时间戳与服务器当前时间的差值超过一定范围，认证将失败。
SIGNATURE : 签名，用于验证消息的完整性和发送者的身份。签名需要使用您的 API Secret 对特定字符串进行 HMAC-SHA256 加密计算。计算签名的字符串格式为 "op=auth&args=[YOUR_API_KEY,TIMESTAMP]" 。务必注意字符串的大小写和顺序，以及连接符 & 的使用。您需要使用 API Secret 作为密钥，对上述字符串进行 HMAC-SHA256 运算，得到的十六进制字符串即为签名。例如，在 Python 中，可以使用 hmac 模块进行签名计算。

示例 (Python):


import hmac
import hashlib
import time
import 

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
TIMESTAMP = str(int(time.time()))

string_to_sign = f"op=auth&args=[{API_KEY},{TIMESTAMP}]"
signature = hmac.new(
    API_SECRET.encode('utf-8'),
    string_to_sign.encode('utf-8'),
    hashlib.sha256
).hexdigest()

auth_message = {
    "op": "auth",
    "args": [
        API_KEY,
        TIMESTAMP,
        signature
    ]
}

print(.dumps(auth_message))

注意事项：

请将代码中的 YOUR_API_KEY 和 YOUR_API_SECRET 替换为您的实际 API Key 和 API Secret。
API Secret 必须严格保密，切勿泄露给他人或存储在不安全的地方。
时间戳的精度需要与服务器的要求一致，通常为秒级。
签名算法必须与服务器的要求一致，通常为 HMAC-SHA256。
在不同的编程语言中，HMAC-SHA256 算法的实现方式可能略有不同，请参考相应的文档。
成功发送认证消息后，服务器会返回认证结果，请根据返回结果判断认证是否成功。
如果认证失败，请检查 API Key、API Secret、时间戳和签名是否正确。

3.3 订阅

完成身份认证后，用户可以通过发送订阅消息来实时接收不同频道的更新信息。订阅功能允许用户根据自身需求，定制化地获取所需的数据流。订阅消息遵循以下JSON格式：

{
  "op": "subscribe",
  "args": [
    "topic1",
    "topic2",
    ...
  ]
}

在上述JSON结构中， op 字段的值固定为 "subscribe" ，用于指示订阅操作。 args 字段是一个数组，其中包含一个或多个字符串，每个字符串代表一个需要订阅的频道名称。通过在 args 数组中添加不同的频道名称，用户可以同时订阅多个频道。

以下是一些常用的频道及其所提供的信息：

publicTrade. : 提供特定交易对的实时成交数据。需要替换为具体的交易对代码，例如 publicTrade.BTC-USDT 。该频道提供每一笔成交的价格、数量、交易方向等信息。用户可以通过该频道实时追踪市场交易动态。
instrument_info. : 提供特定交易对的详细信息。同样需要替换为具体的交易对代码，例如 instrument_info.ETH-USDT 。该频道提供交易对的合约乘数、最小下单数量、价格精度等重要参数。该频道信息更新频率较低，主要用于获取交易对的静态信息。
order : 提供用户订单状态的实时更新。任何订单的创建、成交、取消等状态变化都会通过该频道推送给用户。用户可以通过该频道实时监控自己的订单执行情况。为了安全考虑，该频道需要身份验证才能订阅。
position : 提供用户持仓信息的实时更新。任何持仓数量、平均持仓成本、盈亏等信息的变化都会通过该频道推送给用户。用户可以通过该频道实时监控自己的持仓情况。同样，该频道需要身份验证才能订阅。

请注意，订阅频道时务必区分大小写。某些频道可能需要额外的权限或身份验证才能成功订阅。建议查阅API文档，了解每个频道的具体要求和使用限制。

3.4 取消订阅

取消订阅功能允许用户停止接收特定频道或主题的实时更新。这对于管理信息流、降低服务器负载以及优化用户体验至关重要。要取消订阅，客户端需要向服务器发送一个特定的“取消订阅”消息。

取消订阅消息的格式遵循JSON结构，包含一个操作码（"op"）和一个参数列表（"args"）。操作码明确指示服务器执行“取消订阅”操作，参数列表则包含了要取消订阅的频道或主题的名称。服务器收到此消息后，会从相应的订阅列表中移除客户端，从而停止向其推送相关消息。

取消订阅消息的具体格式如下：


{
  "op": "unsubscribe",
  "args": [
    "topic1",
    "topic2",
    ...
  ]
}

字段解释：

op: 字符串类型，固定值为 "unsubscribe"，表示取消订阅操作。
args: 数组类型，包含一个或多个字符串，每个字符串代表一个要取消订阅的主题或频道。例如， "topic1" 可能代表一个特定的加密货币交易对，而 "topic2" 可能代表与该交易对相关的市场新闻更新。

重要注意事项：

客户端可以一次性取消订阅多个主题，只需将它们添加到 "args" 数组中。
服务器应验证取消订阅请求，确保客户端具有取消订阅指定主题的权限。
服务器应返回一个确认消息，表明取消订阅操作已成功完成。失败情况也应通过适当的错误消息进行报告。
主题名称区分大小写。客户端需要确保提供的主题名称与订阅时使用的名称完全一致。

3.5 心跳机制

为了维护客户端与服务器之间的持久连接，并确保通信链路的活跃性，需要实现一种周期性的心跳机制。心跳机制的目的是检测连接是否仍然有效，防止因长时间空闲导致的连接断开，尤其是在网络环境不稳定的情况下。

客户端需要按照预定的时间间隔，向服务器发送心跳消息。这种心跳消息通常是一个轻量级的请求，用于告知服务器客户端仍然处于活动状态。心跳消息的典型格式如下，使用JSON格式表达：


{
  "op": "ping"
}

"op" 字段代表操作类型，此处 "ping" 表示这是一个心跳探测请求。这种简洁的格式减少了网络传输的开销，提高了效率。

服务器在接收到客户端发送的 {"op": "ping"} 心跳消息后，必须立即回复一个确认消息，表明服务器正常运行并能够响应客户端的请求。服务器回复的消息通常为：


{
  "op": "pong"
}

"pong" 对应于 "ping" ，表示服务器成功接收并响应了心跳请求。如果客户端在预定的时间内没有收到服务器的 {"op": "pong"} 响应，则客户端可以认为连接已经断开，需要重新建立连接。心跳间隔的具体时长需要根据实际应用场景和网络环境进行调整，以达到最佳的保活效果。

4. 签名算法

Bybit API 采用 HMACSHA256（Hash-based Message Authentication Code using SHA256）算法对所有 API 请求的参数进行签名，从而验证请求的来源以及确保数据的完整性和真实性。该签名机制能够有效防止恶意篡改和重放攻击，是保证交易安全的关键环节。以下是详细的签名步骤：

参数排序与拼接：
必须将所有参与请求的参数按照其键（Key）的字母升序进行排列。注意，仅包括直接作为请求参数传递的键值对，不包括请求体（request body）中的参数。然后，将排序后的参数键值对以 key=value 的形式拼接成一个字符串。键值对之间使用 & 符号连接。务必确保参数值已进行 URL 编码（如果需要）。例如： apiKey=YOUR_API_KEY&orderType=Market&qty=0.01&side=Buy&symbol=BTCUSDT&timestamp=1678886400
HMACSHA256 签名：
使用您的 API Secret 作为密钥（Key），对上一步骤中拼接好的字符串进行 HMACSHA256 签名。 API Secret 必须妥善保管，切勿泄露。不同编程语言的 HMACSHA256 实现方式略有不同，请参考相应的文档。
十六进制转换：
将 HMACSHA256 签名后的结果（通常是二进制数据）转换为十六进制字符串表示。这是因为十六进制字符串更易于在 HTTP 请求头中传输。大多数编程语言都提供了将二进制数据转换为十六进制字符串的函数或库。
签名加入请求头：
将生成的签名结果（十六进制字符串）添加到 HTTP 请求头中。 Bybit API 约定将签名放在名为 HMACSHA256 的请求头字段中。例如： HMACSHA256: YOUR_SIGNATURE 。请确保请求头中包含 Content-Type，例如 "Content-Type: application/"。

5. 常见问题

如何获取 API 密钥？
- 登录 Bybit 官网，进入您的账户中心，导航至 API 管理页面，创建一个新的 API 密钥。创建过程中，您需要设置 API 密钥的权限，例如交易、提现等。务必仔细阅读并理解各项权限的含义，仅赋予密钥所需的最小权限集，以降低安全风险。创建完成后，请妥善保管您的 API 密钥和密钥，Bybit 不会再次显示密钥，如果丢失只能重新创建。
如何处理 API 请求错误？
- 当 API 请求失败时，查看 API 响应中的 retCode （返回码）和 retMsg （返回信息）字段。 retCode 是一个数值，指示错误类型， retMsg 提供了更详细的错误描述。Bybit 官方文档中会列出常见的 retCode 及其含义，根据这些信息，您可以诊断问题并采取相应的处理措施，例如检查请求参数、网络连接或服务器状态。请特别注意HTTP状态码，200代表请求成功，非200状态码需要额外关注。
如何避免达到速率限制？
- API 速率限制是为了保护 Bybit 系统免受滥用，确保所有用户的稳定服务。优化代码逻辑，例如批量处理订单，减少不必要的 API 请求。如果需要实时数据，强烈建议使用 WebSocket API 接收数据流，避免频繁轮询 REST API 接口。使用 WebSocket 可以显著降低 API 请求频率，同时提供更低的延迟。如果必须使用REST API，在代码中实现指数退避算法，当遇到速率限制时，逐渐增加请求之间的间隔。
如何保证 API 密钥的安全？
- API 密钥是访问您 Bybit 账户的凭证，必须妥善保管，切勿泄露给任何第三方。定期更换 API 密钥，降低密钥泄露后的潜在风险。强烈建议您设置 API 密钥的权限，仅允许其执行必要的交易操作，避免未经授权的提现或其他敏感操作。启用双因素身份验证 (2FA) 增加账户安全性。避免将 API 密钥硬编码到代码中，使用环境变量或配置文件安全地存储密钥。
测试网和主网有什么区别？
- Bybit 提供测试网 (Testnet) 和主网 (Mainnet) 两种环境。测试网是一个模拟交易环境，您可以在其中使用模拟资金测试 API 接口的功能和性能，而不会产生任何实际的资金损失。主网是真实的交易环境，所有交易都会涉及真实资金。在将 API 代码部署到主网之前，务必先在测试网上进行充分的测试和验证，确保代码的正确性和稳定性。请注意，测试网的数据和主网的数据是隔离的。

Bybit API就像探险：新手到高手的跃迁指南

Bybit 交易所 API 接口文档详解

1. 概述

1.1 认证方式

1.2 速率限制

1.3 错误处理

2. REST API 接口详解

2.1 获取服务器时间

2.2 获取交易对信息

2.3 下单

2.4 撤单

2.5 获取订单列表

2.6 获取持仓信息

3. WebSocket API 接口详解

3.1 连接地址

3.2 认证

3.3 订阅

3.4 取消订阅

3.5 心跳机制

4. 签名算法

5. 常见问题

必看！2024 年 Kraken 瑞波币 (XRP) 手续费降低终极攻略

币安安全攻略：像堡垒一样保护你的加密资产！

相关推荐

Bybit 资金费率全解析：2024 年交易者必看！

掌握 Coinbase API：2024 最新教程，你的加密货币应用开发指南！

想省币圈手续费？欧易 Bybit 隐藏优惠大揭秘！

专家揭秘：Bybit 如何凭借 5 大优势领跑加密货币衍生品交易？

Bybit币种选择指南：像选马拉松伙伴一样！ (2024最新)

Bybit 更新就像瑞士军刀，交易功能全面升级！

绝对干货！Bybit 银行卡充值教程：你一定要知道的秘密！

期权交易风险管控：抹茶与Bybit实战策略，高手都在用！

2024 最新：像马拉松一样购买 DigiByte (DGB) 的 Bybit 技巧！

必看！掌握这 3 个 Bybit 合约交易技巧，助你快速入门