Bithumb API使用指南：从入门到实战秘籍

频道： 动态 日期： 浏览：49

Bithumb API 使用指南：从入门到实践

Bithumb，作为韩国领先的加密货币交易所之一，提供了强大的应用程序编程接口（API），允许开发者和交易者以编程方式访问其市场数据、执行交易和管理账户。本文将深入探讨 Bithumb API 的使用方法，从账户设置、认证授权到数据获取和交易执行，并提供一些实践性的示例。

账户设置与API Key申请

在使用 Bithumb API 交易数字资产或获取市场数据之前，必须拥有一个 Bithumb 账户，并申请用于身份验证和授权的 API 密钥。API 密钥是访问 Bithumb API 的凭证，它由 API Key (Public Key) 和 Secret Key (Private Key) 组成。请务必妥善保管您的 Secret Key，避免泄露。

注册 Bithumb 账户： 首先，访问 Bithumb 官网，按照指引完成注册流程。务必完成 KYC (Know Your Customer) 身份验证，以便解锁 API 的全部功能。
  • 启用 2FA： 为了保障账户安全，强烈建议启用双重验证 (2FA)。

  • 申请 API Key：

    在 Bithumb 平台进行 API 密钥的申请，是访问其交易数据和执行自动化交易的首要步骤。此过程涉及登录您的 Bithumb 账户，并导航至账户设置或专门的 API 管理页面。

    在 API 密钥申请过程中，您通常需要提供详细的信息，以便 Bithumb 了解您使用 API 的目的和所需的访问权限。这可能包括：

    • API 用途说明： 详细描述您计划如何使用 API，例如，量化交易、市场数据分析、自动化交易机器人等。
    • 访问权限选择： 根据您的需求选择合适的 API 权限。Bithumb 通常提供多种权限选项，例如，只读权限（仅用于获取市场数据）、交易权限（允许进行买卖操作）、提现权限（允许提取账户资金）等。请务必仔细选择所需的最小权限集，以降低潜在的安全风险。
    • IP 地址白名单： 为了增强安全性，建议您设置 IP 地址白名单，限制只有来自特定 IP 地址的请求才能访问 API。这可以有效防止未经授权的访问。
    • API Key 名称： 为您的 API Key 设置一个易于识别的名称，方便您日后管理和区分不同的 API Key。

    完成信息填写和权限选择后，Bithumb 会为您生成一对 API 密钥：

    • API Key (公钥)： 用于标识您的身份，可以公开使用。
    • Secret Key (私钥)： 用于对您的 API 请求进行签名，验证请求的合法性。

    请务必高度重视 Secret Key 的安全。 它是您访问 Bithumb API 的关键凭证，一旦泄露，可能导致您的账户遭受未经授权的访问和资金损失。

    以下是一些保护 Secret Key 的最佳实践：

    • 妥善保管： 将 Secret Key 存储在安全的地方，例如加密的数据库或密钥管理系统。
    • 切勿泄露： 不要将 Secret Key 存储在版本控制系统（如 Git）中，不要通过电子邮件或即时通讯工具发送 Secret Key，不要在公共论坛或社交媒体上分享 Secret Key。
    • 定期更换： 为了提高安全性，建议您定期更换 API Key 和 Secret Key。
    • 使用环境变量： 在代码中使用 API Key 和 Secret Key 时，不要直接将其硬编码在代码中，而是应该使用环境变量或配置文件来存储。
    • 监控 API 使用情况： 定期监控 API 的使用情况，及时发现异常活动。

    设置 API 权限： 在生成 API Key 时，您可以设置不同的权限，例如：
    • 只读权限 (Read-only)： 只能访问市场数据，不能进行交易操作。
    • 交易权限 (Trade)： 可以进行买卖交易。
    • 提现权限 (Withdrawal)： 可以提取账户资金 (需满足特定条件)。

    • 请根据您的实际需求选择合适的权限，最小化安全风险。

    API 认证与授权

    Bithumb API 采用 API Key (API 密钥) 和 Secret Key (私钥) 相结合的方式，实现严格的身份验证与授权机制。API Key 用于标识您的账户，而 Secret Key 则用于对请求进行签名，以确保请求的完整性和真实性。每次向 Bithumb API 发送请求时，您必须在 HTTP 请求头中精确地包含必要的认证信息。这些信息通常包括 API Key 和使用 Secret Key 生成的签名，具体的 Header 名称和格式请参考 Bithumb 官方 API 文档。

    为了保障您的账户安全，请务必妥善保管您的 API Key 和 Secret Key。切勿将 Secret Key 泄露给任何第三方，也不要将其存储在不安全的地方，例如公共的代码仓库或客户端应用程序中。一旦 Secret Key 泄露，您的账户将面临被恶意利用的风险。

    Bithumb API 提供了不同的权限级别，您可以通过 API Key 的配置来控制 API 调用的范围。请根据您的实际需求，设置合适的权限，避免授予不必要的权限，以降低潜在的安全风险。例如，您可以创建一个只允许读取数据的 API Key，而禁止进行交易操作。

    在开发过程中，请务必仔细阅读 Bithumb 官方 API 文档，了解 API 认证和授权的详细步骤和要求。文档中通常会提供示例代码，帮助您正确地实现认证过程。同时，建议定期检查您的代码，确保认证机制的安全性，并及时更新 API 相关的库和依赖项。

    常用的认证方式：

    • HMAC-SHA512 签名： Bithumb 等加密货币交易所广泛采用 HMAC-SHA512（Keyed-Hashing for Message Authentication using SHA-512）算法，作为其API请求的主要安全认证机制。这种方法利用共享密钥（Shared Secret Key）对请求数据进行哈希运算，生成唯一的签名，从而验证请求的来源和数据完整性。
      • 原理： HMAC-SHA512 结合了哈希函数 SHA-512 和一个密钥，发送方使用密钥对消息进行哈希处理，生成消息认证码（MAC）。接收方使用相同的密钥对接收到的消息进行同样的哈希处理，然后比较两个 MAC 值。如果 MAC 值匹配，则表明消息在传输过程中未被篡改，且消息的发送者是可信的。
      • 安全性： SHA-512 是一种强大的哈希算法，即使原始数据发生微小改变，也会导致哈希值产生巨大变化。结合密钥的使用，HMAC-SHA512 能够有效防止中间人攻击和重放攻击。
      • 实施步骤：
        1. 准备数据： 构造包含所有必要参数的 API 请求数据。
        2. 生成签名： 使用你的私钥（Secret Key）和 SHA-512 算法对请求数据进行 HMAC 处理，生成签名。通常，这涉及将请求数据与密钥进行组合，然后应用 SHA-512 哈希函数。
        3. 附加签名： 将生成的签名作为请求头或请求参数的一部分发送到 Bithumb API。
        4. 验证签名： Bithumb 服务器接收到请求后，使用存储在你账户中的私钥，按照相同的步骤重新计算签名。然后，服务器会将计算出的签名与请求中提供的签名进行比较。如果两个签名匹配，则请求被认为是合法的。
      • 优势：
        • 数据完整性： 确保请求在传输过程中未被篡改。
        • 身份验证： 验证请求的发送者是否是合法的用户。
        • 防止重放攻击： 通过在请求中包含时间戳或其他唯一标识符，可以防止攻击者捕获并重新发送之前的请求。

    签名过程简述：

    1. 构建规范化请求字符串： 收集所有参与签名的请求参数，务必包含所有必要参数，例如API密钥、时间戳、请求方法以及任何业务相关的请求数据。然后，按照参数名称的字母顺序（区分大小写）对这些参数进行排序。将排序后的参数及其对应的值，以`参数名=参数值`的形式拼接成字符串。特别注意，参数值需要进行URL编码，以确保特殊字符被正确处理。如果参数值本身就是一个数组或JSON对象，则需要先将其序列化为字符串，再进行URL编码。
    2. 生成 Payload（待签名数据）： 对上一步构建的规范化请求字符串进行编码，这是生成签名的重要步骤。通常推荐并且广泛使用的是UTF-8编码，以确保跨平台和系统的兼容性。使用UTF-8编码可以避免因字符集不一致而导致的签名验证失败。如果平台或API有特殊要求，则应遵循其指定的编码方式。Payload本质上就是将需要进行哈希计算的数据准备好。
    3. 计算 HMAC 签名： 使用您的Secret Key作为密钥，这是一个高度敏感的信息，务必妥善保管，切勿泄露。使用HMAC-SHA512（Hash-based Message Authentication Code with SHA-512）算法对Payload（待签名数据）进行运算。HMAC-SHA512是一种带密钥的哈希函数，它结合了密钥的安全性以及SHA-512算法的强大哈希能力。运算的结果是一个固定长度的哈希值，这就是最终的签名。这个签名将用于验证请求的完整性和身份。
    4. 添加签名到请求： 将计算得到的HMAC签名添加到HTTP请求头或请求参数中，具体添加方式取决于API的具体要求。常见的做法是将签名放在名为`X-Signature`或类似的自定义HTTP头中，或者作为请求参数`signature`传递。同时，可能还需要传递时间戳（timestamp）和API密钥（API Key），以便服务器验证签名的有效性和请求的身份。确保以服务器期望的方式格式化和传递这些参数。
    添加请求头： 将 API Key 和签名添加到 HTTP 请求头中，例如：

    Api-Key: YOURAPIKEY Api-Sign: YOURHMACSIGNATURE Api-Timestamp: CURRENT_TIMESTAMP (UNIX timestamp in milliseconds)

    注意：

    • Api-Timestamp 是至关重要的请求时间戳，它代表了发起API请求的确切时间。该时间戳的主要作用是增强安全性，用于有效地防御潜在的重放攻击。重放攻击是指恶意攻击者截获并重新发送合法的API请求，以达到非法目的。通过验证时间戳的有效性（例如，检查它是否在允许的时间窗口内），服务器可以拒绝过时的或可疑的重放请求，从而保护系统免受损害。 请注意，时间戳通常以 Unix 时间格式（自 Epoch 以来的秒数）表示。
    • 不同的编程语言和开发框架都提供了成熟且经过充分测试的 HMAC-SHA512 算法库，开发者可以直接调用这些库来实现消息认证码的生成。HMAC-SHA512 是一种广泛使用的加密哈希函数，它结合了密钥和消息内容，生成一个唯一的哈希值，用于验证消息的完整性和身份。 例如，在 Python 中，可以使用 hashlib 库；在 Java 中，可以使用 javax.crypto 库；在 JavaScript 中，可以使用 crypto API。 选择合适的库并遵循其文档，可以简化签名过程并确保安全性。
    • 为确保正确实施签名算法并避免潜在的错误，请务必查阅 Bithumb API 官方文档，获取关于签名算法的全面且详细的说明，包括具体的参数格式、数据类型、编码方式以及任何特定的要求。 官方文档通常会提供各种编程语言的示例代码，这些代码可以作为参考和起点，帮助开发者快速理解和实现签名过程。 仔细阅读并理解官方文档是成功集成 Bithumb API 的关键步骤。 文档中可能包含关于错误处理、常见问题解答以及最佳实践的指导。

    常用 API 接口

    Bithumb API 是一套功能强大的工具，为开发者提供了广泛的接口，覆盖了加密货币交易生态系统的各个重要方面。这些接口允许开发者访问和操控市场数据、执行交易操作以及管理用户账户，从而构建复杂的应用程序和自动化交易策略。

    以下是一些常用的 API 接口，它们构成了 Bithumb API 的核心功能集：

    1. 公共接口 (Public APIs):

    • 公共应用程序编程接口（APIs）是加密货币交易所、区块链浏览器和其他相关服务提供商提供的开放访问点。 这些接口允许开发者和交易员以编程方式检索实时市场数据、历史交易记录、账户信息（如果已授权）以及执行交易操作。 公共 API 通常采用 RESTful 或 WebSocket 协议，并提供各种数据格式，如 JSON。 通过公共 API，可以构建自动化交易机器人、数据分析工具、投资组合管理应用以及其他与加密货币相关的创新应用。 常见的应用场景包括获取最新的比特币价格、监控交易深度、计算套利机会、以及自动执行预设的交易策略。 注意，使用公共 API 时应遵守服务提供商的速率限制和服务条款，以避免被限制访问。
    行情信息 (Ticker): 获取指定交易对的实时行情数据，例如：最新成交价、最高价、最低价、成交量等。

    GET /public/ticker/{currency_pair}

    例如：获取 BTC/KRW 交易对的行情信息：

    GET /public/ticker/BTC_KRW

  • 交易深度 (Order Book): 获取指定交易对的买单和卖单列表。

    GET /public/orderbook/{currency_pair}

    例如：获取 ETH/KRW 交易对的交易深度：

    GET /public/orderbook/ETH_KRW

  • 历史成交 (Trades): 获取指定交易对的历史成交记录。

    GET /public/transactionhistory/{currencypair}

    例如：获取 XRP/KRW 交易对的历史成交记录：

    GET /public/transactionhistory/XRPKRW

    • 2. 私有接口 (Private APIs):

    • 定义与访问限制： 私有接口是指仅供特定应用程序或服务内部使用的应用程序编程接口。这些接口通常不对外部开发者公开，主要用于模块间的通信和功能调用。 访问权限受到严格控制，旨在防止未经授权的访问和潜在的安全风险。
    • 用途： 私有接口在软件架构中扮演着关键角色，用于封装内部实现细节，对外提供稳定的抽象层。 例如，一个大型应用程序的不同模块可能通过私有接口进行数据交换和协同工作。
    • 优势： 使用私有接口可以提高代码的可维护性和可扩展性。 当内部实现发生更改时，只要私有接口保持稳定，就不会影响其他模块的功能。 私有接口还可以增强安全性，防止恶意用户利用未公开的接口漏洞。
    • 示例场景： 考虑一个支付处理系统。 系统的内部模块，如账户管理、交易验证和风险评估，可能通过私有接口进行通信。 外部开发者只能通过公开的API发起支付请求，而无法直接访问内部模块的敏感数据和功能。
    • 安全考量： 虽然私有接口旨在隐藏内部实现，但仍需采取适当的安全措施来防止潜在的攻击。 例如，可以使用访问控制列表 (ACL) 来限制对私有接口的访问。 定期进行安全审计和漏洞扫描也是必不可少的。
    账户余额查询 (Account Balance): 查询账户中各种加密货币和法币的余额。需要进行 API 认证。

    POST /info/balance

    需要传递的参数：currency (例如：BTC, ETH, KRW)

  • 挂单交易 (Place Order): 提交买单或卖单。需要进行 API 认证。

    POST /trade/place

    需要传递的参数：

    • currency_pair: 交易对 (例如：BTC_KRW)
    • type: 交易类型 (buy 或 sell)
    • price: 价格
    • units: 数量
  • 取消挂单 (Cancel Order): 取消尚未成交的挂单。需要进行 API 认证。

    POST /trade/cancel

    需要传递的参数：

    • order_id: 订单 ID
    • type: 交易类型 (buy 或 sell)
  • 查询订单状态 (Order Info): 查询指定订单的状态。需要进行 API 认证。

    POST /info/order_detail

    需要传递的参数：

    • order_id: 订单 ID
    • type: 交易类型 (buy 或 sell)

    • 实践示例 (Python)

    以下是一个使用 Python 访问 Bithumb API 获取 BTC/KRW (比特币/韩元) 行情信息的示例代码。此示例展示了如何使用 requests 库发送 HTTP 请求，并处理 API 返回的 JSON 数据。 

    import requests
