玩转Bithumb API：开发者必备高效接入指南，掘金数字资产！

Bithumb 平台 API 使用说明

本文档旨在为开发者提供 Bithumb 交易平台 API 的详细使用说明，帮助其高效、准确地接入并利用 Bithumb 的各项功能。

概述

Bithumb API 提供了一整套全面的接口，赋予开发者通过程序化方式深度访问实时市场行情、高效管理个人账户以及执行各种交易活动的能力。该 API 严格遵循 RESTful 架构设计原则，确保与各种编程语言和平台的兼容性。所有数据交换均采用 JSON 格式，这是一种轻量级且易于解析的数据格式，旨在优化网络传输效率。为了开始使用 Bithumb API，开发者必须首先注册一个 Bithumb 账户，并通过安全验证流程生成独有的 API 密钥对。这些密钥对包括一个公共密钥（API Key）和一个私有密钥（Secret Key），用于验证开发者身份并授权其访问特定 API 功能。请务必妥善保管您的私有密钥，切勿泄露给任何第三方，以防止潜在的安全风险。API 密钥的生成和管理可在 Bithumb 账户的 API 管理页面完成，并允许您根据实际需求配置不同的权限级别，例如只读访问或完全交易权限。Bithumb API 采用严格的速率限制机制，以防止滥用并确保所有用户的服务质量。开发者应仔细阅读 Bithumb API 文档，了解具体的速率限制策略以及如何优雅地处理 API 请求限制，例如使用指数退避算法。

API 密钥

所有与本平台API的交互都需要进行身份验证。身份验证机制基于API密钥和Secret密钥，旨在确保只有授权用户才能访问受保护的资源，并防止恶意行为。

• API 密钥 (API Key): 这是一个公开的标识符，用于唯一识别您的账户。 类似于您的用户名，但不应用于任何形式的加密或签名。API 密钥允许服务器识别与请求关联的特定用户或应用程序。
• Secret 密钥 (Secret Key): 这是一个私密的密钥，如同密码一样，用于对您的API请求进行数字签名。 签名过程确保请求在传输过程中未被篡改，并验证请求的真实来源。 Secret 密钥必须保密，绝不能泄露给任何人。

为了保障账户安全，请务必采取一切必要措施来妥善保管您的 API 密钥和 Secret 密钥。 切勿将密钥存储在公共代码仓库、客户端应用程序或任何不安全的位置。 泄露这些密钥可能导致未经授权的访问，进而导致您的账户被盗用、数据泄露或资金损失。 定期轮换您的 API 密钥和 Secret 密钥是保持账户安全的重要措施。

获取 Bithumb API 密钥

要开始使用 Bithumb API 进行自动化交易或数据分析，您需要先获取 API 密钥。以下步骤将详细指导您完成密钥的创建过程，并说明每个环节的注意事项。

1. 登录 Bithumb 平台：
   确保您已拥有 Bithumb 账户。使用您的用户名和密码登录 Bithumb 官方网站。如果您还没有账户，需要先注册一个。请务必使用安全的密码，并启用双重验证 (2FA) 以增强账户安全性。
2. 前往 “API 管理” 页面：
   登录后，导航至 “API 管理” 页面。该页面通常位于账户设置或用户中心的相关选项中。您可以在网站的菜单栏或个人资料设置中找到该链接。具体位置可能因 Bithumb 平台界面的更新而略有变化，如有疑问，请参考 Bithumb 的官方帮助文档。
3. 创建新的 API 密钥：
   在 API 管理页面，点击“创建 API 密钥”或类似的按钮。系统将提示您为新的 API 密钥命名，并设置其权限。这是一个非常重要的步骤，因为它决定了此 API 密钥可以执行哪些操作。Bithumb 通常会提供多种权限选项，例如：
   • 交易权限 (Trade)： 允许使用 API 密钥进行买卖操作，包括下单、撤单、查询订单状态等。
   • 提现权限 (Withdraw)： 允许使用 API 密钥发起提现请求。 请谨慎授予此权限，除非您完全信任使用此密钥的应用程序或脚本。
   • 账户信息权限 (Account Info)： 允许使用 API 密钥查询账户余额、交易历史等信息。
   • 市场数据权限 (Market Data)： 允许使用 API 密钥获取市场行情数据，如价格、成交量等。
   仔细阅读每个权限的说明，并根据您的实际需求进行选择。 强烈建议仅授予必要的最低权限，以降低安全风险。 例如，如果您只需要使用 API 密钥进行交易，则不要授予提现权限。
4. 创建成功后，保存 API 密钥和 Secret 密钥：
   API 密钥创建成功后，Bithumb 将生成两个关键的密钥：
   • API 密钥 (API Key)： 用于标识您的身份，相当于用户名。
   • Secret 密钥 (Secret Key)： 用于对 API 请求进行签名，相当于密码。 Secret 密钥必须严格保密，切勿泄露给他人。
   Bithumb 通常只会显示 Secret 密钥一次，请务必将其安全地存储在加密的文件或密码管理器中。如果 Secret 密钥丢失，您可能需要重新创建 API 密钥。请注意，泄露 API 密钥和 Secret 密钥可能导致您的账户资金被盗，因此请务必采取适当的安全措施。

   创建 API 密钥后，您就可以在您的程序或脚本中使用它来访问 Bithumb 的 API 接口了。请仔细阅读 Bithumb 的 API 文档，了解如何使用 API 密钥进行身份验证和发送 API 请求。

API 端点

Bithumb API 的基本端点为： https://api.bithumb.com 。 这是所有 API 请求的根 URL，务必确保所有请求都以此地址开头。

