Bithumb API：通往韩国加密货币市场的钥匙
Bithumb，作为韩国领先的加密货币交易所之一，为开发者提供了一套强大的API，使得他们能够以编程方式访问其市场数据、执行交易以及管理账户。理解和使用 Bithumb API 对于希望深入韩国加密货币市场或者构建相关应用程序的开发者至关重要。本文将深入探讨 Bithumb API 的各个方面，帮助开发者更好地利用它。
API 概述
Bithumb API 提供了一套全面的 RESTful 接口，开发者可以通过发送 HTTP 请求来访问和利用 Bithumb 交易所的各种功能。为了满足不同的访问需求和安全级别，Bithumb API 主要分为两类：Public API (公共 API) 和 Private API (私有 API)。
- Public API (公共 API): 公共 API 允许无需身份验证即可访问的数据和功能。 这类 API 主要用于获取市场数据，如最新的交易价格、交易量、订单簿信息、以及交易所支持的币种列表等。由于无需授权，公共 API 的访问速度通常较快，适合快速获取公开信息。开发者可以利用公共 API 构建行情监控工具、数据分析应用或集成 Bithumb 的市场信息到其他平台。
- Private API (私有 API): 私有 API 需要进行身份验证，通过 API 密钥对 (API Key) 和密钥 (Secret Key) 来验证用户的身份。 私有 API 主要用于执行交易操作，例如下单、取消订单、查询账户余额、获取交易历史等。由于涉及到用户的资金安全，使用私有 API 时需要格外注意安全措施，妥善保管 API 密钥，并采取必要的安全策略，例如限制 API 密钥的访问权限、启用两因素认证等。 只有通过验证的请求才能访问用户的账户数据和执行交易。
准备工作：API 密钥
要访问 Bithumb 平台的 Private API，您需要在 Bithumb 官方网站注册一个账户，并且成功生成 API 密钥对。API 密钥由两部分组成：API Key（也称为 Public Key）和 Secret Key（也称为 Private Key）。API Key 用于标识您的身份，Secret Key 则用于对您的请求进行签名，以确保安全性。
- 注册 Bithumb 账户: 访问 Bithumb 官方网站（ https://www.bithumb.com/ ），按照页面提示完成账户注册流程。您可能需要提供您的电子邮件地址、手机号码，并设置一个安全的密码。请务必使用真实有效的信息进行注册。
- 身份验证 (KYC): 根据 Bithumb 的合规性要求，以及您希望使用的 API 功能的权限级别，您可能需要完成身份验证（Know Your Customer，KYC）流程。这通常涉及提交您的身份证明文件（例如护照、身份证）和地址证明文件（例如水电费账单）供 Bithumb 审核。请确保您提供的文件清晰可辨，并且符合 Bithumb 的要求。KYC 验证的级别越高，您能够访问的 API 功能和交易限额可能也会相应提高。
- 生成 API 密钥: 成功登录您的 Bithumb 账户后，导航至账户设置页面或者专门的 API 管理页面。在该页面，您可以找到申请生成 API 密钥的选项。按照页面提示，您可能需要设置 API 密钥的权限，例如允许交易、提现、查询余额等。请仔细选择您需要的权限，并遵循最小权限原则，只授予 API 密钥必要的权限，以降低潜在的安全风险。生成 API 密钥后，系统会提供您的 API Key 和 Secret Key。请务必将您的 Secret Key 妥善保管在安全的地方。切勿以任何方式将其泄露给他人，也不要将其存储在不安全的位置，例如源代码、公共存储库或未经加密的文档中。Secret Key 丢失或泄露可能导致您的账户资产面临风险。建议定期更换您的 API 密钥，并启用 Bithumb 提供的双重验证 (2FA) 功能，以增强账户的安全性。
Public API 的使用
Public API 提供了丰富的加密货币市场数据，助力开发者构建各种应用程序、进行数据分析和市场研究。 以下是一些常用的 Public API 端点，它们提供了不同维度的数据信息：
- 获取所有交易对信息： 通过该接口，您可以获取平台支持的所有交易对的详细信息，包括交易对名称、基础货币、报价货币、交易精度以及其他相关参数。这些信息对于了解市场交易结构至关重要。
- 获取指定交易对的市场行情： 该接口允许您查询特定交易对的实时市场行情数据，如最新成交价、最高价、最低价、成交量、24小时涨跌幅等。这些数据是进行快速交易决策和风险评估的基础。
- 获取 K 线数据： K 线数据（也称为 OHLC 数据，即开盘价、最高价、最低价、收盘价）是技术分析的重要工具。通过此接口，您可以获取不同时间周期的 K 线数据，例如 1 分钟、5 分钟、1 小时、1 天等，用于分析价格趋势和预测未来走势。
- 获取深度数据： 深度数据（也称为订单簿数据）展示了市场上买单和卖单的挂单情况，包括每个价格上的挂单数量。通过分析深度数据，您可以了解市场的买卖力量对比，判断市场的支撑位和阻力位。
- 获取最新成交记录： 该接口提供最新的成交记录，包括成交时间、成交价格、成交数量和交易方向（买入或卖出）。通过观察成交记录，您可以了解市场的实时交易动态。
- 获取平台支持的币种信息： 该接口列出平台支持的所有加密货币的详细信息，包括币种名称、代币符号、精度、以及其他相关的链上信息。
https://api.bithumb.com/public/ticker/{currency_pair}
其中 {currency_pair} 是交易对的名称，例如 BTC_KRW。
https://api.bithumb.com/public/transactionhistory/{currencypair}
https://api.bithumb.com/public/orderbook/{currency_pair}
你可以使用任何 HTTP 客户端（例如 curl、wget 或编程语言中的 HTTP 库）来发送请求并获取数据。例如，使用 curl 获取 BTC_KRW 的行情：
bash curl https://api.bithumb.com/public/ticker/BTC_KRW
Private API 的使用
Private API 允许用户以编程方式安全地管理其 Bithumb 账户，实现自动化交易、数据分析和账户管理等功能。使用Private API 务必妥善保管您的API密钥，切勿泄露给他人，并定期更换密钥以确保账户安全。访问Private API 需要进行严格的身份验证，以确保只有授权用户才能访问账户信息和执行交易操作。
以下是一些常用的 Private API 端点，这些端点涵盖了账户信息查询、订单管理、交易执行等多个方面，为用户提供了全面的账户管理能力：
POST https://api.bithumb.com/info/account
需要提供 endpoint, api-key, timestamp, signature 这些请求头。
POST https://api.bithumb.com/trade/place
需要提供订单类型、数量、价格等参数。
POST https://api.bithumb.com/trade/cancel
身份验证
使用 Bithumb Private API 之前，必须对每个请求进行签名，以验证请求的身份和完整性。Bithumb 采用 HMAC-SHA512 算法生成请求签名，确保通信安全可靠。详细签名流程如下：
-
构造数据字符串:
将所有请求参数按照
key=value的格式拼接成一个字符串。务必按照参数名称的字典顺序进行排序，然后对拼接后的字符串进行 URL 编码，确保特殊字符得到正确处理。例如，将空格替换为%20，将等号=替换为%3D。 - 计算消息摘要: 使用您的 Secret Key 作为密钥，对上一步构造的数据字符串进行 HMAC-SHA512 运算。HMAC（Hash-based Message Authentication Code）是一种消息认证码算法，通过散列函数和密钥，验证消息的完整性和真实性。
- 生成签名: 将 HMAC-SHA512 运算得到的消息摘要（通常是十六进制字符串）转换为 Base64 编码。Base64 是一种常用的编码方式，将二进制数据转换为文本格式，方便在 HTTP 请求头中传输。
-
添加请求头:
将您的 API Key、当前时间戳 (Timestamp) 和生成的签名添加到 HTTP 请求头中。这些信息将用于 Bithumb 服务器验证请求的合法性。通常，这些请求头的名称是
Api-Key、Api-Timestamp和Api-Signature，具体名称请参考 Bithumb API 文档。
以下是一个 Python 示例，演示如何生成 Bithumb API 请求签名：
import hashlib
import hmac
import time
import base64
import urllib.parse
def generate_signature(endpoint, params, secret_key, api_key):
"""生成 Bithumb API 请求签名"""
enc_params = urllib.parse.urlencode(params)
data = endpoint + chr(0) + enc_params + chr(0) + api_key
hmac_key = secret_key.encode('utf-8')
hmac_data = data.encode('utf-8')
signature = hmac.new(hmac_key, hmac_data, hashlib.sha512).hexdigest()
return signature
发送 Private API 请求
发送 Private API 请求时，必须包含特定的请求头以进行身份验证和授权。这些请求头确保了只有经过授权的用户才能访问私有数据并执行敏感操作。
-
Api-Key: 你的 API Key，用于标识你的账户。请妥善保管你的 API Key，避免泄露给未授权方。API Key 通常在你的账户设置或开发者控制台中生成和管理。 -
Api-Sign: 使用你的 Secret Key 生成的签名。签名用于验证请求的完整性和真实性，防止请求被篡改。签名算法通常涉及将请求参数、时间戳、Endpoint 和 Secret Key 组合在一起进行哈希运算（例如，HMAC-SHA256）。 -
Api-Timestamp: 请求的时间戳（以毫秒为单位）。时间戳用于防止重放攻击。服务端通常会验证时间戳的有效性，例如，拒绝超过一定时间窗口的请求。
以下是一个 Python 示例，演示如何发送账户余额请求：
import requests
import time
import hashlib
import hmac
import urllib.parse
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
endpoint = "/info/account"
params = {
"currency": "BTC"
}
timestamp = str(int(time.time() * 1000))
def generate_signature(endpoint, params, secret_key, api_key):
query_string = urllib.parse.urlencode(params)
message = endpoint + "?" + query_string + timestamp + api_key
hmac_obj = hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha512)
signature = hmac_obj.hexdigest()
return signature
signature = generate_signature(endpoint, params, secret_key, api_key)
headers = {
"Api-Key": api_key,
"Api-Sign": signature,
"Api-Timestamp": timestamp
}
url = "https://api.bithumb.com" + endpoint + "?" + urllib.parse.urlencode(params)
response = requests.get(url, headers=headers)
print(response.())
重要提示：
-
请务必替换
YOUR_API_KEY和YOUR_SECRET_KEY为你自己的真实 API Key 和 Secret Key。 - Secret Key 必须保密，切勿泄露给他人。
- 实际的签名生成算法可能因交易所而异。请参考交易所的官方 API 文档以获取准确的签名生成方法。本示例使用了 HMAC-SHA512 算法，并假设请求方法是 GET。不同交易所可能采用不同的哈希算法和请求方法。
- 本示例使用 GET 请求，如果交易所要求使用 POST 请求，请相应地修改代码。
- 仔细阅读并理解交易所的 API 文档，了解所有必需的参数和请求头的要求。
- 错误处理：在实际应用中，请添加适当的错误处理机制，例如检查响应状态码和处理异常。
- 速率限制：了解交易所的速率限制策略，并在你的代码中实现相应的限制措施，以避免被封禁。
错误处理
Bithumb API 利用标准的 HTTP 状态码体系来反馈请求的处理结果。开发者应充分理解这些状态码的含义，以便构建健壮的应用。以下列出了一些常见的状态码及其具体含义：
-
200 OK: 请求已成功处理并返回了预期结果。这是最理想的状态，表明服务器已成功接收、处理并响应了客户端的请求。 -
400 Bad Request: 请求格式错误或缺少必要的参数。这通常意味着客户端发送的请求不符合 API 的规范，例如，参数类型不正确、缺少必需的参数或参数值超出允许的范围。开发者需要仔细检查请求的构造，确保所有参数都符合 API 的要求。 -
401 Unauthorized: 身份验证失败。客户端未提供有效的身份验证凭据，或提供的凭据已过期或无效。在使用 API 之前，务必正确配置 API 密钥和签名，并确保密钥处于有效期内。 -
403 Forbidden: 客户端没有足够的权限访问请求的资源。即使身份验证成功，客户端也可能因为权限不足而无法访问某些 API 接口或数据。检查你的 API 密钥是否具有访问目标资源的权限。 -
429 Too Many Requests: 客户端在短时间内发送了过多的请求，触发了 API 的速率限制。为了保证服务的稳定性和公平性，Bithumb API 限制了每个客户端在一定时间内的请求次数。开发者需要实现速率限制机制，例如使用指数退避算法，以避免触发此错误。 -
500 Internal Server Error: 服务器内部发生错误，无法完成请求。这通常是服务器端的问题，例如代码错误、数据库连接问题或服务器资源不足。如果频繁出现此错误，应及时联系 Bithumb 技术支持。
除了 HTTP 状态码，Bithumb API 的响应体通常包含一个
status
字段和一个
message
字段，提供更详细的错误信息。
status
字段是一个字符串，
"0000"
表示请求成功。任何其他值都表示发生了错误，具体的错误代码可以参考 Bithumb API 的官方文档。
message
字段包含对错误的简要描述，有助于开发者快速定位问题。
编写代码时，必须同时检查 HTTP 状态码和响应体中的
status
字段。优先检查 HTTP 状态码，因为它可以快速判断请求是否成功。如果 HTTP 状态码表明请求失败，则可以进一步检查
status
字段和
message
字段，以获取更详细的错误信息。通过充分利用这些信息，开发者可以及时发现、诊断和处理 API 调用中的错误，提高应用程序的稳定性和可靠性。建议使用 try-except 块等结构化错误处理机制来捕获和处理异常，避免程序崩溃或产生意外行为。
速率限制
Bithumb API 实施了速率限制机制，旨在防止恶意滥用行为，保障服务器稳定性和可用性。当客户端在短时间内发送过多请求时，服务器将返回
429 Too Many Requests
错误状态码，表明请求已被限制。
为了避免触发速率限制，开发者必须严格遵循 Bithumb 官方文档中关于速率限制的具体规定。这些规定通常包括每分钟或每秒允许的最大请求数量，以及不同 API 端点可能存在的差异化限制策略。请务必仔细查阅官方文档，了解最新的速率限制规则。
在程序设计中，应当采取措施来应对潜在的速率限制错误。一种常用的方法是使用指数退避算法进行重试。该算法的核心思想是，当收到
429
错误时，程序暂停一段时间后重试请求，并且每次重试都将等待时间翻倍，直到达到最大重试次数或成功发送请求。通过指数退避，可以有效避免因短时间内大量重试请求而进一步加剧服务器压力，同时提高请求最终成功的可能性。
除了指数退避，还可以考虑使用其他策略来优化 API 请求，例如：批量请求，将多个操作合并到一个请求中；缓存数据，避免重复请求相同的数据；使用 WebSocket 连接，建立持久连接，减少请求的频率。
Bithumb API 是一个强大的工具，可以让你以编程方式访问和管理 Bithumb 交易所的数据和功能。通过理解 API 的各个方面，包括 Public API、Private API、身份验证、错误处理和速率限制，你可以构建出各种有用的应用程序，例如交易机器人、市场分析工具和账户管理工具。请务必仔细阅读 Bithumb 的官方文档，并遵循其规定，以确保你的应用程序能够正常运行。
