Bybit API：手把手教你用Python玩转自动化交易！

Bybit平台的API交易使用指南

概述

Bybit平台提供了一套功能完善且强大的应用程序编程接口（API），旨在赋能开发者和专业交易员，使其能够以程序化的方式高效地访问和利用Bybit交易所的各项核心功能。 通过Bybit API，用户能够构建复杂的自动化交易策略、执行深入的市场数据分析、实现订单的精细化管理以及开发各种定制化的交易工具，从而显著提高交易效率和整体灵活性。 例如，高频交易者可以利用API毫秒级的响应速度来快速执行交易，量化研究者可以利用API获取历史数据进行策略回测，普通交易者也可以利用API设置自动止损止盈订单，避免时刻盯盘。

本指南将提供对Bybit API的全面而详细的介绍，包括API的认证方式、请求结构、常用接口的用法以及错误处理机制等。 我们的目标是帮助您快速掌握Bybit API的使用方法，并顺利地将其集成到您自己的交易系统中。无论您是经验丰富的量化交易员，还是刚刚接触API编程的初学者，本指南都将为您提供有价值的指导和实用的示例代码，助您在Bybit平台上充分发挥API的强大功能。我们将涵盖现货、合约等主要交易类型的API使用，并介绍如何安全有效地管理您的API密钥。

准备工作

在使用Bybit API之前，需要进行一些准备工作，以确保能够顺利、安全地进行程序化交易和数据获取。

1. 注册Bybit账户： 如果您还没有Bybit账户，请前往Bybit官方网站（例如：bybit.com）注册。注册时，请确保使用安全可靠的电子邮件地址，并设置强密码，开启双重验证（2FA），以提高账户安全性。
2. KYC认证： 为了确保账户安全并符合全球反洗钱（AML）和了解你的客户（KYC）监管要求，请务必完成Bybit的KYC（Know Your Customer）身份认证。不同级别的KYC认证可能会影响API的使用权限和提现额度。 请在Bybit账户设置中查找KYC认证选项，并按照提示上传所需身份证明文件。
3. 启用API： 登录您的Bybit账户，进入“API管理”页面。 该页面通常可以在账户设置或个人中心找到。点击“创建新密钥”或类似按钮，开始创建新的API密钥。在填写相关信息时，例如API密钥名称，您可以选择一个易于识别的名称，方便您管理多个API密钥。 同时，请仔细选择API密钥的权限。对于交易机器人或程序化交易， 请务必开启“交易”权限 ，否则您的程序将无法进行任何交易操作。Bybit还提供了其他权限选项，例如“只读”权限，允许您获取市场数据但无法进行交易。
4. 获取API密钥： 成功创建API密钥后，Bybit系统将生成API密钥（API Key）和API密钥密钥（API Secret）。 请务必妥善保管您的API Secret，切勿泄露给任何人。 API Key用于标识您的身份，而API Secret用于对API请求进行签名，以验证请求的真实性和完整性。 可以将API Secret视为您账户的“交易密码”，一旦泄露，可能会导致您的账户被盗用。建议将API Key和API Secret保存在安全的地方，例如加密的数据库或专门的密钥管理工具。 请注意，Bybit API密钥通常具有IP地址限制和权限限制，您可以在创建API密钥时进行配置，以进一步提高安全性。 如果您怀疑API Secret已泄露，请立即撤销该API密钥，并重新生成新的API密钥。

API Endpoint

Bybit API提供了多个Endpoint，每个Endpoint都对应着不同的功能模块，使得开发者可以高效地访问和利用Bybit平台提供的各种服务。常见的Endpoint类型包括：

• 公共API (Public API)： 这类Endpoint主要用于获取公开的市场数据，例如实时的交易对价格信息、订单簿深度（Order Book Depth）、历史交易记录（Trade History）、以及其他市场统计数据。公共API的设计特点是不需要API密钥进行身份认证，任何人都可以直接访问，方便快速获取市场概况。这些数据对于量化分析、市场监控和构建交易策略至关重要。
• 私有API (Private API)： 这类Endpoint用于执行涉及账户安全和资产变动的操作，例如下单交易（Placing Orders）、撤销订单（Cancelling Orders）、查询账户余额（Account Balance Inquiry）、获取历史订单记录（Order History Retrieval）以及资金划转（Fund Transfer）。为了保障用户资产安全，私有API需要使用API密钥（API Key）和密钥（Secret Key）进行严格的身份认证，确保只有授权用户才能执行这些操作。API密钥必须妥善保管，避免泄露。