所有 API 请求都应以此端点为基础，并加上相应的 API 路径。例如，要获取特定加密货币的行情信息，您可能需要访问 https://api.bithumb.com/public/ticker/BTC_KRW ，其中 /public/ticker/BTC_KRW 是 API 路径。 请务必参考 Bithumb 官方 API 文档以获取所有可用 API 路径及其参数的详细说明。正确使用 API 端点和路径是成功调用 Bithumb API 的关键。

请求方法

Bithumb API 支持以下 HTTP 请求方法，开发者可以根据不同的业务需求选择合适的请求方法进行数据交互：

• GET: 主要用于从服务器请求和获取数据资源，不会对服务器上的数据产生任何修改。 GET 请求通常会将参数附加在 URL 后面，例如 /api/v1/ticker?currency=BTC 。由于参数直接暴露在 URL 中，因此 GET 请求不太适合传输敏感数据。浏览器和服务器通常会对 URL 的长度有所限制，因此 GET 请求更适合用于获取少量数据。
• POST: 用于向服务器提交数据，以便创建或更新资源。与 GET 请求不同，POST 请求将参数放在 HTTP 请求体中，因此可以传输更多的数据，也更适合传输敏感数据。例如，当您需要提交交易订单、提币请求等涉及数据变更的操作时，应使用 POST 请求。 Bithumb API 在需要客户端提供数字签名时，通常也需要通过 POST 方法传递签名数据以确保安全性。

请求头

为了确保安全和正确的API交互，所有向服务器发起的API请求都必须包含以下请求头信息。这些请求头信息用于身份验证、数据格式声明和防止重放攻击。

• Content-Type: application/ (对于 POST/PUT 等包含请求体的请求)。此请求头告知服务器请求体的数据格式。 application/ 表明请求体是 JSON 格式的数据。对于 GET 请求，通常不需要此头部，或者可以设置为其他适当的值。
• Api-Key: 您的 API 密钥。API 密钥是分配给您的唯一标识符，用于验证您的身份并授权访问API。请务必妥善保管您的API密钥，防止泄露。通常，API密钥可以在API提供商的控制面板或开发者文档中找到。
• Api-Sign: 请求签名的十六进制哈希值。请求签名是通过对请求参数、API 密钥、时间戳等信息进行哈希运算得到的。服务器使用此签名验证请求的完整性和真实性，防止篡改。签名算法通常在API文档中详细说明，常见的哈希算法包括 HMAC-SHA256 和 SHA-512。签名的生成过程需要严格按照API文档的规范进行。
• Api-Timestamp: 请求的时间戳（Unix 时间戳，单位：毫秒）。时间戳用于防止重放攻击。服务器会验证时间戳的有效性，如果时间戳与服务器当前时间相差过大，请求将被拒绝。Unix 时间戳是从1970年1月1日0时0分0秒（UTC）起至现在的总毫秒数。

请求签名

为确保API请求的完整性和安全性，所有 POST 请求都需要进行签名验证。签名机制能有效防止未经授权的请求和数据篡改。详细的签名算法流程如下：

1. 准备数据：参数化处理与排序
• 将所有需要通过 POST 请求发送的参数，包括请求体（Body）中的参数，按照其参数名称的字母升序进行排列。这是为了确保即使参数顺序不同，生成的签名结果也是一致的，从而保证请求的有效性。
• 将排序后的参数名和参数值进行拼接，形成键值对字符串。参数名与参数值之间使用等号（ = ）连接，不同的参数对之间使用&符号（ & ）连接。例如：如果参数有 param1=value1 和 param2=value2 ，那么拼接后的字符串为 param1=value1&param2=value2 。注意，对于数组类型的参数，需要将其展开成多个键值对。
2. 构建消息：生成签名原文
• 将API请求的路径（例如： /api/v1/order ），上一步骤中拼接好的参数字符串，以及当前的时间戳（精确到毫秒级别）按照顺序连接起来，形成最终用于签名的消息原文。时间戳必须是自 Unix Epoch (1970-01-01 00:00:00 UTC) 起的毫秒数。
• 消息原文的格式通常为： [API路径]?[参数字符串][时间戳] 。例如： /api/v1/order?param1=value1&param2=value2167888640000 。其中，问号（ ? ）用于分隔API路径和参数字符串。
3. 哈希计算：HMAC-SHA512加密
• 使用您的Secret Key（API密钥）作为密钥，对上一步骤中构建的消息原文进行HMAC-SHA512哈希运算。HMAC (Hash-based Message Authentication Code) 是一种使用密钥对消息进行加密的算法，可以确保消息的完整性和真实性。
• HMAC-SHA512算法会生成一个固定长度的哈希值，该值取决于Secret Key和消息原文。确保您的Secret Key安全地存储，避免泄露。
4. 格式转换：十六进制编码
• 将HMAC-SHA512哈希运算的结果转换为十六进制字符串表示。这是因为哈希运算的结果通常是二进制数据，不方便在HTTP头部或者URL中传输。
• 十六进制编码将每个字节转换为两个十六进制字符，从而方便进行文本传输和存储。
• 将转换后的十六进制字符串作为签名值，添加到HTTP请求的头部或者参数中，以便服务器进行验证。

Python 示例:

这段 Python 代码片段展示了如何使用 hashlib , hmac , time , 和 urllib.parse 模块来构建一个加密货币 API 请求的签名。签名通常用于验证请求的来源，确保其未被篡改，并增加安全性。

import hashlib
import hmac
import time
import urllib.parse

