Bithumb API 调用指南：从入门到实践
Bithumb API 简介
Bithumb 作为韩国领先的加密货币交易所之一，提供了强大的应用程序编程接口 (API)，旨在促进开发者访问交易所的各项功能和服务。通过 Bithumb API，开发者可以获取实时市场数据，自动化交易流程，并有效地管理其账户。深入理解并熟练运用 Bithumb API 对于构建复杂的量化交易系统、开发先进的数据分析平台，以及将加密货币功能无缝集成到现有应用程序中至关重要。
Bithumb API 主要分为两大类：公共 API (Public API) 和私有 API (Private API)。公共 API 允许匿名访问，无需进行身份验证，主要用于获取公开的市场信息，例如实时行情数据、订单簿深度、历史交易记录等。 这些数据对于市场分析、价格监控和构建信息聚合器非常有用。与此相对，私有 API 则需要进行严格的身份验证，通过 API 密钥进行访问，用于执行与账户相关的敏感操作，包括资金管理（如充值和提现）、订单管理（如创建、取消和查询订单）以及交易历史查询。 私有 API 的访问需要格外小心，务必妥善保管 API 密钥，防止泄露导致资产损失。
公共 API 提供了以下主要功能：
- 实时行情数据： 获取指定交易对的最新价格、交易量、最高价、最低价等信息。
- 订单簿深度： 查询买单和卖单的详细信息，了解市场的供需情况。
- 历史交易记录： 获取指定交易对的历史成交数据，用于趋势分析和回测。
私有 API 提供了以下主要功能：
- 账户余额查询： 获取账户中各种加密货币和法币的余额信息。
- 订单创建与取消： 提交买单和卖单，并随时取消未成交的订单。
- 订单状态查询： 查询指定订单的当前状态，如已成交、部分成交、待成交等。
- 交易历史查询： 获取账户的交易历史记录，用于税务申报和盈亏分析。
- 资金充值与提现： 进行加密货币和法币的充值和提现操作。 (需要KYC认证)
使用 Bithumb API 需要注意以下关键事项：
- API 密钥管理： 务必安全存储 API 密钥，避免泄露。建议启用两因素认证 (2FA) 以增强安全性。
- 频率限制： Bithumb 对 API 请求频率有限制，需要遵守相关规定，避免因超出频率限制而被封禁。
- 数据格式： Bithumb API 返回的数据通常为 JSON 格式，需要使用相应的库进行解析。
- 错误处理： 需要妥善处理 API 调用过程中可能出现的错误，如网络错误、权限错误、参数错误等。
- 身份验证： 私有 API 的调用需要进行身份验证，通常涉及生成签名，并将签名添加到请求头中。
通过合理使用 Bithumb API，开发者可以构建各种强大的加密货币应用，从而提升交易效率和投资决策能力。务必仔细阅读 Bithumb 官方 API 文档，了解最新的 API 功能和使用规则。
Public API 调用
Public API 主要用于获取 Bithumb 交易所的公开市场数据，无需身份验证即可访问。通过这些 API，开发者和交易者可以实时获取市场动态，进行数据分析和交易策略制定。常见的 Public API 包括：
- Ticker API: 用于获取指定加密货币（例如 BTC/KRW、ETH/KRW）的最新交易价格、24小时成交量、最高价、最低价、涨跌幅等关键市场信息。Ticker API 返回的数据通常包含时间戳，方便追踪价格变化趋势。开发者可以利用这些数据构建价格监控工具或自动化交易系统。
- Orderbook API: 提供指定加密货币的买卖盘深度信息，也称为订单簿数据。Orderbook API 显示了当前市场上买单和卖单的价格和数量，帮助交易者了解市场供需情况和潜在的价格支撑位和阻力位。订单簿数据通常按照价格进行排序，提供多个深度的买卖盘信息，例如，买一价、买二价...卖一价、卖二价...。
- Transaction History API: 用于获取指定加密货币的交易历史记录，包括成交价格、成交数量、成交时间等详细信息。Transaction History API 可以用来分析市场交易活动，例如，可以分析特定时间段内的交易量分布，判断市场活跃程度。 这些历史数据对于技术分析和回测交易策略至关重要。 某些交易所的API还会返回交易类型（买入或卖出）。
调用示例 (Ticker API)：
Bithumb交易所的Ticker API允许开发者实时获取指定加密货币的最新交易信息，通过构造特定的URL即可访问。URL的基本格式如下：
https://api.bithumb.com/public/ticker/{currency}
其中，
{currency}
是一个占位符，需要根据您希望查询的加密货币交易对进行替换。不同的交易对代码代表不同的加密货币和法定货币组合。例如：
-
BTC_KRW：表示比特币 (BTC) 与韩元 (KRW) 的交易对。这个API调用将返回关于Bithumb市场上比特币/韩元交易对的最新信息。 -
ETH_KRW：表示以太坊 (ETH) 与韩元 (KRW) 的交易对。 -
XRP_KRW：表示瑞波币 (XRP) 与韩元 (KRW) 的交易对。
API返回的数据通常包含以下关键信息，但具体内容可能会根据Bithumb的API文档进行调整，强烈建议查阅官方文档获取最准确的信息：
-
timestamp：最新交易发生的时间戳，通常以Unix时间格式表示。 -
opening_price：最近24小时的开盘价格。 -
closing_price：最近24小时的收盘价格。 -
min_price：最近24小时的最低价格。 -
max_price：最近24小时的最高价格。 -
average_price：最近24小时的平均价格。 -
units_traded：最近24小时交易的加密货币总量。 -
volume_1day：最近24小时的交易量。 -
volume_7day：最近7天的交易量。 -
buy_price：当前买入价。 -
sell_price：当前卖出价。
请注意，在使用Bithumb API之前，务必仔细阅读Bithumb官方的API文档，了解最新的API调用规则、频率限制以及数据格式，以确保您的应用程序能够正确地获取和处理数据。同时，要遵守Bithumb的使用条款，避免滥用API资源。
Python 代码示例：
为了获取加密货币的实时行情数据，我们可以使用 Python 编程语言，并结合
requests
库发送 HTTP 请求，以及
库解析返回的 JSON 数据。以下代码展示了如何从 Bithumb 交易所获取比特币 (BTC) 的韩元 (KRW) 交易对的行情数据。
import requests
import
def get_ticker(currency):
"""
获取指定加密货币的行情数据。
Args:
currency (str): 加密货币交易对，例如 "BTC_KRW"。
Returns:
dict: 包含行情数据的字典，如果请求失败则返回 None。
"""
url = f"https://api.bithumb.com/public/ticker/{currency}"
try:
response = requests.get(url)
response.raise_for_status() # 抛出 HTTPError，以处理错误的状态码
except requests.exceptions.RequestException as e:
print(f"请求出错: {e}")
return None
try:
data = .loads(response.text)
return data
except .JSONDecodeError as e:
print(f"JSON 解析出错: {e}")
return None
if __name__ == "__main__":
btc_ticker = get_ticker("BTC_KRW")
if btc_ticker:
print(.dumps(btc_ticker, indent=4, ensure_ascii=False)) # ensure_ascii=False 解决中文显示问题
else:
print("获取 BTC_KRW 行情数据失败。")
上述代码首先导入
requests
和
库，以便发送 HTTP 请求和解析 JSON 数据。
get_ticker
函数接收币种代码（例如 "BTC_KRW"）作为参数，构造 Bithumb API 的 URL，并使用
requests.get
方法向该 URL 发送 GET 请求。 为了提高代码的健壮性，我们使用了
try...except
块来捕获可能发生的异常，例如网络连接错误（
requests.exceptions.RequestException
）和 JSON 解析错误（
.JSONDecodeError
）。
response.raise_for_status()
方法会在 HTTP 响应状态码不是 200 OK 的情况下抛出异常，方便我们检测请求是否成功。 如果请求成功 (状态码为 200)，则使用
.loads
方法将 JSON 格式的响应数据转换为 Python 字典。为了更清晰地展示数据，主程序调用
get_ticker
函数后，使用
.dumps
方法将结果格式化输出，
indent=4
参数用于指定缩进量，
ensure_ascii=False
保证输出中文内容不被转义为 ASCII 码。
Private API 调用
Private API 主要用于执行交易操作和管理个人账户信息，因此访问这些接口通常需要进行严格的身份验证。在 Bithumb 交易所，这种身份验证机制依赖于 API Key 和 Secret Key 的组合。
要开始使用 Bithumb 的 Private API，您需要首先在 Bithumb 交易所的账户设置页面中生成一个 API Key。这个过程包括登录您的 Bithumb 账户，导航至 API 管理或安全设置部分，并按照指示创建新的 API Key。创建 API Key 时，一个至关重要的步骤是设置与其关联的权限。这些权限决定了 API Key 可以执行的操作类型，例如，您可以授予 API Key 进行交易的权限、查询账户余额的权限，或者访问特定市场数据的权限。请务必根据您的实际需求仔细选择合适的权限，以确保账户安全。
创建 API Key 后，您将获得一个 API Key 和一个 Secret Key。API Key 用于标识您的身份，而 Secret Key 则用于对请求进行签名，以防止未经授权的访问。请务必妥善保管您的 Secret Key，不要将其泄露给任何人。如果您的 Secret Key 泄露，您的账户可能会面临风险。
使用 Private API 时，您需要在每个请求中包含 API Key，并使用 Secret Key 对请求进行签名。签名的过程通常涉及使用特定的加密算法（例如 HMAC-SHA512）将请求参数和 Secret Key 组合在一起，然后生成一个唯一的签名字符串。Bithumb 的 API 文档会详细说明如何生成正确的签名，以及如何在请求中包含 API Key 和签名。
请注意，不正确的权限设置或不安全的密钥管理可能会导致您的账户被盗或数据泄露。因此，在使用 Private API 时，请务必仔细阅读 Bithumb 的 API 文档，并采取必要的安全措施。
身份验证流程：
- 提交身份信息： 用户需提供有效的身份证明文件，例如身份证、护照或驾驶执照的扫描件或照片。确保图像清晰、完整，所有信息可读。同时，可能需要填写包含姓名、出生日期、居住地址等个人信息的表格。部分平台可能要求进行实名认证，验证所提供身份信息的真实性。
常用的 Private API 包括：
- Account API: 获取经过身份验证用户的账户详细信息，例如总余额、可用余额、已冻结资金以及各种加密货币的持有量等。此API通常需要提供API密钥和签名，以确保安全性并验证请求的来源。交易所或平台可能会提供不同类型的账户API，用于访问现货账户、保证金账户或衍生品账户的信息。
- Place Order API: 用于在交易所或交易平台上提交买入或卖出加密货币的订单。此API允许指定交易对（例如BTC/USD）、订单类型（市价单、限价单等）、订单数量和价格（如果是限价单）。成功执行后，订单将进入交易所的订单簿，等待撮合。调用此API通常需要提供API密钥、签名和必要的订单参数。
- Cancel Order API: 允许用户通过API取消之前提交的订单。要取消订单，通常需要提供订单ID。交易所或平台会验证请求的权限，并尝试从订单簿中移除指定的订单。此API对于管理和调整交易策略至关重要。
- Order History API: 提供访问用户历史订单记录的功能。此API通常允许指定时间范围、交易对以及订单状态（已成交、已取消、未成交）等过滤条件。返回的数据包括订单ID、订单类型、提交时间、成交价格、成交数量、手续费等信息。通过分析订单历史记录，用户可以评估交易策略的有效性，并进行风险管理。
Python 代码示例 (账户 API 交互):
以下 Python 代码演示了如何使用 Python 的
requests
库与加密货币交易所的账户 API 进行交互。 该示例涵盖了身份验证、请求构建和响应处理的基本步骤。 为了安全起见，API 密钥和密钥永远不应硬编码到脚本中，而应作为环境变量安全存储和检索。 请注意，每个交易所的具体实现可能会有所不同，因此请务必查阅目标交易所的官方 API 文档。
requests
库是用于发起 HTTP 请求的常用 Python 库。
hashlib
提供各种哈希算法，对于创建安全消息摘要至关重要。
hmac
模块用于生成基于密钥的哈希消息身份验证码 (HMAC)，从而验证数据完整性和真实性。
time
模块提供与时间相关的功能，例如获取当前时间戳，这通常在 API 请求中是必需的。
base64
模块用于对数据进行 base64 编码和解码，有时用于 API 身份验证方案。
import requests
import hashlib
import hmac
import time
import base64
替换为您的 API Key 和 Secret Key
请务必将以下占位符替换为您从交易所获得的真实 API Key 和 Secret Key。这些密钥用于验证您的身份并授权您访问账户数据。
API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
以下
get_account_info
函数用于检索指定加密货币的账户信息。
def get_account_info(currency):
endpoint = "/info/account"
url = "https://api.bithumb.com" + endpoint
nonce = str(int(time.time() * 1000))
params = {
"currency": currency
}
query_string = f"endpoint={endpoint[1:]}&nonce={nonce}&order_currency={currency}&payment_currency=KRW" # 手动构建查询字符串
encoded_query_string = query_string.encode('utf-8')
secret_key_bytes = SECRET_KEY.encode('utf-8')
signature = hmac.new(secret_key_bytes, encoded_query_string, hashlib.sha512).hexdigest()
headers = {
"Api-Key": API_KEY,
"Api-Sign": signature.upper(),
"Api-Nonce": nonce,
}
response = requests.post(url, headers=headers, data=params)
if response.status_code == 200:
data = response.()
return data
else:
print(f"Error: {response.status_code}")
print(response.text) # 打印响应内容以进行调试
return None
该函数首先构造请求所需的参数，包括时间戳（nonce）和币种代码。然后，它使用您的 Secret Key 对查询字符串进行 HMAC-SHA512 签名。签名用于确保请求的完整性和真实性。
query_string
必须严格按照指定的顺序拼接，即
endpoint
,
nonce
,
order_currency
,
payment_currency
。
payment_currency
默认为
KRW
。 API Key、签名（转换为大写）和 nonce 被添加到 HTTP 请求头中。
endpoint
的第一个斜杠必须移除。
if __name__ == "__main__":
account_info = get_account_info("BTC")
if account_info:
print(.dumps(account_info, indent=4))
这段代码演示了如何调用
get_account_info
函数并打印返回的账户信息。
.dumps
用于格式化 JSON 输出，使其更易于阅读。 请注意，错误处理包括打印 HTTP 状态代码和响应内容，以便于调试。
错误处理
在与 Bithumb API 交互时，开发者可能会遭遇多种类型的错误，涵盖 API 密钥配置问题、请求参数不符合规范、网络连接不稳定以及 Bithumb 服务器自身的问题。为确保应用程序的稳定性和可靠性，必须实施严谨且全面的错误处理机制。
-
HTTP 状态码校验：
HTTP 状态码是评估 API 请求是否成功的关键指标。正确解读这些状态码有助于快速定位问题。常见的状态码及其含义包括：
- 200 (OK)： 请求已成功处理，API 返回了预期结果。
- 400 (Bad Request)： 客户端发出的请求存在错误，通常是由于请求参数缺失、格式不正确或超出允许范围。仔细检查请求参数及其数据类型是解决此类问题的关键。
- 401 (Unauthorized)： 身份验证失败，通常是由于 API 密钥无效、未激活或与请求不匹配。请确保 API 密钥已正确配置并具有执行所需操作的权限。
- 403 (Forbidden): 服务器拒绝访问请求资源，即使客户端已通过身份验证。这可能由于权限不足或 IP 地址被限制。
- 429 (Too Many Requests)： 请求频率超过了 Bithumb API 的速率限制。为了避免此错误，实施请求速率限制策略，例如使用队列或延迟机制，以确保请求频率符合 API 的限制。
- 500 (Internal Server Error)： Bithumb 服务器遇到了内部错误，无法完成请求。此错误通常需要 Bithumb 团队进行调查和修复。开发者应记录此错误，并在必要时联系 Bithumb 支持。
- 503 (Service Unavailable): Bithumb 服务器暂时无法处理请求。通常是由于服务器维护或过载。开发者应稍后重试请求。
- JSON 响应解析与错误检测： Bithumb API 的响应数据通常采用 JSON 格式。即使 HTTP 状态码为 200，也务必解析 JSON 响应，以检查其中是否包含错误代码或错误消息。API 响应中可能包含详细的错误信息，有助于诊断和解决问题。开发者应该检查 JSON 响应中的特定字段（通常是 "status" 或 "code"）来确定请求是否成功，并根据错误消息采取适当的措施，例如重新构建请求或通知用户。
速率限制
为保障交易平台的稳定性和公平性，防止恶意攻击和API滥用，Bithumb 对其 API 接口的调用频率实施了严格的速率限制策略。开发者在使用 Bithumb API 时，必须严格遵守这些限制，否则可能会导致 API 请求被拒绝，甚至账户被暂时或永久封禁。
具体的速率限制策略会根据不同的 API 接口、用户等级以及市场情况而有所不同。开发者应仔细查阅 Bithumb 官方 API 文档，特别是关于 "Rate Limiting" 或 "API Usage" 部分的说明，以获取最准确和最新的速率限制信息。这些信息通常会明确规定每个 API 接口在特定时间段内（例如，每分钟、每秒）允许的最大请求数量。文档可能还会详细说明如何处理超出速率限制的情况，例如返回的错误代码和重试机制。
为了有效地管理 API 调用频率并避免超出限制，开发者可以采用多种技术手段。一种常用的方法是使用编程语言提供的 `sleep` 或 `delay` 函数，在每次 API 调用后暂停一段时间。暂停的时间长度应根据 API 的速率限制来精确计算，确保 API 调用频率不超过允许的范围。例如，如果某个 API 接口的速率限制是每分钟 60 次请求，则每次 API 调用后至少需要暂停 1 秒钟，以避免超出限制。更高级的方法是使用令牌桶算法或漏桶算法等流量整形技术，这些算法可以更平滑地控制 API 调用频率，并允许在短时间内发送突发请求，同时保证总体调用频率不超过限制。
安全性
在使用 Bithumb API 时，安全性是至关重要的考量因素。不当的安全措施可能导致账户资金损失或其他严重问题。
-
严格保护 API Key 和 Secret Key：
API Key 和 Secret Key 是访问 Bithumb API 的关键凭证，相当于你的账户密码。务必将它们视为高度敏感信息，并采取以下措施进行保护：
- 不要在公共场合或不安全的网络环境中泄露 API Key 和 Secret Key。
- 不要将 API Key 和 Secret Key 存储在版本控制系统（如 Git）中，尤其是在公共仓库中。
- 使用环境变量或专门的密钥管理工具来存储 API Key 和 Secret Key，避免硬编码在代码中。
- 定期轮换 API Key 和 Secret Key，以降低泄露风险。Bithumb 平台通常提供密钥生成和管理功能。
- 启用双因素身份验证（2FA），增加一层额外的安全保护。
-
强制使用 HTTPS：
Bithumb API 应该只允许通过 HTTPS 协议进行访问。HTTPS 通过 TLS/SSL 协议对数据进行加密，防止中间人攻击和数据窃取。确保你的 API 请求 URL 以
https://开头。如果发现 API 端点使用 HTTP 协议，立即停止使用并向 Bithumb 报告。 -
充分验证 API 响应数据：
接收到 Bithumb API 的响应数据后，必须进行严格的验证，以防止数据篡改或伪造。验证可以包括以下步骤：
- 检查响应的状态码： 确保状态码指示请求成功。常见的成功状态码包括 200 OK。
- 验证响应数据的完整性： 可以使用哈希算法（如 SHA-256）对响应数据进行校验，确保数据在传输过程中没有被篡改。部分 API 可能会提供签名机制，用于验证响应数据的来源和完整性。
- 检查数据类型和格式： 确保响应数据的数据类型和格式与 API 文档中描述的一致。
- 对数值进行范围检查： 确保数值在合理的范围内，防止恶意数据注入。
- 处理错误情况： 妥善处理 API 返回的错误信息，并进行适当的日志记录，以便进行问题排查。
进阶应用
在熟练掌握 Bithumb API 的基本调用方法之后，开发者可以深入探索并构建更为复杂和精密的应用程序，例如：
- 构建自动化交易系统： 通过 Bithumb API，可以程序化地执行交易策略，实现自动下单功能，预设止损点和盈利目标，以此降低风险并提高收益。更进一步，还可以根据市场行情自动调整交易参数，实现自适应交易。自动交易系统能够24/7不间断运行，抓住市场机会，并减少人为情绪干扰。系统还可以集成多种风险控制机制，例如资金分配限制，最大持仓比例等。
- 开发数据分析工具： Bithumb API 提供丰富的历史交易数据，开发者可以利用这些数据构建强大的数据分析工具。这些工具能够进行深度技术分析，识别市场趋势和交易信号。量化交易策略可以通过对历史数据的回测进行验证和优化。还可以结合机器学习算法，预测市场走势，提升交易决策的准确性。数据可视化功能可以将复杂的交易数据转化为易于理解的图表，帮助用户更好地把握市场动态。
- 集成加密货币服务： 开发者可以将 Bithumb API 无缝集成到各类应用程序中，为用户提供便捷的加密货币交易服务。例如，可以将API集成到钱包应用中，方便用户直接在钱包内进行交易。也可以构建交易所聚合平台，汇集来自不同交易所的交易对，为用户提供更广泛的选择和更优的价格。还可以开发定制化的交易机器人，满足不同用户的个性化需求。通过API集成，可以快速构建并推出创新的加密货币服务。