想快速上手Bithumb API？这篇教程让你少走弯路！

阅读：98 分类： 焦点

Bithumb 交易所 API 使用指南

简介

Bithumb 作为韩国领先的加密货币交易所之一，为用户提供多样化的数字资产交易服务，涵盖比特币（Bitcoin）、以太坊（Ethereum）等主流加密货币以及众多新兴的数字资产。 为了赋能开发者社群，Bithumb 专门设计并提供了功能完善的应用程序编程接口（API）， 允许开发者无缝接入 Bithumb 平台，构建定制化的交易策略、实时行情监控系统、自动化交易机器人、以及深度数据分析工具等创新应用。 本文将深入解析 Bithumb API 的各项功能特性和使用方法，通过详细的示例代码和实践指南，旨在帮助开发者快速理解并高效利用 Bithumb API，从而加速开发进程并提升应用性能。

API 概述

Bithumb API 主要分为 Public API 和 Private API 两类，分别用于访问不同的数据和功能。理解这两种API的区别是使用Bithumb API进行开发的基础。

  • Public API ：提供市场行情数据、交易信息以及其他公开数据，允许开发者在无需身份验证的情况下访问这些信息。例如，可以获取特定交易对的实时价格、历史交易记录、订单簿深度等数据。Public API主要用于数据分析、市场监控等场景。
  • Private API ：提供账户信息查询、交易委托（包括下单、撤单等）以及其他涉及用户个人资产的操作。为了保护用户资产安全，访问Private API需要进行严格的身份验证。通常需要使用API密钥（API Key）和密钥（Secret Key）进行签名认证，确保请求的合法性和安全性。Private API是进行交易机器人开发、自动化交易等场景的关键。

Public API

Public API 提供以下常用接口，助力开发者构建高效的加密货币应用程序和服务：

  • 行情信息 ：获取指定币种的当前价格、24小时最高价、24小时最低价、交易量、涨跌幅等实时行情数据。通过此接口，您可以了解市场动态，为交易决策提供支持。数据通常以JSON或其他易于解析的格式提供。
  • 交易历史 ：获取指定币种的最近交易记录，包括成交时间、成交价格、成交数量、交易类型（买入或卖出）等详细信息。您可以利用这些历史数据进行趋势分析、回测交易策略以及监控市场异常波动。
  • 挂单信息 ：获取指定币种的买单和卖单挂单信息，也称为订单簿数据。挂单信息包括挂单价格、挂单数量等。您可以基于订单簿数据分析市场深度和流动性，判断市场支撑位和阻力位，从而制定更有效的交易策略。 部分API还提供深度订单簿数据，显示更详细的挂单分布情况。

API 示例

以下是一个获取比特币 (BTC) 行情信息的 Public API 请求示例，该示例展示了如何通过API接口获取加密货币市场的实时数据：

GET /public/ticker/BTC_KRW HTTP/1.1
Host: api.bithumb.com

上述请求旨在从Bithumb交易所获取BTC/KRW交易对的行情数据。 Host字段指定了API服务器的地址。

响应示例：

{
"status": "0000",
"data": {
"opening_price": "50000000",
"closing_price": "52000000",
"min_price": "49000000",
"max_price": "53000000",
"average_price": "51000000",
"units_traded": "100",
"volume_1day": "150",
"volume_7day": "1000",
"buy_price": "51500000",
"sell_price": "52500000",
"date": "1678886400000"
}
}

