Bithumb API快速上手：教程、密钥、交易实战！
Bithumb API 连接教程
介绍
本文档旨在提供一个全面的 Bithumb API 连接教程，旨在帮助开发者快速、高效地集成 Bithumb 交易平台。本教程将深入讲解如何安全获取并配置 API 密钥，详细阐述基于 HTTP 协议的身份验证流程，并提供常用 API 接口的实际使用示例，例如实时行情数据获取、交易下单、账户信息查询等。我们还将收集并解答开发者在集成过程中可能遇到的常见问题，力求提供一份详尽、实用的开发指南，降低开发门槛，加速应用上线。
准备工作
在开始使用 Bithumb API 之前，请确保您已完成以下准备工作，这将有助于您顺利地进行开发和测试：
- 拥有 Bithumb 账户并完成身份验证 (KYC): 如果您还没有 Bithumb 账户，请访问 Bithumb 官方网站进行注册。注册后，务必按照指示完成身份验证（KYC）。KYC 流程通常需要您提供身份证明文件（如护照或身份证）以及地址证明等信息。完成 KYC 认证后，您才能获得访问 Bithumb API 的权限，并参与交易等活动。
- 具备一定的编程基础: 本教程假设您具备一定的编程基础，例如熟悉 Python、Java、JavaScript 或其他编程语言。您需要了解基本的编程概念，例如变量、数据类型、循环、条件语句和函数。您还应该熟悉 HTTP 请求和响应，以及 JSON 数据格式。这些知识将帮助您理解和使用 Bithumb API。
-
安装必要的开发工具和库:
根据您选择的编程语言，安装相应的开发工具和必要的库。例如，如果您选择使用 Python，您需要安装 Python 解释器，以及用于发送 HTTP 请求的
requests库。您可以使用 pip 包管理器来安装requests库：pip install requests。对于其他编程语言，您需要安装相应的 HTTP 客户端库，例如 Java 中的 Apache HttpClient 或 JavaScript 中的 Axios。您可能还需要安装 JSON 解析库，以便处理 Bithumb API 返回的 JSON 数据。您还应该选择一个合适的集成开发环境 (IDE) 或文本编辑器来编写和调试代码。
获取 Bithumb API 密钥
为了使用 Bithumb 交易所的 API 接口，您需要先获取 API 密钥。以下步骤详细介绍了如何操作：
- 登录 Bithumb 官方网站: 请使用您的 Bithumb 账户和密码，通过浏览器访问 Bithumb 官方网站 (bithumb.com)。确保您访问的是官方网站，以防止钓鱼攻击和账户信息泄露。
- 导航至 API 管理页面: 成功登录后，在您的账户设置或个人资料页面中找到 "API 管理"、"API 密钥管理" 或类似的选项。该选项通常位于账户安全或开发者设置区域。点击进入 API 管理页面。
-
创建新的 API 密钥:
在 API 管理页面，找到 "创建 API 密钥"、"添加 API 密钥" 或类似的按钮，并点击它。系统会引导您进行 API 密钥的创建流程。在这个过程中，您需要仔细设置 API 密钥的权限。Bithumb 允许您根据需求选择不同的权限，例如：
- 交易权限： 允许通过 API 进行买入和卖出操作。如果您需要通过程序自动交易，则必须启用此权限。
- 查询权限： 允许通过 API 查询账户余额、交易历史、市场行情等信息。这是最基础的权限，几乎所有 API 应用都需要此权限。
- 提现权限（可选）： 允许通过 API 发起提现请求。此权限风险较高，请谨慎授予。
-
安全地记录 API 密钥:
成功创建 API 密钥后，Bithumb 系统会生成两个重要的密钥：
- API Key (API 密钥)： 用于标识您的身份，相当于您的用户名。
- Secret Key (私钥)： 用于签名您的 API 请求，验证请求的合法性，相当于您的密码。
重要提示：
- 请勿将您的 API 密钥和 Secret Key 泄露给任何第三方。
- 定期检查您的 API 密钥权限，并根据需要进行调整。
- 如果您怀疑您的 API 密钥已被泄露，请立即删除该密钥并创建一个新的密钥。
- 启用双重身份验证 (2FA) 以增强您 Bithumb 账户的安全性。
身份验证
Bithumb API 采用基于 API Key 和 Secret Key 的安全身份验证机制。 为了确保交易安全以及账户的有效访问，您必须在每一个API请求中附带这两个关键凭证。 Bithumb 服务器将利用这些密钥来验证您的身份，并授权您访问相应的API资源。
身份验证的具体实现方式取决于您所选用的编程语言和HTTP客户端库。 不同语言和客户端在处理HTTP请求头和签名方面可能存在差异。 以下列举了一些常用的身份验证方法示例，旨在帮助您理解如何在不同的环境下进行身份验证：
Python 示例:
以下代码展示了如何使用 Python 与 Bithumb API 交互，获取账户余额等信息。 该示例使用
requests
库发送 HTTP 请求，
time
库生成时间戳，
hashlib
和
hmac
库创建签名，以及
base64
库进行编码。
requests
库是 Python 中用于发送 HTTP 请求的标准库。如果未安装，可以使用
pip install requests
命令进行安装。
import requests
import time
import hashlib
import hmac
import base64
from urllib.parse import urlencode
配置 API 密钥
在使用 Bithumb API 之前，需要在 Bithumb 平台创建 API 密钥对。 创建后，将 API Key 和 Secret Key 替换为以下变量的值。 请妥善保管您的 Secret Key，避免泄露。
API_KEY = "YOUR_API_KEY" # 替换为您的 API Key
SECRET_KEY = "YOUR_SECRET_KEY" # 替换为您的 Secret Key
生成 API 签名
Bithumb API 使用签名机制来验证请求的合法性。
generate_signature
函数用于生成 API 请求的签名。 签名算法使用 HMAC-SHA512，并使用 Base64 编码结果。
def generate_signature(endpoint, data={}, api_secret=SECRET_KEY):
"""
生成 Bithumb API 签名。
Args:
endpoint: API 端点，例如 "/info/balance".
data: 请求参数字典 (可选).
api_secret: 您的 Secret Key.
Returns:
签名字符串.
"""
endpoint = endpoint.encode('utf-8')
form_data = urlencode(data).encode('utf-8')
secret_key = api_secret.encode('utf-8')
message = endpoint + chr(0) + form_data
hashed = hmac.new(secret_key, message.encode('utf-8'), hashlib.sha512)
signature = base64.b64encode(hashed.digest())
return signature
该函数接收三个参数： API 端点 (
endpoint
)、请求参数 (
data
) 和 Secret Key (
api_secret
)。 它首先将端点和请求参数编码为 UTF-8 格式。 然后，使用 Secret Key 和 HMAC-SHA512 算法对包含端点和请求参数的消息进行哈希处理。 将哈希结果进行 Base64 编码，并返回签名字符串。
获取账户余额
get_balance
函数用于获取指定货币的账户余额。 它调用
generate_signature
函数生成签名，并构造包含签名和其他必要头部信息的 HTTP POST 请求。 如果请求成功，则返回账户余额信息。 如果请求失败，则打印错误信息并返回
None
。
def get_balance(currency="KRW"):
"""
获取账户余额。
Args:
currency: 货币类型，默认为 KRW (韩元).
Returns:
账户余额信息，如果请求失败则返回 None.
"""
endpoint = "/info/balance"
data = {"currency": currency}
signature = generate_signature(endpoint, data)
headers = {
"Api-Key": API_KEY,
"Api-Sign": signature.decode('utf-8'),
"Api-Nonce": str(int(time.time() * 1000))
}
url = "https://api.bithumb.com" + endpoint
try:
response = requests.post(url, headers=headers, data=data)
response.raise_for_status() # 检查 HTTP 状态码
return response.()
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
return None
API 密钥的安全性
请务必妥善保管您的 API 密钥（特别是 Secret Key），不要将其泄露给他人。 API 密钥泄露可能导致您的账户被盗用或遭受其他安全风险。 建议将 API 密钥存储在安全的位置，例如环境变量或加密的配置文件中。
错误处理
示例代码包含基本的错误处理机制，例如检查 HTTP 状态码和捕获请求异常。 在实际应用中，可能需要更完善的错误处理机制，以便更好地应对各种异常情况。
使用示例
在Python脚本中，
if __name__ == "__main__":
结构用于判断当前模块是被直接运行还是被导入。当脚本被直接执行时，
__name__
变量的值会被设置为
"__main__"
，此时条件成立，该结构下的代码会被执行。如果脚本是被其他模块导入的，
__name__
变量的值则为模块的名称，条件不成立，结构下的代码不会执行。
例如：
if __name__ == "__main__":
balance = get_balance()
if balance:
print(f"账户余额: {balance}")
else:
print("获取余额失败")
上述代码中，
get_balance()
函数用于获取账户余额。如果在主程序中运行该脚本，
if __name__ == "__main__":
条件成立，
get_balance()
函数会被调用，并根据返回值打印账户余额或错误信息。
f"账户余额: {balance}"
使用了f-string，这是Python 3.6+版本中引入的一种字符串格式化方法，它允许你在字符串中嵌入表达式。在获取账户余额失败的情况下，将会打印“获取余额失败”的信息。
在加密货币应用场景中，
get_balance()
函数可能调用区块链API或连接到本地节点来查询特定地址的余额。例如，可以使用Web3.py库与以太坊区块链交互，或者使用相应的SDK与比特币区块链交互。具体实现取决于所使用的区块链平台。
说明:
-
API_KEY和SECRET_KEY变量需要替换为您在加密货币交易所申请获得的 API Key 和 Secret Key。API Key 用于标识您的身份，Secret Key 用于生成签名，确保交易安全。请务必妥善保管您的 Secret Key，避免泄露，防止资金损失。 -
generate_signature()函数用于生成 API 签名。该签名是基于请求参数和 Secret Key 通过哈希算法（例如 HMAC-SHA256）计算得出的，用于验证 API 请求的合法性和完整性。交易所服务器会使用相同的算法验证签名，如果签名不匹配，则请求将被拒绝。 -
get_balance()函数用于获取账户余额。您可以修改currency参数来获取不同加密货币或法币的余额，例如 BTC、ETH、USDT 或 USD。交易所通常会提供各种货币的余额信息，方便用户了解其资产状况。 请注意，不同的交易所对于货币代码可能存在差异，需要参考交易所的API文档进行调整。 -
Api-Nonce是一个时间戳（通常是 Unix 时间戳），以毫秒或秒为单位，用于防止重放攻击。重放攻击是指攻击者截获并重新发送合法的 API 请求。通过使用 Nonce，交易所可以识别并拒绝重复的请求。每次请求都需要使用不同的 Nonce 值，确保请求的唯一性。建议使用当前时间戳作为 Nonce 值。 -
urlencode函数用于将请求参数编码成 URL 格式。URL 编码会将特殊字符（例如空格、斜杠等）转换为百分号编码，以便在 URL 中安全传输。正确的 URL 编码对于 API 请求的成功至关重要。 不同的编程语言和库都提供了 urlencode 函数。
常用 API 接口
Bithumb API 提供了一系列功能强大的接口，允许开发者获取实时市场数据、执行交易操作、查询账户详情等。这些接口旨在为用户提供全面的加密货币交易和管理工具。以下列出了一些常用的 API 接口，并对其功能进行了更详细的描述：
-
/public/ticker/{currency}:
获取指定加密货币的最新行情信息，例如当前价格、最高价、最低价、成交量等。
{currency}占位符需要替换为具体的货币代码，例如 BTC_KRW。返回的数据通常包括交易对的最新成交价、24小时内的最高价和最低价、累计成交量、以及时间戳等信息，可用于实时监控市场动态。 -
/public/orderbook/{currency}:
获取指定加密货币的实时订单簿信息，包括买单和卖单的价格和数量。
{currency}同样需要替换为具体的货币代码。 订单簿数据对于理解市场深度和流动性至关重要，可以帮助交易者制定更明智的交易策略。API 返回的数据通常按照价格排序，显示不同价格上的买单和卖单数量。 -
/public/transaction_history/{currency}:
获取指定加密货币的最新交易历史记录，包括成交价格、成交数量和成交时间。
{currency}仍然需要替换为具体的货币代码。 该接口对于分析市场趋势和交易活动非常有用。返回的数据通常包括交易时间戳、交易价格、交易数量以及交易类型（买入或卖出）。 - /info/account: 获取用户的账户信息，例如账户ID、账户状态等。此接口需要进行身份验证。返回的数据通常包括账户的创建时间、账户状态（例如是否激活）、以及其他与账户相关的配置信息。
- /info/balance: 获取用户账户中各种加密货币的余额信息，包括可用余额和冻结余额。此接口同样需要进行身份验证。返回的数据通常包括每种加密货币的币种代码、可用余额、冻结余额以及总余额。
- /trade/place: 提交新的交易订单。用户可以通过此接口进行买入或卖出操作，并指定交易对、交易数量和交易价格。此接口需要进行身份验证，并且需要提供必要的交易参数，例如交易类型（买入或卖出）、交易对、价格和数量。
- /trade/cancel: 撤销尚未成交的交易订单。用户可以通过此接口取消之前提交的订单。此接口需要进行身份验证，并且需要提供要取消的订单ID。
为了充分利用 Bithumb API 的功能，请务必仔细阅读官方 API 文档，其中包含了所有可用接口的完整列表、详细参数说明、请求示例和响应格式，以及相关的安全性和速率限制信息。理解这些文档对于正确使用 API 至关重要。
常见问题
- 请求失败，提示 "Invalid API Key": 请仔细检查您使用的 API Key 是否与Bithumb平台提供的一致。 API Key区分大小写，任何细微的拼写错误都可能导致验证失败。 确保您已正确复制并粘贴了API Key，并且没有包含任何额外的空格或字符。请确认您的API Key是否已激活，并拥有执行所需操作的权限。
- 请求失败，提示 "Invalid Signature": 这通常表示您的请求签名验证失败。 请务必确认您使用的签名算法（通常是HMAC-SHA256）实现正确无误。 仔细核对您使用的 Secret Key，它必须与您的API Key配对，并且在签名过程中使用。 Secret Key也区分大小写。 时间戳 (Nonce) 必须是单调递增的，并且与服务器时间保持同步。 如果您的本地时间与Bithumb服务器时间偏差过大，签名验证也会失败。 建议使用网络时间协议 (NTP) 服务同步您的系统时间。 请检查请求参数的顺序是否与签名算法的要求一致。
- 请求失败，提示 "Too Many Requests": Bithumb API 为了保障系统稳定，对请求频率有限制。 您可能在短时间内发送了过多的请求，超过了允许的最大值。 请详细阅读 Bithumb API 文档，了解针对不同接口的具体请求频率限制。 通常，API文档会明确说明每分钟或每秒允许的最大请求数。 建议您在代码中实现请求频率控制机制，例如使用令牌桶算法或漏桶算法来平滑请求流量。 考虑使用指数退避算法，在收到 "Too Many Requests" 错误时，逐渐增加请求之间的等待时间，避免持续触发频率限制。 您还可以考虑使用 WebSocket 连接，以减少请求次数。
- 请求失败，提示 "Insufficient Funds": 您的账户余额不足以完成您尝试执行的交易。 请检查您的账户中是否有足够的资金来支付交易所需的金额，包括交易费用。 如果您尝试进行市价单交易，价格可能会波动，导致实际成交价格高于您的预期，需要更多的资金。 确认您已正确计算了交易金额和手续费。 您可以通过Bithumb平台或API查询您的账户余额。 确保您有足够的可用余额，而不是仅有持仓资产。 如果您使用了杠杆交易，请注意维持足够的保证金水平。
错误处理
在调用 Bithumb API 时，进行完善的错误处理至关重要。务必对API请求进行严谨的错误检测和处理，确保应用的健壮性和稳定性，从而及时发现、诊断并解决潜在问题。可通过检查 HTTP 状态码以及 API 返回的 JSON 响应体中的
status
和
message
字段来判断 API 请求是否成功。例如，HTTP 状态码 200 通常表示成功，而 4xx 或 5xx 则表示客户端或服务器端错误。
status
字段通常包含数值错误代码，
message
字段则提供错误的详细描述。
如果API请求失败，根据 API 返回的错误代码和错误信息采取适当的补救措施。这可能包括：实施重试机制（例如，使用指数退避算法避免过度请求），仔细审查并调整 API 请求的参数（确保数据类型和格式正确），验证 API 密钥和权限是否有效，检查网络连接是否稳定，或在问题持续存在时联系 Bithumb 客服寻求支持。请记录所有错误信息，以便进行调试和分析，提升应用程序的可靠性。同时，考虑实现监控和警报系统，以便在发生错误时及时通知相关人员。
强烈建议仔细阅读并理解 Bithumb 官方 API 文档，特别关注错误代码部分。文档中详细列出了所有可能的错误代码及其具体含义，以及相应的建议处理方法。 熟悉常见的错误代码，例如无效的 API 密钥、参数错误、请求频率超限等，能有效提高问题解决的效率。 还应关注 Bithumb 官方发布的任何关于 API 更新或变更的公告，以免因 API 版本不兼容而导致错误发生。维护一个更新的错误代码参考表，可以帮助开发人员快速定位并解决问题。