Bithumb API 使用指南：新手开发者如何快速上手？ | 自动化交易

2025-03-05 10:04:47 75

Bithumb API 方案

本文档概述了 Bithumb 交易所提供的应用程序编程接口 (API) 方案，旨在为开发者提供全面且易于理解的指南，以便与 Bithumb 平台进行集成，实现自动交易、数据分析、以及其他基于 API 的应用。

API 概述

Bithumb API 提供了一套全面的接口，使开发者能够以编程方式与 Bithumb 交易平台进行交互。这包括实时市场数据查询、账户管理、订单执行和取消、以及资金划转等核心功能。通过API，用户可以构建自动化交易策略、集成Bithumb数据到第三方应用、或者创建自定义的交易界面。

API接口主要分为两类： 公共 API 和 私有 API 。公共 API 允许访问无需身份验证的市场信息，例如实时价格、交易量、历史数据等。私有 API 则需要身份验证，用于执行需要授权的操作，例如下单、查询账户余额、以及提取资金。

公共 API 通常用于获取以下信息：

市场行情： 获取特定交易对的最新价格、最高价、最低价、成交量等。
交易对信息： 查询交易对的详细信息，例如最小交易单位、价格精度等。
交易历史： 获取特定交易对的历史成交记录。

私有 API 用于执行需要用户授权的操作，例如：

账户管理： 查询账户余额、交易历史、充提记录等。
订单管理： 下达限价单、市价单等各种类型的订单，并可以查询、修改、取消订单。
资金管理： 进行充币和提币操作。

在使用 Bithumb API 之前，开发者需要仔细阅读官方文档，了解 API 的请求方式、参数、返回值格式、以及频率限制等重要信息。同时，为了保障账户安全，务必妥善保管 API 密钥，并采取必要的安全措施，例如使用 IP 白名单、设置合理的权限限制等。

公共 API: 公共 API 无需身份验证即可访问，主要用于获取实时市场数据，例如交易对的最新价格、交易量、买卖盘口信息等。这些数据对于市场分析和策略制定至关重要。私有 API: 私有 API 需要进行身份验证，才能访问用户的账户信息并执行交易操作。这包括查询账户余额、下达订单、取消订单、以及提取资金等敏感操作。安全性是使用私有 API 的首要考虑因素，需要妥善保管 API 密钥和私钥。

API 端点

Bithumb API 的端点遵循 RESTful 架构，这意味着它使用标准的 HTTP 方法（例如 GET、POST、PUT 和 DELETE）来执行不同的操作，并以一种可预测和一致的方式进行数据交互。RESTful API 的设计理念是利用 HTTP 协议本身的语义来简化客户端和服务器之间的通信，从而提高系统的可扩展性和可维护性。每个端点代表着一种资源，例如交易对、订单簿或用户账户信息。通过向这些端点发送 HTTP 请求，您可以检索、创建、更新或删除相应的资源。

以下是一些常用的 API 端点示例，但请注意，具体的端点和参数可能会根据 Bithumb 官方 API 文档进行更新。强烈建议您在开发时查阅最新的文档，以确保兼容性和准确性：

公共 API:

/public/ticker/{currency} : 获取指定币种的 Ticker 信息，包括但不限于最新成交价、24小时涨跌幅、24小时最高价、24小时最低价、24小时成交量等关键市场数据。此接口对于快速了解特定加密货币的市场表现至关重要。
/public/orderbook/{currency} : 获取指定币种的 Order Book 信息，呈现买盘和卖盘的深度数据。Order Book 展示了不同价格级别的买单和卖单数量，帮助用户分析市场供需关系、评估市场流动性，并制定更精明的交易策略。返回的信息通常包括买单价格、买单数量、卖单价格、卖单数量以及订单的时间戳。
/public/transaction_history/{currency} : 获取指定币种的交易历史记录，包括成交价格、成交数量以及成交时间等详细信息。通过分析历史交易数据，用户可以识别市场趋势、评估价格波动性，并进行技术分析，从而做出更明智的投资决策。返回的数据通常会分页显示，并允许用户指定时间范围和数量。