Bybit API的Endpoint地址会根据您所连接的环境而有所不同，选择正确的Endpoint至关重要，否则可能导致连接失败或者数据错误。

• 主网 (Mainnet)： 主网Endpoint用于真实的交易环境，所有交易操作都会实际影响您的账户资产。主网Endpoint地址通常为： https://api.bybit.com 。请务必在确认您的交易策略和代码经过充分测试后，才连接到主网进行实盘交易。
• 测试网 (Testnet)： 测试网Endpoint提供一个模拟的交易环境，用于测试您的API调用和交易策略，而不会实际消耗您的资金。测试网Endpoint地址通常为： https://api-testnet.bybit.com 。强烈建议开发者在将交易策略部署到主网之前，先在测试网上进行充分的测试和验证，以避免因代码错误或策略问题导致不必要的损失。Bybit通常会为测试网提供免费的测试币。

强烈建议您在测试网环境下进行API测试，以避免在真实交易环境中出现错误。

API 认证

Bybit 私有 API 需要使用 HMAC SHA256 算法进行认证，以确保通信安全和身份验证。未经验证的请求将被拒绝，从而保护用户的账户和数据。 认证过程涉及构建请求参数、生成数字签名和添加认证信息，详细步骤如下：

1. 构建请求参数： 需将所有请求参数按照字母顺序（ASCII 码顺序）进行排序。 排序完成后，将这些参数及其对应的值拼接成一个字符串。拼接时需要注意保持参数名和参数值之间的正确连接，通常使用等号（=）连接，不同的参数对之间使用连接符（例如 & 符号）分隔。务必确保 URL 编码正确处理，避免特殊字符干扰签名生成。
2. 生成签名： 使用您的 API Secret 作为密钥，对上一步构建的请求参数字符串进行 HMAC SHA256 加密。 HMAC (Hash-based Message Authentication Code) SHA256 是一种常用的消息认证码算法，它结合了哈希函数和密钥，能够有效地验证消息的完整性和真实性。 不同编程语言有相应的库函数可以实现 HMAC SHA256 加密。 生成的签名是一个十六进制字符串，它将作为请求的一部分发送给 Bybit 服务器。
3. 添加认证信息： 将您的 API Key、生成的签名以及当前的时间戳添加到 HTTP 请求头（Headers）或请求参数中。 具体采用哪种方式取决于 Bybit API 的具体要求。 API Key 用于标识您的账户，时间戳用于防止重放攻击。 通常，时间戳需要以 Unix 时间戳的形式提供，精确到秒或毫秒。 这些认证信息将允许 Bybit 服务器验证请求的来源和完整性，从而安全地处理您的 API 请求。

不同编程语言的实现方式略有不同，请参考Bybit官方文档提供的示例代码。

常用API接口

以下是一些常用的Bybit API接口，方便开发者集成和进行自动化交易：

• 获取账户信息（资金余额）： /v5/account/wallet-balance (GET) - 获取账户的可用余额、已用保证金等详细资金信息。此接口提供所有币种的余额快照，是风险管理和交易决策的重要依据。返回数据包括总资产、可用资产、已用保证金等关键指标。
• 下单（创建订单）： /v5/order/create (POST) - 创建新的订单，包括限价单、市价单、止损单等多种订单类型。需要提供交易对、订单方向（买/卖）、订单数量、订单类型、价格（限价单）等参数。该接口支持高级订单选项，例如冰山订单和只减仓订单。
• 取消订单（撤销订单）： /v5/order/cancel (POST) - 取消指定订单，需要提供订单ID。可以单个取消或批量取消订单。通常在需要快速调整交易策略或应对市场突发情况时使用。确保提供正确的订单ID以避免操作错误。
• 获取订单列表（查询订单历史）： /v5/order/list (GET) - 获取账户的订单列表，可以根据订单状态、交易对、开始时间、结束时间等参数进行过滤。该接口用于跟踪订单执行情况，监控交易历史，并进行交易分析。通过分页参数可以获取大量订单数据。
• 获取K线数据（蜡烛图数据）： /v5/market/kline (GET) - 获取指定交易对的K线数据，用于技术分析。可以指定K线周期（例如1分钟、5分钟、1小时、1天等），并获取一段时间内的开盘价、最高价、最低价、收盘价和成交量。K线数据是技术交易者的重要工具。
• 获取深度数据（订单簿）： /v5/market/orderbook (GET) - 获取指定交易对的深度数据，展示买单和卖单的挂单情况。深度数据反映了市场的买卖力量对比，可以帮助交易者评估市场深度和潜在的支撑阻力位。返回数据通常包含多个价格层级的买单和卖单数量。

