当前位置：首页 > 词典 > 正文

掌握Bithumb API：交易接口、密钥安全与最佳实践！

词典
时间：2025-03-06
访问：71

本文详解Bithumb API，涵盖公开/私有API、身份验证、下单流程及错误处理。助您快速上手，安全高效地开发Bithumb应用。

Bithumb API 接口详解

Bithumb 作为韩国最大的加密货币交易所之一，提供了强大的 API 接口，允许开发者访问其市场数据、进行交易、管理账户等。理解 Bithumb API 的运作方式，对于希望构建自动化交易策略、数据分析工具或集成 Bithumb 平台的第三方应用至关重要。本文将深入探讨 Bithumb API 的各个方面，帮助开发者更好地利用其功能。

API 概述

Bithumb API 提供了对平台功能的编程访问接口，主要分为公开 API 和私有 API 两大类。选择合适的 API 类型取决于开发者的具体需求，公开 API 主要用于获取市场信息，而私有 API 则允许用户进行账户管理和交易操作。

公开 API (Public API): 此类 API 无需进行身份验证即可访问，主要用于获取各种市场数据。这些数据包括但不限于：所有可用交易对的详细信息，例如交易对的名称、交易单位、报价单位等；实时行情数据，包括最新成交价、最高价、最低价、成交量等；历史交易记录，可以用于分析市场趋势和波动；以及订单簿信息，展示买单和卖单的价格和数量。公开 API 适用于创建行情监控工具、数据分析平台等应用场景。
私有 API (Private API): 此类 API 需要进行身份验证才能访问，允许用户执行账户管理和交易操作。用户可以通过私有 API 管理账户资金，例如充值和提现；提交各种类型的订单，包括市价单、限价单、止损单等；查询订单的当前状态，例如已成交、未成交、部分成交等；查看完整的历史交易记录，包括成交价格、成交时间、成交数量等；以及获取账户余额和持仓信息，了解当前账户的资产状况。私有 API 适用于开发自动化交易程序、量化交易策略、以及用户账户管理工具等应用场景。

为了使用 Bithumb 的私有 API，开发者必须首先注册一个 Bithumb 账号。注册成功后，需要在 Bithumb 平台创建 API 密钥。API 密钥由 API-KEY (API 密钥) 和 API-SECRET (API 密钥密钥) 两部分组成，务必妥善保管。 API-SECRET 相当于账户密码，一旦泄露，可能导致账户资金损失，因此绝对不能泄露给任何第三方，并建议定期更换 API 密钥，提高账户安全性。在调用私有 API 时，需要使用 API-KEY 和 API-SECRET 对请求进行签名，以确保请求的安全性。 Bithumb 官方文档提供了详细的签名算法说明和示例代码，开发者可以参考这些文档来实现请求签名。

公开 API

公开 API 提供以下主要功能：

行情信息: 获取指定交易对的实时行情数据，包括但不限于当前价格（最新成交价）、24小时内最高价、24小时内最低价、24小时内交易量（包括基础货币和计价货币）、24小时内成交额以及加权平均价格等。这些数据对于快速了解市场动态至关重要。
交易历史: 获取特定交易对的历史交易记录，详细信息包括成交价格、成交数量、成交时间戳以及买卖方向（买入或卖出）。这些历史数据可用于技术分析、趋势预测以及算法交易策略的制定。
交易对信息: 获取 Bithumb 交易所支持的所有交易对的详细参数信息，例如交易手续费率（买入和卖出）、最小交易单位（最小下单数量）、价格精度（小数点位数）、交易状态（是否可交易）以及交易对的详细描述。这些信息有助于用户了解交易规则，避免不必要的损失。
订单簿: 获取特定交易对的实时订单簿信息，包括买单（Bid）和卖单（Ask）的价格和数量。订单簿数据反映了市场深度和买卖力量的分布情况，是进行高频交易和套利交易的关键数据来源。通过分析订单簿，可以更好地预测价格走向和市场情绪。
最近成交价: 获取特定交易对的最新成交价格。该信息通常作为市场行情变化的快速指示器，反映了最新的市场供需情况。与行情信息中的当前价格类似，但更侧重于即时性。

示例 (获取 BTC/KRW 行情信息):

使用 GET 方法请求 /public/ticker/BTC_KRW 接口，可以获取比特币（BTC）兑韩元（KRW）的实时行情数据。

响应结果 (JSON 格式):