此JSON响应包含了Bithumb交易所提供的BTC/KRW交易对的关键市场指标。各个字段的含义如下：

  • status : 请求状态码，指示API请求是否成功。 "0000" 通常表示请求成功，其他代码可能表示错误，需要查阅API文档了解具体含义。
  • data : 包含行情数据的 JSON 对象，该对象提供了关于交易对价格和交易量等详细信息。各字段的含义如下：
    • opening_price : 开盘价，指特定时间段（例如，一天）开始时的交易价格。
    • closing_price : 收盘价，指特定时间段结束时的交易价格。
    • min_price : 最低价，指在特定时间段内达到的最低交易价格。
    • max_price : 最高价，指在特定时间段内达到的最高交易价格。
    • average_price : 平均价，指在特定时间段内的平均交易价格，通常通过加权平均计算。
    • units_traded : 交易量（最近 24 小时），指在过去24小时内交易的加密货币数量。
    • volume_1day : 一天内成交量，指过去24小时内以相应计价货币计算的总交易额。
    • volume_7day : 七天内成交量，指过去7天内以相应计价货币计算的总交易额。
    • buy_price : 买一价，也称为最高买入价，指当前市场上最高的买单价格。
    • sell_price : 卖一价，也称为最低卖出价，指当前市场上最低的卖单价格。
    • date : 时间戳，表示行情数据生成的时间，通常以Unix时间戳（毫秒）表示。

错误处理

公共API在交互过程中，可能会由于各种原因返回错误状态码，这些状态码有助于开发者诊断和解决问题。以下是一些常见的错误状态码示例，以及它们通常代表的含义：

  • 5100 : 请求参数错误。这意味着客户端发送的请求中包含了无效、缺失或格式错误的参数。开发者应仔细检查请求参数，确保其符合API文档的要求，例如数据类型、范围限制、必填项等。常见的错误包括参数类型不匹配、超出范围、缺少必要参数等。
  • 5200 : 无效的API密钥。API密钥用于验证客户端的身份和授权。当API密钥无效时，API服务器会拒绝请求。这可能是由于密钥被错误地配置、过期或被撤销。开发者应确保使用了正确的API密钥，并定期检查密钥的有效性。
  • 5300 : 权限不足。客户端试图访问其没有权限访问的资源或执行其没有权限执行的操作。这可能是由于用户角色权限设置不正确或API访问策略限制。开发者应检查用户权限设置，并确保API密钥具有足够的权限来访问所需资源。
  • 5600 : 余额不足。在需要消耗资源（例如交易手续费、数据查询费用）的API调用中，如果账户余额不足，API服务器会返回此错误。开发者应检查账户余额，并确保有足够的余额来完成操作。可以通过充值或调整资源使用策略来解决此问题。
  • 5900 : 交易异常。在执行涉及资金转移或数据变更的交易时，如果发生意外错误，API服务器可能会返回此错误。这可能是由于网络问题、数据库故障、或其他系统错误。开发者应记录错误信息，并尝试重新提交交易。如果问题持续存在，应联系API提供商寻求支持。

开发者在集成公共API时，必须充分考虑各种可能的错误情况，并根据不同的错误码，采取相应的处理措施。这包括但不限于：记录错误日志、向用户显示友好的错误信息、重试操作、或者联系技术支持。良好的错误处理机制可以提高应用程序的健壮性和用户体验。

Private API

Private API 提供账户管理、交易委托以及更高级的账户操作功能，这些功能都需要通过严格的身份验证机制来保障账户安全。Private API通常用于自动化交易策略、程序化订单执行以及个性化的账户管理工具开发。

使用Private API的关键在于理解并正确实施身份验证流程。这通常涉及到API密钥的生成、管理和安全存储。API密钥用于验证请求的来源，确保只有授权用户才能访问和操作账户信息。

账户管理功能包括查询账户余额、交易历史、持仓信息以及其他与账户相关的关键数据。交易委托功能允许用户通过API提交各种类型的订单，例如市价单、限价单、止损单等。Private API还可能提供撤销订单、修改订单以及批量订单处理等功能，以便实现更高效的交易管理。

由于涉及到敏感的账户信息和交易操作，Private API的安全至关重要。通常会采用多重安全措施，例如IP白名单、请求频率限制、数据加密传输（HTTPS）以及定期的安全审计，以确保API的安全性和稳定性。

身份验证