私有 API:

/info/account : 获取账户详细信息。此接口提供账户余额、可用资金、已用保证金、冻结资金等关键数据。权限验证必不可少，建议采用安全的身份验证机制（如 API 密钥和签名）。
/trade/place : 下达交易订单。此接口允许用户提交买入或卖出订单，需要指定交易对、订单类型（市价单、限价单等）、价格（限价单）、数量等参数。强烈建议进行参数校验，防止恶意攻击。
/trade/cancel : 取消未成交订单。用户可以通过此接口取消尚未完全成交的订单。需要提供订单 ID 作为参数。实现幂等性至关重要，避免重复取消。
/trade/orders : 查询未成交订单列表。此接口允许用户查看当前所有未成交的挂单。支持分页查询和时间范围筛选，优化查询性能。
/wallet/withdraw : 发起提现请求。用户可以通过此接口将账户中的资金提现到指定地址。需要验证提现地址的有效性和用户身份。考虑加入双重验证机制，增强安全性。

重要提示：在 API 调用中， {currency} 占位符必须替换为有效的币种代码，例如 BTC_KRW 代表比特币兑韩元交易对。务必仔细核对币种代码，避免交易错误。

认证

使用 Bithumb 私有 API 必须进行身份验证，以确保数据安全和用户账户安全。Bithumb API 使用 API 密钥 (API Key) 和私钥 (Secret Key) 相结合的方式进行认证。API 密钥用于唯一标识用户，类似于用户名，而私钥则用于对请求进行数字签名，用于验证请求的来源和数据完整性，防止恶意篡改。

身份验证的过程包含以下几个关键步骤：

获取 API 密钥和私钥：
在 Bithumb 交易所的官方网站或移动应用程序中的个人中心或 API 管理页面，您可以创建并管理 API 密钥对。在创建密钥时，请务必启用所需的 API 权限，例如交易权限、资金划转权限或查询权限等，并限制 API 密钥的使用 IP 地址，以增强安全性。强烈建议您启用双因素认证（2FA）以保护您的 Bithumb 账户安全。在获得 API 密钥和私钥后，请将它们安全地存储在本地，避免存储在云端或其他不安全的地方。特别要注意的是， 私钥是高度敏感的信息，切勿将其泄露给任何第三方，包括 Bithumb 的工作人员 。一旦私钥泄露，您的账户将面临被盗用的风险。
生成请求签名：
在发起任何私有 API 请求之前，您需要使用私钥对请求的参数进行签名。签名过程通常涉及以下步骤：
- 构建请求字符串： 将请求的所有参数按照字母顺序排序，并将它们连接成一个字符串。确保 URL 参数和 POST 参数都包含在签名字符串中。
- 添加时间戳： 将当前时间戳（以秒为单位的 Unix 时间）添加到请求字符串中。时间戳用于防止重放攻击。
- 使用 HMAC-SHA512 算法进行签名： 使用私钥作为密钥，对请求字符串进行 HMAC-SHA512 加密。HMAC-SHA512 是一种消息认证码算法，可以有效地验证数据的完整性和来源。
- 将签名转换为大写字符串： 将生成的签名转换为大写字符串。
在请求头中包含认证信息：
将 API 密钥、签名和时间戳包含在 HTTP 请求头中，以便 Bithumb 服务器可以验证您的身份并授权您的请求。通常情况下，请求头包含以下字段：
- Api-Key : 您的 API 密钥，用于标识您的 Bithumb 账户。
- Api-Sign : 使用私钥生成的请求签名，用于验证请求的真实性和完整性。
- Api-Timestamp : 发起请求时的时间戳，用于防止重放攻击。时间戳的有效时间通常很短，例如 5 秒或 10 秒。
- Content-Type : 指定请求体的 MIME 类型，通常为 application/x-www-form-urlencoded 或 application/ 。
除了以上三个字段外，您可能还需要根据 Bithumb API 的具体要求添加其他请求头字段。请务必仔细阅读 Bithumb API 的文档，以确保您的请求头包含所有必需的信息。

