Bithumb 交易所 API 使用指南
本文将详细介绍 Bithumb 交易所 API 的使用方法,帮助开发者快速接入 Bithumb 平台,进行交易、获取行情数据等操作。
1. API 概述
Bithumb 提供了一套功能全面的 RESTful API,使开发者和交易者能够以编程方式与交易所进行深度交互。利用该API,用户可以自动化交易策略,构建数据分析工具,并集成Bithumb的功能到其他应用程序中。通过 API,您可以:
- 查询账户信息: 获取您的账户余额,包括各种数字货币和韩元(KRW)的可用余额、已冻结余额等详细信息。同时,也能查询历史账户变动记录,方便追踪资金流动。
- 管理交易: 创建、修改和取消订单,支持市价单、限价单等多种订单类型。您可以设置止损止盈策略,并实时监控订单状态。
- 获取实时市场数据: 订阅实时行情数据流,包括最新的交易价格、成交量、买一价/卖一价、深度数据等。这些数据对于高频交易和算法交易至关重要。
- 获取历史数据: 下载历史交易数据,包括K线数据(OHLCV)、历史成交记录等。利用历史数据可以进行回测,优化交易策略,并进行市场趋势分析。
- 管理 API 密钥: 生成、管理和删除您的 API 密钥。您可以为每个密钥设置不同的权限,例如只读权限或交易权限,以提高安全性。密钥的访问权限管理是保障账户安全的重要环节。
- 提币和充币: 发起数字货币的提币请求,并获取充币地址。方便用户在Bithumb交易所与其他钱包或交易所之间转移数字资产。
Bithumb API 采用标准的 HTTP 请求方法 (GET, POST, DELETE),并使用 JSON 作为数据交换格式。API响应返回的状态码遵循 HTTP 协议标准,方便开发者处理各种情况。API还提供了详细的错误代码和错误信息,帮助开发者快速定位和解决问题。
2. API 密钥申请
为了充分利用 Bithumb API 的强大功能,您需要获取并配置 API 密钥。 API 密钥是您访问 Bithumb 数据和执行交易的凭证。 请严格按照以下步骤操作,确保密钥的安全和正确配置:
- 登录 Bithumb 账户: 访问 Bithumb 官方网站并使用您的账户凭据(用户名和密码)进行登录。确保您已启用双重身份验证(2FA)以增强账户安全性。
- 导航至 API 管理页面: 成功登录后,找到 “API 管理”、“API 设置” 或类似的页面。该页面通常位于账户设置、安全设置或开发者中心等区域。由于 Bithumb 平台界面可能会更新,如果难以找到,请查阅 Bithumb 的官方帮助文档或联系客服。
- 创建新的 API 密钥: 在 API 管理页面,点击 “创建新的 API 密钥”、“生成 API Key” 或类似的按钮。这将启动密钥生成流程。
-
配置 API 密钥权限:
这是至关重要的一步,您需要根据您的具体需求精确设置 API 密钥的权限。错误的权限配置可能导致安全风险或功能限制。Bithumb 通常提供以下权限选项:
- 交易权限 (Trade): 授予此权限后,您可以通过 API 接口下单买卖数字货币,进行交易操作。 务必谨慎授予此权限,只在需要自动交易的场景下开启。
- 查询权限 (Info/Read): 允许您通过 API 接口查询账户余额、持仓信息、历史交易记录、市场行情数据等。 这是最常用的权限,几乎所有应用都需要。
- 提现权限 (Withdraw): 允许您通过 API 接口将数字货币提取到指定的外部地址。 强烈建议您不要轻易开启此权限。 只有在极少数高度信任的自动化提现场景下才考虑开启,并务必设置提现白名单,限制提现地址,以最大限度地降低安全风险。
权限配置注意事项:
- 最小权限原则: 始终遵循最小权限原则,仅授予 API 密钥执行其所需任务的最低权限。
- 权限组合: 根据您的应用程序或交易策略的需求,合理组合不同的权限。例如,一个只用于监控市场行情的程序只需要查询权限,而一个自动交易机器人则需要交易权限和查询权限。
-
保存 API Key 和 Secret Key:
成功创建 API 密钥后,Bithumb 会生成一个
API Key (公钥)
和一个
Secret Key (私钥)
。
API Key 相当于您的用户名,用于标识您的身份;Secret Key 相当于您的密码,用于验证您的身份。
请务必采取以下措施妥善保管您的 Secret Key:
- 立即备份: 将 API Key 和 Secret Key 立即保存到一个安全的地方,例如加密的密码管理器、离线存储设备或物理介质。
- 禁止泄露: 绝对不要将您的 Secret Key 泄露给任何人,包括 Bithumb 的客服人员。 任何声称需要您的 Secret Key 的行为都可能是欺诈。
- 安全存储: 不要将 API Key 和 Secret Key 存储在不安全的地方,例如明文的文本文件、电子邮件或聊天记录中。
- 定期更换: 定期更换 API Key 和 Secret Key 是一个良好的安全习惯,可以降低密钥泄露带来的风险。 Bithumb 平台通常提供密钥轮换功能。
- 风险提示: 如果您怀疑您的 Secret Key 已经泄露,请立即撤销该 API 密钥并重新生成新的密钥。
3. API 认证
所有 Bithumb API 请求都必须经过身份验证,以确保安全性和用户账户的保护。 您需要在每个 API 请求的 HTTP 头部中包含两个关键信息:API Key 和 Secret Key。 这些密钥用于验证请求的来源,并确保只有授权用户才能访问和操作其账户数据。 Bithumb 使用 HMAC-SHA512 算法对请求进行数字签名,这是一个强大的加密散列函数,用于验证请求的完整性和真实性。
API Key: 您的 API Key 是一个公开的标识符,用于标识您的应用程序或账户。 它类似于用户名,但不同于密码。 API Key 本身并不能授权任何操作,它只是告诉 Bithumb 服务器哪个账户正在发起请求。
Secret Key: 您的 Secret Key 是一个私密的、只有您知道的密钥,必须妥善保管。 类似于密码,Secret Key 用于生成 HMAC-SHA512 签名,证明请求确实来自您,并且在传输过程中没有被篡改。 切勿将您的 Secret Key 泄露给任何其他人,也不要将其存储在不安全的地方。
HMAC-SHA512 签名: HMAC-SHA512 (Hash-based Message Authentication Code using SHA512) 是一种消息认证码算法,它结合了哈希函数 SHA512 和一个密钥(Secret Key),以生成一个唯一的签名。 该签名基于请求的所有重要参数(例如 API 端点、请求时间戳、请求参数等)计算得出。 Bithumb 服务器会使用相同的参数和您的 Secret Key 重新计算签名,并将其与您在请求中提供的签名进行比较。 如果两个签名匹配,则请求被认为是有效的,否则将被拒绝。 这可以有效防止中间人攻击和数据篡改。
更详细地说明,生成签名通常包含以下步骤:
- 构建请求字符串: 将所有请求参数按照字母顺序排序,并将它们连接成一个字符串。
- 添加时间戳: 为了防止重放攻击,需要在请求中包含一个时间戳,并将其包含在请求字符串中。
- 计算 HMAC-SHA512 签名: 使用您的 Secret Key 和请求字符串作为输入,使用 HMAC-SHA512 算法计算签名。
- 添加签名到请求头: 将计算得到的签名添加到 HTTP 请求头中的特定字段(例如 "X-Bithumb-Signature")。
请参阅 Bithumb API 文档以获取有关如何生成 HMAC-SHA512 签名的详细说明和代码示例。 正确的 API 认证是使用 Bithumb API 的关键,请务必仔细阅读并理解相关文档。
请求头示例:
在与加密货币交易所或服务进行API交互时,正确的请求头至关重要。它们包含了服务器验证和处理请求所需的重要元数据。以下是一些关键请求头的示例:
Content-Type: application/x-www-form-urlencoded
Content-Type
头指定了请求体的MIME类型。
application/x-www-form-urlencoded
是常用的编码格式,用于通过HTTP POST方法发送数据。它会将数据编码成键值对的形式,例如
key1=value1&key2=value2
。 确保你的请求体按照此格式正确编码,否则服务器可能无法解析你的请求。
Api-Key: YOUR API KEY
Api-Key
头通常用于身份验证。 你需要将
YOUR
API
KEY
替换为你从加密货币交易所或服务提供商处获得的API密钥。 此密钥用于标识你的应用程序或用户,并授予你访问API的权限。务必妥善保管你的API密钥,避免泄露,因为它可能会被滥用。
Api-Sign: YOUR API SIGNATURE
Api-Sign
头用于验证请求的完整性和真实性。 它通常是通过对请求参数、API密钥和nonce值进行加密哈希运算生成的。
YOUR
API
SIGNATURE
必须使用特定的签名算法(例如HMAC-SHA256)生成,并且要与服务器端配置的算法一致。 交易所会使用这个签名来确认请求确实是由你发送的,并且没有被篡改。
Api-Nonce: YOUR_NONCE
Api-Nonce
头包含一个随机的、唯一的数字,称为nonce。 Nonce用于防止重放攻击,攻击者截获你的请求并重复发送。 每次发送请求时,你都必须生成一个新的nonce值。 通常,nonce可以是时间戳或递增的计数器。服务器会跟踪已使用的nonce值,并拒绝重复使用的nonce,从而防止重放攻击。
确保根据API文档的要求正确设置这些请求头,否则你的请求可能会被拒绝或处理失败。仔细阅读API文档,了解每个请求头所需的确切格式和值。
签名过程:
- 生成 Nonce (随机数): Nonce 是一个仅使用一次的随机数,对于增强交易安全性至关重要,主要用于防止重放攻击。重放攻击指的是攻击者截获并重复发送已授权的交易,从而未经授权地访问或操作系统。为了确保 Nonce 的唯一性,强烈建议使用 Unix 时间戳(自 Unix 纪元开始至今的总秒数)。Unix 时间戳能提供高精度的时间标记,降低生成重复 Nonce 的概率。在某些场景下,可以使用结合了时间戳和其他随机因素(例如随机字符串)的 Nonce 生成方法,以进一步提高安全性。选择合适的 Nonce 生成策略取决于具体应用的安全需求和性能考量。
- 构造 Payload (请求负载): Payload 是指请求体中的字符串,包含了所有需要传递给服务器的参数。构建 Payload 的过程至关重要,需要确保参数的顺序和格式与 API 文档严格一致。细微的差异,例如参数顺序的错误或格式不匹配,都可能导致签名验证失败,进而导致请求被服务器拒绝。在构建 Payload 时,务必参考 API 文档,仔细核对每个参数的名称、类型和格式要求。推荐使用编程语言提供的字符串格式化功能,例如 Python 的 f-string,来清晰、准确地构造 Payload 字符串,避免手动拼接字符串时可能出现的错误。还需要注意对特殊字符进行转义,以防止其干扰 Payload 的解析。
- 生成 Signature (签名): 签名是对 Payload 进行加密后生成的唯一标识,用于验证请求的完整性和真实性。生成签名的过程通常使用密钥(Secret Key)和哈希算法。在这个例子中,采用 HMAC-SHA512 算法对 Payload 进行加密,HMAC(Hash-based Message Authentication Code)是一种消息认证码算法,它结合了密钥和哈希函数,能够有效地防止数据被篡改。SHA512 是一种安全散列算法,能够生成 512 位的哈希值。生成 HMAC-SHA512 哈希值后,需要将其转换为 Base64 编码,Base64 是一种将二进制数据编码为 ASCII 字符串的编码方式,便于在网络上传输。最终生成的 Base64 编码字符串就是签名。为了保证签名的安全性,Secret Key 必须妥善保管,绝对不能泄露给任何第三方。
以下是一个 Python 示例,展示了如何生成 Bithumb API 签名:
import time
import hmac
import hashlib
import base64
def generate_signature(endpoint, params, api_secret, api_key):
"""Generates Bithumb API signature."""
nonce = str(int(time.time()))
m = endpoint.replace("/", "")
query_string = f"{m}{chr(0)}{params}{chr(0)}{nonce}"
h = hmac.new(api_secret.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha512)
signature = base64.b64encode(h.digest()).decode('utf-8')
return signature, nonce
示例用法
以下代码演示了如何使用Python生成符合要求的API签名,用于安全地与加密货币交易所或其他需要身份验证的API进行交互。请务必替换占位符为您自己的API密钥和秘钥。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_SECRET_KEY"
endpoint = "/info/account"
# API接口地址,例如获取账户信息的接口
params = "currency=BTC"
# 请求参数,例如指定交易币种为BTC
上述代码定义了API密钥(
api_key
)、API秘钥(
api_secret
)、目标API接口地址(
endpoint
)和请求参数(
params
)。
endpoint
变量指定了您想要访问的API端点,而
params
变量包含了您想要传递给API的查询参数。请根据实际API文档修改这些变量的值。
signature, nonce = generate_signature(endpoint, params, api_secret, api_key)
此行代码调用
generate_signature
函数,该函数负责生成API签名和随机数(nonce)。该函数接收API接口地址、请求参数、API秘钥和API密钥作为输入,并返回计算得到的签名和随机数。
print(f"Api-Key: {api_key}")
print(f"Api-Sign: {signature}")
print(f"Api-Nonce: {nonce}")
这些代码行将生成的API密钥、签名和随机数打印到控制台。这些值将被添加到API请求的头部或查询参数中,具体取决于API的要求。
Api-Key
用于标识您的身份,
Api-Sign
用于验证请求的完整性,
Api-Nonce
用于防止重放攻击。
4. 常用 API 接口
以下是一些常用的 Bithumb API 接口,用于访问市场数据、管理账户和执行交易操作。
-
查询账户余额:
/info/account
用于查询指定币种在 Bithumb 账户中的可用余额、锁定余额等信息。
- 请求方法:POST
-
参数:
currency
(币种代码,例如 BTC, ETH, XRP)。 -
请求示例:
currency=BTC
-
返回:包含账户余额信息的 JSON 对象,包括
available
(可用余额)、balance
(总余额)、trade_fee
(交易手续费率)等字段。 - 错误处理:常见的错误包括无效的币种代码,API 密钥权限不足等。
-
查询市场行情:
/public/ticker/{currency_pair}
用于获取指定交易对的最新市场行情数据,例如最新成交价、最高价、最低价等。
- 请求方法:GET
-
参数:
currency_pair
(交易对,例如 BTC_KRW, ETH_KRW, LTC_KRW)。 -
请求示例:
/public/ticker/BTC_KRW
-
返回:包含最新行情信息的 JSON 对象,包括
closing_price
(最新成交价)、high_price
(最高价)、low_price
(最低价)、volume
(成交量)、prev_closing_price
(昨日收盘价)等字段。 - 数据时效性:该接口返回的数据为实时数据,但存在网络延迟等因素影响,可能存在一定的滞后性。
-
下单:
/trade/place
用于在 Bithumb 交易所创建买入或卖出订单。
- 请求方法:POST
-
参数:
-
order_currency
(交易货币,例如 BTC, ETH)。 -
payment_currency
(结算货币,例如 KRW)。 -
units
(交易数量,以交易货币为单位)。 -
price
(委托价格,以结算货币为单位)。 -
type
(买/卖类型,bid
为买入,ask
为卖出)。
-
-
请求示例:
{ "order_currency": "BTC", "payment_currency": "KRW", "units": "0.01", "price": "50000000", "type": "bid" }
-
返回:包含订单信息的 JSON 对象,包括
order_id
(订单 ID)、status
(订单状态)等字段。 - 注意事项:下单前请确认账户余额充足,并注意交易手续费。
-
取消订单:
/trade/cancel
用于取消尚未完全成交的订单。
- 请求方法:POST
-
参数:
-
type
(订单类型,bid
或ask
,与下单时一致)。 -
order_id
(要取消的订单 ID)。 -
currency
(交易对,例如 BTC_KRW)。
-
-
请求示例:
{ "type": "bid", "order_id": "1234567890", "currency": "BTC_KRW" }
- 返回:包含取消结果的 JSON 对象,通常包含成功或失败的状态码。
- 限制:只有未完全成交的订单才能被取消。
-
查询订单状态:
/info/orders
用于查询指定订单的详细状态信息,例如成交数量、剩余数量等。
- 请求方法:POST
-
参数:
-
order_id
: 订单 ID。 -
type
: 订单类型 (bid
或者ask
)。 -
currency
: 交易对 (e.g., BTC_KRW)。
-
-
请求示例:
{ "order_id": "1234567890", "type": "bid", "currency": "BTC_KRW" }
-
返回:包含订单详细信息的 JSON 对象,包括
status
(订单状态)、executed_volume
(已成交数量)、remaining_volume
(剩余数量)等字段。
-
获取交易历史数据:
/public/transaction_history/{currency_pair}
用于获取指定交易对的历史成交记录。
- 请求方法:GET
-
参数:
currency_pair
(交易对,例如 BTC_KRW)。 -
请求示例:
/public/transaction_history/BTC_KRW
-
返回:包含历史交易记录的 JSON 对象,每条记录包含
transaction_date
(交易时间)、type
(交易类型,buy/sell)、units_traded
(交易数量)、price
(成交价格)等字段。 - 分页:该接口通常支持分页查询,可以通过参数指定返回的交易记录数量和起始位置。
示例请求 (Python):
使用Python的
requests
库与Bithumb交易所的API交互,获取账户信息。
import requests
def get_account_info(api_key, api_secret, currency="BTC"):
此函数从Bithumb交易所检索账户信息。它需要API密钥 (
api_key
)、API密钥Secret (
api_secret
)以及可选的货币类型 (
currency
,默认为"BTC") 作为输入参数。
endpoint = "/info/account"
定义API端点
/info/account
,用于获取账户信息。这是相对于Bithumb API基础URL的路径。
url = "https://api.bithumb.com/info/account"
构造完整的API请求URL。 这是Bithumb API的基础URL与特定端点的组合。
params = f"currency={currency}"
signature, nonce = generate_signature(endpoint, params, api_secret, api_key)
headers = {
"Content-Type": "application/x-www-form-urlencoded",
"Api-Key": api_key,
"Api-Sign": signature,
"Api-Nonce": nonce
}
try:
response = requests.post(url, headers=headers, data=params)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
return response.()
except requests.exceptions.RequestException as e:
print(f"Error: {e}")
return None
params = f"currency={currency}"
构建请求参数字符串。这里,我们指定要查询的货币类型。该参数通过POST请求发送。
signature, nonce = generate_signature(endpoint, params, api_secret, api_key)
调用
generate_signature
函数来生成API签名和nonce值。API签名用于验证请求的真实性,nonce是一个随机数,用于防止重放攻击。该函数(未在此处定义)接收API端点、请求参数、API密钥Secret和API密钥作为输入,并返回生成的签名和nonce。
headers = { "Content-Type": "application/x-www-form-urlencoded", "Api-Key": api_key, "Api-Sign": signature, "Api-Nonce": nonce }
设置HTTP请求头。
Content-Type
指定请求体的格式为
application/x-www-form-urlencoded
。
Api-Key
包含您的API密钥。
Api-Sign
包含生成的API签名。
Api-Nonce
包含生成的nonce值。这些头信息对于Bithumb API的身份验证至关重要。
try: response = requests.post(url, headers=headers, data=params) response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx) return response.() except requests.exceptions.RequestException as e: print(f"Error: {e}") return None
使用
requests.post
方法发送POST请求到Bithumb API。
url
是API端点,
headers
包含认证信息,
data
包含请求参数。
response.raise_for_status()
会检查响应状态码,如果状态码表示错误(4xx或5xx),则会引发HTTPError异常。如果请求成功,
response.()
会将响应体解析为JSON格式并返回。如果发生任何
requests.exceptions.RequestException
类型的异常(例如网络错误,连接超时等),则会捕获该异常,打印错误信息并返回
None
。
示例用法
要开始使用API,您需要提供有效的API密钥和密钥。请务必妥善保管您的密钥,避免泄露,这可能导致资金损失或其他安全风险。
api_key = "YOUR_API_KEY"
api_secret = "YOUR_SECRET_KEY"
获取账户信息是常见的API用例。 以下代码展示如何使用您的API密钥和密钥来获取帐户信息。
get_account_info
函数负责处理与API的身份验证和数据检索。
account_info = get_account_info(api_key, api_secret)
获取账户信息后,可以进行错误检查,确保成功检索到数据。如果成功,账户信息将被打印出来。如果出现错误,则应适当地处理,例如记录错误消息或通知用户。
if account_info:
print(account_info)
此示例展示了API密钥和密钥如何用于安全访问账户信息。请记住,在生产环境中,您应该使用环境变量或安全密钥管理系统来存储您的API密钥和密钥,而不是将它们直接嵌入到您的代码中。
5. 错误处理
Bithumb API 使用标准的 HTTP 状态码来指示请求处理的结果。开发者应熟悉并正确处理这些状态码,以便构建健壮的应用程序。常见的状态码及其含义如下:
- 200 OK: 请求成功。服务器成功处理了请求并返回了期望的结果。
- 400 Bad Request: 客户端请求错误。通常表示请求参数不符合API的要求,例如缺少必要的参数、参数格式错误或参数值超出范围。仔细检查请求参数,确保符合API文档的规范。
- 401 Unauthorized: 认证失败。表示客户端未提供有效的身份验证凭据,或者提供的凭据已过期或无效。检查API密钥是否正确配置,并确保有权访问请求的资源。
- 403 Forbidden: 禁止访问。客户端通过了身份验证,但服务器拒绝客户端访问特定的资源。这可能由于权限不足或API密钥未被授权访问该资源。
- 429 Too Many Requests: 请求频率过高。表示客户端在短时间内发送了过多的请求,超过了API的速率限制。开发者应实施速率限制策略,例如使用指数退避算法来重试请求,以避免被API阻止。
- 500 Internal Server Error: 服务器内部错误。表示服务器在处理请求时遇到了未预料到的错误。这通常是服务器端的问题,客户端可以稍后重试请求。如果问题持续存在,应联系Bithumb的技术支持团队。
- 503 Service Unavailable: 服务不可用。服务器暂时无法处理请求,通常由于服务器过载或维护。客户端可以稍后重试请求。
除了 HTTP 状态码之外,Bithumb API 返回的 JSON 响应通常包含一个
status
字段,用于更详细地指示请求的状态。例如,
"status": "0000"
通常表示请求成功。 然而,不同的API端点可能会使用不同的状态码值来表示成功或其他特定状态。务必参考具体API端点的文档以了解状态码的含义。 如果
status
字段的值不是表示成功的代码(例如,不是
"0000"
),则表示请求失败。
message
字段通常会包含更详细的错误信息,帮助开发者诊断问题。 仔细阅读
message
字段的内容,它可以提供有关错误原因的线索,例如无效的订单类型、余额不足或市场未开放。
6. 请求频率限制
Bithumb API 实施了严格的请求频率限制机制,旨在防止恶意滥用、保障系统稳定性和公平性,并确保所有用户都能获得高质量的服务。 具体的频率限制策略(例如每分钟允许的请求数量、不同API端点的限制差异等)详尽地列于Bithumb官方API文档中,建议开发者在集成API之前务必仔细查阅该文档。 文档通常会根据API的功能和复杂度定义不同的限制,以便优化资源分配。
当您的请求超过预设的频率限制时,Bithumb服务器会返回HTTP 429错误状态码,表明“请求过多”。 收到此错误后,您必须暂停发送后续请求,并在一段特定的冷却时间(通常也在API文档中指定)过后才能重新尝试。 为了避免触发频率限制,建议开发者实施以下策略:
- 缓存数据: 对于不经常变动的数据,建议在客户端或服务器端进行缓存,减少不必要的API请求。
- 批量请求: 如果API支持批量操作,尽量将多个小请求合并为一个大请求,降低请求次数。
- 异步处理: 使用异步方式发送API请求,避免阻塞主线程,并且可以更好地控制请求速率。
- 监控请求: 密切监控API请求的发送频率和返回状态,及时发现并处理频率限制问题。
- 指数退避: 当收到HTTP 429错误时,采用指数退避算法,逐渐增加重试请求的间隔时间,避免持续触发频率限制。
合理规划和管理您的API请求,有助于维持与Bithumb API的稳定连接,并确保您的应用程序能够高效可靠地运行。 请始终参考Bithumb官方API文档,以获取最新的频率限制信息。
7. 总结
本指南介绍了 Bithumb 交易所 API 的基本使用方法,包括 API 密钥申请、认证、常用接口和错误处理。 通过 API,您可以方便地进行自动化交易和数据分析。 请务必仔细阅读 Bithumb 官方 API 文档,了解更多详细信息和高级功能。 并且始终注意安全,妥善保管您的 API 密钥。