hashlib 模块提供了多种哈希算法（如 SHA-256），用于创建消息摘要。
hmac 模块实现了基于哈希的消息认证码（HMAC），使用密钥来增强哈希算法的安全性。
time 模块用于获取当前时间戳，通常用作 API 请求的一部分，以防止重放攻击。
urllib.parse 模块用于编码 URL 参数，确保它们在 HTTP 请求中正确传输。

secret_key = "YOUR_SECRET_KEY"
api_path = "/public/orderbook"
params = {"count": "5"}
timestamp = str(int(time.time() * 1000))

secret_key 变量存储你的 API 密钥，务必妥善保管，避免泄露。这是用于生成签名的关键信息。
api_path 变量定义了你要请求的 API 端点，例如获取订单簿的公共接口。
params 字典包含了 API 请求的查询参数。 在这个例子中， count 参数设置为 "5"，可能表示请求返回订单簿中的前 5 个条目。
timestamp 变量存储当前时间戳，精确到毫秒。将其转换为字符串格式，以便在后续的签名生成过程中使用。 使用时间戳能够有效防止重放攻击，保证接口调用的时效性。

1. 准备数据

在进行签名或数据加密之前，通常需要对数据进行预处理。这一步的核心在于确保参数的顺序一致性，以便生成的签名在客户端和服务器端能够匹配，从而验证数据的完整性和真实性。

sorted_params = urllib.parse.urlencode(sorted(params.items()))

这行代码的作用是将字典形式的参数 ( params ) 转换为 URL 编码的字符串，并按照键（key）的字母顺序进行排序。具体分解如下：

• params.items() : 将字典 params 转换为键值对的列表，例如 [('key1', 'value1'), ('key2', 'value2')] 。
• sorted(...) : 对键值对列表进行排序，默认按照键的字母顺序升序排列。例如，如果 params 是 {'b': '2', 'a': '1', 'c': '3'} ，那么 sorted(params.items()) 将返回 [('a', '1'), ('b', '2'), ('c', '3')] 。
• urllib.parse.urlencode(...) : 将排序后的键值对列表转换为 URL 编码的字符串。URL 编码会将特殊字符（例如空格、标点符号等）转换为 % 加上十六进制表示的形式，以确保数据在 URL 中传输时不会出现问题。 例如， [('a', '1'), ('b', '2'), ('c', '3')] 经过 URL 编码后可能得到 a=1&b=2&c=3 。 如果值包含特殊字符，例如空格，它也会被编码，例如 a=1&b=2%20space&c=3 。

通过这种方式，无论参数的初始顺序如何，最终得到的 sorted_params 字符串都会保持一致，这对于生成可靠的签名至关重要。在加密货币领域，尤其是在与交易所API交互时，参数的排序和编码是保证交易安全的基础步骤。

2. 生成消息

在构建加密签名之前，我们需要生成消息字符串。此消息字符串是API请求的关键组成部分，用于验证请求的真实性和完整性。

生成消息的步骤如下：将API路径 ( api_path ) 与查询参数字符串连接起来。查询参数字符串是通过对所有请求参数进行排序并按照特定格式组合而成的。这意味着你需要按照字母顺序对参数名进行排序，并将每个参数名与其对应的值用等号（ = ）连接起来。然后，将这些参数对用"&"符号连接起来，形成一个完整的查询参数字符串（ sorted_params ）。

接下来，将时间戳（ timestamp ）也添加到消息字符串中。时间戳通常以Unix纪元时间（自1970年1月1日午夜以来经过的秒数）表示，并且对于防止重放攻击至关重要。时间戳应该与API请求一起发送，并且需要在服务器端进行验证，以确保请求在有效的时间窗口内发出。

因此，最终的消息字符串可以表示为：

message = api_path + "?" + sorted_params + "&timestamp=" + timestamp

请注意，有些API可能要求将时间戳直接附加到排序后的参数字符串之后，而不使用"&"符号。务必参考API的官方文档，以确保正确的消息生成方法。

准确的消息生成对于确保API请求的安全性至关重要。任何细微的错误都可能导致签名验证失败，从而导致请求被拒绝。因此，务必仔细检查消息生成过程中的每个步骤。

3. 使用 Secret Key 进行哈希

使用 Secret Key 进行哈希是一种通过密钥来增强哈希函数安全性的方法，常用于消息认证码 (HMAC) 的生成。HMAC 能够验证数据的完整性以及发送者的身份。以下代码展示了如何使用 Python 的 hmac 和 hashlib 库，结合 Secret Key 以及 SHA512 哈希算法，为消息生成签名。

将 Secret Key 和消息都编码为 UTF-8 格式的字节串。这是因为哈希函数通常处理字节数据，而非直接处理字符串。UTF-8 是一种通用的字符编码，能够表示几乎所有的 Unicode 字符。

secret_key_encoded = secret_key.encode('utf-8')
message_encoded = message.encode('utf-8')

接下来，使用 hmac.new() 函数创建一个 HMAC 对象。该函数接受三个参数：Secret Key 的字节串、消息的字节串，以及哈希算法。这里使用的哈希算法是 SHA512，它能产生 512 位的哈希值，提供较高的安全性。 hmac.new() 返回的 HMAC 对象可以用于计算消息的 HMAC 值。

signature = hmac.new(secret_key_encoded, message_encoded, hashlib.sha512).hexdigest()

调用 HMAC 对象的 hexdigest() 方法，将 HMAC 值转换为十六进制字符串。十六进制字符串是一种常用的表示哈希值的方式，方便存储和传输。

完整的代码如下：

import hmac
import hashlib

secret_key = "你的SecretKey"  # 替换为你自己的 Secret Key
message = "要进行哈希的消息"  # 替换为你要哈希的消息