请求格式与响应格式

Bithumb API 使用 JSON (JavaScript Object Notation) 格式进行数据通信，确保数据在不同系统间的可读性和互操作性。所有API请求的 Content-Type 头部信息通常设置为 application/ ，明确告知服务器请求体的内容类型为JSON。服务器返回的响应数据也采用JSON格式，便于客户端解析和处理请求结果。

一个典型的 API 请求示例 (使用 curl)：展示了如何通过命令行工具发送一个POST请求到Bithumb API，进行交易操作。


curl -X POST \
  'https://api.bithumb.com/trade/place' \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Api-Sign: YOUR_API_SIGNATURE' \
  -H 'Api-Timestamp: 1678886400' \
  -H 'Content-Type: application/' \
  -d '{
    "order_currency": "BTC",
    "payment_currency": "KRW",
    "type": "bid",
    "price": "50000000",
    "units": "0.01"
  }'

以上curl命令中， -X POST 指定请求方法为POST。 -H 用于设置HTTP头部，包括 Api-Key （你的API密钥，用于身份验证）, Api-Sign (根据请求参数生成的签名，用于防止篡改), Api-Timestamp （时间戳，用于防止重放攻击）和 Content-Type 。 -d 用于设置请求体，包含了订单的详细信息： order_currency (交易的币种), payment_currency (结算币种), type (交易类型，如买入"bid"或卖出"ask"), price (单价) 和 units (数量)。特别注意，API Key、API Signature和时间戳是访问Bithumb API的关键认证信息，务必妥善保管和正确生成签名。

一个典型的 API 响应示例：展示了服务器返回的数据结构，包含请求的状态和订单ID。


{
  "status": "0000",
  "data": {
    "order_id": "C0000000000000000000000000000001"
  }
}

在这个响应中， status 字段指示API请求的状态码，是了解请求成功与否的重要指标。 data 字段则包含具体的返回数据，在本例中是 order_id ，表示成功创建的订单ID。状态码 "0000" 通常意味着请求成功，其他状态码可能表示错误或异常情况，需要查阅Bithumb API文档进行详细解读。例如，常见的错误码可能包括参数错误、权限不足或服务器内部错误等。

错误处理

Bithumb API 使用标准的 HTTP 状态码以及 JSON 响应中的 status 字段，双重机制来清晰地指示请求的执行结果。HTTP 状态码提供了快速的高级别反馈，而 status 字段则提供了更为精细的错误信息。常见的 HTTP 状态码及其含义包括：

200 OK : 请求已成功处理。这意味着服务器成功接收、理解并接受了客户端的请求。
400 Bad Request : 请求格式错误或包含无效参数。通常是由于客户端提交的数据类型不正确、缺少必需字段或包含非法值导致的。
401 Unauthorized : 身份验证失败。客户端未提供有效的身份验证凭据，例如 API 密钥错误或缺失，或提供的 Token 无效。
403 Forbidden : 权限不足。客户端已通过身份验证，但没有执行所请求操作的权限。这可能是由于账户权限设置不正确或API调用不在允许的访问范围内。
429 Too Many Requests : 请求频率过高，超过了API限制。为了防止滥用，Bithumb对API调用频率进行了限制。客户端应实现重试机制，并遵循速率限制策略。
500 Internal Server Error : 服务器内部错误。这表明服务器在处理请求时遇到了未预料到的问题。这种情况通常需要Bithumb官方进行修复。

除了 HTTP 状态码外，JSON 响应中的 status 字段包含 Bithumb 交易所定义的特定错误代码。这些错误代码提供了关于错误的更详细的信息。例如，错误代码 "5100" 通常表示提供的 API 密钥无效或已过期，而错误代码 "5600" 表示尝试下单的数量低于交易所允许的最小订单数量。开发者应该仔细查阅 Bithumb 的 API 文档，了解每个错误代码的具体含义，并根据这些错误代码采取相应的处理措施，例如，重新请求 API 密钥、调整订单数量或通知用户进行适当的操作。