import hashlib
import hmac
import time
import  # 显式引入  库

API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
API_URL = "https://api.bithumb.com"

def get_ticker(currency_pair):
    """
    获取指定交易对的行情信息。

    Args:
        currency_pair (str): 交易对，例如 "BTC_KRW"。

    Returns:
        dict: 包含行情信息的字典，如果请求失败则返回 None。
    """
    url = f"{API_URL}/public/ticker/{currency_pair}"
    try:
        response = requests.get(url)
        response.raise_for_status()  # 检查 HTTP 状态码，如果状态码不是 200，则抛出异常
        data = response.() # 使用 () 方法解析 JSON 响应
        return data
    except requests.exceptions.RequestException as e:
        print(f"请求错误: {e}")
        return None

# 示例调用
if __name__ == '__main__':
    ticker_data = get_ticker("BTC_KRW")
    if ticker_data:
        print(.dumps(ticker_data, indent=4, ensure_ascii=False)) # 使用 .dumps 格式化输出，方便阅读
    else:
        print("获取行情信息失败")

    代码说明：

    • requests 库用于发送 HTTP 请求。请确保已安装该库： pip install requests 。
    • API_KEY 和 SECRET_KEY 需要替换为你自己的 Bithumb API 密钥。
    • get_ticker 函数接收一个交易对字符串作为参数，例如 "BTC_KRW"。
    • response.raise_for_status() 会检查 HTTP 状态码，如果状态码不是 200，则会抛出一个异常。这有助于检测请求是否成功。
    • response.() 方法用于将 API 返回的 JSON 数据解析为 Python 字典。
    • .dumps(ticker_data, indent=4, ensure_ascii=False) 使用 .dumps 格式化输出 JSON 数据， indent=4 表示缩进 4 个空格， ensure_ascii=False 表示允许输出非 ASCII 字符（例如中文）。
    • if __name__ == '__main__': 这段代码确保只有在直接运行脚本时才会执行示例调用，而不是在作为模块导入时执行。

    获取 BTC/KRW 行情信息

    使用 get_ticker("BTC_KRW") 函数可以获取比特币 (BTC) 与韩元 (KRW) 交易对的实时行情数据。该函数调用会向交易所的 API 发送请求，请求指定交易对的最新交易信息。

    ticker_data = get_ticker("BTC_KRW")

    在获取到 ticker_data 后，需要进行有效性检查。验证 ticker_data 是否为空，以确保 API 请求成功并返回了数据。检查 ticker_data['status'] 字段。通常，状态码 "0000" 表示请求成功，而其他状态码可能表示错误或异常情况。根据交易所的 API 文档，不同的状态码代表不同的错误类型，例如请求参数错误、API 访问频率超限等。

    if ticker_data and ticker_data['status'] == "0000":

    如果 ticker_data 不为空且状态码为 "0000"，则表明成功获取到 BTC/KRW 的行情信息。接下来，可以使用 .dumps(ticker_data, indent=4) 函数将 JSON 格式的行情数据进行格式化输出。 indent=4 参数会使输出的 JSON 数据具有四个空格的缩进，从而提高可读性。通过格式化输出，可以清晰地查看行情数据中的各个字段及其对应的值，例如最新成交价、最高价、最低价、交易量等。

    print(.dumps(ticker_data, indent=4)) # 格式化输出 JSON 数据

    如果 ticker_data 为空或 ticker_data['status'] 不为 "0000"，则说明获取行情信息失败。可能是由于网络连接问题、API 请求参数错误、交易所 API 故障等原因导致的。此时，应该输出错误提示信息，例如 "获取行情信息失败"，并根据实际情况进行错误处理，例如重新发起请求、检查 API 请求参数、联系交易所技术支持等。为了提高程序的健壮性，可以添加更详细的错误处理机制，例如记录错误日志、发送告警信息等，以便及时发现和解决问题。

    else:

    print("获取行情信息失败")

    注意：

    • API 密钥和密钥替换： 请务必将代码中的占位符 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为您从交易所或服务提供商处获得的真实 API Key 和 Secret Key。API Key 用于标识您的身份，Secret Key 用于验证请求的签名，保证交易安全。泄露您的 Secret Key 可能导致资产损失，请务必妥善保管。
    • 公共接口与私有接口： 此示例代码仅展示了如何访问加密货币交易所或服务的公共 API 接口，这些接口通常提供市场数据、交易对信息等公开信息。若要访问私有接口，例如进行下单、查询账户余额等操作，需要在 HTTP 请求中添加身份验证信息。常用的身份验证方式包括签名认证（HMAC）和 API Key 认证。请参考具体的 API 文档，了解如何正确构造包含认证信息的请求。
    • HTTP 请求库的选择： 我们强烈建议使用 requests 库来处理 HTTP 请求。 requests 库是一个功能强大且易于使用的 Python HTTP 客户端，可以简化发送 HTTP 请求、处理响应的过程。它提供了友好的 API，支持各种 HTTP 方法（GET, POST, PUT, DELETE 等），以及处理请求头、请求体、Cookie 等功能。 requests 库还内置了连接池和 SSL 验证等功能，可以提高性能和安全性。您也可以选择其他 HTTP 客户端库，例如 urllib3 或 aiohttp ，但 requests 通常是更简单易用的选择。

    安全注意事项

    • 保护 API Key 和 Secret Key： 切勿将 API Key 和 Secret Key 泄露给任何第三方。这些密钥是访问您的 Bithumb 账户的凭证，泄露会导致资产损失。请务必将 Secret Key 视为高度机密信息，绝对避免通过任何不安全的渠道（如电子邮件、聊天应用或公共代码仓库）共享。避免在公共场合或不安全的环境中存储 API Key 和 Secret Key，例如避免将它们硬编码到客户端应用程序或存储在未加密的文件中。考虑使用安全的密钥管理系统或环境变量来存储这些敏感信息。
    • 限制 API 权限： Bithumb API 提供了多种权限设置，例如交易、提现和账户信息访问等。根据您的实际需求，仔细配置 API 权限，只授予必要的权限。例如，如果您的应用程序只需要读取市场数据，则无需授予交易或提现权限。最小化权限授予原则可以有效降低潜在的安全风险，即使 API Key 泄露，攻击者也无法执行超出授权范围的操作。
    • 使用 HTTPS： 始终使用 HTTPS 协议访问 Bithumb API。HTTPS 通过 TLS/SSL 协议对数据进行加密，确保数据在传输过程中的安全性，防止中间人窃听或篡改数据。所有 Bithumb API 端点都应使用 HTTPS 协议，请在您的代码中验证 URL 是否以 `https://` 开头。
    • 验证 API 响应： 验证从 Bithumb API 收到的响应的完整性和真实性。可以验证响应的签名或使用其他机制来确保数据未被篡改。这有助于防止中间人攻击，攻击者可能会拦截 API 响应并注入恶意数据。检查响应头中的 `Content-Type`，确保响应格式符合预期。
    • 频率限制： Bithumb API 对请求频率有限制，旨在防止滥用和维护系统稳定性。请务必了解并遵守 Bithumb API 的频率限制，避免过度请求导致 IP 地址被封禁。合理设计您的应用程序，优化 API 请求的频率和数量。使用缓存机制可以减少对 API 的请求次数。如果需要高频交易，请联系 Bithumb 了解专门的解决方案。
    • 错误处理： 建立健全的错误处理机制，以便在 API 请求失败时能够及时发现和处理。记录详细的错误日志，包括错误代码、错误信息和请求参数，以便进行故障排除。实施重试机制，在网络不稳定或服务器繁忙时自动重试 API 请求。向用户提供友好的错误提示信息，帮助他们理解问题并采取相应的措施。
    • 定期审查： 定期审查 API Key 的使用情况和权限设置，及时发现和处理安全风险。监控 API 请求日志，查找异常活动，例如未经授权的访问或异常的交易模式。定期轮换 API Key，可以降低密钥泄露带来的风险。检查代码中是否存在硬编码的 API Key，并将其替换为安全的密钥管理方案。