secret_key_encoded = secret_key.encode('utf-8')
message_encoded = message.encode('utf-8')
signature = hmac.new(secret_key_encoded, message_encoded, hashlib.sha512).hexdigest()

print(signature)

signature 变量现在包含了消息的 HMAC 值，可以使用它来验证消息的完整性和发送者的身份。在实际应用中，需要安全地保管 Secret Key，防止泄露。

API 接口示例

1. 获取市场行情

使用 GET /public/ticker/{currency} 接口可以实时获取指定交易对的市场行情数据。

该接口允许开发者查询特定加密货币交易对的最新成交价、最高价、最低价、成交量等关键信息，从而进行市场分析和制定交易策略。

• currency: 交易对币种，指定需要查询的交易市场。其格式为 {基础货币}_{计价货币} ，例如 BTC_KRW 表示比特币 (BTC) 与韩元 (KRW) 的交易对。务必使用大写字母表示货币代码。其他例子包括： ETH_USDT (以太坊/泰达币), LTC_BTC (莱特币/比特币)。确保交易对在交易所中实际存在，否则API将返回错误。

请求示例:

GET /public/ticker/BTC_USDT

返回示例 (JSON):

{
  "ticker": {
    "high": "43000.00",
    "low": "41000.00",
    "last": "42500.00",
    "volume": "1000.00",
    "timestamp": "1678886400000"
  }
}

字段说明:

• high : 24小时内最高成交价。
• low : 24小时内最低成交价。
• last : 最新成交价。
• volume : 24小时内成交量 (以基础货币计价)。
• timestamp : 数据更新的时间戳 (毫秒)。

错误处理:

如果请求的 currency 不存在，API 将返回相应的错误代码和错误信息。开发者应该妥善处理这些错误，以确保应用程序的稳定性和可靠性。

例如，如果交易对不存在，可能会返回如下错误：

{
  "error": "Invalid currency pair."
}

示例: 获取Bithumb交易所BTC/KRW交易对的行情数据

使用 GET 方法请求Bithumb公开API，以获取比特币(BTC)与韩元(KRW)交易对的实时行情数据。此API接口无需身份验证，任何人都可以访问。通过此接口，您可以获取到诸如最新成交价、最高价、最低价、交易量等关键市场信息，这些信息对于进行交易决策至关重要。

请求的URL为： https://api.bithumb.com/public/ticker/BTC_KRW

该请求会返回一个JSON格式的数据，其中包含了Bithumb交易所BTC/KRW交易对的详细行情信息。开发者可以通过解析JSON数据来获取所需的数据字段，例如：

• closing_price : 最新成交价
• opening_price : 开盘价
• high_price : 最高价
• low_price : 最低价
• units_traded : 交易量
• volume_1day : 24小时累计交易量
• volume_7day : 7天累计交易量
• prev_closing_price : 前日收盘价
• fluctate_24H : 24小时涨跌额
• fluctate_rate_24H : 24小时涨跌幅

请注意，由于API接口的结构可能会发生变化，建议开发者在使用前查阅Bithumb官方API文档以获取最新信息。高频访问API可能会受到速率限制，请合理控制请求频率。

响应示例:

该JSON响应示例提供了加密货币市场数据的快照，展示了特定时间段内的关键交易指标。仔细分析这些指标有助于理解市场动态和潜在趋势。

字段详解:

status : 状态码，"0000" 通常表示请求成功。其他状态码可能指示错误或需要进一步处理的情况。在实际应用中，应根据API文档检查并处理各种状态码，确保程序的健壮性。

data : 包含实际市场数据的对象。该对象下的每个字段都提供了特定视角的市场信息。

opening_price : 开盘价，表示该时间段内第一笔交易的价格。示例中为 "40000000"，单位通常是最小货币单位，例如，如果加密货币是按聪计价，则此价格需要除以相应系数才能得到实际价格。开盘价是分析市场情绪的起点。

closing_price : 收盘价，表示该时间段内最后一笔交易的价格。示例中为 "40500000"。收盘价常被视为评估投资回报的重要参考。

min_price : 最低价，表示该时间段内达到的最低价格。示例中为 "39800000"。最低价是评估市场风险的指标，可以帮助设置止损订单。

max_price : 最高价，表示该时间段内达到的最高价格。示例中为 "40800000"。最高价是评估市场潜在收益的指标，可以帮助设置止盈订单。

average_price : 平均价，表示该时间段内的平均交易价格。示例中为 "40300000"。平均价可以提供更平滑的价格趋势视图，减少短期价格波动的影响。

units_traded : 交易单位数量，表示该时间段内交易的加密货币单位总数。示例中为 "1000"。该数值反映了市场的活跃程度。需要注意的是，具体单位取决于加密货币的类型。

volume_1day : 24小时成交量，表示过去24小时内的总交易量。示例中为 "10000"。这是衡量市场流动性的关键指标。

volume_7day : 7天成交量，表示过去7天内的总交易量。示例中为 "70000"。更长时间的交易量可以提供更全面的市场趋势信息。

date : 时间戳，表示数据生成的时间。示例中为 "1678886400000"，通常是Unix时间戳（毫秒）。需要将其转换为可读的日期和时间格式。

重要提示: 解读这些数据时，需要结合具体的加密货币类型、交易平台以及市场环境进行综合分析。例如，了解所交易的加密货币的流通量、市值以及相关的市场新闻事件，有助于更准确地评估风险和机会。不同的交易平台可能提供不同格式和精度的数据，需要仔细查阅API文档并进行适当的数据处理。

2. 获取交易对 Orderbook

GET /public/orderbook/{currency}

