您现在的位置是: 首页 > 帮助 帮助
Bithumb API 掘金:手把手教你玩转加密货币交易 (附Python代码)
时间:2025-03-07 46人已围观
Bithumb API 连接
本文档旨在介绍如何连接并使用 Bithumb API 进行加密货币交易和数据获取。 我们将涵盖 API 的基本概念、身份验证方法、常用端点以及在使用 API 时需要注意的事项。
1. 了解 Bithumb API
Bithumb API 是一种强大的程序化接口,允许开发者与 Bithumb 数字资产交易所进行深度交互。 通过 API,开发者可以自动化交易策略,监控市场动态,以及高效地管理其 Bithumb 账户。API 提供了多种功能,显著提高了交易效率和灵活性。
-
获取市场数据:
API 能够提供实时、准确的市场数据,包括但不限于:
- 最新的数字资产价格(如 BTC、ETH 等)。
- 24 小时交易量,反映市场活跃程度。
- 历史交易记录,用于分析市场趋势和波动性。
- 深度行情数据,包括买单和卖单的挂单量和价格,揭示市场供需关系。
-
管理账户:
用户可以通过 API 安全地管理其 Bithumb 账户信息:
- 查询账户余额,包括可用余额和已冻结余额。
- 查看详细的交易历史记录,追踪每一笔交易的执行情况。
- 查询充币和提币记录,方便财务管理。
- 获取账户安全设置信息,确保账户安全。
-
进行交易:
API 允许用户执行各种交易操作:
- 提交限价单、市价单等不同类型的订单。
- 取消未成交的订单。
- 修改现有订单的价格或数量。
- 批量下单,提高交易效率。
Bithumb API 采用广泛应用的 RESTful 架构,这意味着它使用标准的 HTTP 请求方法 (GET, POST, PUT, DELETE) 来访问和操作资源。 数据传输格式为 JSON (JavaScript Object Notation),这是一种轻量级、易于解析的数据格式,方便开发者在各种编程语言中使用。API 提供了详细的文档和示例代码,帮助开发者快速上手。
2. API 密钥获取
要通过 Bithumb API 访问其服务,你需要拥有有效的 API 密钥。这些密钥允许你以编程方式与 Bithumb 交易所进行交互,例如检索市场数据、执行交易和管理账户。请按照以下详细步骤获取并安全地管理你的 Bithumb API 密钥:
- 注册 Bithumb 账户: 如果你尚未拥有 Bithumb 账户,你需要先注册一个。访问 Bithumb 官方网站,按照注册流程填写所需信息,包括电子邮件地址、密码等。务必使用强密码并启用双因素身份验证 (2FA) 以增强账户安全性。
- 完成 KYC 认证: 为了遵守监管要求和提高账户安全级别,Bithumb 要求用户完成 KYC(了解你的客户)认证。登录你的 Bithumb 账户,按照平台指示提交必要的身份证明文件,例如护照、身份证或驾驶执照。KYC 认证可能需要一段时间进行审核,请耐心等待。
-
创建 API 密钥:
成功登录 Bithumb 账户并完成 KYC 认证后,你可以创建 API 密钥。导航至 Bithumb 账户的 "API 管理" 或类似页面。在该页面,你可以创建一个新的 API 密钥对。在创建 API 密钥时,你需要详细设置 API 密钥的权限。常见的权限包括:
- 读取交易数据: 允许 API 密钥访问市场数据,例如价格、交易量等。
- 下单: 允许 API 密钥代表你执行买卖订单。
- 提取资金: 允许 API 密钥提取账户中的加密货币(强烈不建议在未经充分安全评估的情况下授予此权限)。
成功创建 API 密钥后,你会获得两个关键信息:
- API Key: 这相当于你的公钥,用于在 API 请求中标识你的身份。在发送 API 请求时,你需要提供 API Key 以告知 Bithumb 你是谁。
- Secret Key: 这相当于你的私钥,用于生成请求签名。请求签名用于验证请求的真实性和完整性,确保请求未被篡改。 妥善保管你的 Secret Key,切勿将其泄露给任何人。任何人如果获得了你的 Secret Key,就可以代表你执行 API 请求,从而可能导致资金损失。不要将 Secret Key 存储在不安全的地方,例如明文存储在代码库中。 考虑使用硬件安全模块 (HSM) 或其他安全存储方案来保护 Secret Key。
3. 身份验证
Bithumb API 采用 HMAC-SHA512 签名机制,确保请求的安全性与完整性。所有对 Bithumb API 的调用都必须通过有效的身份验证才能成功执行。这意味着每个 API 请求都必须包含特定的头部信息,用于验证请求者的身份并防止恶意篡改。
以下是进行身份验证所需的 HTTP 头部信息:
-
Api-Key
: 你的 Bithumb API 密钥。API 密钥是平台分配给你的唯一标识符,用于识别你的账户。请务必妥善保管你的 API 密钥,切勿泄露给他人,以防止未经授权的访问。 -
Api-Sign
: 使用你的 Secret Key (私钥) 生成的数字签名。此签名是使用 HMAC-SHA512 算法对请求参数和某些其他数据进行加密计算的结果。通过验证此签名,Bithumb 可以确认请求是由你发起的,并且在传输过程中没有被篡改。生成签名的具体步骤通常包含:构建签名字符串,使用你的 Secret Key 对其进行 HMAC-SHA512 哈希运算,并将结果转换为十六进制字符串。 -
Api-Timestamp
: 请求的时间戳,表示请求发送时的 Unix 时间(自 1970 年 1 月 1 日 00:00:00 UTC 以来的毫秒数)。时间戳用于防止重放攻击。Bithumb 服务器会检查请求的时间戳与服务器当前时间的差异,如果超过一定的阈值(通常是几秒或几分钟),请求将被拒绝。这样可以避免攻击者捕获你的请求并稍后重新发送。确保你的系统时间与网络时间同步,以避免因时间戳错误导致的身份验证失败。
请注意,API 密钥和私钥需要通过 Bithumb 官方渠道申请,并妥善保管私钥,避免泄露。
签名生成步骤:
-
构造规范化的请求数据字符串:
为了确保签名的一致性和安全性,必须对所有需要参与签名的请求参数进行规范化处理。 具体步骤如下:
- 参数筛选: 排除所有值为空的参数,以及签名(signature)参数本身。这是为了防止空值或签名值影响最终的签名结果。
- 参数名排序: 将剩余的请求参数按照其参数名称的字母升序进行排列。这是一个关键步骤,保证了相同参数的不同排列顺序会产生不同的签名,从而提高安全性。
- 参数连接: 将排序后的参数,以键值对的形式(key=value)连接成一个字符串。多个键值对之间通常使用 "&" 符号进行分隔。 务必保证URL编码一致性,避免编码问题导致的签名失败。
- 生成精确的时间戳: 获取当前时间的 Unix 时间戳,精确到毫秒级别。时间戳在签名中扮演着重要的角色,它可以有效防止重放攻击(Replay Attack)。攻击者如果在一段时间后尝试重用之前的请求,时间戳的过期机制会使得签名失效,从而保护系统的安全。不同的平台或语言获取毫秒级时间戳的方法可能有所不同,例如在 JavaScript 中可以使用 `Date.now()`,在 Python 中可以使用 `time.time() * 1000`。时间戳通常需要转换为字符串类型,以便参与后续的签名计算。
-
计算高安全性的 HMAC-SHA512 签名:
使用您的 Secret Key,对包含时间戳和规范化请求数据字符串的完整字符串进行 HMAC-SHA512 签名。 HMAC (Hash-based Message Authentication Code) 是一种利用哈希函数进行消息认证的算法,SHA512 是一种安全哈希算法。
- 密钥安全: Secret Key 必须妥善保管,绝不能泄露给任何第三方。 一旦 Secret Key 泄露,攻击者就可以伪造签名,从而对系统造成严重的安全威胁。
- 签名算法: HMAC-SHA512 算法能够提供强大的安全保障,防止篡改和伪造。 该算法使用 Secret Key 对数据进行哈希运算,生成一个唯一的签名。
- 签名格式: 签名结果通常以十六进制字符串或 Base64 编码的形式表示。 具体格式取决于 API 的要求。
示例代码 (Python):
此示例演示如何使用 Python 生成 Bithumb API 请求所需的签名。它依赖于
hashlib
,
hmac
,
time
, 和
urllib.parse
库。请确保已安装这些库。特别是,请注意Bithumb的签名机制,它在连接endpoint和参数字符串时使用空字符(
chr(0)
)。
import hashlib
import hmac
import time
import urllib.parse
请将以下变量替换为您实际的 Bithumb API 密钥和私钥。务必妥善保管您的私钥,避免泄露。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
generate_signature(endpoint, params)
函数负责生成 API 请求的签名。它接受 API 端点和请求参数作为输入。
def generate_signature(endpoint, params):
"""生成 Bithumb API 签名。"""
endpoint = endpoint.encode('utf-8')
params_string = urllib.parse.urlencode(params).encode('utf-8')
secret_key_bytes = secret_key.encode('utf-8')
data = endpoint + chr(0) + params_string #Null character added
signature = hmac.new(
secret_key_bytes,
data, # Encode data to bytes if needed. Already encoded above.
hashlib.sha512
).hexdigest()
return signature
该函数首先将端点和参数字符串编码为 UTF-8 字节。然后,它将私钥编码为 UTF-8 字节,并使用
hmac.new()
函数创建一个 HMAC 对象。该函数使用 SHA512 算法对连接后的端点、空字符和参数字符串进行哈希处理。最终生成的十六进制摘要就是 API 签名。
注意,Bithumb API 特别要求在端点和参数之间添加空字符 (
chr(0)
)。 务必包含它,签名才能正确生成。
get_timestamp()
函数用于获取当前时间戳(以毫秒为单位)。此时间戳将作为请求参数之一发送到 Bithumb API。
def get_timestamp():
"""获取当前时间戳 (毫秒)."""
return str(int(time.time() * 1000))
示例用法
在使用API进行身份验证和数据交互时,以下示例代码展示了如何构造合法的请求。需要定义API的端点和所需的参数。
endpoint = "/info/account"
指定了要访问的账户信息端点。
params = {"currency": "BTC"}
定义了请求参数,这里指定了要查询的货币为比特币(BTC)。
为了确保请求的安全性,需要生成时间戳和签名。
timestamp = get_timestamp()
获取当前时间戳,时间戳是防止重放攻击的重要措施。时间戳通常表示自 Unix 纪元(1970 年 1 月 1 日 00:00:00 UTC)以来的秒数。
signature = generate_signature(endpoint, params)
使用端点和参数生成签名,签名用于验证请求的完整性和真实性,防止数据被篡改。生成签名时,通常会涉及API密钥、时间戳和请求参数,并使用特定的哈希算法(如HMAC-SHA256)进行加密。
接下来,构造HTTP请求头。
headers = { "Api-Key": api_key, "Api-Sign": signature, "Api-Timestamp": timestamp, "Content-Type": "application/x-www-form-urlencoded" }
Api-Key
包含您的API密钥,用于标识您的身份。务必妥善保管您的API密钥,避免泄露。
Api-Sign
包含生成的签名,用于验证请求的完整性。
Api-Timestamp
包含生成的时间戳,用于防止重放攻击。
Content-Type: application/x-www-form-urlencoded
指定请求体的格式。在使用POST请求发送数据时,必须设置此头部,表明数据以URL编码的形式发送。
对于不同的API,可能还需要设置其他的请求头,例如
Accept
头部用于指定接受的响应类型,
User-Agent
头部用于标识客户端。
使用
requests
库发送 HTTP 请求
在 Python 中,
requests
库是一个强大的工具,用于发送 HTTP 请求,例如与加密货币交易所的 API 进行交互。以下是如何使用
requests
库发送 GET 或 POST 请求的示例。
import requests
导入
requests
库。这是使用该库的前提。
url = "https://api.bithumb.com/public" + endpoint # 或者 /private 用于私有端点
定义要访问的 URL。公共端点用于获取公开数据,而私有端点需要身份验证才能访问个人账户信息或执行交易。确保正确构造包含所需
endpoint
的完整 URL。
endpoint
可以是API文档中规定的不同接口,例如获取ticker信息或订单簿。
data = params # 使用 data=params 进行 POST 请求
如果需要发送 POST 请求,将参数存储在
params
字典中。对于 GET 请求,这些参数通常会附加到 URL 上。对于 POST 请求,它们会被包含在请求体中。注意,不同的API对参数的要求可能不同,务必查阅对应API的文档。
try:
response = requests.get(url, headers=headers, params=data) # 或者使用 requests.post 发送 POST 请求
response.raise_for_status() # 针对错误的响应状态码(4xx 或 5xx)抛出 HTTPError 异常
print(response.())
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
使用
requests.get()
或
requests.post()
方法发送请求。可选地,可以传递
headers
字典以包含自定义 HTTP 头部,例如指定内容类型或授权令牌。
params
字典用于传递查询字符串参数(对于 GET 请求)或表单数据(对于 POST 请求)。
response.raise_for_status()
方法用于检查响应状态码是否表示成功。如果响应状态码在 400 到 599 之间,此方法将引发
HTTPError
异常。这是一种快速检测 API 请求是否成功的方法。
response.()
方法用于将响应体解析为 JSON 对象。许多加密货币 API 都返回 JSON 格式的数据。如果 API 返回的是其他格式,可能需要使用
response.text
获取原始文本,然后使用其他库(如 XML 解析器)进行处理。
使用
try...except
块来捕获
requests.exceptions.RequestException
异常,该异常涵盖了请求期间可能发生的各种错误,例如网络连接问题、超时和无效的 URL。这有助于确保程序的健壮性,并提供有用的错误信息。
headers
是一个可选的字典,用于设置HTTP请求头。例如,可以添加
'Content-Type': 'application/'
头部来指定请求体的格式为JSON,或者添加
'Authorization': 'Bearer YOUR_API_KEY'
头部来进行身份验证。具体需要添加哪些头部取决于API的要求。
4. 常用 API 端点
以下是一些常用的 Bithumb API 端点,开发者可以通过这些端点获取市场数据或执行交易操作。 Bithumb API 分为公共 API 和私有 API 两类,公共 API 无需身份验证即可访问,提供市场行情等信息;私有 API 需要身份验证,用于账户管理和交易操作。
-
公共 API (Public API): 用于获取市场行情和交易数据,无需 API 密钥。
-
/public/ticker/{currency}
: 获取指定币种的实时行情数据。此端点返回的信息包括:最新成交价(last)、最高价(high)、最低价(low)、成交量(volume)、时间戳(timestamp)等。{currency}
需要替换为具体的币种代码,例如 'BTC_KRW'。 返回数据格式通常为 JSON。 -
/public/orderbook/{currency}
: 获取指定币种的订单簿数据。订单簿数据包含买单(bids)和卖单(asks)的价格和数量信息,可以用于分析市场深度和供需关系。{currency}
需要替换为具体的币种代码。 -
/public/trades/{currency}
: 获取指定币种的最新成交记录。此端点返回的数据包括成交价格(price)、成交数量(units)、成交时间(timestamp)等,可以用于跟踪市场动向。{currency}
需要替换为具体的币种代码。
-
-
私有 API (Private API): 用于账户管理和交易操作,需要 API 密钥进行身份验证。 API 密钥包括 API Key 和 Secret Key,需要在 Bithumb 账户中生成。
-
/info/account
: 获取账户信息。返回账户的详细信息,例如账户创建时间、账户状态等。访问此端点需要提供 API Key 和 Secret Key 进行身份验证,并且可能需要设置请求头(Headers)以指定签名方式。 -
/info/balance
: 获取账户余额。返回账户中各种币种的余额信息,包括可用余额(available)和冻结余额(in_use)。访问此端点同样需要 API 密钥。 -
/trade/place
: 下单。用于提交买入或卖出订单。需要指定币种(currency)、订单类型(type, 例如:limit, market)、价格(price,仅限价单)和数量(units)。订单类型是重要的参数,限价单允许用户指定价格,而市价单会立即以当前市场价格成交。 -
/trade/cancel
: 取消订单。用于取消尚未成交的订单。需要提供订单 ID(order_id) 作为参数。 -
/info/orders
: 获取订单列表。 用于查询指定币种的历史订单和当前未完成的订单。可以根据订单状态(order_status)进行筛选。需要提供币种代码。
-
具体 API 文档请参考 Bithumb 官方文档。
5. 代码示例 (获取账户余额)
以下是一个使用 Python 编程语言,配合
requests
库获取 Bithumb 交易所账户余额的详细示例代码。该示例演示了如何生成符合 Bithumb API 安全要求的签名,并发送经过身份验证的请求。
为了实现这一目标,你需要安装
requests
库。你可以使用 pip 包管理器来安装:
pip install requests
现在,引入必要的 Python 模块:
import hashlib
import hmac
import time
import urllib.parse
import requests
请务必替换以下占位符为你自己的 Bithumb API 密钥和私钥。这些密钥可以在你的 Bithumb 账户的 API 管理页面找到。
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
generate_signature
函数负责生成符合 Bithumb API 规范的签名。该签名用于验证请求的真实性和完整性。该函数接受 API 终点 (endpoint) 和请求参数 (params) 作为输入,并使用你的私钥对它们进行哈希处理。
def generate_signature(endpoint, params):
"""生成 Bithumb API 签名."""
endpoint = endpoint.encode('utf-8')
params_string = urllib.parse.urlencode(params).encode('utf-8')
secret_key_bytes = secret_key.encode('utf-8')
关键步骤包括:将 endpoint 和参数进行编码,并使用空字符连接它们,然后使用 SHA512 算法和你的私钥对其进行 HMAC 哈希运算。
data = endpoint + chr(0) + params_string #Null character added
signature = hmac.new(
secret_key_bytes,
data.encode('utf-8'),
hashlib.sha512
).hexdigest()
return signature
get_timestamp
函数用于获取当前时间戳,精确到毫秒。Bithumb API 要求所有请求都包含时间戳,以防止重放攻击。
def get_timestamp():
"""获取当前时间戳 (毫秒)."""
return str(int(time.time() * 1000))
设置 API 终点为
/info/balance
,并指定要查询的货币为 BTC (比特币)。
endpoint = "/info/balance"
params = {
"currency": "BTC"
}
调用
get_timestamp
函数获取当前时间戳,并使用
generate_signature
函数生成签名。
timestamp = get_timestamp()
signature = generate_signature(endpoint, params)
构建 HTTP 请求头。请求头必须包含 API 密钥、签名和时间戳,以及
Content-Type
声明。
headers = {
"Api-Key": api_key,
"Api-Sign": signature,
"Api-Timestamp": timestamp,
"Content-Type": "application/x-www-form-urlencoded"
}
构建完整的 API 请求 URL。注意,余额查询属于私有 API,因此 URL 包含
/trade
部分。
url = "https://api.bithumb.com/trade" + endpoint #Private endpoint
使用
requests.post
方法发送 POST 请求。将请求头和参数传递给该方法。
try:
response = requests.post(url, headers=headers, data=params)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
data = response.()
print(data)
检查 API 响应状态码。如果状态码为 "0000",表示请求成功。然后,从响应数据中提取可用的 BTC 余额。
if data['status'] == "0000": #Success code
print(f"BTC available balance: {data['data']['available_btc']}")
else:
print(f"Error: {data['message']}")
处理可能发生的请求异常。例如,网络连接错误或服务器错误。
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
注意: 请将 YOUR_API_KEY
和 YOUR_SECRET_KEY
替换为你自己的 API 密钥和 Secret Key。 此代码会输出你的 BTC 可用余额。
6. 错误处理
Bithumb API 采用标准的 HTTP 状态码和 JSON 格式的响应体来反馈操作结果,特别是错误信息。通过分析这些信息,开发者可以准确诊断问题并采取适当的措施。以下列出了一些常见的 HTTP 状态码,以及它们在 Bithumb API 交互中可能代表的含义:
-
400 Bad Request
: 表示客户端发送的请求存在错误,例如请求参数格式不正确、缺少必要的参数、参数值超出允许范围等。 开发者应仔细检查请求的各个参数,确保其符合 API 文档的规范。 详细的错误信息通常会在 JSON 响应体中提供,例如具体的字段错误提示。 -
401 Unauthorized
: 表明客户端未通过身份验证,通常是由于 API 密钥 (API Key) 或密钥 (Secret Key) 不正确,或者签名 (Signature) 验证失败导致的。 开发者必须确保提供的 API 密钥和密钥是有效的,并且签名算法正确无误。 还应检查 API 密钥是否具有足够的权限来执行所请求的操作。 -
429 Too Many Requests
: 指示客户端在短时间内发送了过多的请求,超过了 Bithumb API 的速率限制。 为了避免此错误,开发者应实施速率限制策略,例如使用令牌桶算法或漏桶算法来控制请求的发送频率。 API 文档通常会明确说明各个接口的速率限制,开发者应严格遵守。重试请求时,建议使用指数退避算法,逐渐增加重试间隔,以避免再次触发速率限制。 -
500 Internal Server Error
: 表示 Bithumb 服务器内部发生了错误,这通常与客户端的请求无关。 开发者可以稍后重试请求。 如果该错误持续发生,建议联系 Bithumb 的技术支持团队进行报告。 在重试之前,可以尝试清除缓存或更改网络环境。
除了以上常见的 HTTP 状态码,Bithumb API 还会通过 JSON 响应体提供更详细的错误信息。 开发者应该解析 JSON 响应体,提取错误代码和错误消息,以便更准确地诊断问题。 根据不同的错误代码,开发者应采取相应的处理措施,例如:
- 重试请求 : 对于间歇性的错误,例如网络超时或服务器繁忙,可以尝试重试请求。
- 检查参数 : 对于参数错误,应仔细检查请求的各个参数,确保其符合 API 文档的规范。
- 降低请求频率 : 对于速率限制错误,应降低请求频率,避免超过 API 的限制。
- 处理身份验证错误 : 对于身份验证错误,应检查 API 密钥和密钥是否正确,以及签名算法是否正确无误。
- 记录错误日志 : 建议将所有错误信息记录到日志中,以便后续分析和调试。
通过合理地处理 Bithumb API 返回的错误信息,开发者可以提高应用程序的稳定性和可靠性。
7. 注意事项
- API 密钥安全: 务必将你的 Bithumb API 密钥和 Secret Key 视为最高机密,如同银行密码一般妥善保管。切勿以任何形式泄露给任何第三方,包括但不限于分享、截屏、上传至公共代码仓库(如 GitHub)、发送邮件或聊天消息。一旦密钥泄露,可能导致资产被盗或数据被非法访问。启用双重验证(2FA)能够增强账户安全性。
- 请求频率限制: Bithumb API 对请求频率有限制,旨在保障平台的稳定性和公平性。超出限制可能会导致 IP 地址或账户被临时或永久封禁。在使用 API 之前,请详细阅读 Bithumb 官方文档,了解不同接口的频率限制(例如,每分钟或每秒允许的请求次数)。可以考虑实施请求队列或指数退避策略,以避免超出限制。
- 交易风险: 使用 Bithumb API 进行自动化交易存在固有风险。市场波动、网络延迟、程序错误或 API 故障都可能导致意外损失。在进行实盘交易之前,务必进行充分的模拟交易(使用测试 API),并设置合理的止损策略和风险管理措施。充分理解各种订单类型(限价单、市价单、止损单)的运作机制。
- 数据准确性: Bithumb API 提供的数据(如价格、交易量、订单簿)可能存在延迟或与实际市场情况略有偏差。这可能是由于网络延迟、数据处理延迟或其他技术问题造成的。在做出任何交易决策之前,建议结合多个数据源(例如,其他交易所或行情软件)进行交叉验证。不要完全依赖 API 提供的数据进行高频交易。
- 官方文档: 始终将 Bithumb 官方文档作为你使用 Bithumb API 的权威参考指南。官方文档会定期更新,包含最新的 API 信息、接口变更、参数说明、错误代码以及最佳实践。定期查阅官方文档,确保你使用的 API 版本是最新的,并且符合 Bithumb 的规定。注意阅读更新日志,及时了解API 的变动。
在使用 Bithumb API 之前,请务必仔细阅读并理解 Bithumb API 官方文档,深入了解各个接口的细节、参数以及潜在限制。遵循最佳实践指南,以确保安全、稳定和高效地使用 API。同时,关注 Bithumb 官方公告和社区讨论,及时获取最新的 API 更新和安全提示。