status 字段指示 API 请求的状态。 0000 表示请求成功并返回有效数据。如果请求失败，该字段将包含相应的错误代码，例如网络错误或无效的 API 密钥。

data 字段包含有关 BTC/KRW 交易对的最新市场信息。


{
  "status": "0000",
  "data": {
    "opening_price": "45000000",
    "closing_price": "46000000",
    "min_price": "44500000",
    "max_price": "46500000",
    "units_traded": "100",
    "acc_trade_value": "4600000000",
    "prev_closing_price": "44800000",
    "units_traded_24H": "200",
    "acc_trade_value_24H": "9200000000",
    "fluctate_24H": "1200000",
    "fluctate_rate_24H": "0.0267",
    "date": "1678886400000"
  }
}

字段解释：

opening_price : 当日开盘价格。
closing_price : 当日收盘价格。
min_price : 当日最低价格。
max_price : 当日最高价格。
units_traded : 当日交易量。
acc_trade_value : 当日累计交易额。
prev_closing_price : 前一日收盘价格。
units_traded_24H : 过去 24 小时交易量。
acc_trade_value_24H : 过去 24 小时累计交易额。
fluctate_24H : 过去 24 小时价格波动额。
fluctate_rate_24H : 过去 24 小时价格波动率。
date : 数据时间戳（毫秒）。Unix 时间戳，表示数据生成的时间。

status 字段是返回状态码， 0000 通常表示请求成功，其他状态码代表不同的错误类型。 data 字段包含具体且详细的行情数据，开发者可以根据这些数据进行分析和应用开发。请注意，数据是实时更新的，每次请求都会返回最新的市场信息。

私有 API

私有 API 提供以下主要功能，允许用户以编程方式访问和管理其加密货币账户：

账户信息: 查询账户详细信息，包括各种加密货币的余额、可用余额、冻结余额，以及当前交易手续费率。该功能还允许用户获取账户的保证金信息（如果适用）。
下单: 创建买单或卖单，支持多种订单类型。包括：
- 市价单： 以当前市场最优价格立即执行的订单。
- 限价单： 以指定价格或更优价格执行的订单。
- 止损单： 当市场价格达到预设止损价格时触发的订单。
- 止损限价单： 当市场价格达到预设止损价格时触发的限价单。
- 高级订单类型： 部分交易所还提供冰山订单、隐藏订单等高级订单类型，以满足更复杂的交易需求。
订单查询: 查询订单状态，包括：
- 未成交订单（挂单）： 尚未完全成交的订单，显示订单的详细信息，如价格、数量、订单类型等。
- 已成交订单： 已经完全成交的订单，显示成交价格、成交数量、成交时间等信息。
- 已取消订单： 用户主动取消或因故被交易所取消的订单。
- 历史订单： 查询指定时间范围内的所有订单记录。
订单取消: 取消尚未完全成交的订单，允许用户在市场情况变化时及时调整交易策略。部分交易所可能对取消订单的数量或频率有限制。
交易记录: 查询历史交易记录，包括所有买入和卖出交易的详细信息，如交易时间、交易对、成交价格、成交数量、手续费等。这些记录对于账户审计和税务报告非常重要。
提币: 将加密货币从 Bithumb 交易所提现到用户控制的其他钱包地址。用户需要提供目标钱包地址和提币数量，并可能需要进行身份验证。需要注意提币手续费和提币限额。
充币: 获取 Bithumb 交易所为用户生成的唯一充币地址，用于将加密货币充值到 Bithumb 账户。用户需要确保充值的加密货币类型与充币地址对应，否则可能导致资金丢失。充币到账通常需要一定数量的网络确认。

身份验证:

使用私有 API 接口进行访问，需要进行严格的身份验证，以确保安全性和数据访问控制。这需要你在每个请求的头部 (Header) 中包含必要的身份验证信息。

Api-Key : API 密钥是一个公开的标识符，用于识别你的应用程序或账户。它类似于用户名，但更适合机器之间的通信。请务必妥善保管你的 API 密钥，避免泄露。
Api-Secret : API 密钥是与 Api-Key 配对使用的私有密钥，类似于密码。它用于生成签名 ( Api-Sign )，验证请求的来源和完整性。绝对不要在客户端代码中硬编码 Api-Secret ，并将其存储在安全的地方，例如服务器端环境变量或密钥管理系统。
Api-Sign : 签名是一个根据请求的参数、 Api-Secret 以及特定算法生成的哈希值。它的作用是防止请求被篡改，并确保请求是由授权的客户端发出的。服务端会使用相同的算法和 Api-Secret 重新计算签名，并与请求中的 Api-Sign 进行比较，如果两者匹配，则验证通过。签名算法通常包括 HMAC-SHA256 或类似的加密哈希函数。正确生成签名需要仔细阅读 API 文档，并理解签名算法的细节。