此端点允许您检索指定交易对的订单簿信息，订单簿是市场深度的一种可视化表示，展示了特定资产在不同价格水平上的买单（出价）和卖单（要价）。 通过分析订单簿，您可以了解市场的供需关系、潜在的价格支撑位和阻力位，以及流动性情况。该接口返回当前市场上未成交的买单和卖单信息，按照价格由优到劣排序。

• currency: 交易对币种。 这是必需参数，用于指定您要查询的交易对。 交易对的格式通常为 {基础货币}_{报价货币} ，例如 BTC_KRW 表示比特币（BTC）兑韩元（KRW）的交易对。 其他示例包括 ETH_USDT , LTC_BTC 等。请确保使用交易所支持的正确交易对格式。
• count: (可选) 返回的挂单数量。 这是一个可选参数，允许您控制响应中返回的订单数量。 默认值为 5，这意味着如果您不提供此参数，API 将返回前 5 个最佳出价和要价。 最大值为 50，这意味着您最多可以请求 50 个出价和 50 个要价。 选择合适的数量取决于您所需的市场深度信息。较小的数量可以提供更快的响应速度，而较大的数量可以提供更全面的市场概览。

响应数据结构：

响应通常以 JSON 格式返回，包含出价（bids）和要价（asks）两个数组。 每个数组都包含一系列订单，每个订单通常包含价格（price）和数量（quantity）两个字段。 价格表示订单的执行价格，数量表示订单中待交易的资产数量。

示例：

假设您要查询 BTC_USDT 交易对的订单簿，并请求返回 10 个挂单。 您可以使用以下 URL：

GET /public/orderbook/BTC_USDT?count=10

示例：获取Bithumb交易所BTC/KRW交易对的深度数据

使用HTTP GET方法请求Bithumb公共API，获取指定交易对的订单簿信息。订单簿包含买单（bid）和卖单（ask）的价格和数量数据，反映了市场供需情况。

请求URL:

GET https://api.bithumb.com/public/orderbook/BTC_KRW?count=10

URL参数解释：

• /public/orderbook/BTC_KRW : 指定API端点为获取BTC/KRW交易对的订单簿数据。BTC代表比特币，KRW代表韩元。不同的交易所和交易对，API端点会有所不同。
• ?count=10 : 使用GET请求的查询参数，指定返回订单簿的深度数量。在这个例子中， count=10 表示请求返回买单和卖单各10条最佳价格的订单信息。省略该参数或使用不同的数值将会返回不同数量的订单信息。不同的API对 count 参数可能有限制。

请求头(Headers):

通常，公共API不需要认证，因此无需在请求头中包含认证信息。但是，为了更好的兼容性，建议设置 Content-Type 为 application/ 。

Content-Type: application/

响应数据 (Response):

API响应通常为JSON格式，包含时间戳、订单簿数据等信息。订单簿数据会分别列出买单和卖单的价格和数量，按照价格排序。

例如，响应数据可能包含以下字段：

• timestamp : 订单簿生成的时间戳（Unix时间戳）。
• payment_currency : 支付货币，这里是KRW。
• order_currency : 订单货币，这里是BTC。
• bids : 买单数组，每个元素包含 price （价格）和 quantity （数量）。
• asks : 卖单数组，每个元素包含 price （价格）和 quantity （数量）。

重要提示：

• 使用API时请务必阅读交易所的官方文档，了解API的使用规则和限制。
• 频繁请求API可能会触发速率限制（Rate Limiting），导致请求失败。请合理控制请求频率。
• 订单簿数据是动态变化的，请注意数据的时效性。

响应示例:

以下JSON格式的响应示例展示了加密货币交易平台返回的订单簿数据。理解这些数据结构对于进行高频交易、量化分析以及评估市场深度至关重要。

{ "status": "0000", "data": { "timestamp": "1678886400000", "payment currency": "KRW", "order currency": "BTC", "bids": [ { "price": "40400000", "quantity": "0.1" }, { "price": "40390000", "quantity": "0.2" } ], "asks": [ { "price": "40500000", "quantity": "0.3" }, { "price": "40510000", "quantity": "0.4" } ] } }

字段解释：

• status : 请求状态码。 "0000" 通常表示请求成功。其他状态码可能指示错误。
• data : 包含实际数据的容器对象。
• timestamp : 以Unix时间戳格式（毫秒）表示的订单簿更新时间。通过此时间戳，可以追踪订单簿的实时变化。
• payment currency : 结算货币，本例中为韩元（KRW）。 这是交易时使用的计价货币。
• order currency : 订单货币，本例中为比特币（BTC）。这是交易的标的资产。
• bids : 买单列表。每个买单包含：
  • price : 买入价格。 示例： "40400000" (KRW)。
  • quantity : 买入数量。 示例： "0.1" (BTC)。
• asks : 卖单列表。每个卖单包含：
  • price : 卖出价格。 示例： "40500000" (KRW)。
  • quantity : 卖出数量。 示例： "0.3" (BTC)。

重要提示： 订单簿数据是动态变化的，会随着交易的进行不断更新。 开发者应注意处理数据更新和并发问题。实际应用中通常会返回更深度的订单簿信息，包含更多的买单和卖单，以便更好地反映市场深度。理解订单簿的结构以及如何解析其中的数据，是开发交易机器人、风险管理系统等应用的关键。

3. 下单交易

API端点： POST /trade/place

此API端点用于提交新的交易订单。通过向 /trade/place 发送POST请求，用户可以指定交易的各种参数，例如交易对、交易方向（买入或卖出）、订单类型、价格和数量。服务器将验证请求的有效性，并在满足市场条件时执行订单。

请求方法： POST

请求体（Request Body）： 请求体应包含一个JSON对象，其中包含以下字段：

