Bithumb API接口详解：入门与实践指南
Bithumb API 接口详解：从入门到实践
Bithumb 是韩国最大的加密货币交易所之一，其 API 接口为开发者提供了访问市场数据、执行交易、管理账户等功能。本文将深入探讨 Bithumb API 的使用方法，帮助开发者快速上手，并构建自己的交易应用。
Bithumb API 概述
Bithumb API 采用 RESTful 架构，通过标准的 HTTP 请求方法（如 GET, POST, PUT, DELETE）进行数据交互，易于开发者集成。RESTful 架构的优势在于其轻量级、可扩展性和通用性，使其成为构建 Web API 的首选方案。 API 的所有请求和响应都采用 JSON 格式，方便解析和处理。
Bithumb API 提供了丰富的功能，覆盖了加密货币交易的各个方面，其主要功能包括：
- 市场数据 API : 提供对 Bithumb 交易所实时市场数据的访问。 这包括获取最新的加密货币价格（实时行情）、历史交易数据（包括时间戳、价格和交易量）、订单簿信息（买单和卖单的深度）等。开发者可以利用这些数据进行市场分析、量化交易策略的制定以及构建交易机器人。市场数据API 是无需授权即可使用的公共API。
- 交易 API : 允许用户执行实际的交易操作。 这包括提交新的买单或卖单（下单）、取消未成交的订单（取消订单）、以及查询特定订单的当前状态（例如，已成交、部分成交、已取消等）。 交易 API 需要进行身份验证，以确保账户安全。提交订单时，需要指定交易对（例如 BTC/KRW）、订单类型（市价单或限价单）、交易数量和价格。
- 账户 API : 用于管理用户的 Bithumb 账户。 这包括查询账户中各种加密货币和法币的余额、获取完整的交易历史记录（包括充值、提现和交易），以及查看账户的资金流水。账户 API 也需要进行身份验证。账户信息 API 可以帮助用户跟踪其投资组合的表现并进行风险管理。
Bithumb API 分为 Public API 和 Private API。Public API 无需身份验证即可访问，主要提供公开的市场数据，如行情信息和交易历史。 开发者可以免费使用 Public API 构建信息聚合器、行情监控工具等。 Private API 则需要通过 API 密钥和签名进行身份验证，用于执行交易和管理账户。 为了保证账户安全，建议开发者妥善保管 API 密钥，并采取必要的安全措施，例如限制 API 密钥的访问权限和使用频率。Private API 通常需要用户生成API Key，并使用API Secret进行签名，以保证请求的安全性。
准备工作
在使用 Bithumb API 之前，必须完成一系列准备工作，确保能够安全且高效地访问和利用其提供的功能。 这些准备步骤是至关重要的，能够保障您的交易安全，并简化开发流程。
- 注册 Bithumb 账户 : 您需要在 Bithumb 交易所注册一个账户。 访问 Bithumb 官方网站，按照指示填写必要的个人信息并完成身份验证流程。 身份验证通常包括上传身份证明文件，以符合监管要求并提高账户安全性。 如果您已经拥有 Bithumb 账户，则可以跳过此步骤。
- 生成 API 密钥 : 登录您的 Bithumb 账户后，导航至 API 管理页面。通常可以在“账户设置”或类似的选项中找到。 在 API 管理页面，您可以创建新的 API 密钥对。 创建时，务必仔细设置 API 密钥的权限。 Bithumb 允许您精细地控制 API 密钥可以执行的操作，例如交易、查询账户余额、获取市场数据等。 请根据您的实际需求分配权限，遵循最小权限原则。 特别注意，务必禁用不必要的权限，例如提现权限，以降低安全风险。 生成 API 密钥后，请将其妥善保管。 API 密钥是访问您 Bithumb 账户的凭证，泄露给他人可能会导致资金损失或其他安全问题。 建议将 API 密钥存储在安全的地方，例如加密的配置文件或密钥管理系统中。 永远不要将 API 密钥硬编码到您的代码中，也不要通过不安全的渠道传输 API 密钥。
-
安装必要的开发工具
: 根据您选择的编程语言，安装相应的开发工具包和依赖项。 例如，如果您选择使用 Python，常用的 HTTP 请求库包括
requests和aiohttp（用于异步请求）。 您可以使用 pip 包管理器来安装这些库：pip install requests aiohttp。 可能还需要安装用于处理 JSON 数据的库，例如u（更快的 JSON 库）。 根据您的具体需求，您可能还需要安装其他库，例如用于数据分析的pandas或用于加密和签名的库。 仔细阅读 Bithumb API 的文档，了解所需的依赖项，并确保您的开发环境已正确配置。 推荐使用虚拟环境来隔离不同项目的依赖项，避免版本冲突。
Public API 的使用
Public API 提供无需身份验证的接口，允许开发者和用户访问 Bithumb 交易所的公开市场数据。这些API端点通常用于获取实时的交易行情、历史交易记录、订单簿信息以及其他市场统计数据。由于不需要进行身份验证，任何人都可以调用这些API，极大地便利了数据获取和分析，但同时也意味着访问频率可能受到限制，以防止滥用。
通过 Public API，可以快速构建各种应用，例如：行情显示工具、价格预警系统、量化交易策略分析模块等。需要注意的是，在使用 Public API 时，务必遵守 Bithumb 交易所的 API 使用条款，包括但不限于请求频率限制、数据使用规范等。合理的使用 Public API 可以帮助您更好地了解市场动态，进行更有效的投资决策。
获取当前市场行情
以下是一个使用 Python 和
requests
库获取 BTC/KRW (比特币/韩元) 市场行情的示例代码。此代码演示了如何通过API接口获取实时交易数据，并进行简单的异常处理，确保程序的健壮性。
import requests
url = "https://api.bithumb.com/public/ticker/BTC_KRW"
try:
response = requests.get(url)
response.raise_for_status() # 检查请求是否成功
data = response.()['data']
print(f"当前 BTC/KRW 价格: {data['closing_price']}")
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
except (KeyError, TypeError) as e:
print(f"解析 JSON 失败: {e}")
这段代码首先定义了 Bithumb 交易所提供的 API 的 URL，该 API 提供 BTC/KRW 交易对的实时行情数据。 然后，使用
requests.get()
方法向该 URL 发送一个 HTTP GET 请求。
requests
库简化了 HTTP 请求的发送和接收过程。 之后，使用
response.()
方法将服务器返回的 JSON 格式的响应内容解析为 Python 字典。 这个过程将 JSON 数据转换为 Python 对象，方便后续的数据提取和处理。 从解析后的 JSON 数据中提取出
closing_price
(最新成交价)，并通过
print()
函数将其显示在控制台上。
closing_price
代表了最近一次成交的比特币价格，以韩元计价。通过分析这个价格，可以了解当前的市场趋势和波动情况。
需要注意的是，在使用
requests
库访问 API 时，务必进行适当的异常处理，以应对可能发生的网络请求失败或 JSON 数据解析错误。
response.raise_for_status()
函数用于检查 HTTP 响应的状态码是否指示请求成功 (通常是 200 OK)。 如果状态码不在 200-300 的范围内，该函数会抛出一个
HTTPError
异常，表明请求遇到了问题。 这种异常处理机制可以帮助开发者及时发现和解决网络问题。 另外，代码中还捕获了
KeyError
和
TypeError
异常，用于处理 JSON 数据解析过程中可能出现的键不存在或数据类型不匹配的情况。 完善的异常处理机制能够确保程序的健壮性和稳定性，即使在遇到错误的情况下也能正常运行，并给出友好的提示信息。
获取最近交易历史
本节将演示如何利用 Python 编程语言以及流行的
requests
库，从 Bithumb 交易所获取 BTC/KRW（比特币/韩元）交易对的最近交易历史数据。
示例代码如下，它展示了如何构造 API 请求、处理响应数据并提取关键交易信息：
import requests
url = "https://api.bithumb.com/public/trades/BTC_KRW"
try:
response = requests.get(url)
response.raise_for_status() # 检查 HTTP 状态码，如果请求失败则抛出异常
data = response.()['data'] # 将 JSON 响应转换为 Python 字典，并提取 'data' 键对应的值（交易数据列表）
for trade in data:
print(f"时间: {trade['transaction_date']}, 类型: {trade['type']}, 价格: {trade['price']}, 数量: {trade['units_traded']}")
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}") # 捕获请求异常，例如网络连接错误、超时等
except (KeyError, TypeError) as e:
print(f"解析 JSON 失败: {e}") # 捕获 JSON 解析错误，例如键不存在、数据类型不匹配等
上述代码与获取市场行情的代码在核心逻辑上相似，主要区别在于目标 API 的 URL 以及对返回的 JSON 数据的处理方式。获取交易历史的 API 通常返回一个包含多条交易记录的列表，因此需要使用
for
循环遍历该列表，并从每条交易记录中提取所需的信息，如交易时间、交易类型（买入/卖出）、成交价格和成交数量。
response.raise_for_status()
方法用于检查 HTTP 响应状态码，如果状态码表示请求失败（例如 404 Not Found 或 500 Internal Server Error），则会抛出一个异常，从而可以更好地处理错误情况。
response.()
方法将服务器返回的 JSON 格式数据转换为 Python 字典，方便后续的数据提取和处理。对可能出现的
KeyError
和
TypeError
异常进行捕获，增强了代码的健壮性，使得程序在面对不规范的 API 响应时能够更加稳定地运行。
Private API 的使用
Private API 提供需要身份验证的接口，用于访问交易所或平台的敏感数据和执行特定操作。与公开API不同，Private API通常需要通过API密钥、签名和其他安全机制进行身份验证，以确保只有授权用户才能访问这些功能。这些API允许用户执行交易，例如买入或卖出加密货币，查询账户余额，管理订单，以及执行其他与账户管理相关的操作。由于涉及资金和账户安全，使用Private API时务必采取必要的安全措施，例如保护API密钥，使用安全的网络连接，并定期审查API访问权限。
身份验证
使用 Bithumb 的 Private API 需要进行身份验证，以确保请求的安全性。 Bithumb 采用 HMAC-SHA512 算法对请求进行数字签名，以此验证请求的来源和完整性。详细的身份验证过程涉及密钥的管理和签名生成，客户端需谨慎处理敏感信息。
- 准备请求参数 : 构建一个包含所有请求参数的字典。请求参数包括交易对、数量、价格等必要信息。确保参数名称和值的类型与 Bithumb API 文档的要求一致。
- 构建消息 : 将请求参数按照字母顺序进行排序，并将排序后的所有参数值拼接成一个字符串。参数顺序是签名算法的关键组成部分，必须严格遵守字母顺序。
- 计算签名 : 使用您的 API Secret Key 作为密钥，对拼接后的消息字符串进行 HMAC-SHA512 签名运算。HMAC-SHA512 算法能有效防止篡改，保障数据安全。
- 添加 HTTP 头部 : 将 API Key、生成的签名以及当前时间戳添加到 HTTP 请求头部。 这些头部信息是服务端验证请求身份的关键凭证，时间戳用于防止重放攻击。
以下是一个使用 Python 计算 Bithumb API 签名的示例代码。此示例展示了如何使用 Python 的
hmac
和
hashlib
库生成签名，以及如何将必要的身份验证信息添加到 HTTP 头部。
import hashlib
import hmac
import time
import base64
def generate_signature(endpoint, params, secret_key, api_key):
"""
生成 Bithumb API 请求签名.
Args:
endpoint: API 端点，例如 '/trade/place'.
params: 请求参数 (字典)，包含交易所需的参数.
secret_key: API Secret Key，请妥善保管.
api_key: API Key，用于标识您的账户.
Returns:
包含 API Key, 签名, 和时间戳的字典，用于添加到 HTTP 头部.
"""
params['endpoint'] = endpoint # 将 endpoint 也加入签名计算，确保端点信息参与签名
# 1. 准备排序后的参数字符串
param_string = "".join(f"{key}{value}" for key, value in sorted(params.items()))
# 2. 使用 Secret Key 进行 HMAC-SHA512 签名
secret_key_bytes = secret_key.encode('utf-8')
param_string_bytes = param_string.encode('utf-8')
signature_bytes = hmac.new(secret_key_bytes, param_string_bytes, hashlib.sha512).digest()
signature = base64.b64encode(signature_bytes).decode('utf-8')
# 3. 获取当前时间戳 (毫秒级)
timestamp = str(int(time.time() * 1000))
headers = {
'Api-Key': api_key,
'Api-Signature': signature,
'Api-Timestamp': timestamp
}
return headers
请务必将
YOUR_SECRET_KEY
和
YOUR_API_KEY
替换为您的实际 API 密钥。切勿将您的 Secret Key 泄露给他人，并建议定期更换 API 密钥以增强安全性。请仔细阅读 Bithumb 官方 API 文档，了解最新的身份验证要求和最佳实践。
查询账户余额
以下是一个使用 Python 和
requests
库查询数字资产账户余额的示例代码，以Bithumb交易所为例。此示例展示了如何通过 API 获取韩元（KRW）余额，并包括了必要的身份验证步骤。
import requests import hashlib import hmac import time import base64
API KEY = "YOUR API KEY" # 替换为您的 API 密钥 SECRET KEY = "YOUR SECRET KEY" # 替换为您的 Secret 密钥
def get balance(): url = "https://api.bithumb.com/info/balance" # Bithumb API 地址 params = { "currency": "KRW" # 查询韩元（KRW）余额 } endpoint = "/info/balance" # API endpoint, 用于生成签名 headers = generate signature(endpoint, params, SECRET KEY, API KEY) # 生成带有签名的头部
try:
response = requests.post(url, headers=headers, data=params) # 发送 POST 请求
response.raise_for_status() # 检查响应状态码，如果不是 200，则抛出异常
data = response.() # 将响应内容解析为 JSON 格式
if data['status'] == "0000": # 检查 API 返回的状态码，"0000" 通常表示成功
print(f"可用 KRW 余额: {data['data']['available']}") # 打印可用余额
print(f"冻结 KRW 余额: {data['data']['locked']}") # 打印冻结余额
else:
print(f"请求失败: {data['message']}") # 打印错误信息
except requests.exceptions.RequestException as e: # 捕获请求异常，例如网络错误
print(f"请求失败: {e}") # 打印请求异常信息
except (KeyError, TypeError) as e: # 捕获 JSON 解析异常，例如键不存在或类型错误
print(f"解析 JSON 失败: {e}") # 打印 JSON 解析异常信息
注意：
generate_signature
函数未在此处提供。你需要根据交易所的 API 文档实现此函数。该函数通常涉及对请求参数进行排序、使用你的 Secret Key 进行哈希运算，并生成一个包含签名的 HTTP 头部。不同的交易所可能有不同的签名生成方式，务必参考其官方文档。此代码段旨在演示如何发起 API 请求并处理响应，实际应用中需要替换 API 密钥和 Secret Key，并实现
generate_signature
函数。在生产环境中使用API密钥时，请注意安全存储，避免泄露。
调用函数查询余额
get_balance()
这段代码展示了如何通过 API 调用来查询加密货币账户的余额。它首先配置了 API 的 URL，指定了请求的目标地址，并设置了请求所需的参数，例如账户标识符或其他必要的身份验证信息。 随后，调用
generate_signature()
函数，该函数负责生成符合 API 安全要求的签名。签名的生成通常涉及使用私钥对请求参数进行加密哈希处理，以确保请求的完整性和真实性，防止篡改。 完成签名生成后，代码使用
requests.post()
方法发起一个 POST 请求，将请求参数以 JSON 格式或其他 API 要求的格式发送到指定的 URL。 生成的签名被添加至 HTTP 头部，通常以
X-Signature
或类似的自定义头部字段传递，以便服务器进行验证。 服务器接收到请求后，会验证签名是否有效，验证通过后才会处理请求。 代码处理 API 返回的响应数据。 它检查响应状态码，判断请求是否成功。如果请求成功，则解析 JSON 响应，从中提取账户余额信息。 余额信息可能以不同的格式返回，代码需要根据 API 文档进行解析，并将其转换为可用的数值类型，以便后续使用。例如，可以将余额显示在用户界面上，或者用于进行其他交易操作。
下单
在加密货币交易中，下单是执行买入或卖出操作的关键步骤。该过程与查询账户余额的操作相似，均需要精心构造请求参数，对请求进行签名以确保安全性，并通过发送 HTTP POST 请求与交易所服务器进行交互，最后对交易所返回的响应数据进行解析和处理。
详细而言，下单请求的构造涉及指定交易对（例如 BTC/USDT）、订单类型（市价单、限价单等）、买卖方向（买入或卖出）、下单数量以及价格（仅限价单需要）。这些参数必须按照交易所 API 文档的要求进行格式化。
安全性至关重要，因此需要对请求进行签名。签名过程通常包括使用您的私钥对请求参数进行哈希运算，并将生成的签名附加到请求头或请求体中。交易所会使用您的公钥验证签名，确保请求的真实性和完整性，防止篡改。
下单请求通过 HTTP POST 方法发送至交易所指定的 API 端点。发送请求需要使用编程语言中的 HTTP 客户端库，例如 Python 的 `requests` 库或 JavaScript 的 `axios` 库。
交易所会返回一个包含订单状态和相关信息的 JSON 响应。您需要解析该响应，检查订单是否成功提交，以及订单的执行情况。如果订单未成功提交，响应中通常会包含错误代码和错误信息，帮助您进行问题排查。
更深入的细节，如具体参数格式、签名算法和错误码，请务必参考 Bithumb API 文档，文档会详细说明各个 API 接口的使用方法和注意事项。不同交易所的 API 接口可能存在差异，因此务必查阅相应交易所的文档。
注意事项
- API 调用频率限制 : Bithumb API 为了保障系统稳定性和公平性，对每个 IP 地址的 API 调用频率设置了严格的限制。 短时间内大量请求可能会导致触发限流机制，从而被临时禁止访问。具体的频率限制信息，例如每分钟或每秒钟允许的请求数量，通常会在 Bithumb 官方 API 文档中详细说明。开发者应当根据文档说明，合理控制 API 请求频率，可以使用诸如延迟、批量处理等技术手段来避免超出限制。务必监控 API 返回的 HTTP 状态码和错误信息，及时发现并处理因频率限制导致的问题。
- API 文档 : 请务必仔细阅读 Bithumb 官方提供的 API 文档，这是理解和正确使用 Bithumb API 的关键。API 文档详细描述了每个接口的功能、请求参数（包括参数类型、是否必选、取值范围等）、请求方式（如 GET、POST），以及返回值的结构和含义。 通过阅读 API 文档，开发者可以准确地构造 API 请求，正确解析 API 返回的数据，从而避免因参数错误或数据理解偏差导致的问题。API 文档通常还会包含示例代码、错误码列表、版本更新说明等重要信息，建议开发者在开始集成 Bithumb API 之前仔细阅读，并在开发过程中随时查阅。
- 安全性 : API 密钥（通常包括 API Key 和 Secret Key）是访问 Bithumb API 的重要凭证，务必妥善保管，切勿泄露给任何第三方。 不要将 API 密钥硬编码到代码中，尤其是公开的代码仓库（如 GitHub）。推荐使用环境变量、配置文件等方式存储 API 密钥，并确保这些文件或变量的访问权限受到严格控制。同时，定期更换 API 密钥也是一个良好的安全实践。如果怀疑 API 密钥泄露，应立即禁用旧密钥并生成新的密钥。还应采取其他安全措施，例如限制 API 密钥的 IP 访问权限，开启双因素认证等，以提高账户的安全性。
- 错误处理 : 在编写调用 Bithumb API 的代码时，需要进行充分的错误处理，以确保程序的健壮性和可靠性。 Bithumb API 可能会返回各种错误码，例如参数错误、权限不足、服务器错误等。开发者应该根据 API 文档中提供的错误码列表，针对不同的错误情况进行相应的处理。 例如，对于参数错误，应该检查请求参数是否符合 API 的要求；对于权限不足，应该检查 API 密钥是否具有相应的权限；对于服务器错误，可以尝试重试请求或联系 Bithumb 技术支持。还应该使用 try-catch 等异常处理机制，捕获程序运行过程中可能出现的异常，并进行适当的日志记录和错误提示，以便及时发现和解决问题。
- 资金安全 : 加密货币交易具有高风险性，价格波动剧烈，存在亏损的可能。 在使用 Bithumb API 进行交易操作之前，请务必充分了解市场风险，制定合理的交易策略，并谨慎控制交易仓位。不要投入超出自身承受能力的资金进行交易。同时，还应密切关注市场动态，及时调整交易策略。Bithumb API 仅提供交易工具，不对用户的交易决策承担任何责任。用户应自行承担交易风险。建议新手投资者在进行真实交易之前，先进行模拟交易，熟悉交易流程和风险。