速率限制

为保障 Bithumb API 服务的整体稳定性和公平访问，我们实施了速率限制策略。该策略旨在防止滥用，确保所有开发者都能获得可靠且一致的 API 体验。速率限制的具体规则并非一成不变，而是根据您所访问的 API 端点和您的账户认证级别动态调整。例如，公共端点可能具有比需要身份验证的私有端点更严格的限制。同时，更高级别的认证用户通常会分配到更高的速率限制。

作为开发者，您必须密切关注并合理控制您的 API 请求频率，避免超出既定的速率限制。频繁的请求可能会导致您的请求被暂时拒绝，影响您的应用程序功能。我们强烈建议您实施适当的重试机制和错误处理，以便在遇到速率限制时能够优雅地处理。

您可以通过检查 HTTP 响应头中的 X-RateLimit-Limit 和 X-RateLimit-Remaining 字段，实时了解您当前的速率限制使用情况。 X-RateLimit-Limit 表示在给定时间窗口内允许的最大请求数量，而 X-RateLimit-Remaining 则表示您在该时间窗口内剩余的可用请求次数。利用这些信息，您可以优化您的请求策略，避免不必要的速率限制。

请务必查阅 Bithumb API 的官方文档，详细了解不同端点和认证级别的具体速率限制规则。我们会定期更新文档，以反映最新的策略变化。准确理解这些规则对于构建高效且可靠的 API 集成至关重要。

SDK 和示例代码

为了便于开发者高效地集成和使用 Bithumb API，Bithumb官方以及活跃的第三方开发者社区会提供一系列精心设计的软件开发工具包（SDK）和详尽的示例代码。这些SDK本质上是预先构建好的代码库，它们封装了与Bithumb API进行交互时所涉及的复杂底层细节，例如API请求的构造、身份验证流程的处理、数据格式的转换以及错误响应的解析等。通过使用SDK，开发者可以极大地简化开发流程，避免重复编写大量的样板代码。

这些SDK通常会针对特定的编程语言进行优化，以便开发者可以使用自己熟悉的语言进行开发。开发者可以根据项目所使用的编程语言选择最合适的SDK。Bithumb API的SDK通常支持多种流行的编程语言，涵盖了Python、Java、Node.js、Go以及PHP等。每个SDK都配有相应的文档和示例代码，开发者可以参照这些示例代码来学习如何使用SDK提供的各种功能，从而快速上手并高效地利用Bithumb API构建自己的应用程序。

示例代码通常涵盖了API的各种常见用例，例如获取市场行情数据、查询账户余额、下单交易、取消订单以及获取历史交易记录等。通过学习这些示例代码，开发者可以了解到如何正确地构造API请求、如何处理API响应以及如何处理潜在的错误情况。一些高级的SDK可能还会提供额外的功能，例如自动重试机制、请求速率限制处理以及数据缓存等，从而进一步提高应用程序的稳定性和性能。

安全性建议

在使用 Bithumb API 进行加密货币交易和数据访问时，安全性至关重要。由于API密钥一旦泄露可能导致严重的资产损失或信息泄露，因此必须采取一系列严格的安全措施来保护您的账户和数据。以下是一些关键的安全建议，旨在帮助您最大程度地降低风险：