详细的API接口文档请参考Bybit官方网站。

API使用示例 (Python)

以下是一个使用Python和 requests 库调用Bybit API的示例。该示例涵盖了如何生成API签名、获取账户余额以及创建订单。

你需要安装 requests 库：

pip install requests

接下来，你需要导入必要的库：

requests 库用于发送HTTP请求， hashlib 和 hmac 用于生成API签名， time 用于获取当前时间戳。

import requests import hashlib import hmac import time import

请务必妥善保管你的API密钥和API Secret。不要将它们泄露给他人或提交到公共代码仓库。

API KEY = "YOUR API KEY" # 替换为你的API密钥 API SECRET = "YOUR API SECRET" # 替换为你的API Secret BASE_URL = "https://api-testnet.bybit.com" # 使用测试网，正式环境为 "https://api.bybit.com"

generate_signature 函数用于生成API请求的签名。签名是使用你的API Secret和请求参数计算出的哈希值。Bybit API使用签名来验证请求的完整性和真实性。

def generate signature(params, api secret): """生成API签名""" param str = '&'.join([f"{k}={v}" for k, v in sorted(params.items())]) hash = hmac.new(api secret.encode("utf-8"), param_str.encode("utf-8"), hashlib.sha256) return hash.hexdigest()

get_wallet_balance 函数用于获取账户余额。你需要指定账户类型 ( accountType ) 和币种 ( coin )。

accountType 可以是 "UNIFIED" (统一账户) 或 "CONTRACT" (交易账户)。 coin 指定要查询的币种，如果不指定，将返回所有币种的余额。

def get wallet balance(): """获取账户余额""" endpoint = "/v5/account/wallet-balance" url = BASE_URL + endpoint

params  =  {
     "accountType": "UNIFIED", #UNIFIED: 统一账户, CONTRACT: 交易账户
    "coin":  "USDT",  #币种，不填则获取所有币种
     "timestamp": str(int(time.time() * 1000)),  # 毫秒级时间戳
      "recvWindow": "5000" # 请求超时时间，毫秒为单位
}

signature = generate_signature(params, API_SECRET)
headers  = {
       "BYBIT-API-KEY":  API_KEY,
      "BYBIT-API-SIGN": signature,
     "BYBIT-API-TIMESTAMP": str(int(time.time()  * 1000)),
    "BYBIT-API-RECV-WINDOW": "5000"
}

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

if response.status_code  ==  200:
     print("获取账户余额成功:")
     print(.dumps(response.(), indent=4))
else:
     print(f"获取账户余额失败，状态码: {response.status_code}")
     print(response.text)

create_order 函数用于创建订单。你需要指定交易对 ( symbol )、买卖方向 ( side )、订单类型 ( order_type ) 和数量 ( qty )。

symbol 是交易对，例如 "BTCUSDT" 。 side 是买卖方向，可以是 "Buy" 或 "Sell" 。 order_type 是订单类型，可以是 "Market" (市价单) 或 "Limit" (限价单)。 qty 是订单数量。

对于限价单，你还需要指定价格 ( price )。 timeInForce 指定订单的有效时间，通常设置为 "GTC" (Good Till Cancelled)，表示订单会一直有效，直到被成交或取消。

def create order(symbol, side, order type, qty, price=None): """下单""" endpoint = "/v5/order/create" url = BASE_URL + endpoint

