Bitfinex API 挂单

Bitfinex 是一家历史悠久的加密货币交易所，提供了强大的 API 接口，允许开发者和交易者自动化交易策略。 挂单，也称为限价单，是 API 交互中常见的操作之一。 本文将深入探讨 Bitfinex API 中挂单的相关概念、参数、使用方法以及需要注意的问题。

挂单类型

Bitfinex API 提供了多样化的挂单类型，以满足不同交易策略和风险管理需求，覆盖了加密货币交易中的各类常见场景：

• 限价单 (LIMIT): 这是最基本且常用的挂单类型。限价单允许交易者指定一个特定的价格（限价）来买入或卖出资产。只有当市场价格达到或优于（低于买入，高于卖出）设定的限价时，订单才会被执行。通过使用限价单，交易者能够精确地控制交易的执行价格，避免以超出预期的高价买入或低于预期的低价卖出，从而实现更有效的成本控制。
• 市价单 (MARKET): 市价单是指以当前市场上最佳可得价格立即执行的订单。市价单确保了订单的快速成交，适用于对成交速度有较高要求的场景。然而，由于市场价格的波动性，使用市价单执行的实际成交价格可能与下单时看到的价格略有偏差，特别是在市场流动性较差或波动剧烈的情况下。
• 止损限价单 (STOP LIMIT): 止损限价单是一种结合了止损单和限价单特性的高级订单类型。交易者首先设置一个止损价格（STOP PRICE），当市场价格达到或突破该止损价时，止损限价单会被激活，并转化为一个限价单，以预先设定的限价或更优的价格执行。这种订单类型有助于限制潜在损失，同时避免在市场剧烈波动时以不利的价格成交，确保交易价格在可接受的范围内。止损价和限价可以相同，也可以不同，取决于交易者的风险偏好和市场预期。
• 止损单 (STOP): 止损单是一种用于限制潜在损失的订单类型。交易者设定一个止损价格（STOP PRICE），当市场价格达到或突破该止损价时，止损单会被触发，并立即转化为一个市价单执行。止损单的主要目的是在市场价格朝着不利方向变动时，自动平仓以控制损失，避免更大的亏损。
• 追踪止损单 (TRAILING STOP): 追踪止损单是一种动态调整止损价格的订单类型，能够随着市场价格的有利变动而自动调整止损价格。交易者设定一个追踪幅度（TRAILING DELTA），止损价格会始终保持与市场价格一定的距离。当市场价格上涨时（对于做多订单），止损价格也会相应提高；当市场价格下跌时，止损价格则保持不变。这种订单类型有助于锁定利润，并允许交易者在市场行情有利的情况下继续获利，同时在市场行情反转时及时止损，避免利润回吐。
• 市价止损单 (TRAILING STOP MARKET): 市价止损单与追踪止损单类似，都是一种动态调整止损价格的订单类型。不同之处在于，当止损价格被触发时，市价止损单会立即以市场价格执行。这种订单类型在止损价被触发时确保快速成交，但成交价格可能不如限价止损单那样精确。
• 冰山订单 (HIDDEN): 冰山订单，又称隐藏订单，是一种可以部分隐藏订单数量的订单类型。交易者可以将大额订单拆分成多个小额订单，只有一部分订单数量会显示在订单簿上，剩余部分则隐藏起来。当一部分订单成交后，隐藏的订单会自动补充到订单簿上，维持显示的数量。这种订单类型旨在减少大额订单对市场价格的影响，防止被其他交易者察觉，从而避免市场操纵或被他人利用。

API 端点和参数

Bitfinex API 提供了专门的端点用于执行挂单、修改订单和取消订单等操作。主要的 API 端点是 /v2/orders ，通过该端点，用户可以与 Bitfinex 交易平台进行订单相关的交互。

以下是创建订单时常用的参数，这些参数允许用户精细化地控制订单的行为和属性：