签名生成:

为了确保 API 请求的安全性和完整性，签名机制是必不可少的。签名需要使用您的 API-SECRET 密钥，通过 HMAC-SHA512 算法对请求参数进行加密处理。以下是详细的签名生成步骤：

参数排序： 将所有需要包含在请求中的参数（包括查询参数和 POST 请求体中的参数）按照其键名的字母顺序进行升序排列。请注意，如果参数值本身也是一个复杂的数据结构（例如 JSON 对象），则应该对该数据结构内部的键名进行排序。空值参数也应该参与排序，但不需要参与后续的拼接和加密。
字符串拼接： 将排序后的参数按照 "key=value" 的格式拼接成一个字符串。多个参数之间使用 "&" 符号连接。对于 URL 编码的参数，拼接前需要进行 URL 解码。例如，如果排序后的参数是 {a:1, b:2, c:3} ，拼接后的字符串应该是 a=1&b=2&c=3 。
HMAC-SHA512 加密： 使用您的 API-SECRET 密钥对拼接后的字符串进行 HMAC-SHA512 加密。 HMAC (Hash-based Message Authentication Code) 是一种使用哈希函数和密钥生成消息认证码的算法。 SHA512 是一种安全哈希算法，HMAC-SHA512 将 SHA512 与密钥结合使用，提供更强的安全性。不同的编程语言和库可能提供不同的 HMAC-SHA512 实现，请确保使用符合安全标准的实现。
Base64 编码： 将 HMAC-SHA512 加密后的结果进行 Base64 编码。 Base64 是一种将二进制数据转换为 ASCII 字符串的编码方式，用于在不支持二进制数据传输的协议中传输数据。 Base64 编码后的字符串可以直接作为签名值包含在 API 请求头或请求参数中。

示例 (查询账户余额):

API 端点: POST /info/balance

功能描述: 此 API 接口允许用户查询其账户内指定加密货币的余额信息，包括总量、可用余额和已用余额。适用于需要实时监控账户资产状况的应用场景。

请求参数 (JSON 格式):

{
    "currency": "BTC"  // 必填，指定要查询的币种，例如："BTC" (比特币), "ETH" (以太坊), "LTC" (莱特币) 等
}

请求参数说明:

currency : 字符串类型， 必须提供 。用于指定需要查询余额的加密货币代码。请确保使用交易所支持的正确币种代码。

请求头 (HTTP Headers):

Api-Key: YOUR_API_KEY       // 您的 API 密钥，用于身份验证
Api-Secret: YOUR_API_SECRET   // 您的 API 密钥对应的密钥，用于签名
Api-Sign: YOUR_SIGNATURE     // 使用 Api-Secret 和请求参数生成的签名，用于防止篡改。签名算法请参考API文档的安全验证部分。

请求头说明:

Api-Key : 您的唯一 API 密钥，由交易所分配，用于标识您的身份。
Api-Secret : 与 API 密钥关联的密钥，必须妥善保管，用于生成签名。
Api-Sign : 请求签名，是使用 Api-Secret 对请求参数进行哈希运算后得到的字符串。确保请求的完整性和真实性。

响应结果 (JSON 格式):

{
    "status": "0000", // 状态码，"0000" 表示成功，其他值表示错误。具体错误码请参考API文档。
    "data": {
        "total_btc": "1.0",       // 账户拥有的 BTC 总量
        "available_btc": "0.5",   // 可用的 BTC 数量，可以用于交易
        "in_use_btc": "0.5",      // 正在使用的 BTC 数量，例如挂单冻结的 BTC
        "total_krw": "1000000",   // 账户拥有的 KRW (韩元) 总量
        "available_krw": "500000", // 可用的 KRW 数量
        "in_use_krw": "500000",   // 正在使用的 KRW 数量
        "trade_fee": "0.0025"    // 交易手续费，以小数表示，例如 0.0025 表示 0.25%
    }
}

响应结果字段解释:

status : 字符串类型，表示 API 请求的状态。 "0000" 通常表示成功。
data : JSON 对象，包含账户余额信息。
- total_btc : 字符串类型，表示账户拥有的 BTC 总量。
- available_btc : 字符串类型，表示可用于交易的 BTC 数量。
- in_use_btc : 字符串类型，表示当前正在使用的 BTC 数量（例如，挂单冻结的 BTC）。
- total_krw : 字符串类型，表示账户拥有的 KRW 总量。
- available_krw : 字符串类型，表示可用于交易的 KRW 数量。
- in_use_krw : 字符串类型，表示当前正在使用的 KRW 数量（例如，挂单冻结的 KRW）。
- trade_fee : 字符串类型，表示交易手续费率，例如 "0.0025" 代表 0.25%。

total_btc 表示账户拥有的 BTC 总量， available_btc 表示可用的 BTC 数量， in_use_btc 表示正在使用的 BTC 数量（例如挂单冻结）。 trade_fee 表示交易手续费，以小数形式表示，例如0.0025 表示0.25%。注意，所有金额均以字符串形式返回，以避免精度问题。

下单示例:

使用 HTTP POST 方法向 /trade/place 端点提交交易请求。

请求参数:

JSON 格式的请求体包含以下参数，用于指定交易的具体细节：

{
    "ordercurrency": "BTC",  // 交易货币，例如比特币（BTC）
     "paymentcurrency": "KRW", // 支付货币，例如韩元（KRW）
    "units":  "0.01", // 交易数量，例如买入/卖出 0.01 个 BTC
    "price": "45000000", // 交易价格，例如以 45,000,000 KRW 的价格购买
      "type": "bid"  // 交易类型： bid (买入), ask (卖出)
}

order_currency 指定要交易的加密货币的币种代码。 payment_currency 指定用于支付的法定货币或其他加密货币的币种代码。 units 指定要交易的加密货币的数量，必须是正数。 price 指定交易的价格，以 payment_currency 计价。 type 指定交易类型， bid 表示买入， ask 表示卖出。

请求头:

为了验证请求的身份并确保其安全性，需要在 HTTP 请求头中包含以下身份验证信息：

Api-Key: YOURAPIKEY      // 您的 API 密钥，用于标识您的账户
Api-Secret:  YOURAPISECRET  // 您的 API 密钥，用于验证请求签名
Api-Sign: YOUR_SIGNATURE      // 请求签名，用于防止篡改，通过对请求参数和密钥进行哈希运算生成

请务必安全地保管您的 Api-Key 和 Api-Secret ，不要泄露给他人。 Api-Sign 的生成方法通常由交易所的 API 文档提供，它涉及到将请求参数、时间戳和 Api-Secret 按照一定的规则进行哈希运算。

错误处理

Bithumb API 采用HTTP状态码和自定义状态码相结合的方式来反馈请求结果。开发者应当同时检查HTTP状态码（例如200 OK表示成功）以及Bithumb API自定义状态码。下面列出一些常见的Bithumb API自定义状态码，但请注意，这并非完整列表，务必查阅Bithumb官方API文档获取最准确和最新的状态码信息：

0000 : 成功 - 表示API请求已成功处理并返回预期结果。
5100 : 无效的 API 密钥 - 表明提供的API密钥不正确或不存在。开发者应检查API密钥是否已正确配置，并确保与Bithumb账户关联。
5200 : API 密钥已过期 - 指示使用的API密钥已过期，无法再用于访问API。开发者需要重新生成或更新API密钥。密钥过期可能是出于安全原因，定期轮换密钥是良好的安全实践。
5300 : 签名验证失败 - 表明请求的签名验证失败。这通常是由于签名算法错误、密钥不匹配或请求参数被篡改所致。开发者应仔细检查签名算法的实现，确保使用正确的密钥和参数生成签名。时间同步也非常重要，因为签名通常包含时间戳，时间偏差过大会导致签名验证失败。
5400 : 请求参数错误 - 指示请求中包含无效或缺失的参数。开发者应仔细检查API文档，确认请求参数的名称、类型和格式是否正确。一些参数可能是必需的，而另一些参数则有特定的取值范围或约束。
5500 : 余额不足 - 表明账户余额不足以执行请求的操作，例如下单。开发者应检查账户余额，并确保有足够的资金用于交易。
5600 : 订单不存在 - 指示指定的订单ID不存在。这可能是由于订单已被取消、成交或订单ID错误所致。开发者应检查订单ID是否正确，并确认订单是否仍然有效。
5700 : 交易失败 - 指示交易未能成功执行。这可能是由于多种原因引起的，例如市场流动性不足、价格变动过快或服务器错误。开发者应检查市场状况，并重试交易。如果问题仍然存在，请联系Bithumb客服。