params = {
     "symbol": symbol,
     "side": side, # Buy,  Sell
     "orderType": order_type, # Market, Limit
    "qty": qty,
     "timeInForce":  "GTC",  #  Good Till Cancelled
    "timestamp": str(int(time.time()  * 1000)), # 毫秒级时间戳
      "recvWindow": "5000",  #  请求超时时间，毫秒为单位
    "accountType": "UNIFIED"
}

if order_type == "Limit":
     params["price"] = price

signature = generate_signature(params,  API_SECRET)

headers = {
     "BYBIT-API-KEY": API_KEY,
     "BYBIT-API-SIGN": signature,
    "BYBIT-API-TIMESTAMP": str(int(time.time() * 1000)),
      "BYBIT-API-RECV-WINDOW": "5000"
}

response = requests.post(url,  headers=headers, data=params)

if response.status_code  == 200:
     print("下单成功:")
     print(.dumps(response.(),  indent=4))
else:
     print(f"下单失败，状态码: {response.status_code}")
    print(response.text)

示例用法

在Python脚本中，可以使用以下方式来调用和执行与加密货币交易相关的函数：

if name == "__main__":
    get_wallet_balance()  # 获取账户余额

    #create_order("BTCUSDT", "Buy", "Market", "0.001")  # 市价买入指定数量的BTCUSDT
    #create_order("BTCUSDT", "Sell", "Limit", "0.001", "26000") # 以限价26000 USDT卖出指定数量的BTCUSDT

代码解释：

• if name == "__ main __": ：这是Python的常用入口点，确保代码只在脚本直接运行时执行，而不是被作为模块导入时执行。
• get_wallet_balance() ：这是一个函数调用示例，用于获取当前交易账户的余额信息。该函数内部应该包含与交易所API交互，查询账户资金的逻辑。
• create_order("BTCUSDT", "Buy", "Market", "0.001") ：此行代码被注释掉，它展示了如何创建一个市价买单。函数 create_order 接收多个参数，包括：交易对（例如"BTCUSDT"），交易方向（"Buy" 表示买入），订单类型（"Market" 表示市价单），以及交易数量（"0.001" 表示0.001个BTC）。这意味着以当前市场价格立即买入0.001个BTCUSDT。
• create_order("BTCUSDT", "Sell", "Limit", "0.001", "26000") ：此行代码也被注释掉，它展示了如何创建一个限价卖单。除了交易对、交易方向和交易数量外，限价单还需要指定一个价格（"26000" USDT）。这意味着只有当市场价格达到或高于26000 USDT时，才会卖出0.001个BTC。

注意事项：

• 在使用这些函数之前，需要确保已经正确配置了交易所API密钥，并且安装了必要的Python库（例如，用于与交易所API交互的库）。
• 订单的参数（例如交易对、数量、价格）需要根据实际情况进行调整。
• 在实际交易中，需要谨慎考虑风险，并根据自己的交易策略来设置订单。
• 以上代码仅为示例，具体的实现方式可能因交易所API而异。
• 注释的代码需要根据实际情况取消注释并修改参数后方可使用。

请将 YOUR_API_KEY 和 YOUR_API_SECRET 替换为您自己的API密钥。

错误处理

与Bybit API交互时，会遇到不同的HTTP状态码，这些状态码提供了关于请求处理结果的重要信息。理解并恰当处理这些状态码对于构建稳定可靠的应用程序至关重要。以下是一些常见的状态码及其含义：

• 200 OK： 这是最常见的成功状态码，表明请求已成功处理，服务器已返回预期的响应。
• 400 Bad Request： 此状态码表示客户端发送的请求存在问题，例如缺少必需的参数、参数格式不正确或参数值无效。仔细检查请求参数并确保它们符合API文档的规范。
• 401 Unauthorized： 此状态码表明客户端未经过身份验证或提供的身份验证凭据无效。检查API密钥是否正确配置，并且是否拥有执行请求操作所需的权限。请确保API密钥已激活并且未过期。
• 429 Too Many Requests： 此状态码表示客户端在给定的时间内发送了过多的请求，超过了API的速率限制。实施速率限制策略，例如使用指数退避算法，以避免超过API限制。请参考Bybit API文档了解具体的速率限制规则。
• 500 Internal Server Error： 此状态码表示服务器在处理请求时遇到了意外错误。这通常是服务器端的问题，客户端可以稍后重试该请求。如果问题持续存在，请联系Bybit支持团队。