• symbol : 交易对，明确指定交易的资产。 例如，"tBTCUSD" 代表比特币/美元，"tETHUSD"代表以太坊/美元。 symbol 参数必须是 Bitfinex 平台支持的有效交易对。
• amount : 订单数量。正数表示买入，负数表示卖出。 数量的单位取决于 symbol 指定的交易对。 例如，如果 symbol 是 "tBTCUSD"，那么 amount 的单位就是比特币。
• type : 订单类型，定义了订单的执行方式。 常见的订单类型包括 "LIMIT" (限价单)、"MARKET" (市价单)、"STOP" (止损单)、"STOP LIMIT" (止损限价单)、"TRAILING STOP" (追踪止损单) 和 "FILL OR KILL" (FOK) 等。 每种订单类型都有其特定的用途和参数要求。
• price : 限价单的价格。只有当市场价格达到或优于指定价格时，限价单才会被执行。 此参数仅在 type 为 "LIMIT" 或 "STOP LIMIT" 等限价相关的订单类型时有效。
• price_trailing : 追踪止损单的追踪距离。 定义了止损价格与市场价格之间的距离。 随着市场价格的上涨（对于多单）或下跌（对于空单），止损价格也会相应地调整，始终保持与市场价格的固定距离。
• price_aux_limit : 止损限价单的限价价格。 当止损价格被触发时，系统会以该限价价格挂出一个限价单。 这允许用户在止损触发后，以指定的价格范围内成交。
• price_oco_stop : OCO (One-Cancels-the-Other) 订单的止损价格。 OCO 订单包含一个限价单和一个止损单，当其中一个订单被执行时，另一个订单会被自动取消。 price_oco_stop 指定了止损单的触发价格。
• hidden : 是否隐藏订单数量。 如果设置为 true ，则订单不会显示在 Bitfinex 的公开订单簿上。 这可以避免大额订单对市场造成不必要的影响。
• postonly : 是否只允许以挂单方式成交。 如果设置为 true ，则订单只能以挂单的形式存在于订单簿上，不能立即成交。 如果订单会立即成交，则会被取消。 这可以确保用户始终是做市商 (market maker)，从而享受更低的交易手续费。
• reduceonly : 是否只允许减少仓位。 用于平仓操作。 如果设置为 true ，则订单只能用于减少当前持有的仓位，而不能增加仓位。这对于风险管理和避免意外开仓非常有用。
• tif (Time In Force): 订单的有效期。 定义了订单在订单簿上保持有效的时间。 可以设置为 "GTC" (Good Till Cancelled， 永久有效，直到被取消)、"IOC" (Immediate or Cancel， 立即成交，否则取消) 或 "FOK" (Fill or Kill， 必须全部成交，否则取消)。
• client_order_id (cid): 客户端自定义的订单 ID。 用于跟踪订单状态。 允许用户自定义订单的标识符，方便在自己的系统中进行订单管理和跟踪。 这个 ID 不会被 Bitfinex 使用，仅仅是客户端用来识别订单的。

API 调用示例 (Python)

以下是一个使用 Python 和 requests 库与 Bitfinex API 交互，创建限价单的示例。为了安全地进行 API 调用，需要生成签名，该签名基于您的 API 密钥和密钥。

import requests import import hashlib import hmac import time

API_KEY = "YOUR_API_KEY" API_SECRET = "YOUR_API_SECRET" BASE_URL = "https://api.bitfinex.com/v2"

def generate_signature(path, data, secret): """ 生成用于 Bitfinex API 请求的签名。 参数: path (str): API 端点路径。 data (dict): 请求负载数据。 secret (str): 您的 API 密钥。 返回值: tuple: 包含 nonce 和签名的元组。 """ nonce = str(int(round(time.time() * 1000))) # 使用毫秒级时间戳作为 nonce，增加唯一性 body = .dumps(data) # 将请求数据序列化为 JSON 字符串 signature = f"/api{path}{nonce}{body}".encode('utf8') # 构建用于签名的字符串 digest = hmac.new(secret.encode('utf8'), signature, hashlib.sha384).hexdigest() # 使用 HMAC-SHA384 算法生成签名 return nonce, digest