访问Private API需要进行身份验证，这是确保数据安全和限制未授权访问的关键措施。要成功进行身份验证，您需要以下信息：

  • API Key : API Key 类似于您的用户名，用于唯一标识您的开发者身份。它允许API服务器识别您的应用程序或账户，并确定您拥有的权限。 您需要在API提供商处注册并获取API Key。请将其视为公开信息，但仍然谨慎保管，避免泄露给不信任的第三方。
  • Secret Key : Secret Key 类似于您的密码，用于对您的API请求进行签名，验证请求的完整性和真实性。 这可以防止恶意用户伪造您的请求。 Secret Key 必须极其安全地保存，切勿将其嵌入到客户端代码（例如，JavaScript）或公开存储在任何地方。 泄露 Secret Key 将导致严重的安全性风险，例如账户被盗用或数据泄露。通常，Secret Key 应该存储在服务器端的安全环境中，并通过安全的方式用于请求签名。

身份验证流程通常涉及以下步骤：

  1. 获取 API Key 和 Secret Key : 在 API 提供商的平台上注册并创建 API 密钥对。
  2. 构建 API 请求 : 构造包含所有必需参数的 API 请求。
  3. 生成签名 : 使用 Secret Key 和特定的签名算法（例如 HMAC-SHA256）对请求进行签名。 签名过程通常涉及对请求参数进行排序、连接和哈希处理。
  4. 添加签名到请求头或查询参数 : 将生成的签名添加到 API 请求头或查询参数中。
  5. 发送请求 : 将带有签名信息的 API 请求发送到 API 服务器。
  6. 验证签名 : API 服务器使用与您相同的算法和您的 Secret Key 验证请求中的签名。如果签名验证成功，服务器将处理您的请求；否则，服务器将拒绝请求并返回错误。

请务必仔细阅读 API 提供商的文档，了解其特定的身份验证要求和签名机制。 不同 API 的身份验证方法可能有所不同。

API 请求签名

所有 Private API 请求都需要进行签名，这是验证请求完整性和真实性的关键步骤，旨在确保请求的安全性，防止恶意篡改和未经授权的访问。签名过程依赖于您的私钥（Secret Key），该密钥必须妥善保管，切勿泄露给任何第三方。

  1. 将请求参数按照字母顺序排序。参数排序是签名过程的第一步，目的是确保每次请求的签名结果一致，即使参数的顺序发生变化。排序不仅包括参数名称，还包括参数值，确保整体的字母顺序。
  2. 将排序后的参数拼接成字符串。参数拼接是将排序后的参数按照特定格式连接成一个字符串，作为 HMAC-SHA512 加密的输入。拼接格式通常是 "key1=value1&key2=value2&..."，具体格式取决于 API 的要求。
  3. 使用 Secret Key 对字符串进行 HMAC-SHA512 加密。HMAC-SHA512 是一种安全的哈希算法，通过结合 Secret Key 对拼接后的字符串进行加密，生成唯一的签名。Secret Key 的长度和复杂度直接影响签名的安全性。
  4. 将加密后的结果转换为大写十六进制字符串。加密后的签名通常是二进制数据，需要转换为十六进制字符串才能方便地添加到请求头中。转换为大写可以确保签名格式的一致性。
  5. 将签名添加到请求头中。签名最终需要添加到 HTTP 请求头中，以便服务器进行验证。通常使用自定义的请求头字段，例如 "X-Bithumb-Signature"。

以下是一个 Python 示例代码，用于生成 API 请求签名。该示例仅用于演示签名过程，实际应用中需要根据 API 的具体要求进行调整。

import hashlib import hmac import base64 import time

def generate_signature(endpoint, params, secret_key): """ 生成 Bithumb API 请求签名。 

Args:
    endpoint: API 接口地址，例如 "/info/balance"。
    params: 请求参数字典。参数字典包含了所有需要传递给 API 的参数，例如数量、价格、交易类型等。
    secret_key: Bithumb Secret Key。请务必妥善保管您的 Secret Key，切勿泄露。

Returns:
    API 请求签名。返回的是一个大写十六进制字符串，用于添加到 HTTP 请求头中。
"""
encoded_params = base64.b64encode(str(params).encode('utf-8'))
p_string = endpoint + chr(0) + encoded_params.decode('utf-8') + chr(0) + str(int(time.time() * 1000))
hashed = hmac.new(bytes(secret_key, 'utf-8'), p_string.encode('utf-8'), hashlib.sha512)
return hashed.hexdigest().upper()
  • 此处只是签名代码的例子，在使用时请务必结合其他的参数一同完成请求。除了签名之外，还需要添加 API Key 等其他必要的身份验证信息。务必仔细阅读 API 文档，了解所有必需的参数和请求格式。
  • 注意：示例代码中使用了 time.time() 获取当前时间戳，这可能受到客户端时钟的影响。建议使用服务器端时间戳，以确保签名有效性。
  • 强烈建议使用 HTTPS 协议进行 API 请求，以确保数据传输的安全性。