• symbol (String): 交易对代码，例如 "BTC/USDT"。指定要交易的资产对。
• side (String): 交易方向，可以是 "buy" (买入) 或 "sell" (卖出)。
• type (String): 订单类型，可以是 "market" (市价单) 或 "limit" (限价单)。 市价单会立即以当前最佳市场价格执行，而限价单只有在市场价格达到指定价格时才会执行。
• price (Number, optional): 限价单的价格。仅当订单类型为 "limit" 时才需要此参数。
• quantity (Number): 要交易的数量。 以基础资产的数量表示。
• client_order_id (String, optional): 客户端自定义订单ID。 用于唯一标识订单，方便客户端跟踪订单状态。 如果未提供，服务器会自动生成一个。

示例请求体：

{
  "symbol": "BTC/USDT",
  "side": "buy",
  "type": "limit",
  "price": 30000,
  "quantity": 0.1,
  "client_order_id": "my_unique_order_123"
}

响应（Response）：

成功的请求将返回HTTP状态码 200 OK 和一个JSON对象，其中包含以下字段：

• order_id (String): 服务器生成的订单ID。
• status (String): 订单状态，例如 "pending" (待处理), "open" (已挂单), "filled" (已成交), "canceled" (已取消), "partially_filled" (部分成交)。
• symbol (String): 交易对代码。
• side (String): 交易方向。
• type (String): 订单类型。
• price (Number): 订单价格（如果是限价单）。
• quantity (Number): 订单数量。
• executed_quantity (Number): 已成交数量。
• average_price (Number): 平均成交价格。
• client_order_id (String): 客户端自定义订单ID（如果提供）。
• timestamp (Number): 订单创建的时间戳（Unix时间戳，毫秒）。

错误处理：

如果请求失败，服务器将返回相应的HTTP错误代码（例如 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error）和一个JSON对象，其中包含有关错误的详细信息，例如错误代码和错误消息。常见的错误包括：

• INVALID_SYMBOL : 无效的交易对代码。
• INVALID_SIDE : 无效的交易方向。
• INVALID_ORDER_TYPE : 无效的订单类型。
• INSUFFICIENT_BALANCE : 账户余额不足。
• INVALID_PRICE : 无效的价格。
• INVALID_QUANTITY : 无效的数量。
• MARKET_UNAVAILABLE : 市场不可用。
• AUTHENTICATION_FAILED : 身份验证失败。

安全注意事项：

• 确保使用HTTPS协议来保护API请求的安全性。
• 妥善保管API密钥，不要将其泄露给他人。
• 实施适当的速率限制和身份验证机制，以防止滥用和恶意攻击。

请求参数:

• order_currency: 交易对中的基础货币，指定要交易的币种。 例如，若要交易比特币，则 order_currency 应设置为 BTC 。 这是交易对中第一个出现的币种，代表你想购买或出售的标的资产。 此参数至关重要，因为它定义了你将使用哪种加密货币进行交易。
• payment_currency: 结算货币，用于支付或接收交易结算的币种。 例如，如果结算货币是韩元，则 payment_currency 应设置为 KRW 。 这是交易对中第二个出现的币种，代表你用于购买或接收的计价单位。 它决定了交易的定价单位，以及最终收益或损失的计算方式。
• units: 交易数量，表示买入或卖出的 order_currency 的数量。 这是一个数值参数，表示你要交易的标的资产的数量。 务必根据你的交易策略和风险承受能力设置此参数，并仔细检查输入的数量，以避免意外交易。
• price: 委托价格，仅在限价单 ( limit ) 中有效。 这是你愿意买入或卖出 order_currency 的价格。 对于买入订单，价格越高，成交的可能性越大；对于卖出订单，价格越低，成交的可能性越大。 此参数允许你控制交易的执行价格，并设定目标买入或卖出价位。
• type: 交易类型，指定是买入 ( bid ) 还是卖出 ( ask )。 bid 表示买入订单，即你希望购买 order_currency 。 ask 表示卖出订单，即你希望出售 order_currency 。 此参数决定了交易的方向，即你是市场的买方还是卖方。
• side: 交易方向，指定是限价单 ( limit ) 还是市价单 ( market )。 limit 表示限价单，允许你指定交易价格。订单只有在达到或超过指定价格时才会执行。 market 表示市价单，会以当前市场最优价格立即执行订单。 选择 limit 可以控制交易价格，但成交速度可能较慢；选择 market 可以快速成交，但可能无法获得理想价格。

示例:

以下是一个加密货币交易订单的JSON格式示例，展示了关键的订单参数。该示例模拟了一个用户试图用法定货币韩元(KRW)购买比特币(BTC)的场景。

{
"order_currency": "BTC",
// 指定订单购买的加密货币为比特币 (BTC)。 这是交易对中的基础货币。
"payment_currency": "KRW",
// 指定用于支付的法定货币为韩元 (KRW)。这是交易对中的报价货币。
"units": "0.01",
// 指定购买的比特币数量为 0.01 BTC。这是订单的大小。
"price": "40500000",
// 指定购买比特币的单价为 40,500,000 韩元 (KRW)。此价格仅为示例，实际价格会随市场波动。
"type": "bid",
// 指定订单类型为 "bid"，意味着这是一个买单 (买入比特币)。 相应的，卖单类型为 "ask"。
"side": "limit"
// 指定订单边为 "limit"，意味着这是一个限价单。 限价单允许交易者指定他们愿意购买或出售资产的特定价格。 这种类型的订单只有在市场价格达到或优于指定价格时才会执行。
}

该JSON结构清晰地定义了交易意图，包括交易对（BTC/KRW）、交易数量、价格以及订单类型和方向。理解这些参数对于理解加密货币交易至关重要。