妥善保管 API 密钥和私钥： API 密钥和私钥是访问 Bithumb API 的凭证，相当于账户的密码。绝对不要将私钥泄露给任何人，即使是 Bithumb 官方人员也不会主动索取您的私钥。不要将密钥以明文形式存储在任何地方，包括但不限于文本文件、电子邮件、聊天记录等。推荐使用专门的密钥管理工具或者硬件钱包来安全地存储和管理您的 API 密钥。
使用 HTTPS 进行数据传输： HTTPS (Hypertext Transfer Protocol Secure) 是一种安全的 HTTP 协议，通过 SSL/TLS 加密数据传输，防止数据在传输过程中被窃听或篡改。务必确保所有与 Bithumb API 的交互都使用 HTTPS 协议，即 API 请求的 URL 以 `https://` 开头。避免使用 HTTP 协议，因为它不提供任何加密，数据以明文形式传输，极易被攻击者截获。
验证服务器证书： SSL 证书用于验证服务器的身份，防止中间人攻击。在建立 HTTPS 连接时，浏览器或客户端会验证服务器提供的 SSL 证书是否有效。您可以使用浏览器或专业的 SSL 证书验证工具来检查 Bithumb API 服务器的 SSL 证书是否由受信任的证书颁发机构 (CA) 签发，以及证书是否过期。如果发现证书无效，请立即停止使用 API 并联系 Bithumb 官方客服。
限制 API 密钥的权限： Bithumb API 允许您为 API 密钥设置不同的权限，例如只允许进行交易操作，禁止提现操作；或者只允许访问市场数据，禁止进行任何交易操作。根据您的实际需求，为 API 密钥设置最小必要的权限，避免授予过多的权限，以降低风险。即使 API 密钥泄露，攻击者也只能在您授权的范围内进行操作。
定期更换 API 密钥： 定期更换 API 密钥是一种预防性的安全措施。即使您没有发现任何安全问题，也建议您定期更换 API 密钥，例如每月或每季度更换一次。更换 API 密钥可以有效地防止因密钥泄露而造成的损失。更换 API 密钥后，请务必更新所有使用该密钥的应用程序或脚本。
监控 API 使用情况： 密切监控 API 的使用情况，包括请求频率、交易量、交易类型等。如果发现任何异常行为，例如突然出现大量的提现请求、不明来源的交易请求等，请立即停止使用 API 并联系 Bithumb 官方客服。您可以使用 Bithumb API 提供的监控功能，或者自行开发监控工具来监控 API 的使用情况。同时，注意查看Bithumb官方发布的任何安全公告，以获取最新的安全信息。

未来发展

Bithumb 交易所作为韩国领先的加密货币交易平台，其API方案的未来发展将紧密围绕市场需求、技术革新以及监管政策的变化展开。开发者应保持对Bithumb官方渠道（包括公告、开发者文档以及技术博客）的密切关注，以便第一时间掌握API的最新动态。

可能的演进方向包括：

新增API端点： 为了支持更多样化的交易策略和数据分析需求，Bithumb可能会推出新的API端点，例如针对特定交易对的深度行情数据、历史交易数据更细粒度的查询接口、高级订单类型（如冰山订单、止损限价订单）的API支持等。
现有接口优化： Bithumb可能会持续对现有API接口进行性能优化，例如提升响应速度、减少延迟、提高并发处理能力，以满足高频交易和量化交易的需求。也可能改进数据格式，使其更易于解析和使用。
认证方式升级： 随着安全威胁的不断演变，Bithumb可能会采用更安全的API认证方式，例如引入双因素认证（2FA）、IP白名单、更复杂的密钥管理机制等，以增强API的安全性，防止未经授权的访问。
Websocket API增强： 实时数据推送的需求日益增长，Bithumb可能会进一步增强其Websocket API，提供更全面、更稳定的实时行情、交易和订单簿数据，并支持更多的订阅选项，方便开发者构建实时交易应用。
监管合规： 面对不断变化的加密货币监管环境，Bithumb的API设计也将更加注重合规性，例如可能会增加KYC（了解你的客户）/AML（反洗钱）相关的API接口，或者调整API的使用权限，以符合监管要求。
开发者工具和文档完善： Bithumb可能会推出更完善的开发者工具和文档，例如提供示例代码、SDK（软件开发工具包）、API调用调试工具等，以降低开发者的接入成本，提高开发效率。

为确保应用程序与Bithumb API的持续兼容性，开发者应定期检查并更新其代码，遵循最新的API规范，并参与Bithumb开发者社区的讨论，及时反馈问题和建议。