API 示例

以下是一个获取账户余额的 Private API 请求示例，展示了如何安全地访问您的账户信息。请注意，Private API 需要身份验证，确保只有授权用户才能访问敏感数据。

请求： 

POST /info/balance HTTP/1.1
Host: api.bithumb.com
Content-Type: application/x-www-form-urlencoded
Api-Key: YOUR_API_KEY
Api-Signature: YOUR_SIGNATURE
Api-Nonce: 1678886400000

请求体 (Body)： 

currency=BTC

说明：

  • POST /info/balance : 指定了请求方法 (POST) 和 API 端点。 /info/balance 是用于查询账户余额的路径。
  • Host: api.bithumb.com : 指定了API服务器的域名。 务必使用正确的域名。
  • Content-Type: application/x-www-form-urlencoded : 指定了请求体的格式。 application/x-www-form-urlencoded 是一种常用的格式，用于发送简单的键值对数据。
  • Api-Key: YOUR_API_KEY : 您的API密钥，用于标识您的身份。 请务必妥善保管您的API密钥，不要泄露给他人。
  • Api-Signature: YOUR_SIGNATURE : 使用您的私钥生成的签名，用于验证请求的完整性和真实性。签名算法通常涉及对请求参数、API密钥和时间戳进行哈希运算。
  • Api-Nonce: 1678886400000 : 一个时间戳，用于防止重放攻击。 Nonce 必须是唯一的，并且在一段时间内有效。建议使用毫秒级的时间戳。
  • currency=BTC : 指定要查询的币种。 在此示例中，我们查询的是比特币 (BTC) 的余额。

响应示例： 

{
  "status": "0000",
  "data": {
     "available_btc": "1.0",
     "in_use_btc": "0.5",
     "balance_btc": "1.5"
  }
}

响应字段说明：

  • status : 请求状态码，"0000" 表示成功。其他状态码表示错误，请参考API文档了解具体的错误代码和含义。
  • data : 包含账户余额信息的 JSON 对象。
  • data 对象中的字段：
    • available_btc : 可用比特币数量。 指的是可以立即用于交易或提现的比特币数量。
    • in_use_btc : 正在使用的比特币数量。 指的是当前正在挂单或用于其他用途的比特币数量。
    • balance_btc : 总比特币数量。 指的是可用比特币数量和正在使用的比特币数量的总和。

常用 Private API 接口

  • /info/balance : 查询账户余额。此接口允许用户获取其在交易所或平台上的账户余额信息，包括可用余额、冻结余额等。该接口通常需要身份验证，确保只有授权用户才能访问其账户信息。返回的数据格式可能包括币种类型、余额数量以及时间戳等。
  • /trade/place : 创建交易委托。通过此接口，用户可以提交买入或卖出加密货币的交易委托。请求参数通常包括交易对（例如 BTC/USD）、交易方向（买入/卖出）、委托类型（限价单、市价单等）、委托价格和委托数量。成功创建委托后，交易所会返回委托ID，用于后续查询或取消委托。
  • /info/orders : 查询交易委托。此接口用于查询用户提交的交易委托的状态和详细信息。可以根据委托ID、交易对、委托状态（例如 pending、filled、canceled）等条件进行筛选。返回的数据通常包括委托价格、委托数量、已成交数量、委托时间以及手续费等信息。
  • /trade/cancel : 取消交易委托。用户可以使用此接口取消尚未成交的交易委托。通常需要提供委托ID作为参数。成功取消委托后，交易所会返回确认信息。请注意，已成交的委托无法取消。
  • /info/account : 查询账户信息。此接口提供用户的账户相关的更详细的信息，包括账户等级、累计交易量、手续费率以及其他安全设置等。返回的数据可以帮助用户了解其账户的状态和权益。
  • /info/wallet_address : 查询钱包地址。此接口允许用户获取其在交易所或平台上的钱包地址，用于接收加密货币。通常会返回不同币种对应的钱包地址。用户应该仔细核对钱包地址，避免因地址错误而导致资产损失。请注意，某些交易所可能会为每个用户生成唯一的钱包地址，而另一些交易所可能会使用共享地址。

