Bybit API 使用教程详解

Bybit API 提供了与 Bybit 交易所进行交互的强大工具，允许开发者构建自动化交易机器人、数据分析工具以及其他定制化应用。本文将深入探讨 Bybit API 的使用方法，涵盖认证、常用接口、代码示例等方面，帮助读者快速上手。

1. 准备工作

在使用 Bybit API 之前，为了确保顺利对接并安全地进行交易，需要完成以下详细的准备工作：

• 注册 Bybit 账户: 访问 Bybit 官方网站 ( https://www.bybit.com/ ) 并完成账户注册流程。注册过程可能包括邮箱或手机号码验证，请按照页面提示完成操作。
• 创建 API 密钥: 成功登录 Bybit 账户后，导航至账户管理或 API 管理页面。在此页面，你可以创建新的 API 密钥对。API 密钥由两部分组成：API Key 和 API Secret。API Key 类似于你的用户名，用于标识你的身份。API Secret 则相当于密码，用于对 API 请求进行签名，确保请求的真实性和完整性。请务必妥善保管 API Secret，切勿以任何方式泄露给他人。创建 API 密钥时，Bybit 允许你设置不同的权限，例如只读权限（仅能获取数据，不能进行交易）、交易权限（可以进行交易操作）以及提现权限（允许从账户提现资金，强烈建议不要开启此权限，除非有特殊需求）。根据你的实际需求，遵循最小权限原则，选择最合适的权限组合。请注意，某些权限可能需要进行额外的身份验证。创建完成后，请务必将 API Key 和 API Secret 存储在安全的地方，因为 API Secret 只会显示一次。
• 选择编程语言: Bybit API 提供了广泛的语言支持，包括但不限于 Python、Java、JavaScript、Go、C# 和 PHP 等。选择你最熟悉且擅长的编程语言，这将显著提高开发效率和代码质量。同时，也需要考虑该语言是否有成熟的 Bybit API SDK 或第三方库可用，这些库可以简化 API 调用过程，减少重复代码的编写。
• 安装必要的库: 根据所选的编程语言，安装相应的 HTTP 客户端库以及任何必要的 Bybit API SDK 或第三方库。例如，如果选择 Python，常用的 HTTP 客户端库包括 requests 、 aiohttp 和 httpx 。如果使用 Bybit 官方或第三方 SDK，通常会包含对 API 接口的封装，简化了身份验证、数据序列化和错误处理等操作。务必查阅所选库的官方文档，了解如何正确安装和使用。例如，对于 Python 的 requests 库，可以使用 pip install requests 命令进行安装。

2. 认证方式

Bybit API 采用 HMAC-SHA256 算法进行身份验证，确保请求的完整性和真实性。所有对 API 的调用都必须包含一个数字签名，该签名通过对请求参数、您的 API Secret 密钥以及当前时间戳进行加密计算得出。这种机制可以有效防止未经授权的访问，并确保数据在传输过程中未被篡改。

HMAC-SHA256 （Hash-based Message Authentication Code with SHA-256）是一种消息认证码算法，它结合了哈希函数 SHA-256 和密钥来生成签名。SHA-256 是一种安全哈希算法，产生 256 位的哈希值，用于保证数据的完整性。HMAC 利用密钥来增强哈希函数的安全性，防止中间人攻击。

以下 Python 代码示例演示了如何生成符合 Bybit API 要求的签名：

import hashlib
import hmac
import time
import urllib.parse

def generate_signature(api_secret, params_string, timestamp):
  """
  生成 Bybit API 签名.

  Args:
    api_secret: 您的 API Secret 密钥. 这是您账户的私有密钥，必须妥善保管。
    params_string: 请求参数字符串 (已进行 URL 编码). 包含所有请求参数，例如交易对、数量、价格等，并按照 URL 编码规范进行编码。
    timestamp: 当前 Unix 时间戳 (秒).  表示请求发送的时间，用于防止重放攻击。

  Returns:
    十六进制签名字符串 (小写).
  """
  param_str = str(timestamp) + params_string  # 时间戳必须是字符串类型
  hash = hmac.new(api_secret.encode("utf-8"), param_str.encode("utf-8"), hashlib.sha256)
  signature = hash.hexdigest() # 获取十六进制表示的签名
  return signature

代码详解：

• 导入必要的 Python 模块： hashlib （用于哈希计算）、 hmac （用于生成 HMAC）、 time （用于获取时间戳）和 urllib.parse (用于 URL 编码，虽然示例中没有直接使用，但在实际应用中，参数需要进行 URL 编码)。
• generate_signature 函数接收三个参数：您的 api_secret 、经过 URL 编码的 params_string 和 timestamp 。
• 将时间戳和参数字符串连接起来，组成签名的基础字符串 param_str 。 务必确保时间戳是字符串类型。
• 使用 hmac.new 创建一个 HMAC 对象，指定 api_secret 作为密钥， param_str 作为消息，以及 hashlib.sha256 作为哈希算法。
• 调用 HMAC 对象的 hexdigest() 方法，生成十六进制表示的签名字符串。
• 返回生成的签名。

在构建 API 请求时，您需要将 API Key 、 timestamp 和生成的 signature 添加到请求头部（Headers）或查询字符串中，具体取决于 Bybit API 的接口要求。通常， API Key 用于标识您的身份， timestamp 用于防止重放攻击，而 signature 用于验证请求的完整性。

示例请求头：

X-BAPI-API-KEY: YOUR_API_KEY
X-BAPI-TIMESTAMP: 1678886400
X-BAPI-SIGN: YOUR_GENERATED_SIGNATURE

安全提示：

• 务必保护好您的 API Secret ，不要将其泄露给任何第三方。
• 定期更换您的 API Secret ，以提高安全性。
• 仔细检查您的请求参数，确保其准确无误，避免因参数错误导致签名验证失败。
• 始终使用 HTTPS 协议发送 API 请求，以加密数据传输，防止中间人攻击。

3. 常用 API 接口

Bybit API 提供了全面的接口集合，支持开发者访问市场数据、管理账户信息和执行交易操作。这些接口允许程序化交易策略的实现、数据分析以及自动化交易流程。以下列举了一些常用的 API 接口，并详细说明其功能和用途：

• 获取服务器时间: /v3/public/time 该接口用于同步客户端时间与 Bybit 服务器时间，确保交易操作的时间戳准确性。时间同步对于高频交易和策略执行至关重要。返回值为服务器当前时间戳。
• 获取合约信息: /v3/public/instruments 该接口提供所有可交易合约的详细规范，包括合约代码、标的资产、保证金率、最小价格变动单位（Tick Size）、合约乘数、交割日期（如适用）以及其他重要参数。这些信息对于理解合约条款和风险管理至关重要。
• 获取深度数据: /v3/public/order-book/L2 该接口返回指定合约的 Level 2 深度行情数据，展示买单和卖单的挂单价格和数量。深度数据对于评估市场流动性、预测价格走势以及执行更精确的交易决策至关重要。不同深度级别的数据量可能影响接口响应速度。
• 获取 K 线数据: /v3/public/kline 该接口允许检索指定合约的历史 K 线数据（OHLCV - 开盘价、最高价、最低价、收盘价、成交量）。开发者可以自定义 K 线的时间周期（例如 1 分钟、5 分钟、1 小时、1 天），用于技术分析、图表绘制和回溯测试交易策略。
• 获取账户信息: /v3/private/account/info 该接口提供用户的账户概览，包括账户余额、可用保证金、已用保证金、未实现盈亏、已实现盈亏等信息。使用此接口需要进行身份验证，确保账户安全。账户信息是监控资金状况和调整交易策略的基础。
• 下单: /v3/private/order/create 该接口允许用户创建新的交易订单，支持多种订单类型，包括限价单（Limit Order）、市价单（Market Order）、止损限价单（Stop Limit Order）、止损市价单（Stop Market Order）等。下单时需要指定交易方向（买入/卖出）、合约代码、数量和价格（如适用）。使用此接口需要进行身份验证。
• 撤单: /v3/private/order/cancel 该接口允许用户取消尚未成交的挂单。撤单需要提供订单 ID。及时撤单可以避免不必要的风险，尤其是在市场波动剧烈时。使用此接口需要进行身份验证。
• 查询订单: /v3/private/order/list 该接口允许用户查询特定订单或所有订单的状态，包括订单 ID、订单类型、订单价格、订单数量、成交数量、订单状态（例如 New, Partially Filled, Filled, Canceled, Rejected）。通过查询订单状态，用户可以监控交易执行情况并进行相应的调整。使用此接口需要进行身份验证。

4. 代码示例 (Python)

以下是一个使用 Python 编程语言获取 Bybit 交易平台合约信息的示例代码。此示例展示了如何构建请求、添加必要的身份验证头，并解析返回的 JSON 数据。请确保已安装必要的 Python 库，如 requests 和 urllib 。

import requests
import 
import time
import urllib.parse
import hashlib

API_KEY = "YOUR_API_KEY"  # 替换为你的 Bybit API Key
API_SECRET = "YOUR_API_SECRET"  # 替换为你的 Bybit API Secret
BASE_URL = "https://api.bybit.com"  # Bybit API base URL，可以选择其他环境，例如测试网

def generate_signature(api_secret, query_string, timestamp):
    """
    生成 Bybit API 请求签名。

    Args:
        api_secret: 你的 API Secret.
        query_string: 查询字符串参数.
        timestamp: 时间戳.

    Returns:
        生成的签名.
    """
    param_str = timestamp + query_string
    hash = hashlib.sha256((param_str).encode('utf-8')).hexdigest()
    return hash

def get_instruments(symbol):
    """
    获取 Bybit 永续合约信息。

    Args:
        symbol: 合约交易对，例如 BTCUSDT、ETHUSDT 等。必须是有效的 Bybit 交易对。

    Returns:
        合约信息 JSON 对象，如果请求成功。如果请求失败，则返回 None。
    """
    endpoint = "/v3/public/instruments"  # API 端点，指定获取合约信息的路径
    url = BASE_URL + endpoint  # 完整的 API 请求 URL

    params = {
        "category": "linear",  # 线性合约，Bybit 支持线性合约和反向合约
        "symbol": symbol  # 要查询的合约交易对
    }
    params_string = urllib.parse.urlencode(params) # 将参数编码为 URL 查询字符串

    timestamp = str(int(time.time() * 1000))  # 获取当前时间戳，单位为毫秒
    signature = generate_signature(API_SECRET, params_string, timestamp)  # 生成签名

    headers = {
        "X-BAPI-API-KEY": API_KEY,  # API Key，用于身份验证
        "X-BAPI-TIMESTAMP": timestamp,  # 时间戳，防止请求重放攻击
        "X-BAPI-SIGN": signature,  # 签名，用于验证请求的合法性
        "Content-Type": "application/"  # 指定内容类型为 JSON
    }

    response = requests.get(url, headers=headers, params=params)  # 发送 GET 请求

    if response.status_code == 200:  # 检查响应状态码
        return response.()  # 将响应内容解析为 JSON 对象并返回
    else:
        print(f"Error: {response.status_code} - {response.text}")  # 打印错误信息，包括状态码和响应文本
        return None  # 返回 None 表示请求失败

if __name__ == "__main__":
    symbol = "BTCUSDT"  # 指定要查询的合约交易对
    instruments = get_instruments(symbol)  # 调用函数获取合约信息

    if instruments:  # 检查是否成功获取合约信息
        print(.dumps(instruments, indent=4))  # 格式化打印 JSON 对象

务必将代码中的 YOUR_API_KEY 和 YOUR_API_SECRET 替换为你自己在 Bybit 平台申请的 API Key 和 API Secret。请妥善保管你的 API Secret，不要泄露给他人。此代码示例使用了线性USDT永续合约类别。Bybit 平台提供了现货、交割、期权等不同类别的合约，请根据实际需求修改 category 参数。在生产环境中使用 API 时，请注意频率限制，避免被限流。

5. 常见问题

• 权限错误: 请仔细核实您的 API 密钥是否已启用执行相关操作所需的权限。例如，如果您尝试进行交易，请确保您的 API 密钥具有交易权限。权限不足可能导致API调用失败。
• 签名错误: 签名是验证请求完整性和身份的关键。请务必检查您使用的签名算法是否与 Bybit API 文档中的说明完全一致。参数的排序必须严格按照 API 文档的要求进行，参数值的编码（例如 URL 编码）也必须正确无误。常见的错误包括参数顺序错误、编码不正确或使用了错误的密钥。
• 频率限制: Bybit API 为了保障系统稳定性和公平性，对每个 API 密钥的请求频率都有限制。请务必了解不同 API 接口的频率限制，并合理控制您的请求频率。建议您实施重试机制和指数退避策略，以应对因频率限制导致的错误。考虑使用批量请求来减少总请求次数。
• 时间戳错误: Bybit API 使用时间戳来防止重放攻击。时间戳必须是 Unix 纪元以来的毫秒数，并且与 Bybit 服务器的时间相差不能超过一定范围（通常是几秒钟）。请确保您的系统时钟与网络时间同步，并使用精确的毫秒级时间戳。检查时区设置是否正确。
• 网络错误: 网络连接不稳定或中断会导致 API 请求失败。请检查您的网络连接是否正常，并确保您的防火墙或代理服务器没有阻止与 Bybit API 服务器的通信。可以使用 `ping` 命令或 `traceroute` 命令来诊断网络问题。考虑使用稳定的网络连接，例如有线连接。

6. 错误处理

Bybit API 遵循标准的 HTTP 协议，使用 HTTP 状态码和 JSON 格式的错误响应来指示操作是否成功。HTTP 状态码提供了一个概览性的错误分类，而 JSON 格式的错误信息则包含更详细的错误描述，便于开发者进行精确定位和问题排查。常见的 HTTP 状态码和对应的错误类型包括：

• 400 Bad Request : 通常表示客户端发送的请求存在问题，例如请求参数缺失、格式错误、参数类型不匹配，或者参数值超出允许范围。 开发者需要仔细检查请求的参数，确保符合 API 文档的要求。
• 401 Unauthorized : 表明请求未经过身份验证，或者提供的 API 密钥无效。这可能是由于 API 密钥未配置，或者密钥已被禁用。开发者需要检查 API 密钥是否正确配置，并且具有访问该 API 接口的权限。同时，需要注意保管好 API 密钥，防止泄露。
• 429 Too Many Requests : 指示客户端在短时间内发送了过多的请求，超过了 Bybit API 的频率限制。为了保护 API 服务的稳定性，Bybit 对每个 API 接口都设置了请求频率限制。开发者需要控制请求的频率，避免触发此错误。可以采用诸如队列、延时重试等机制来优化请求发送策略。
• 500 Internal Server Error : 这是一个服务器端的错误，表明 Bybit 服务器在处理请求时遇到了未知的内部错误。这种情况通常与客户端无关，开发者可以稍后重试该请求。如果此错误持续发生，建议联系 Bybit 技术支持。

在编写代码时，务必实现完善的错误处理机制，以便在出现错误时能够及时捕获并进行相应的处理。 这包括记录错误日志、向用户显示友好的错误提示，以及根据错误类型进行重试或者采取其他补救措施。在 Python 中，推荐使用 try...except 语句来捕获潜在的异常，例如 requests.exceptions.RequestException (当网络请求失败时抛出), .JSONDecodeError (当 JSON 解析失败时抛出) 等。 通过捕获这些异常，可以保证程序的健壮性，避免程序因未处理的异常而崩溃。

例如，以下 Python 代码演示了如何使用 try...except 块来处理 API 请求可能出现的异常：

import requests
import 

try:
    response = requests.get('https://api.bybit.com/v2/public/tickers?symbol=BTCUSD')
    response.raise_for_status()  # 检查 HTTP 状态码，如果不是 200，则抛出异常
    data = response.()
    print(data)

except requests.exceptions.RequestException as e:
    print(f"网络请求错误: {e}")
except .JSONDecodeError as e:
    print(f"JSON 解析错误: {e}")
except Exception as e:
    print(f"其他错误: {e}")

在上面的代码中， response.raise_for_status() 会检查 HTTP 状态码。 如果状态码表示错误 (例如 400, 401, 429, 500)，则会抛出一个 requests.exceptions.HTTPError 异常，该异常会被 except requests.exceptions.RequestException as e: 捕获。 代码还捕获了 .JSONDecodeError 和 Exception 异常，以处理 JSON 解析错误和其他未知的异常情况。 通过这种方式，可以确保程序在面对各种潜在错误时能够优雅地处理，提高程序的稳定性和可靠性。

7. 高级用法

• WebSocket API: Bybit 提供 WebSocket API，它允许开发者建立持久连接，实时接收推送的市场数据和账户信息更新。相较于传统的 REST API 轮询方式，WebSocket API 显著降低了延迟，适用于构建对市场变化高度敏感且需要快速响应的交易策略，例如高频交易机器人、套利系统以及实时风险管理平台。通过订阅特定的市场主题（例如：交易对的价格更新、深度行情），开发者可以立即获得数据更新，而无需频繁发送请求。
• REST API v5: Bybit 致力于优化其 API 基础设施，目前正在积极推进从旧版本到 REST API v5 的迁移。 REST API v5 旨在提供更高效、更安全、更稳定的服务，并引入了新的功能和改进。 强烈建议开发者密切关注 Bybit 官方文档，及时了解最新的 API 接口、参数变更、认证方式以及错误代码处理，以便顺利过渡并充分利用新版本的功能。 迁移计划可能涉及 API 端点的变化，以及请求和响应格式的更新，务必进行充分的测试和验证。
• 使用 SDK: 为了简化 Bybit API 的集成过程，Bybit 官方和活跃的第三方开发者社区提供了多种软件开发工具包 (SDK)。这些 SDK 封装了底层的 API 调用，并提供了更高级别的函数和类，从而减少了开发者需要编写的代码量。 使用 SDK 可以简化身份验证、请求构建、数据解析和错误处理等常见任务，从而使开发者能够专注于交易逻辑的实现。 可用的 SDK 通常支持多种编程语言，例如 Python、Java 和 JavaScript。

为了充分利用 Bybit API 的强大功能，请务必参考 Bybit 官方 API 文档。官方文档提供了全面的 API 参考、详细的参数说明、示例代码以及最佳实践指南。文档内容涵盖了各种 API 功能，包括现货交易、合约交易、账户管理、数据查询等。认真阅读并理解文档，将有助于你更有效地开发和部署基于 Bybit API 的交易应用。