Python 示例 (包含签名):

此示例展示如何使用 Python 与加密货币交易所的 API 交互，特别是进行交易下单并包含必要的签名验证。其中使用了requests库发送HTTP请求，hashlib和hmac模块生成安全签名，urllib.parse模块用于处理URL编码。

import requests
import hashlib
import hmac
import time
import urllib.parse

以下代码段定义了必要的API密钥、私钥、API路径以及API端点。 api_key 和 secret_key 是您从交易所获得的凭证，务必妥善保管。 api_path 定义了特定的API接口，而 api_endpoint 则是API服务器的完整URL。

api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY"
api_path = "/trade/place"
api_endpoint = "https://api.bithumb.com" + api_path

此部分定义了交易参数。 order_currency 指定要交易的加密货币（例如，比特币 'BTC'）。 payment_currency 指定结算货币（例如，韩元 'KRW'）。 units 表示交易数量， price 表示价格， type 指明订单类型（例如，'bid' 表示买入）， side 表示订单方向（例如，'limit' 表示限价单）。

params = {
"order_currency": "BTC",
"payment_currency": "KRW",
"units": "0.01",
"price": "40500000",
"type": "bid",
"side": "limit"
}

时间戳对于防止重放攻击至关重要。此行代码生成一个基于当前时间的毫秒级时间戳，并将其转换为字符串格式。这个时间戳会包含在签名中，确保请求的时效性。

timestamp = str(int(time.time() * 1000))

1. 准备数据

在进行签名之前，需要对所有参与签名的参数进行预处理。这通常涉及到对参数按照键名进行排序，并将排序后的参数拼接成字符串。此步骤旨在确保数据的一致性和可验证性，防止因参数顺序不同而导致签名不一致的问题。

sorted_params = urllib.parse.urlencode(sorted(params.items()))

上述Python代码片段展示了如何使用 urllib.parse.urlencode 和 sorted 函数来准备签名数据。

params.items() ： params.items() 方法将参数字典转换为一个包含键值对的列表。例如，如果 params 是 {'a': 1, 'b': 2, 'c': 3} ，那么 params.items() 将返回 [('a', 1), ('b', 2), ('c', 3)] 。

sorted(...) ：然后， sorted() 函数对这个键值对列表进行排序。默认情况下， sorted() 按照键名（key）进行升序排序。对于上面的例子，排序后的结果将是 [('a', 1), ('b', 2), ('c', 3)] 。如果需要自定义排序规则，可以向 sorted() 函数传递一个 key 参数，指定一个用于排序的函数。

urllib.parse.urlencode(...) ： urllib.parse.urlencode() 函数将排序后的键值对列表转换为URL编码的字符串。URL编码是一种将特殊字符转换为可在URL中传输的格式的过程。例如，空格会被编码为 %20 。对于排序后的键值对列表， urllib.parse.urlencode() 会将它们拼接成一个字符串，其中键和值之间用 = 分隔，键值对之间用 & 分隔。对于上面的例子，URL编码后的结果将是 a=1&b=2&c=3 。 这个过程确保了在网络传输过程中数据的完整性和正确性，同时避免了特殊字符可能带来的解析问题。

2. 生成消息

为了确保API请求的安全性，需要根据预定义的规则生成消息，该消息将用于创建数字签名。

消息的生成过程通常遵循以下步骤，并结合请求的具体参数：

1. 构建API路径： 将API的端点路径（ api_path ）作为消息的基础。例如， /api/v1/orders 。
2. 整理参数： 将所有请求参数（ params ）按照键（key）的字母顺序进行排序。 这是至关重要的一步，因为签名的生成依赖于参数顺序的固定性。排序后，将参数以URL查询字符串的形式连接起来。 例如，如果参数包括 symbol=BTCUSDT 和 side=BUY ，排序后应该是 side=BUY&symbol=BTCUSDT 。 使用 sorted_params 变量来表示排序后的参数字符串。
3. 添加时间戳： 将时间戳（ timestamp ）追加到参数字符串的末尾。时间戳通常是一个Unix时间戳，表示自Unix纪元（1970年1月1日 00:00:00 UTC）以来的秒数或毫秒数。将时间戳作为独立参数添加到参数列表中，确保其包含在排序后的参数串中。
4. 组合消息： 将API路径、排序后的参数字符串以及时间戳组合成最终的消息字符串。组合方式通常是将API路径与包含排序参数和时间戳的字符串用问号（ ? ）连接起来。 例如： message = api_path + "?" + sorted_params + "&timestamp=" + timestamp 或者简化的表示方式 message = api_path + "?" + sorted_params + timestamp 取决于具体的API规范。 某些API可能要求时间戳在参数列表之外，因此需要仔细阅读API文档。

代码示例 (Python):

import hashlib
import hmac
import time
import urllib.parse

api_path = "/api/v1/order"
params = {"symbol": "BTCUSDT", "side": "BUY", "type": "MARKET", "quantity": 0.1}
timestamp = str(int(time.time() * 1000)) # milliseconds timestamp

# Sort the parameters
sorted_params = urllib.parse.urlencode(sorted(params.items()))

# Construct the message
message = api_path + "?" + sorted_params + "&timestamp=" + timestamp

print(f"Message: {message}")

上述步骤的目的是生成一个标准化的消息字符串，然后使用密钥对其进行哈希处理，从而生成数字签名。保证服务器能够验证请求的来源和完整性。

3. 使用 Secret Key 进行哈希

为了增强API请求的安全性，通常会使用Secret Key对消息进行哈希处理，生成签名。这个签名会与API密钥和时间戳一起发送到服务器，服务器使用相同的Secret Key和哈希算法验证请求的真实性和完整性。