请求限制

Bithumb API 为了保障系统稳定性和防止滥用，实施了严格的请求频率限制。开发者在使用 Bithumb API 时，务必高度重视并妥善管理其应用程序的请求频率，以避免触发速率限制并导致访问受阻，影响业务的正常运行。

具体的限制规则详细规定了在特定时间段内允许的请求数量。这些规则可能因 API 端点和用户身份验证级别而异。 例如，公共 API 端点可能具有比私有 API 端点更严格的限制。未经验证的用户可能比已验证的用户受到更严格的限制。Bithumb 会根据实际情况动态调整这些规则，开发者需要密切关注官方文档的更新。

Bithumb 官方文档是了解最新请求频率限制规则的权威来源。文档中通常会明确说明每个 API 端点的速率限制，以及超出限制后可能采取的措施，如暂时禁止访问或永久封禁 API 密钥。开发者应定期查阅官方文档，确保其应用程序符合最新的限制要求。

为了有效控制请求频率，开发者可以采取多种策略。一种常见方法是实施请求队列，将 API 请求放入队列中并按照设定的速率逐个发送。 另一种方法是使用缓存机制，将经常访问的数据缓存起来，减少对 API 的直接请求次数。还可以根据 Bithumb API 返回的 HTTP 状态码（如 429 Too Many Requests）来动态调整请求频率，实现自适应限流。

安全提示

  • 妥善保管 API Key 和 Secret Key，避免泄露： 将 API Key 和 Secret Key 视为高度敏感信息，如同银行密码一样。不要轻易分享给他人，也不要存储在不安全的地方。
  • 不要在客户端代码中存储 Secret Key： 将 Secret Key 直接嵌入到客户端代码中（如 JavaScript 或移动应用）是非常危险的行为。一旦客户端代码泄露，Secret Key 也将暴露，导致资产面临风险。应该将 Secret Key 保存在服务器端，通过服务器端代码调用 API。
  • 使用 HTTPS 协议进行 API 请求，确保数据传输安全： HTTPS 协议通过加密数据传输过程，防止中间人攻击，确保 API Key、Secret Key 以及交易数据的安全。所有 API 请求都必须使用 HTTPS 协议，避免使用不安全的 HTTP 协议。
  • 定期检查和更新 API Key 和 Secret Key： 定期更换 API Key 和 Secret Key 可以降低密钥泄露带来的风险。建议每隔一段时间（如每月或每季度）更换一次密钥。同时，如果发现密钥可能已经泄露，应立即更换。
  • 注意处理 API 返回的错误信息，及时发现和解决问题： API 返回的错误信息通常包含问题原因的提示。仔细阅读并理解这些错误信息，可以帮助你快速定位并解决问题，避免因错误操作导致资金损失。
  • 务必详细阅读 Bithumb API 官方文档，了解 API 的最新变化和限制： Bithumb API 可能会不定期进行更新和调整。及时阅读官方文档，了解 API 的最新变化、新增功能以及使用限制，可以避免因使用过时或错误的方法导致程序出错。
  • 对于涉及资金操作的 API，务必进行充分的测试，确保操作的正确性： 在使用涉及资金操作的 API（如交易、提现等）之前，务必使用测试环境或小额资金进行充分的测试。确保 API 调用参数正确、逻辑无误，避免因错误操作导致资金损失。可以使用Bithumb提供的沙盒环境进行测试。
  • 定期审计 API 使用情况，及时发现异常行为： 定期检查 API 的使用记录，例如交易量、交易频率、提现地址等。如果发现异常行为，如非授权的交易或提现，应立即采取措施，例如禁用 API Key、冻结账户等。
  • 使用强密码保护 Bithumb 账户，并开启双重验证： 使用包含大小写字母、数字和特殊符号的复杂密码，并定期更换。开启双重验证（如 Google Authenticator）可以有效防止账户被盗，即使密码泄露，攻击者也无法轻易登录你的账户。