开发者必须基于这些状态码准确判断API请求的结果，并据此采取适当的处理措施，例如重试请求、记录错误日志或向用户显示错误信息。除了状态码之外，API响应通常还会包含详细的错误信息，这些信息可以帮助开发者诊断和解决问题。请务必解析API响应中的错误信息，并将其用于调试和改进应用程序。强烈建议开发者实现完善的错误处理机制，以提高应用程序的稳定性和可靠性。同时关注Bithumb官方发布的API更新和维护公告，以便及时调整代码以适应API的变化。

API 使用限制

Bithumb API 为了保障系统稳定性和防止恶意攻击，对请求频率实施了严格的限制策略。这种限制被称为“速率限制”（Rate Limiting），旨在防止API被过度使用或滥用。开发者在使用Bithumb API时必须高度关注这些速率限制，否则可能导致请求失败并被临时或永久禁止访问API。

具体的速率限制信息，例如每分钟允许的请求次数、不同API端点的限制等，都详细记录在Bithumb官方API文档中。这些信息通常会区分不同的用户级别或API密钥类型，例如免费用户和付费用户可能会有不同的限制。开发者应该仔细阅读文档，了解其API密钥对应的速率限制规则。

当请求频率超过了允许的速率限制时，Bithumb API会返回特定的HTTP错误码，通常是429（Too Many Requests）。开发者需要在代码中处理这种错误，例如通过实施指数退避（Exponential Backoff）策略，即在收到错误后短暂暂停，然后再次尝试发送请求，并逐渐增加暂停时间，直到请求成功或达到最大重试次数。合理的缓存机制也可以有效减少对API的请求次数，提升应用程序的效率。

除了请求频率限制外，Bithumb可能还对单个请求的大小或复杂度有限制。开发者应尽量优化API请求，减少不必要的数据传输，并遵循API文档中关于请求参数和数据格式的建议。不遵循这些建议也可能导致请求失败。

安全注意事项

保护 API 密钥: API-KEY 和 API-SECRET 是访问私有 API 的凭证，务必妥善保管，切勿泄露。将其视为账户密码一样重要。避免将 API 密钥硬编码到应用程序中，推荐使用环境变量或安全的配置文件进行存储。对于公开的源代码仓库，更应严加防范，防止密钥泄露。一旦泄露，立即吊销并重新生成新的 API 密钥。
使用 HTTPS: 所有 API 请求都必须使用 HTTPS 协议，确保数据在传输过程中的加密性，防止中间人攻击和数据窃听。HTTPS 通过 SSL/TLS 协议对数据进行加密，保护敏感信息不被泄露。避免使用 HTTP 协议，因为 HTTP 协议传输的数据是明文的，容易被窃取。检查 API 接口文档，确认所有接口均支持 HTTPS 访问。
验证响应数据: 在处理 API 响应数据之前，务必验证数据的完整性和有效性，防止恶意篡改。可以采用数字签名、哈希校验等方式来验证数据的完整性。同时，根据 API 文档，验证响应数据的格式和类型是否符合预期。对于异常数据，应及时记录并采取相应的安全措施。
实施错误处理: 完善的错误处理机制至关重要，它能帮助开发者及时发现并解决问题，避免造成不必要的损失。详细记录 API 请求和响应的日志，方便问题排查。针对不同的错误类型，采取不同的处理策略，例如，重试请求、降级服务或通知管理员。避免将敏感信息暴露在错误信息中。
定期更新 API 密钥: 为了提高安全性，强烈建议定期更新 API 密钥。设定合理的更新周期，例如，每月或每季度更新一次。更新 API 密钥后，需要及时更新所有使用该密钥的应用程序和系统。密钥更新可以有效降低密钥泄露带来的风险。同时，定期审查 API 密钥的使用情况，及时清理不再使用的密钥。

Bithumb API 提供了丰富的功能，允许开发者访问市场数据、进行交易、管理账户。理解 API 的运作方式、身份验证机制、错误处理方法以及安全注意事项，对于成功开发基于 Bithumb 平台的应用程序至关重要。开发者应该仔细阅读 Bithumb 官方文档，并进行充分的测试，以确保应用程序的稳定性和安全性。

请在主题配置设置声明
本文链接： https://www.996ysj.com/item/509732.html

上一篇：欧易OKX：新手也能轻松玩转的加密货币交易平台？🔥

下一篇：告别糟糕体验：数字钱包优化秘籍，提升你的区块链入口！