以下代码展示了如何使用Python的 hmac 和 hashlib 库来计算消息的哈希签名：

secret_key_encoded = secret_key.encode('utf-8')
message_encoded = message.encode('utf-8')
signature = hmac.new(secret_key_encoded, message_encoded, hashlib.sha512).hexdigest()

将Secret Key和消息文本分别编码为UTF-8字节串。这是因为哈希算法通常作用于字节数据。 hmac.new() 函数使用指定的Secret Key、消息和哈希算法（此处为SHA512）创建一个HMAC对象。 hexdigest() 方法将生成的签名转换为十六进制字符串表示。

接下来，将API密钥、签名和时间戳添加到HTTP请求头中：

headers = {
   "Content-Type": "application/",
  "Api-Key": api_key,
  "Api-Sign": signature,
   "Api-Timestamp":  timestamp
}

Content-Type 设置为 application/ 表明请求体（如果存在）是JSON格式的数据。 Api-Key 是你的API密钥，用于标识你的身份。 Api-Sign 是使用Secret Key生成的哈希签名，用于验证请求的完整性。 Api-Timestamp 是请求的时间戳，用于防止重放攻击。

使用 requests 库发送带有这些header的POST请求到API端点：

response = requests.post(api_endpoint, headers=headers, params=params)

api_endpoint 是API的URL地址， headers 包含了认证信息， params 是查询参数 (GET)。 requests.post() 函数发送POST请求并返回一个 Response 对象。

可以使用以下代码打印服务器返回的响应内容：

print(response.text)

response.text 属性包含了服务器返回的响应体，通常是JSON格式的数据，表示API调用的结果。确保检查响应状态码和内容，以确定API调用是否成功。

错误处理

Bithumb API 利用标准的 HTTP 状态码体系来清晰地反馈 API 请求的处理结果。客户端可以通过这些状态码快速判断请求是否成功，并根据不同的状态码采取相应的处理措施。

• 200 OK : 一切顺利，请求已成功处理。服务器已成功接收、理解并处理了客户端的请求。
• 400 Bad Request : 客户端发出的请求包含错误，例如参数缺失、格式不正确或参数值超出范围。开发者应仔细检查请求参数，确保符合 API 的规范要求。
• 401 Unauthorized : 客户端提供的身份验证信息无效。通常是由于缺少有效的 API 密钥，或者密钥已过期或被禁用。客户端需要提供有效的身份验证凭据才能访问受保护的资源。
• 403 Forbidden : 服务器拒绝执行请求，即使客户端已经过身份验证。这通常是因为客户端没有足够的权限访问所请求的资源。可能需要申请更高的权限或更改访问策略。
• 404 Not Found : 服务器找不到与请求 URI 相匹配的资源。检查请求的 URL 是否正确，并确认资源是否存在。
• 500 Internal Server Error : 服务器在处理请求时遇到了意外错误。这通常是服务器端的代码错误或配置问题。如果是持续出现该错误，应联系 Bithumb 的技术支持。

除了 HTTP 状态码，响应的 JSON 数据中 status 字段也提供了更详细的请求状态信息。通过解析 JSON 响应中的 status 字段，开发者可以获得更精确的错误诊断信息。

• 0000 : 请求成功，与 HTTP 状态码 200 OK 含义相同。
• 其他值：代表具体的错误代码。需要查阅 Bithumb API 文档，获取完整的错误代码列表及其详细解释。每个错误代码都对应着特定的错误场景，有助于开发者快速定位和解决问题。

注意事项

• 仔细阅读 Bithumb API 文档： 深入研究 Bithumb 提供的 API 文档至关重要。透彻理解每个接口的输入参数（包括必选和可选参数）、数据类型、请求方法（如 GET, POST, PUT, DELETE）以及可能的 HTTP 状态码。同时，详细了解每个接口返回的数据结构，包括各个字段的含义、数据类型和单位（例如，价格单位、数量单位等）。重点关注错误代码和异常处理，以便在出现问题时能够快速定位并解决。
• 控制 API 请求频率： Bithumb 交易所对 API 请求频率有限制，目的是防止恶意攻击和保障服务器的稳定运行。务必遵守 Bithumb 官方规定的请求频率限制，例如每分钟或每秒钟允许的最大请求次数。您可以采用合理的策略来控制请求频率，例如使用队列来缓冲请求，或者使用指数退避算法来重试失败的请求。避免短时间内发送大量请求，以免触发频率限制，导致 API 访问被阻止。仔细阅读 API 文档中关于频率限制的具体说明，并根据实际情况进行调整。
• 定期检查 API 密钥权限： API 密钥是访问 Bithumb API 的凭证，务必妥善保管，避免泄露。定期检查您的 API 密钥权限，确保其只拥有完成任务所需的最低权限。例如，如果您的应用程序只需要读取市场数据，则无需赋予交易权限。定期轮换 API 密钥是一种良好的安全实践，可以降低密钥泄露的风险。请定期审查密钥的使用情况，如有异常，立即采取措施，例如禁用密钥并生成新的密钥。
• 关注 Bithumb 官方公告： Bithumb 交易所会定期发布官方公告，内容可能涉及 API 的更新、变更、维护、升级等。请密切关注 Bithumb 官方公告，及时了解 API 的最新动态，以便您能够及时调整您的应用程序，确保其与 API 的兼容性。API 的更新和变更可能会影响您的应用程序的功能，因此及时了解并适应这些变化至关重要。订阅 Bithumb 的官方通知渠道，例如邮件列表、社交媒体等，可以帮助您及时获取最新的公告信息。