Bithumb API对接第三方应用指南
本文档旨在为开发者提供一份详尽的指南，帮助他们将韩国领先的加密货币交易所Bithumb的应用程序编程接口（API）高效、无缝地集成到各类第三方应用程序及服务中。Bithumb API提供了一系列功能强大的接口，允许开发者获取高精度的实时市场数据，包括但不限于订单簿深度、最新成交价格、交易量等；还允许开发者执行交易操作，例如提交限价单、市价单等，实现自动化交易策略；同时，开发者还可以通过API安全地管理用户账户，进行资产查询、充值提现等操作，从而构建功能丰富的加密货币交易平台、智能交易机器人、市场数据分析工具以及投资组合管理系统。
准备工作
在开始对接Bithumb API之前，必须完成以下准备工作，以确保后续开发过程的顺利进行和账户安全：
- Bithumb账户及身份验证： 您需要注册并拥有一个有效的Bithumb账户。完成必要的实名认证（KYC）流程是至关重要的，这不仅符合监管要求，也是使用Bithumb API进行交易的前提。身份验证通常需要提供身份证明、地址证明等信息。请确保您提供的信息真实有效，并仔细阅读Bithumb的相关条款和协议。
- API密钥申请与安全管理： 访问Bithumb官网的API管理页面，申请用于程序化交易的API密钥（API Key）和私钥（Secret Key）。API Key用于标识您的应用程序，Secret Key则用于签名请求，验证身份。**务必极其谨慎地保管您的私钥！** 千万不要将其存储在公共代码库、客户端应用程序或任何可能被他人访问到的地方。最佳实践包括使用环境变量、加密存储或密钥管理系统来保护您的私钥。一旦私钥泄露，请立即撤销并重新生成新的密钥对。
- 开发环境搭建与配置： 根据您选择的编程语言（例如Python、Node.js、Java等）搭建相应的开发环境。安装必要的编程语言解释器、开发工具和依赖库。例如，如果您使用Python，您可能需要安装`requests`库用于发送HTTP请求，或者安装专门的Bithumb API客户端库。确保您的开发环境配置正确，能够顺利运行您的代码。
- 网络连通性测试： 确保您的服务器或应用程序能够稳定地访问Bithumb的API服务器。由于网络环境的复杂性，可能存在防火墙、代理服务器或DNS解析等问题。您可以使用`ping`命令或`curl`等工具测试与Bithumb API服务器的网络连通性。如果遇到网络问题，请检查您的网络配置或联系您的网络管理员。同时，注意Bithumb API可能有地域限制，请确认您的服务器所在地是否允许访问。
API 认证
所有对Bithumb API的请求都需要进行认证，以确保安全性和授权。认证过程主要依赖于在HTTP请求头部添加特定的认证信息。为了成功地与Bithumb API交互，您必须在每个请求的头部中包含以下关键字段：
-
Api-Key: 您的API密钥，这是一个由Bithumb分配的唯一标识符，用于识别您的账户。请妥善保管您的API密钥，避免泄露，因为它类似于您的用户名。 -
Api-Sign: 通过API密钥、私钥和请求参数生成的数字签名。这个签名用于验证请求的完整性和真实性，防止篡改。签名生成算法通常涉及对请求参数进行哈希运算，并使用您的私钥进行加密。具体的签名算法细节，请务必参考Bithumb官方API文档。 -
Api-Timestamp: 当前时间戳，精确到毫秒级。时间戳用于防止重放攻击，即攻击者截获并重新发送之前的请求。服务器会验证时间戳的有效性，如果时间戳与服务器时间相差过大，请求将被拒绝。请确保您的系统时钟与网络时间同步。
生成API签名
API签名对于保护您的API请求至关重要，能够有效防止恶意篡改和未经授权的访问。正确的签名机制可以确保只有拥有有效私钥的用户才能成功发起API调用。下面详细介绍API签名的生成过程：
- 参数排序： 需要对所有请求参数（包括查询参数和请求体中的参数）按照其参数名称的字母顺序进行升序排列。请务必保持参数名称的大小写一致性，并且确保排序的准确性，因为任何细微的偏差都会导致签名验证失败。这一步是保证签名可重复性和一致性的基础。
- 字符串拼接： 将排序后的参数按照 "参数名=参数值" 的格式拼接成一个字符串。如果参数值本身是一个数组或对象，通常需要将其序列化为JSON字符串或其他标准格式。多个参数之间使用 "&" 符号进行连接。需要特别注意的是，参数值如果包含特殊字符，如空格、等号、& 符号等，必须进行URL编码，以避免解析错误。
- HMAC-SHA512加密： 使用您的私钥对拼接后的字符串进行HMAC-SHA512加密。HMAC (Hash-based Message Authentication Code) 是一种消息认证码算法，结合了哈希函数和密钥，能够提供完整性和身份验证。SHA512 是一种安全的哈希算法，能够生成512位的哈希值。将私钥与拼接后的字符串一起作为输入，生成一个唯一的哈希值，该哈希值与私钥相关联，可以有效防止伪造。
- Base64编码： 将HMAC-SHA512加密后的二进制结果进行Base64编码。Base64 是一种将二进制数据转换为ASCII字符的编码方式，主要用于在HTTP协议中传输二进制数据。将加密后的二进制数据进行Base64编码，可以使其更容易在网络上传输，并方便客户端进行处理。最终得到的Base64编码字符串就是您的API签名。
示例 (Python):
本示例展示如何使用Python生成用于加密货币API请求的签名。在与加密货币交易所或其他需要身份验证的API进行交互时，生成正确的签名至关重要。以下代码片段演示了如何使用`hashlib`、`hmac`、`base64`和`time`模块创建签名。
import hashlib
import hmac
import base64
import time
def generate_signature(endpoint, params, secret_key):
"""
生成API签名。
此函数接受三个参数：
-
endpoint(str): API端点，例如"/api/v1/order"。 -
params(dict): 包含请求参数的字典。 这些参数包括时间戳、订单详情等。 -
secret_key(str): 您的私钥，务必妥善保管。这是用于加密签名以验证请求的关键。
函数返回一个字符串，它是根据提供的参数和密钥生成的API签名。
Args:
endpoint (str): API endpoint.
params (dict): 请求参数。
secret_key (str): 您的私钥。
Returns:
str: API签名。
"""
encoded_params = '&'.join([f"{k}={v}" for k, v in sorted(params.items())])
message = endpoint + chr(0) + encoded_params
secret_key_bytes = secret_key.encode('utf-8')
message_bytes = message.encode('utf-8')
hashed = hmac.new(secret_key_bytes, message_bytes, hashlib.sha512)
signature = base64.b64encode(hashed.digest()).decode()
return signature
代码详解：
-
encoded_params = '&'.join([f"{k}={v}" for k, v in sorted(params.items())]): 将参数字典转换为URL编码的字符串。 重要的是对参数进行排序，以确保签名的可预测性。 `sorted(params.items())` 按字母顺序对参数进行排序。 -
message = endpoint + chr(0) + encoded_params: 然后，使用null字符 (chr(0)) 将API端点与编码的参数连接起来。 这是构造签名消息的特定于协议的方式。 -
secret_key_bytes = secret_key.encode('utf-8') message_bytes = message.encode('utf-8'): 将密钥和消息都编码为UTF-8字节。 HMAC需要字节输入。 -
hashed = hmac.new(secret_key_bytes, message_bytes, hashlib.sha512): 使用HMAC-SHA512算法创建哈希。 这涉及使用您的私钥对消息进行加密哈希。 -
signature = base64.b64encode(hashed.digest()).decode(): 将哈希摘要进行Base64编码，并将其解码为字符串。 这是API通常期望的签名格式。
示例用法
在使用API进行身份验证时，需要准备以下要素：你的API密钥（
api_key
）、私钥（
secret_key
）、请求的API端点（
endpoint
）以及请求参数（
params
）。请务必安全保管你的API密钥和私钥，切勿泄露给他人。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
endpoint = "/info/account"
params = { "currency": "BTC" }
签名（
signature
）是通过将API端点、请求参数和私钥进行加密哈希运算生成的。这个签名用于验证请求的完整性和身份。时间戳（
timestamp
）代表请求发送的时间，以毫秒为单位。使用当前时间乘以1000并转换为字符串格式，能有效防止重放攻击。
signature = generate_signature(endpoint, params, secret_key)
timestamp = str(int(time.time() * 1000))
HTTP头部信息（
headers
）包含API密钥、签名和时间戳。这些头部信息将与API请求一起发送到服务器。
Api-Key
头部携带你的API密钥。
Api-Sign
头部携带生成的签名。
Api-Timestamp
头部携带时间戳。正确的头部信息对于API的成功调用至关重要。
headers = {
"Api-Key": api_key,
"Api-Sign": signature,
"Api-Timestamp": timestamp
}
print(headers)
请将
YOUR_API_KEY
和
YOUR_SECRET_KEY
替换成你在交易所或服务商处获得的实际API密钥和私钥。 切记，API 密钥和私钥是访问你账户的重要凭证，泄漏它们可能导致资金损失或其他安全风险。在生产环境中，应使用安全的方式存储和管理这些敏感信息，例如使用环境变量、密钥管理服务等。定期更换 API 密钥也是一种良好的安全实践。
常用API接口
以下是一些常用的Bithumb API接口，包含详细说明、参数解释及常见用例，旨在帮助开发者更高效地接入和使用Bithumb的数字资产交易服务。
市场数据 (Public API):
-
/public/ticker/{currency}: 获取指定币种的实时行情数据。此接口提供币种的最新成交价、最高价、最低价、买一价、卖一价、24小时成交量、24小时成交额等关键信息，帮助用户快速了解市场动态。返回的数据通常包括时间戳，以便追踪价格变化。交易所可能会提供多种计价货币对，例如 `BTC/USDT` 或 `ETH/BTC`，因此 `{currency}` 应明确指定计价货币对，而非单一币种代码。 -
/public/orderbook/{currency}: 获取指定币种的深度信息（买单和卖单）。此接口返回指定币种的买单和卖单挂单列表，按照价格排序，并显示每个价格对应的挂单数量。深度信息对于分析市场供需关系至关重要，用户可以了解当前市场的买卖力量分布情况，判断价格走势。通常，API会限制返回的深度层数，例如只返回前20层或50层的挂单数据，以减少数据传输量。{currency}同样指明计价货币对。 -
/public/trades/{currency}: 获取指定币种的最新成交记录。此接口返回指定币种的最近成交历史记录，包括成交价格、成交数量、成交时间以及买卖方向（买入或卖出）。通过分析成交记录，用户可以了解市场的活跃程度和价格波动情况。成交记录通常按照时间倒序排列，交易所可能会限制返回的成交记录数量，例如只返回最近100条或500条成交记录。{currency}指明交易货币对。
账户信息 (Private API):
-
/info/account: 查询账户的全面信息。 此接口提供用户的账户概览，包括总资产估值、不同币种的详细余额快照、交易手续费等级、以及其他账户相关的配置信息。 通过此接口，用户可以了解其资金分布、交易权限以及享受的优惠费率。 -
/info/balance: 查询特定加密货币的余额详情。 该接口允许用户针对特定币种，查询可用于交易的可用余额以及被冻结的余额。 冻结余额通常是由于挂单、提现申请或其他锁定机制造成的。 通过该接口，用户可以精确掌握特定资产的流动性状况。 -
/info/wallet_address: 获取特定币种的唯一充值地址。 该接口提供指定加密货币的充值地址，用户可以将数字资产转入该地址以充值到交易所账户。 生成的地址通常与用户在交易所的唯一标识符相关联，确保资金能够正确记入账户。 用户需要确保充值的币种与地址类型一致，否则可能导致资产丢失。
交易 (Private API):
-
/trade/place: 下单接口，允许用户提交买入或卖出数字资产的交易请求。该接口通常需要提供交易对（例如 BTC/USDT）、交易方向（买入或卖出）、订单类型（市价单或限价单）、数量和价格（如果是限价单）等参数。交易所会验证这些参数的有效性，并在撮合引擎中创建相应的订单。 -
/info/orders: 查询订单状态接口，允许用户检索其历史和当前未完成的订单信息。通过该接口，用户可以获取订单的详细信息，如订单ID、交易对、订单类型、订单状态（例如：已挂单、部分成交、完全成交、已撤销）、下单时间、成交数量、成交均价等。通常支持根据订单ID、交易对、订单状态等条件进行过滤查询。 -
/trade/cancel: 撤销订单接口，允许用户取消尚未完全成交的订单。该接口通常需要提供要撤销的订单ID。交易所会验证用户是否有权限撤销该订单，并在撮合引擎中移除该订单。成功撤销后，订单中未成交的资产将被返还到用户的账户。
下单示例 (Python):
此示例展示如何使用 Python 向加密货币交易所 Bithumb 发送下单请求。它使用了
requests
库发送 HTTP POST 请求，
time
库获取时间戳，
hashlib
和
hmac
库用于生成签名，
base64
库用于编码签名。
import requests
import time
import hashlib
import hmac
import base64
定义 API 密钥、Secret 密钥、API 接口地址和下单参数。 请务必替换
YOUR_API_KEY
和
YOUR_SECRET_KEY
为您实际的 API 密钥和 Secret 密钥。
endpoint
定义了API的路径，
url
定义了请求的具体URL。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
endpoint = "/trade/place"
url = "https://api.bithumb.com/trade/place" # 正式环境API地址
params = {
"order_currency": "BTC", # 交易币种
"payment_currency": "KRW", # 结算币种
"units": "0.001", # 交易数量
"price": "50000000", # 交易价格
"type": "bid" # bid: 买入, ask: 卖出
}
generate_signature
函数用于生成 API 请求的签名。它首先将请求参数进行 URL 编码，然后将 API 接口地址和编码后的参数拼接成消息。 使用 Secret 密钥对消息进行哈希运算，最后将哈希值进行 Base64 编码。确保参数按照键的字母顺序排序，这是生成有效签名的关键。
chr(0)
在此处用作分隔符。
def generate_signature(endpoint, params, secret_key):
encoded_params = '&'.join([f"{k}={v}" for k, v in sorted(params.items())])
message = endpoint + chr(0) + encoded_params
secret_key_bytes = secret_key.encode('utf-8')
message_bytes = message.encode('utf-8')
hashed = hmac.new(secret_key_bytes, message_bytes, hashlib.sha512)
signature = base64.b64encode(hashed.digest()).decode()
return signature
生成签名和时间戳，时间戳需要精确到毫秒级别。
signature = generate_signature(endpoint, params, secret_key)
timestamp = str(int(time.time() * 1000))
构造 HTTP 请求头，包含 API 密钥、签名和时间戳。 这些头部信息用于验证请求的身份和完整性。
headers = {
"Api-Key": api_key,
"Api-Sign": signature,
"Api-Timestamp": timestamp
}
使用
requests.post
函数发送 POST 请求到 API 接口。 将请求头和参数传递给该函数。建议设置超时时间，以防止请求卡住。
response = requests.post(url, headers=headers, data=params)
打印 API 响应。 检查响应状态码和内容，以确认下单是否成功。 正确处理响应中的错误信息至关重要。
print(response.())
注意，以上代码仅为示例，您需要根据实际情况修改参数，例如交易币种、交易数量和交易价格。 并且，在生产环境中，请务必妥善保管您的 API 密钥和 Secret 密钥，避免泄露。
错误处理
Bithumb API 通信过程中可能会返回多种错误代码，这些代码指示了请求处理过程中出现的问题。开发者必须深入了解这些错误代码，并据此设计健壮的错误处理机制，确保应用程序的稳定性和可靠性。以下列出了一些常见的错误代码及其详细解释：
-
5100: API 密钥无效。此错误表明您提供的 API 密钥可能不正确、已过期或已被禁用。请仔细检查 API 密钥是否正确，并确保您的账户已激活且拥有足够的权限。如果问题仍然存在，请联系 Bithumb 客服支持以获取帮助。 -
5300: 请求参数错误。此错误表示您发送的 API 请求中的某些参数格式不正确、缺失或无效。请仔细检查 API 文档，确认您提供的参数类型、范围和格式是否符合要求。常见的参数错误包括缺少必填参数、参数类型不匹配、参数值超出范围等。 -
5600: 签名验证失败。Bithumb API 使用签名机制来确保请求的完整性和安全性。此错误表明您提供的签名与服务器计算的签名不匹配。这通常是由于签名算法实现错误、API 密钥泄露或请求参数被篡改所致。请务必使用正确的签名算法和 API 密钥，并确保请求参数在签名之前未被修改。 -
5900: 账户余额不足。此错误表示您的 Bithumb 账户余额不足以执行请求的操作，例如下单、提币等。请检查您的账户余额，并确保有足够的资金用于执行所需的操作。如果您使用了杠杆交易，请注意维持足够的保证金，以避免爆仓风险。
为了构建稳定可靠的应用程序，强烈建议开发者在应用程序中实现完善的错误处理机制。这包括但不限于：使用 try-catch 块捕获异常、记录错误日志、向用户显示友好的错误信息、重试失败的请求等。一个良好的错误处理机制可以帮助您及时发现并解决问题，提高应用程序的可用性和用户体验。建议开发者定期审查错误日志，分析常见错误的原因，并采取相应的措施来优化代码和配置。
安全注意事项
- 保护API密钥: 务必妥善保管您的API密钥和私钥，切勿泄露给他人。
- 限制API权限: 根据应用程序的实际需求，只申请必要的API权限。
- 使用HTTPS: 始终使用HTTPS协议进行API请求，以防止数据被窃取。
- 频率限制: 注意Bithumb API的频率限制，避免过度请求导致API被封禁。
- 输入验证: 对所有用户输入进行验证，防止SQL注入等安全漏洞。
- 日志记录: 记录API请求和响应，以便进行调试和审计。
常见问题
-
签名错误:
签名错误通常是由于API密钥、私钥或请求参数不正确导致的。请仔细检查您提供的API密钥和私钥是否与Bithumb账户中生成的密钥完全一致，包括大小写。同时，务必检查请求参数，确保它们符合Bithumb API文档的要求，例如参数的顺序、数据类型和格式。请验证签名算法的实现是否正确，包括哈希算法的选择（如SHA-256）和密钥的编码方式（如Base64）。可以使用在线签名验证工具或Bithumb提供的SDK进行验证。
常见的签名错误还包括：
- 时间戳错误：确保时间戳与Bithumb服务器的时间同步，允许的误差范围通常很小。
- 编码问题：参数值可能需要进行URL编码或其他特定编码。
- 参数顺序错误：某些API要求参数按照特定顺序排列。
-
API请求失败:
API请求失败可能由多种原因引起。请检查您的网络连接是否稳定，并确保您的服务器或应用程序能够正常访问Bithumb的API服务器。如果网络连接正常，请检查您的防火墙或代理设置是否阻止了对Bithumb API服务器的访问。您可以使用ping命令或traceroute命令来诊断网络连接问题。
请确保您使用的API端点是正确的，并且与您要执行的操作相匹配。例如，交易API和行情API的端点是不同的。查看Bithumb的API文档，确认正确的端点地址。
服务器端错误（如500 Internal Server Error）也可能导致API请求失败。在这种情况下，您可以稍后重试，或者联系Bithumb的技术支持。
-
API频率限制:
Bithumb为了保护其API服务器的稳定性和可用性，实施了API频率限制（Rate Limiting）。这意味着您在一定时间内可以发送的API请求数量是有限制的。超过频率限制会导致API请求被拒绝，并可能返回错误代码。请仔细阅读Bithumb API的文档，了解不同API端点的频率限制规则，例如每分钟允许的请求数量。
为了避免触发频率限制，建议您采取以下措施：
- 合理控制API请求的频率：根据实际需求，调整API请求的间隔时间，避免不必要的频繁请求。
- 使用批量请求：如果可能，将多个请求合并为一个批量请求，以减少请求的总数量。
- 实现重试机制：当API请求被频率限制拒绝时，可以实现自动重试机制，在等待一段时间后再次发送请求。
- 使用Websocket：对于需要实时数据的场景，可以考虑使用Websocket API，它可以在单个连接上推送数据，减少了频繁的HTTP请求。
持续学习
Bithumb API作为韩国领先的数字货币交易所Bithumb提供的应用程序编程接口，是连接开发者应用程序与Bithumb交易平台的关键桥梁。为了确保开发者能够充分利用Bithumb API进行高效、安全、稳定的交易和数据分析，Bithumb官方会定期或不定期地对API进行更新和改进。这些更新可能涉及以下几个方面：
- 新增API接口： 为了满足不断变化的市场需求和开发者日益增长的功能需求，Bithumb可能会增加新的API接口，以提供更多的交易类型、更丰富的数据信息或更高级的功能服务。
- 现有API接口优化： 为了提高API的性能、稳定性和安全性，Bithumb可能会对现有的API接口进行优化，例如改进数据传输效率、增强安全性验证机制、修复潜在的漏洞等。
- API文档更新： 随着API接口的更新和改进，Bithumb官方也会及时更新API文档，详细描述新的API接口的使用方法、参数说明、返回值格式等，以及对现有API接口的变更进行说明。
- 安全策略升级： 为了应对日益复杂的网络安全威胁，Bithumb会不断升级安全策略，例如加强身份验证、防止DDoS攻击、保护用户数据安全等，这些安全策略的调整也可能会影响API的使用方式。
- 功能调整： 为了提升用户体验和满足合规要求，Bithumb可能会对API的功能进行调整，例如调整交易规则、修改手续费计算方式等。
因此，对于使用Bithumb API进行开发的开发者来说，持续关注Bithumb官方的API文档至关重要。开发者可以通过以下方式及时获取API的最新信息：
- 定期访问Bithumb官方网站的API文档页面： 这是获取API最新信息的最直接途径，开发者可以定期访问该页面，查看是否有新的API接口、API文档更新或安全策略调整等。
- 订阅Bithumb官方的开发者邮件列表或社区： Bithumb官方可能会通过邮件列表或开发者社区发布API的更新公告，开发者可以通过订阅这些渠道及时获取API的最新信息。
- 关注Bithumb官方的社交媒体账号： Bithumb官方可能会通过社交媒体账号发布API的更新公告，开发者可以通过关注这些账号及时获取API的最新信息。
通过持续学习和关注Bithumb官方的API文档，开发者可以及时了解最新的API接口和功能，并根据API的更新情况及时调整自己的应用程序，以确保其能够与Bithumb交易平台保持兼容，并充分利用API提供的各种功能和服务，从而为用户提供更好的交易体验。