除了HTTP状态码之外，Bybit API的响应体通常包含一个 retCode 字段，该字段提供了关于特定错误的更详细信息。 retCode 是一个数字代码，用于指示错误的类型。查阅Bybit API文档以获取 retCode 及其相应含义的完整列表。通过检查 retCode ，可以更精确地诊断和解决问题。同时，响应体中可能还包含一个 retMsg 字段，其中包含可读的错误消息，有助于理解错误的上下文。

在开发过程中，务必包含适当的错误处理机制，以捕获并处理API返回的错误信息。记录错误信息，以便进行调试和监控。实施重试逻辑，以处理瞬时错误。向用户提供有意义的错误消息，帮助他们了解问题的根本原因并采取适当的措施。

安全提示

• 保护API密钥： 妥善保管您的API密钥（API Key）和API密钥Secret（API Secret），切勿将其泄露给任何第三方。API密钥是访问您Bybit账户的凭证，泄露可能导致资金损失或其他安全风险。请将其视为您账户的密码，并采取相应的安全措施进行保护。强烈建议使用密码管理器存储，并定期更换API Secret。
• 限制API权限： 为您的API密钥配置尽可能精细化的权限控制。仅授予API密钥执行特定任务所需的最小权限集合，避免授予不必要的权限。例如，如果API密钥仅用于获取市场数据，则不要授予其交易权限。Bybit平台提供多种权限选项，请仔细评估并选择最合适的权限组合。
• 监控API使用情况： 定期审查您的API使用情况，包括API请求频率、交易量、IP地址等。通过监控API使用情况，可以及时发现异常活动，例如未经授权的访问或潜在的安全漏洞。Bybit平台提供API使用统计数据，您可以利用这些数据进行监控。同时，设置警报系统，以便在检测到异常活动时及时收到通知。
• 使用IP白名单： 实施IP白名单策略，限制API密钥只能从预定义的IP地址范围访问。这可以防止攻击者利用泄露的API密钥从未知或恶意IP地址访问您的账户。在Bybit平台上配置IP白名单，确保只有授权的IP地址可以访问您的API密钥。定期审查和更新IP白名单，以反映网络环境的变化。
• 使用双因素认证： 强烈建议为您的Bybit账户启用双因素认证（2FA），例如使用Google Authenticator或短信验证码。即使API密钥泄露，攻击者也需要通过双因素认证才能访问您的账户。2FA为您的账户增加了一层额外的安全保护，有效防止未经授权的访问。请务必备份您的2FA恢复密钥，以便在更换设备或丢失身份验证器时恢复访问。

速率限制

Bybit API 为了确保平台的稳定性和公平性，对请求频率设置了严格的限制。这意味着，在一定时间窗口内，每个用户或每个IP地址可以发送的API请求数量是有限制的。超出速率限制的请求将被Bybit服务器拒绝，并返回相应的错误代码，例如 HTTP 429 Too Many Requests，表明您的请求频率过高。

请务必详细参考 Bybit 官方 API 文档中关于速率限制的具体规则。这些规则通常会根据不同的API端点、不同的用户等级或不同的时间段而有所不同。文档会明确说明每个端点的请求限制是多少，以及如何计算您的剩余请求额度。 了解这些细节至关重要，以便您可以合理地规划和优化您的API请求策略。

为了避免触发速率限制，您可以采取以下策略：

• 合理控制API请求频率： 避免在高频交易或数据获取时，无节制地发送API请求。
• 使用批量请求功能： 某些API端点支持批量请求，可以将多个操作合并到一个请求中，从而减少请求的总量。
• 实施指数退避策略： 当收到速率限制错误时，不要立即重试，而是采用指数退避算法，逐渐增加重试之间的间隔时间。
• 缓存数据： 对于不经常变化的数据，可以考虑在本地进行缓存，减少对API的重复请求。
• 监控请求状态： 密切监控API请求的响应状态和剩余请求额度，以便及时调整请求策略。
• 优化代码逻辑： 检查您的代码逻辑，确保只在必要时才发送API请求，避免不必要的网络开销。

通过理解和遵循 Bybit 的速率限制规则，并采取适当的优化措施，您可以确保您的API集成能够稳定可靠地运行，避免因请求频率过高而被限制访问。