def create_order(symbol, amount, price): """ 在 Bitfinex 交易所创建一个限价单。 参数: symbol (str): 交易对符号 (例如，"tBTCUSD" 代表比特币/美元)。 amount (float): 订单数量。正数表示买入，负数表示卖出。 price (float): 限价单的价格。 返回值: str: API 响应的 JSON 字符串。 """ path = "/auth/w/order/submit" data = { "symbol": symbol, "amount": str(amount), # 数量必须是字符串 "type": "LIMIT", # 指定订单类型为限价单 "price": str(price), # 价格必须是字符串 "cid": int(time.time() * 1000), # 客户端订单 ID，用于跟踪订单 "hidden": False, #是否隐藏订单， 默认false "postonly": False #是否是post only 订单， 默认false }

nonce, signature = generate_signature(path, data, API_SECRET)

headers = {
    "bfx-nonce": nonce,
    "bfx-apikey": API_KEY,
    "bfx-signature": signature,
    "Content-Type": "application/" #确保内容类型正确
}

url = BASE_URL + path
response = requests.post(url, headers=headers, data=.dumps(data)) #确保将数据序列化为JSON字符串发送
return response.text  #返回原始字符串

示例：以 27,000 美元的价格买入 0.01 个比特币

在数字货币交易中，执行交易的关键在于明确交易的各项参数。以下代码片段展示了如何使用编程方式，例如通过交易平台的API，以 27,000 美元的价格购买 0.01 个比特币。其中，变量 symbol 代表交易对， amount 代表交易数量， price 代表期望的成交价格。

symbol = "tBTCUSD"
此行代码定义了交易对。 tBTCUSD 是一个常见的表示方式，代表比特币 (BTC) 相对于美元 (USD) 的交易。 "t" 前缀通常用于指示这是一个交易对，具体交易所的表示方式可能有所不同，例如 Coinbase 交易所可能使用 "BTC-USD"，Binance 交易所可能使用 "BTCUSDT"。在实际应用中，需要根据具体的交易所API文档进行调整。

amount = 0.01
此行代码定义了购买的比特币数量。 0.01 表示购买 0.01 个比特币。在不同的交易所，对于交易数量的精度要求可能不同。一些交易所允许更小单位的比特币交易，例如 0.00000001 (一聪，即比特币的最小单位)。

price = 27000
此行代码定义了期望的成交价格。 27000 表示以 27,000 美元的价格购买一个比特币。这通常是一个限价单，只有当市场价格达到或低于 27,000 美元时，交易才会被执行。如果想要立即成交，通常会使用市价单，此时不需要指定价格。

接下来，通过调用交易平台的 API 函数 create_order() 来提交订单。

response = create_order(symbol, amount, price)
此行代码调用名为 create_order 的函数，该函数负责与交易平台的API交互，并将订单提交到交易所。 symbol , amount , 和 price 作为参数传递给该函数。 create_order 函数的具体实现会根据所使用的交易所API而有所不同。 它可能需要进行身份验证、签名请求等操作。

print(response)
此行代码用于打印 create_order 函数返回的响应。 response 对象通常包含有关订单执行情况的信息，例如订单ID、成交价格、成交数量以及任何错误信息。 通过查看响应，可以确认订单是否成功提交以及订单的执行状态。 在生产环境中，应该对 response 进行适当的错误处理和日志记录，以便及时发现和解决问题。

重要提示：

• API 密钥安全至关重要： 请务必将代码示例中的 YOUR_API_KEY 和 YOUR_API_SECRET 替换为你自己从 Bitfinex 平台获取的真实 API 密钥。务必妥善保管你的 API 密钥，切勿泄露给任何第三方。密钥泄露可能导致资产损失或账户被盗用。建议定期更换 API 密钥，提高安全性。启用双因素认证（2FA）进一步保护你的 Bitfinex 账户。
• 代码示例的局限性： 提供的代码示例仅为演示 Bitfinex API 使用的基本框架，实际应用中需要根据你的具体需求进行修改和完善。务必添加全面的错误处理机制，例如捕获 API 请求失败、数据解析错误等异常情况。对所有输入参数进行严格的验证，防止注入攻击和数据不一致问题。考虑使用更健壮的 HTTP 客户端库，例如 requests 或 aiohttp ，以提高代码的稳定性和性能。
• HMAC SHA384 签名验证机制： Bitfinex API 采用 HMAC SHA384 算法对请求进行签名验证，确保请求的完整性和真实性。理解并正确实现 HMAC SHA384 签名算法是与 Bitfinex API 交互的关键。你需要使用你的 API 密钥 ( YOUR_API_SECRET ) 对请求参数进行哈希运算，并将生成的签名包含在请求头中。请仔细阅读 Bitfinex API 文档中关于签名验证的详细说明，确保签名算法的实现与文档描述完全一致。不正确的签名会导致 API 请求被拒绝。

订单状态查询

创建订单后，可以使用 /v2/orders API端点查询订单的实时状态。 为了检索特定订单的信息，您需要提供订单 ID ( order_id ) 或客户端订单 ID ( cid ) 作为请求参数。 订单的状态会随着交易的进行而发生变化，可能的状态包括：

• ACTIVE: 表示订单已成功提交到交易平台，但尚未发生任何交易或被用户主动取消。该订单正等待匹配并执行。
• EXECUTED: 指示订单已经完全成交，意味着订单中的所有数量都已经以指定的价格或更优的价格完成交易。
• PARTIALLY FILLED: 表示订单只有部分数量已经成交，还有剩余数量仍在等待被执行。这通常发生在订单数量较大，市场深度不足以立即完全成交的情况下。
• CANCELED: 表明订单已被用户或系统取消。 取消可能是由于用户主动操作，也可能是由于订单超过了有效期或触发了预设的取消条件。

订单取消

您可以使用 /v2/order/cancel API端点来取消未成交的订单。为了成功取消订单，您需要提供以下两种订单标识符之一作为请求参数：订单 ID ( order_id ) 或客户端订单 ID ( client_order_id ，简称 CID)。订单 ID 是交易所生成的唯一订单标识符，而客户端订单 ID 是您在创建订单时自定义的标识符。请注意，一旦订单完全成交，则无法通过此端点取消，因为已成交部分已经完成交易。若要确认订单状态，请在取消前查询订单详情。

重要注意事项

• API 密钥安全： 请将你的 Bitfinex API 密钥视为高度敏感信息，如同银行密码一般妥善保管。切勿将 API 密钥以任何形式泄露给未经授权的第三方，包括不要在公共代码仓库（如 GitHub）中提交包含密钥的代码，不要通过非加密渠道（如电子邮件、聊天软件）传输密钥，并定期轮换 API 密钥以降低潜在风险。建议启用双因素认证（2FA）增加账户安全性，并密切监控账户活动，防范未经授权的访问。
• 错误处理： Bitfinex API 会通过 HTTP 状态码和 JSON 格式的错误消息返回错误信息。开发过程中必须实现完善的错误处理机制，包括捕获并记录 API 返回的错误代码和消息，根据不同类型的错误采取相应的应对措施，例如重试请求、调整参数或通知用户。详细的错误代码说明请参考 Bitfinex 官方 API 文档，以便快速诊断和解决问题。
• 速率限制： Bitfinex API 为了保障服务稳定性，对每个 API 密钥的请求频率设置了速率限制。超出限制会导致请求被拒绝。你需要仔细阅读 Bitfinex API 文档，了解不同 API 接口的速率限制策略，并据此调整你的程序逻辑，例如使用延迟函数（`time.sleep()`）或队列来控制请求的发送频率。使用批量请求可以有效减少请求次数，从而降低触发速率限制的可能性。
• 市场波动： 加密货币市场具有高度波动性，价格可能在短时间内出现剧烈涨跌。交易前请充分了解相关风险，进行全面的市场分析，并根据自身风险承受能力制定合理的交易策略。密切关注市场动态和新闻事件，及时调整交易策略。
• 资金管理： 切勿将所有资金投入到加密货币交易中。应根据自身的财务状况和风险偏好，合理分配投资资金。建议采用分散投资策略，将资金分配到不同的加密货币或资产类别中，以降低整体投资风险。设置止损单是有效控制损失的手段，可以在市场价格达到预设的止损价位时自动平仓。
• 测试环境： Bitfinex 提供了沙箱（Sandbox）测试环境，允许开发者在模拟市场环境中测试 API 接口和交易策略，而无需使用真实资金。强烈建议在正式上线前，先在沙箱环境中进行充分的测试，验证代码的正确性和稳定性，确保交易策略的有效性。熟悉沙箱环境的各种功能和限制，可以有效避免因代码错误或策略问题造成的资金损失。

其他订单类型详解

止损限价单 (STOP LIMIT) 的工作原理是：当市场价格达到止损价格 (price_stop) 时，系统会自动创建一个限价单，其价格为 price_aux_limit。 这种订单类型可以帮助交易者在控制风险的同时，避免以过低的价格卖出或以过高的价格买入。 追踪止损单 (TRAILING STOP) 是一种动态止损单。 止损价格会根据市场价格的变动而自动调整。 举例来说，如果设置追踪距离为 100 美元，当市场价格上涨 200 美元时，止损价格也会相应地上涨 200 美元。 追踪止损单可以帮助交易者锁定利润，并防止在市场回调时损失过多的利润。 price_trailing 参数用于设置追踪距离。 冰山订单 (HIDDEN) 用于隐藏订单数量。 只有一部分订单数量会显示在订单簿上，剩余部分隐藏。 当显示的数量被成交后，系统会自动显示下一部分数量，直到订单完全成交。 冰山订单可以减少大额订单对市场的影响，并防止被其他交易者察觉。 hidden 参数设置为 True 即可启用冰山订单。

理解这些订单类型的特性，并根据自己的交易策略选择合适的订单类型，是使用 Bitfinex API 进行高效交易的关键。