代码示例

以下是一个使用 Python 编写的 Bithumb API 客户端示例，展示了如何进行身份验证和获取账户余额。该示例涵盖了生成 API 签名、构建请求头以及处理 API 响应的关键步骤。

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

class BithumbClient: def __init__(self, api_key, secret_key): """ 初始化 Bithumb 客户端。 Args: api_key (str): 您的 Bithumb API 密钥。 secret_key (str): 您的 Bithumb API 密钥。 """ self.api_key = api_key self.secret_key = secret_key self.api_url = "https://api.bithumb.com" 

    def generate_signature(self, endpoint, params):
        """
        生成用于 API 请求的签名。

        Bithumb API 使用 HMAC-SHA512 签名进行身份验证。此方法计算请求的正确签名。

        Args:
            endpoint (str): API 端点。
            params (dict): 请求参数。

        Returns:
            str: 生成的 API 签名。
        """
        encoded_params = base64.b64encode(urllib.parse.urlencode(params).encode('utf-8')) # 使用urllib.parse.urlencode进行编码
        p_string = endpoint + chr(0) + encoded_params.decode('utf-8') + chr(0) + str(int(time.time() * 1000))
        hashed = hmac.new(self.secret_key.encode('utf-8'), p_string.encode('utf-8'), hashlib.sha512) # 使用utf-8编码secret_key
        return hashed.hexdigest()

    def get_balance(self, currency="KRW"):
        """
        检索指定币种的帐户余额。

        Args:
            currency (str): 要检索的币种代码（例如，“KRW”，“BTC”）。默认为“KRW”（韩元）。

        Returns:
            dict: API 响应，包含帐户余额信息。
        """
        endpoint = "/info/balance"
        params = {"currency": currency}
        signature = self.generate_signature(endpoint, params)
        nonce = str(int(time.time() * 1000))
        headers = {
            "Api-Key": self.api_key,
            "Api-Signature": signature,
            "Api-Nonce": nonce,
            "Content-Type": "application/x-www-form-urlencoded"
        }
        data = urllib.parse.urlencode(params) # 使用urllib.parse.urlencode对参数进行编码
        url = self.api_url + endpoint
        response = requests.post(url, headers=headers, data=data)
        response.raise_for_status() # 检查是否有HTTP错误
        return response.() # 返回JSON格式的响应

替换为你的 Bithumb API Key 和 Secret Key

在开始与 Bithumb API 交互之前，你需要将示例代码中的占位符替换为你实际的 API 密钥和私钥。 密钥用于验证你的身份并授权访问你的 Bithumb 账户数据和交易功能。

api_key = "YOUR_API_KEY"

secret_key = "YOUR_SECRET_KEY"

以上代码片段展示了如何定义两个变量，分别存储你的 API Key 和 Secret Key。请务必将 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换成你在 Bithumb 平台生成的真实密钥。

client = BithumbClient(api_key, secret_key)

这行代码创建了一个 BithumbClient 类的实例。这个类是用于与 Bithumb API 进行交互的核心组件。创建实例时，需要传入你的 API Key 和 Secret Key 作为参数，用于身份验证。

balance = client.get_balance()

print(balance)

这段代码演示了如何使用 BithumbClient 实例来获取你的账户余额信息。 get_balance() 方法会向 Bithumb API 发送请求，并返回包含你的账户余额数据的响应。 print(balance) 语句用于将返回的余额信息输出到控制台，方便开发者查看。

请务必将 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为你自己的 API 密钥。 妥善保管你的 API 密钥和私钥，避免泄露给他人，以确保你的账户安全。 此代码只是一个简单的示例，开发者可以根据自己的需求进行修改和扩展，例如添加交易功能、监控市场数据等。Bithumb API 提供了丰富的功能，可以满足各种不同的开发需求。请查阅 Bithumb 官方 API 文档以获取更多信息。