Bithumb API 使用指南：从入门到进阶
Bithumb 作为韩国领先的加密货币交易所，其 API 接口为开发者提供了与平台交互的强大工具，可以实现自动化交易、数据分析、行情监控等多种功能。本文将深入探讨 Bithumb API 的使用方法，涵盖从申请 API 密钥到实现复杂交易策略的各个方面。
1. API 密钥申请
在使用 Bithumb API 之前，必须拥有有效的 API 密钥对，包含 API Key 和 Secret Key。这两个密钥用于验证你的身份并授权你访问 Bithumb 的数据和功能。要获取 API 密钥，请按照以下步骤操作：
- 登录 Bithumb 账户： 访问 Bithumb 官方网站，使用你的账户名和密码登录。如果还没有账户，需要先注册一个。
- 访问 API 管理页面： 登录后，导航到账户设置或个人中心，寻找 API 管理或 API 密钥相关的选项。该选项的位置可能因 Bithumb 网站的更新而略有变化，通常位于“我的账户”、“安全设置”或类似的菜单下。
- 创建新的 API 密钥： 在 API 管理页面，选择创建新的 API 密钥。系统可能会要求你进行二次身份验证，例如输入验证码或通过电子邮件确认。
-
设置 API 密钥权限：
创建 API 密钥时，需要仔细设置其权限。Bithumb 提供了多种权限选项，例如：
- 交易权限： 允许 API 密钥进行买入和卖出操作。如果你的程序需要自动交易，则必须开启此权限。
- 查询权限： 允许 API 密钥查询账户余额、交易历史、订单状态等信息。此权限通常是必要的，即使你的程序不进行交易。
- 提现权限： 允许 API 密钥发起数字货币提现请求。出于安全考虑，强烈建议不要开启此权限，除非你完全信任你的程序并且了解潜在的风险。
- 保存 API 密钥： 创建成功后，系统会生成 API Key 和 Secret Key。 务必立即将这两个密钥保存到安全的地方。Secret Key 只会显示一次，如果丢失将无法找回，只能重新生成新的 API 密钥对。
-
安全提示：
- 不要将 API 密钥和 Secret Key 存储在公共代码仓库中，例如 GitHub。
- 不要将 API 密钥和 Secret Key 泄露给他人。
- 定期更换 API 密钥，以提高安全性。
- 启用双重验证，增加账户安全性。
请记住，API 密钥的安全至关重要。一旦泄露，可能会导致你的账户资金损失。请务必采取必要的安全措施，保护你的 API 密钥。
重要安全提示：
- 启用双重身份验证 (2FA)： 为您的 Bithumb 账户启用双重身份验证是至关重要的安全措施。2FA 在您输入密码之外，增加了一层额外的安全验证，通常通过您的手机应用（如 Google Authenticator 或 Authy）生成一次性验证码。即使您的密码泄露，攻击者也需要获取您的 2FA 代码才能访问您的账户。
- 限制 API 密钥的 IP 访问权限： API 密钥允许程序化访问您的 Bithumb 账户。为了增强安全性，请将 API 密钥的 IP 访问权限限制为仅允许特定的 IP 地址访问。这意味着只有来自您信任的服务器或设备的请求才会被允许，从而阻止未经授权的访问。您可以在 Bithumb 账户设置中配置 IP 访问限制。
- 定期轮换 API 密钥： 定期更换您的 API 密钥是降低密钥泄露风险的关键步骤。即使您没有怀疑密钥已泄露，也应该定期生成新的 API 密钥并停用旧的密钥。这可以最大程度地减少攻击者利用泄露密钥的机会窗口。建议至少每 3-6 个月轮换一次 API 密钥。
- 安全存储 API 密钥： 切勿将您的 API 密钥存储在公共代码仓库（如 GitHub）、公开的文档或任何不安全的位置。攻击者会扫描这些地方寻找 API 密钥。请使用安全的密钥管理解决方案，例如加密的配置文件、环境变量或专门的密钥管理服务，以安全地存储和访问您的 API 密钥。同时，确保您的开发环境和服务器安全，防止未经授权的访问。
2. API 接口概览
Bithumb API 提供两种主要接口类型：RESTful API 和 WebSocket API，以满足不同的数据访问和交易需求。
-
RESTful API：
采用请求-响应模式，适用于执行单次、同步的请求。典型应用场景包括：
- 账户管理： 查询账户余额、获取交易历史记录、查询API密钥信息。
- 订单管理： 创建、修改、取消订单，查询订单状态，批量订单操作。
- 市场数据查询： 获取当前市场价格、交易对信息、历史K线数据。
-
WebSocket API：
提供双向、实时的数据流通道。适用于需要持续接收市场更新和事件通知的应用场景：
- 实时行情订阅： 接收最新的价格、成交量等数据，无需轮询。
- 深度数据订阅： 获取实时更新的订单簿深度信息，用于高频交易策略。
- 交易事件通知： 接收订单状态更新、成交确认等事件的实时通知。
API 的选择应基于具体应用场景。需要频繁、实时更新的数据，例如高频交易或实时监控，WebSocket API 是理想选择。对于只需要执行一些简单的、一次性操作，例如查询账户余额或下单，RESTful API 更为便捷。开发者应权衡两种 API 的优缺点，选择最符合自身需求的方案。同时，需要关注 Bithumb 官方文档，了解两种 API 的具体参数、返回值和使用限制。
2.1 RESTful API 接口
Bithumb 平台提供基于 HTTP 协议的 RESTful API，用于访问市场数据和进行交易操作。数据交换格式采用 JSON（JavaScript Object Notation），这是一种轻量级的数据交换格式，易于解析和生成，广泛应用于 Web API 开发。API 分为公共 API 和交易 API 两类，具有不同的访问权限和用途。
公共 API 的基础 URL 为
https://api.bithumb.com/public
。此类 API 用于获取实时的市场信息，无需进行身份验证，可以公开访问。交易 API 的基础 URL 为
https://api.bithumb.com/trade
。此类 API 用于执行交易操作和管理账户，必须进行签名验证，以确保账户安全。
以下是 Bithumb 平台常用的 RESTful API 接口：
-
Public API (公共 API):
用于查询市场行情和交易数据，无需身份验证。
-
/ticker/{currency}: 获取指定币种（如 BTC, ETH, XRP 等）的当前行情信息。返回数据包含最新成交价、最高价、最低价、交易量等关键指标，有助于用户了解市场动态。{currency}需要替换为具体的币种代码。 -
/orderbook/{currency}: 获取指定币种的订单簿信息。订单簿数据按照买单和卖单的价格进行排序，展示市场深度，帮助用户评估市场供需关系。{currency}需要替换为具体的币种代码。 -
/trades/{currency}: 获取指定币种的最近交易历史记录。返回数据包含成交时间、价格、数量和交易类型（买入或卖出），用于分析市场趋势和交易活动。{currency}需要替换为具体的币种代码。
-
-
Trade API (交易 API，需要签名验证):
用于进行交易操作和管理账户，必须进行身份验证。
-
/info/account: 获取账户信息，包括可用余额、已用余额、账户状态等。在进行交易前，可以使用此接口查询账户资金情况。 -
/trade/place: 下单接口，用于提交买入或卖出订单。需要指定币种、交易类型（买入或卖出）、价格和数量等参数。下单前，需要仔细核对参数，确保交易意图正确。 -
/trade/cancel: 撤单接口，用于取消尚未成交的订单。需要提供订单 ID 作为参数。及时撤销未成交订单可以避免不必要的风险。 -
/info/orders: 查询订单信息，可以根据订单 ID 或订单状态进行查询。用于跟踪订单执行情况，了解成交历史。
-
2.2 WebSocket API
Bithumb WebSocket API 提供了一种高效、实时的访问市场数据的方式。 通过建立持久的连接，您可以订阅并接收推送的更新，无需频繁轮询，从而显著降低延迟并优化数据获取效率。 此API支持多种数据流的订阅，包括实时行情、深度订单簿数据、最新交易信息等，满足不同交易策略和分析需求。
WebSocket API 的连接端点为
wss://pubwss.bithumb.com/pub/ws
。 客户端需要使用符合WebSocket协议的库或工具来建立连接。
订阅消息需要按照特定的JSON格式进行构造，并作为文本消息发送到WebSocket服务器。 以下是一个订阅消息的示例：
{
"type": "ticker",
"symbols": ["BTC_KRW", "ETH_KRW"],
"tickTypes": ["30M"]
}
上述JSON结构体中，各字段的含义如下：
-
type: 必需字段，指定订阅的数据类型。 可选值包括但不限于 "ticker" (实时行情，提供最新成交价、成交量等信息), "orderbookdepth" (深度订单簿数据，提供买单和卖单的挂单价格和数量), "trade" (最新交易信息，提供成交时间、价格、数量等信息)。 -
symbols: 必需字段，指定要订阅的交易对列表。 每个交易对由两个币种代码组成，例如 "BTC_KRW" 表示比特币/韩元交易对。 您可以同时订阅多个交易对的数据。 -
tickTypes: 可选字段，仅在订阅 "ticker" 类型时有效，指定行情数据的聚合周期。 例如 ["30M"] 表示订阅30分钟K线数据。 其他可能的取值包括 "1M" (1分钟), "1H" (1小时), "1D" (1天) 等，具体取决于Bithumb提供的支持。如果省略此字段，则默认提供实时逐笔成交数据。
3. API 请求签名
使用 Bithumb Trade API 进行交易操作，必须对每一个API请求进行严格的签名验证，确保请求的完整性和真实性。以下详细描述了签名的生成过程：
-
构造请求参数：
将所有需要传递的请求参数，包括交易类型、交易数量、价格等，按照其参数名称的字母顺序进行升序排列。 特别注意，参数值必须是字符串类型。将排序后的参数以
参数名=参数值的形式拼接成一个字符串。 例如，如果存在参数price=100和quantity=1.5，排序后拼接的字符串应为price=100quantity=1.5。 -
计算 Message：
将上一步构造的请求参数字符串、所请求 API 接口的 Endpoint 路径以及当前时间戳（Unix 时间戳，单位为毫秒）按照顺序拼接成一个新的字符串，该字符串即为 Message。 Endpoint 路径应为不包含域名的相对路径，如
/trade/place。Message 拼接的格式为：请求参数字符串 + Endpoint 路径 + 时间戳。 - 使用 Secret Key 对 Message 进行 HMAC-SHA512 加密： 使用您的 Secret Key 作为密钥，对上一步生成的 Message 字符串进行 HMAC-SHA512 加密。 HMAC-SHA512 是一种哈希消息认证码算法，通过密钥对消息进行加密，保证消息的完整性和真实性。
- 将加密结果转换为 Base64 编码： 将 HMAC-SHA512 加密后的二进制结果转换为 Base64 编码的字符串。 Base64 编码是一种将二进制数据转换为 ASCII 字符串的编码方式，方便在 HTTP Header 中进行传输。这个 Base64 编码的字符串即为最终的签名。
在发送 API 请求时，必须在 HTTP Header 中包含以下三个关键字段，以完成身份验证：
-
Api-Key: 您的 API Key，用于标识您的账户。API Key 是您在 Bithumb 交易所注册后获得的用于访问 API 的身份凭证。 -
Api-Signature: 您通过上述步骤生成的签名字符串。签名用于验证请求的合法性和防止篡改。 -
Api-Timestamp: 时间戳，表示请求发送的时间。必须是 Unix 时间戳，且单位为毫秒。时间戳用于防止重放攻击，确保请求的时效性。服务端会校验时间戳与服务器当前时间的差值，如果超过一定阈值，则认为请求无效。
示例代码 (Python):
本示例演示如何使用 Python 与 Bithumb 交易所的 API 进行交互，进行身份验证和发送交易请求。代码依赖于标准库以及
requests
库。请确保已安装
requests
库：
pip install requests
。
import hashlib
import hmac
import base64
import time
import urllib.parse
import requests
此部分导入必要的 Python 库。
hashlib
用于哈希计算，
hmac
用于生成基于哈希的消息认证码，
base64
用于 base64 编码，
time
用于获取时间戳，
urllib.parse
用于 URL 编码，
requests
用于发送 HTTP 请求。
API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
API_URL = "https://api.bithumb.com/trade"
请务必将
YOUR_API_KEY
和
YOUR_SECRET_KEY
替换为您的 Bithumb API 密钥和密钥。
API_URL
定义了 Bithumb 交易 API 的基本 URL。请注意保管好您的
SECRET_KEY
，切勿泄露。
def generate_signature(endpoint, params):
"""Generates the API signature."""
params_string = urllib.parse.urlencode(params)
timestamp = str(int(time.time() * 1000))
message = endpoint + chr(0) + params_string + chr(0) + timestamp
hmac_key = SECRET_KEY.encode('utf-8')
message_bytes = message.encode('utf-8')
signature = hmac.new(hmac_key, message_bytes, hashlib.sha512).digest()
signature_base64 = base64.b64encode(signature).decode('utf-8')
return signature_base64, timestamp
generate_signature
函数用于生成 API 请求的签名。它接收 API 端点 (
endpoint
) 和参数 (
params
) 作为输入。
-
它使用
urllib.parse.urlencode将参数编码为 URL 字符串。 - 然后，它生成一个时间戳，表示自 Unix 纪元以来的毫秒数。
-
接下来，它将端点、参数字符串和时间戳连接成一个消息，并使用您的
SECRET_KEY作为密钥，使用 HMAC-SHA512 算法对消息进行哈希处理。 - 它将生成的哈希值进行 Base64 编码，并将其作为签名返回。时间戳也会被返回。
- Bithumb API 使用此签名来验证请求的真实性和完整性。
def send_request(endpoint, params):
"""Sends the API request."""
signature, timestamp = generate_signature(endpoint, params)
headers = {
"Api-Key": API_KEY,
"Api-Signature": signature,
"Api-Timestamp": timestamp
}
url = API_URL + endpoint
response = requests.post(url, headers=headers, data=params)
return response.text
send_request
函数用于发送 API 请求。它接收 API 端点 (
endpoint
) 和参数 (
params
) 作为输入。
-
它调用
generate_signature函数生成签名和时间戳。 - 然后，它创建一个包含 API 密钥、签名和时间戳的 HTTP 头部。
- 接下来，它将 API 端点添加到基本 API URL，以创建完整的 URL。
-
它使用
requests.post函数发送带有头部和参数的 POST 请求，并返回响应文本。 -
返回的响应通常是 JSON 格式的字符串，您可以使用
.loads()函数将其解析为 Python 字典。
示例：创建交易订单
以下代码段展示了如何使用API创建限价买单。请注意，实际交易前务必在测试环境进行充分验证。
参数说明：
-
order_currency: 交易币种，例如 "BTC" (比特币)。 -
payment_currency: 结算币种，例如 "KRW" (韩元)。 -
units: 交易数量，代表买入或卖出的加密货币数量。例如，"0.001" 表示交易 0.001 个比特币。请确保精度符合交易所要求。 -
price: 交易价格，以结算币种计价。例如，"50000000" 表示以 5000 万韩元的价格买入指定数量的比特币。 -
type: 订单类型，"bid" 表示买入（做多），"ask" 表示卖出（做空）。
代码示例：
params = {
"order_currency": "BTC",
"payment_currency": "KRW",
"units": "0.001",
"price": "50000000",
"type": "bid" # 买入
}
response = send_request("/trade/place", params)
print(response)
send_request
函数代表向交易所API发送请求的通用函数，需要根据交易所的具体API文档进行实现。
/trade/place
是下单API的示例路径，实际路径可能因交易所而异。
响应：
response
变量将包含来自交易所的响应数据，通常是JSON格式。你需要解析这个响应来确认订单是否成功创建，并获取订单ID等信息。务必检查响应中的错误代码和消息，以便处理潜在的错误情况。
4. 错误处理
Bithumb API 使用错误代码来指示请求的状态。解读这些代码对于确定请求是否成功至关重要。 当 API 请求失败时，服务器会返回一个包含错误代码的 JSON 响应。你需要在你的应用程序中实现适当的错误处理机制，以便能够捕获、解析和响应这些错误。 根据具体的错误类型，你的代码可能需要采取不同的措施，例如重新尝试请求、记录错误日志或通知用户。
以下是一些常见的 Bithumb API 错误代码及其含义，但请注意，这并非完整列表，Bithumb 可能会随时更新错误代码集。建议查阅 Bithumb 官方 API 文档获取最新和最全面的错误代码信息：
-
5100: 无效 API 密钥。表示提供的 API 密钥不正确或已被禁用。需要检查 API 密钥是否正确配置，并确保其处于活动状态。 -
5200: 无效签名。表示请求的签名不正确。签名用于验证请求的完整性和真实性。需要仔细检查签名生成过程，确保使用了正确的私钥和请求参数。时间戳也是影响签名的重要因素，确保时间同步。 -
5300: Nonce 值小于或等于之前的 Nonce 值。Nonce（随机数）用于防止重放攻击。每个请求都必须使用一个唯一的 nonce 值，且该值必须大于先前使用的所有 nonce 值。确保 nonce 值单调递增。可以使用时间戳作为 Nonce，或者维护一个递增的计数器。 -
5600: 余额不足。表示账户中没有足够的资金来执行请求的操作，例如下单。在执行交易操作之前，应该先检查账户余额是否足够。 -
5900: 订单失败（例如，价格过低/过高）。表示由于某种原因，订单无法被执行，常见原因是订单价格与市场价格偏差过大，超出允许范围。需要检查订单参数，例如价格和数量，并确保它们在有效范围内。可以使用 Bithumb API 获取当前市场价格，并据此调整订单价格。
更完善的错误处理逻辑应包括：
- 错误代码分类： 将错误代码分类，例如身份验证错误、余额不足错误、订单错误等，以便更好地理解错误的性质。
- 重试机制： 对于某些类型的错误（例如网络错误），可以实现自动重试机制。 但是，对于身份验证错误和余额不足错误，不应尝试重试。重试时应该采用退避策略，即每次重试之间的时间间隔逐渐增加，以避免对服务器造成过大的压力。
- 日志记录： 将所有错误记录到日志文件中，以便进行调试和分析。日志记录应包括错误代码、错误消息、时间戳和相关请求参数。
- 用户通知： 在适当的情况下，向用户显示错误消息。 错误消息应清晰易懂，并提供解决问题的建议。
- 异常处理： 使用try-except 块来捕获可能发生的异常，例如网络连接错误和 JSON 解析错误。
在你的代码中，务必加入完善的错误处理逻辑。通过捕获并处理 Bithumb API 返回的错误代码，可以提高应用程序的健壮性和可靠性，改善用户体验。
5. 高级应用
掌握了 Bithumb API 的基本使用方法后，可以探索更高级的应用场景，这些应用能够提升交易效率并优化投资策略。
- 自动化交易： 通过编写自动化程序，可以执行预设的交易策略，无需人工干预。常见的策略包括网格交易，即在一定价格范围内自动挂单买卖；套利交易，即利用不同市场或交易对之间的价格差异获利；趋势跟踪策略，即根据市场趋势自动调整仓位。 自动化交易能显著提高交易效率，并降低因情绪波动带来的决策失误。
- 数据分析： Bithumb API 提供了丰富的历史数据接口，可以获取包括历史成交价、成交量、订单簿深度等数据。利用这些数据，可以进行各种分析，例如技术指标分析（如移动平均线、相对强弱指标等）、交易量分析、波动率分析等。数据分析有助于发现潜在的交易机会，并评估市场风险。
- 量化交易： 量化交易是一种结合数学模型和统计分析的交易方法。通过建立量化模型，可以对市场进行预测，并根据模型结果自动执行交易。量化交易需要具备一定的数学和统计学基础，常用的模型包括时间序列模型、机器学习模型等。量化交易能够克服主观情绪的影响，实现更客观、更稳定的交易。
- 风险管理： 利用 Bithumb API 可以实时监控账户风险，并及时采取措施控制风险。例如，可以设置止损止盈，当价格达到预设的止损或止盈价位时，自动平仓。还可以监控账户的保证金比例，当保证金比例低于一定水平时，发出预警或自动减仓。有效的风险管理是保障资金安全的关键。
Bithumb API 使交易策略的自动化成为可能，并为更深入的数据分析提供了便利。通过 API，可以构建个性化的交易系统，优化交易流程，提高交易决策的科学性和准确性，从而提升交易效率和盈利潜力。
