Bithumb REST API解析：快速掌握交易数据与账户管理技巧

Bithumb REST API 文档解析

概述

Bithumb 提供了一套全面的 REST API，允许开发者通过编程方式访问其加密货币交易平台。 这套API旨在简化开发者与Bithumb平台的数据交互，实现自动化交易和高效的市场分析。 通过REST API，开发者能够获取实时市场数据，监控账户余额，并执行包括买入和卖出在内的各种交易操作。

本文档旨在对 Bithumb REST API 进行深入解析，帮助开发者全面理解其主要功能、具体端点以及最佳实践的使用方法。 本文档将详细介绍API的请求结构、响应格式，以及错误处理机制，以便开发者能够高效且可靠地集成 Bithumb API。

我们将重点关注几个关键的 API 端点，这些端点对于大多数开发者来说至关重要，包括：获取市场数据（如交易对的价格、交易量）、检索账户信息（如余额、交易历史记录）、以及执行交易功能（如下单、取消订单）。 每个端点都将附带详细的示例代码和说明，以便于开发者快速上手。

市场数据 API

Bithumb 的市场数据 API 提供了丰富多样的交易对实时和历史数据，涵盖了深度、成交量、价格变动等多维度信息。这些数据流对于加密货币领域的各类参与者至关重要，能够支持各种复杂应用场景。

具体来说，这些数据可以被用于构建高性能的自动化交易机器人，实现程序化交易策略，根据市场动态进行快速决策和执行。高级交易者和量化分析师可以利用这些数据进行深入的市场分析，识别趋势、预测价格走势、评估风险，并制定相应的投资策略。开发者还可以利用市场数据 API 构建信息聚合应用程序，为用户提供全面的市场概览、实时报价、图表分析等功能，方便用户进行投资决策。

Bithumb 市场数据 API 的实时性确保了用户能够第一时间获取最新的市场动态，历史数据则为回溯测试和模型训练提供了宝贵的基础。通过合理利用这些数据，用户可以更深入地了解市场，提高交易效率，并降低投资风险。

行情信息

/public/ticker/{order_currency}_{payment_currency} 端点提供指定交易对的实时市场数据快照。此API接口是获取加密货币市场价格、成交量和其他关键指标的关键途径。

通过替换 {order_currency} 和 {payment_currency} ，您可以指定要查询的具体交易对。例如，要获取比特币 (BTC) 兑 美元 (USD) 的行情信息，您可以使用 /public/ticker/BTC_USD 。

此端点返回的数据通常包含以下关键字段：

• last: 最新成交价。
• high: 过去 24 小时的最高成交价。
• low: 过去 24 小时的最低成交价。
• volume: 过去 24 小时的成交量（以交易货币计）。
• timestamp: 行情信息生成的时间戳。
• bid: 当前最高买入价。
• ask: 当前最低卖出价。
• change: 与前一日收盘价相比的价格变动。
• change_percentage: 与前一日收盘价相比的价格变动百分比。

开发者可以利用这些数据来构建交易机器人、分析市场趋势、或为用户提供实时行情信息。请注意，由于市场波动性，数据会快速变化，因此建议定期刷新数据。

参数：

• order_currency : 交易货币类型。指定用于进行交易的加密货币种类。例如，如果您希望用比特币进行交易，则此参数应设置为 "BTC"。支持的交易货币类型取决于交易所或交易平台的具体规定。
• payment_currency : 结算货币类型。指定用于结算交易的货币种类，通常是法币或者稳定币。例如，如果您的结算货币是韩元，则此参数应设置为 "KRW"。结算货币用于计算交易费用、保证金以及最终的盈亏。选择合适的结算货币可以有效降低汇率风险。

响应：

响应包含以下字段，用于提供加密货币市场的实时和历史数据。正确解析这些字段对于构建可靠的交易策略和分析工具至关重要：

• status : 请求状态码，指示API请求是否成功。例如， 0000 通常表示成功。 不同的状态码应对应不同的错误处理逻辑。完整的API文档应详细列出所有可能的状态码及其含义。
• data : 包含详细行情数据的JSON对象。此对象提供关于特定加密货币交易对的关键信息。
  • opening_price : 24小时内开盘价，表示过去24小时内第一笔交易的价格。该值是分析日内波动性的重要参考点。
  • closing_price : 最新成交价，反映当前市场上加密货币的交易价格。 这是做出交易决策的最直接的指标。
  • min_price : 24小时内最低价，标识过去24小时内的最低交易价格。有助于识别潜在的支撑位。
  • max_price : 24小时内最高价，标识过去24小时内的最高交易价格。有助于识别潜在的阻力位。
  • units_traded : 24小时内成交量，指在过去24小时内交易的加密货币单位数量。成交量是衡量市场活跃度的关键指标，高成交量通常表示市场参与者众多。
  • acc_trade_value : 24小时内成交额，指在过去24小时内交易的总价值，通常以法定货币（如美元）计价。它是通过将每笔交易的成交量乘以成交价，然后将所有交易的价值加总得到的。
  • prev_closing_price : 昨日收盘价，提供前一日交易结束时的价格。是衡量当日价格变动的重要基准。
  • units_traded_24H : 24小时内成交量 (24小时)，该字段可能与`units_traded`字段重复，但应确认其数据来源和计算方式，以便区分。某些API可能使用不同的数据源或计算方法。
  • acc_trade_value_24H : 24小时内成交额 (24小时)，该字段可能与`acc_trade_value`字段重复，但应确认其数据来源和计算方式，以便区分。某些API可能使用不同的数据源或计算方法。确保数据一致性对于避免误导性分析至关重要。
  • timestamp : 时间戳，表示数据更新的时间。时间戳通常以Unix时间戳格式表示，即自1970年1月1日UTC以来的秒数。 确保使用正确的时间格式解析，以避免时区问题。

示例：获取比特币/韩元 (BTC/KRW) 交易对的行情信息

通过发送 HTTP GET 请求，您可以获取 BTC/KRW 交易对的实时行情数据。 行情数据通常包括该交易对的最新成交价、最高价、最低价、成交量以及其他相关信息。这些信息对于交易者进行市场分析和决策至关重要。

GET /public/ticker/BTC_KRW

请求说明：

• 方法 (Method): GET
• 端点 (Endpoint): /public/ticker/BTC_KRW
• 参数 (Parameters): 无需额外参数。

响应示例 (示例数据，实际数值会变化):

{
  "timestamp": 1678886400,
  "ticker": {
    "high": 35000000,
    "low": 33000000,
    "vol": 1000,
    "last": 34500000,
    "buy": 34450000,
    "sell": 34550000,
    "change": 500000,
    "change_percent": 0.0147
  }
}

响应字段说明：

• timestamp : 数据生成的时间戳 (Unix 时间戳)。
• ticker : 包含行情数据的对象。
  • high : 24 小时内最高成交价。
  • low : 24 小时内最低成交价。
  • vol : 24 小时内成交量。
  • last : 最新成交价。
  • buy : 最高买入价。
  • sell : 最低卖出价。
  • change : 与 24 小时前相比的价格变化。
  • change_percent : 与 24 小时前相比的价格变化百分比。

注意事项：

• 请查阅交易所的官方 API 文档，了解具体的响应格式和数据更新频率。
• 不同的交易所提供的行情数据可能略有差异，请仔细阅读 API 文档。
• 对于高频交易，请注意 API 的调用频率限制，避免被限流。

交易历史

/public/transaction_history/{order_currency}_{payment_currency} 端点提供访问特定交易对历史交易数据的接口。此端点允许开发者和用户检索关于指定交易对（例如 BTC_USD）的成交记录，包括成交价格、成交数量和成交时间等详细信息。

通过调用此端点，应用程序可以构建价格图表、分析市场趋势、并执行回溯测试等操作。 交易历史数据对于算法交易策略的制定和执行至关重要。 order_currency 代表交易对中的基础货币，而 payment_currency 代表计价货币。例如，在BTC_USD交易对中，BTC是基础货币，USD是计价货币。

需要注意的是，由于数据量庞大，API 通常会提供分页或限制返回结果数量的机制。开发者应仔细阅读 API 文档，了解如何正确使用参数（如时间范围、起始ID、最大返回条数等）以获取所需的数据子集。同时，务必注意API的使用频率限制，避免因过度请求而触发限流。

参数：

• order_currency : 交易货币类型，指定用于下单或交易的数字货币种类。例如，如果要查询比特币交易对，该参数应设置为 BTC 。此参数区分大小写，必须与交易所支持的货币代码一致。
• payment_currency : 结算货币类型，即用于支付或结算交易的法币或数字货币。例如，如果交易对为BTC/KRW，则该参数应设置为 KRW ，表示以韩元结算。不同的交易所支持的结算货币类型不同，需要查阅相关API文档。
• count : 返回的记录数量，用于控制API响应中包含的历史交易或订单的数量。默认值为20，最大允许值为100。增大此值可以获取更多的历史数据，但同时也会增加响应时间和服务器负载。需要根据实际需求合理设置。
• cont_no : 用于分页的连续编号，是一个可选参数，用于获取超过单次API请求数量限制的历史数据。当需要获取大量历史数据时，首次请求可以不带此参数，API会返回指定数量的记录，并在响应中包含一个 cont_no 值。后续请求可以使用该值作为参数，以获取下一页的数据，依此类推，直到所有数据都被获取。此参数可以有效避免一次性请求过多数据导致的问题。

响应：

响应包含以下关键字段，用于解析交易历史记录及状态：

• status : 请求状态码，指示API请求是否成功。例如： 0000 通常表示请求已成功处理，其他数值可能表示错误代码，需要参考API文档了解具体错误类型及处理方法。
• data : 这是一个JSON数组，包含了用户的交易历史记录。每一条记录代表一笔已完成的交易，数组为空则表示没有交易历史。
  • transaction_date : 交易时间戳，通常以ISO 8601格式（例如： 2023-10-27T10:00:00Z ）表示，方便进行时间排序和过滤。部分API可能使用Unix时间戳（秒或毫秒）表示。
  • type : 交易类型，区分买入和卖出操作。 ask 代表卖出（出售加密货币）， bid 代表买入（购买加密货币）。不同的API可能使用不同的术语，例如 sell 和 buy ，请参考具体API文档。
  • units_traded : 交易数量，表示本次交易中买入或卖出的加密货币的数量。该数值的精度取决于交易对的设置，需要注意不同交易平台的精度差异。
  • price : 交易价格，表示每单位加密货币的成交价格。该价格通常以计价货币（例如：USDT、BTC）表示。
  • total : 总金额，表示本次交易的总成交金额，计算方式为 units_traded * price 。该金额同样以计价货币表示，并可能包含交易手续费。

示例：获取 BTC/KRW 交易历史记录

要获取比特币（BTC）与韩元（KRW）交易对的交易历史记录，您可以使用以下HTTP GET请求。此API端点允许您检索最近发生的交易数据，用于分析市场趋势和交易活动。

GET /public/transaction_history/BTC_KRW?count=50

参数说明：

• /public/transaction_history/BTC_KRW : 此路径指定了要查询的交易对。 BTC_KRW 表示比特币与韩元。 您可以将此参数更改为其他支持的交易对，例如 ETH_USD 或 LTC_EUR 。
• count=50 : 此查询参数定义了要返回的交易记录的数量。 在这个例子中， count=50 表示您请求返回最近的50条交易记录。 您可以根据需要调整此值，但要注意API可能存在最大数量限制，超过限制会返回错误。

响应数据：

API将返回一个JSON格式的数组，其中包含交易历史记录。 每条记录可能包含以下字段（具体字段取决于交易所API的设计）：

• trade_id : 交易的唯一标识符。
• timestamp : 交易发生的时间戳（通常是Unix时间戳或ISO 8601格式）。
• price : 交易的成交价格。
• amount : 交易的数量（以BTC计）。
• type : 交易类型（买入或卖出）。 通常用 buy 或 sell 表示。

注意事项：

• 您应该查阅交易所的API文档，以获取更详细的参数说明和响应数据格式。
• 不同的交易所可能有不同的API调用频率限制。 如果您的请求过于频繁，可能会被暂时阻止访问。
• 请注意保护您的API密钥（如果需要身份验证），不要将其泄露给他人。

市场深度

/public/orderbook/{order_currency}_{payment_currency} 端点提供指定交易对的实时订单簿数据，包括买单（Bid）和卖单（Ask）信息。订单簿是市场供需关系的直观体现，展示了不同价格水平上的买卖挂单数量。其中 order_currency 代表要交易的数字货币，例如比特币（BTC），而 payment_currency 代表用于结算的货币，例如美元（USD）。因此， /public/orderbook/BTC_USD 将返回比特币与美元交易对的订单簿信息。

通过分析订单簿数据，用户可以了解市场的流动性、价格支撑和阻力位，以及潜在的价格波动。例如，如果某个价格水平上存在大量的买单，则可能形成价格支撑；反之，如果某个价格水平上存在大量的卖单，则可能形成价格阻力。订单簿的深度，即特定价格范围内的订单数量，反映了市场的活跃程度和交易深度。流动性高的市场通常具有更深的订单簿，这意味着即使进行大额交易，也不会对市场价格产生显著影响。

返回的数据通常包括每个价格水平的买单和卖单的数量，以及相应的订单大小。交易所通常会提供不同深度的订单簿，例如只显示最佳的几档买卖单，或者显示更深层次的订单簿信息，以便满足不同用户的需求。需要注意的是，订单簿数据是动态变化的，会随着交易的进行而不断更新。

参数：

• order_currency : 交易货币类型。指定您希望查看订单的数字资产类型，例如比特币 (BTC)、以太坊 (ETH) 或莱特币 (LTC)。务必使用交易所支持的货币代码。
• payment_currency : 结算货币类型。这是您用于支付或接收的法定货币或加密货币。 常见示例包括韩元 (KRW)、美元 (USD) 或泰达币 (USDT)。 此参数定义了订单价值的计价货币。
• count : 返回的订单数量。用于限制API响应中返回的订单记录数量。 默认值为 5，最大允许值为 50。如果未指定此参数，API将返回最近的 5 个订单。 使用此参数可以更有效地管理API调用和处理数据。

响应：

响应包含以下字段：该接口返回的数据结构包含了交易的详细信息，用于展示市场深度和价格动态。

• status : 请求状态，指示API请求是否成功。例如： 0000 通常表示请求成功，其他代码可能代表不同的错误类型。详细的状态码定义应参考API文档。
• data : 包含订单簿数据的对象，这是响应的核心部分，包含了市场上的买单和卖单信息。
  • timestamp : 时间戳，记录了订单簿数据生成的准确时间，通常为Unix时间戳（毫秒），方便时间序列分析和数据同步。
  • payment_currency : 结算货币，指定用于结算交易的货币种类，例如USDT。这是交易对中的计价货币。
  • order_currency : 交易货币，指定被交易的货币种类，例如BTC。这是交易对中的基础货币。
  • bids : 买单数组，按照价格降序排列的买单集合，代表了市场上愿意买入该交易货币的所有订单。
    • price : 买单价格，指定买方愿意支付的最高价格。该价格以结算货币计价。
    • quantity : 买单数量，指定买方愿意购买的交易货币数量。
  • asks : 卖单数组，按照价格升序排列的卖单集合，代表了市场上愿意卖出该交易货币的所有订单。
    • price : 卖单价格，指定卖方愿意接受的最低价格。该价格以结算货币计价。
    • quantity : 卖单数量，指定卖方愿意出售的交易货币数量。

示例：

获取 BTC/KRW 交易对的订单簿信息，并通过指定返回数量来限制数据量：

GET /public/orderbook/BTC_KRW?count=10

详细说明：

此 API 请求用于检索特定交易对（在本例中为 BTC/KRW，即比特币对比韩元）的订单簿数据。订单簿是买单（bid orders）和卖单（ask orders）的集合，按照价格进行排序，反映了市场上对该交易对的供需情况。

/public/orderbook/BTC_KRW 指定了要查询的订单簿的端点，其中 BTC_KRW 表示交易对的符号。

?count=10 是一个查询参数，用于限制返回的订单数量。在这个例子中，它指示 API 只返回订单簿中最佳的 10 个买单和 10 个卖单。 增加 count 值将会返回更多订单，但也会增加响应数据的大小。

返回值：

API 将返回一个 JSON 格式的数据，其中包含买单和卖单的价格和数量信息。通常，买单会按照价格从高到低排序（买家愿意支付的最高价格优先），卖单会按照价格从低到高排序（卖家愿意接受的最低价格优先）。

注意事项：

• 不同的交易所或 API 提供商可能会有不同的订单簿结构和数据格式。在使用前务必查阅其官方文档。
• 订单簿数据是动态变化的，反映了市场的实时交易活动。
• count 参数的具体行为可能因 API 实现而异。一些 API 可能会忽略该参数，或者使用不同的默认值。
• 高频交易和市场分析通常会使用订单簿数据来评估市场深度和流动性。

账户信息 API (Private API)

账户信息 API 允许用户查询账户的详细余额信息，包括可用余额、冻结余额以及不同币种的资产分布情况。通过该 API，用户可以全面了解其加密货币账户的财务状况。该 API 还提供交易历史查询功能，用户可以获取包括交易时间、交易类型、交易金额和交易对手方等在内的详细交易记录，方便用户进行财务分析和审计。更重要的是，账户信息 API 还支持实时订单状态查询，用户可以随时掌握其挂单的执行情况，包括订单价格、数量、已成交数量和剩余数量等关键信息。这些 API 需要进行严格的身份验证才能访问，以确保用户账户的安全性和隐私性。通常采用 API 密钥、签名等机制进行身份验证和授权，以防止未经授权的访问和潜在的安全风险。

认证：

访问 Bithumb 的 Private API 接口需要进行严格的身份验证，以确保账户安全和数据完整性。Bithumb 采用 API 密钥（API Key）和秘密密钥（Secret Key）相结合的方式进行身份验证，这是一种常见的安全实践，用于验证请求的来源和授权。

为了成功通过身份验证，您需要在每个 HTTP 请求的头部（Header）中包含以下关键信息：

• Api-Key : 这是您的 API 密钥，用于唯一标识您的 Bithumb 账户。 请务必妥善保管您的 API 密钥，不要泄露给任何第三方。 您可以在 Bithumb 账户的 API 管理页面生成和管理您的 API 密钥。
• Api-Secret : 这是您的秘密密钥，也称为私钥，与 API 密钥配对使用。 秘密密钥用于生成请求签名，验证请求的真实性和完整性。 同样，请务必高度保密您的秘密密钥，切勿以任何形式公开或分享。
• Api-Sign : 这是一个使用您的秘密密钥和请求参数生成的数字签名。 签名算法通常涉及对请求参数进行排序、连接，并使用秘密密钥进行哈希运算（例如，HMAC-SHA512）。 服务端会使用相同的算法和您的秘密密钥重新生成签名，并与您提供的 Api-Sign 进行比较，以验证请求的有效性。 签名过程确保了请求在传输过程中没有被篡改。

请注意，正确的签名生成过程至关重要。 不同的 API 端点可能需要不同的请求参数和签名算法。 请务必参考 Bithumb 官方 API 文档，了解每个 API 端点的具体签名要求和参数格式。 错误的签名会导致身份验证失败，从而无法访问 Private API 接口。

账户余额

/info/balance 端点用于查询您的加密货币账户的余额信息。此端点提供关于账户中各种加密货币持有量的详细数据，包括可用余额、已锁定余额以及总余额。这些信息对于跟踪您的资产组合和管理您的加密货币投资至关重要。

通过调用 /info/balance 端点，您可以实时了解您的资金分配情况。返回的数据通常会包含以下字段：

• 币种 (Currency): 账户中持有的加密货币种类，例如 BTC (比特币), ETH (以太坊), USDT (泰达币) 等。
• 可用余额 (Available Balance): 可以立即用于交易或提现的余额。
• 已锁定余额 (Locked Balance): 由于未完成的订单、抵押或其他原因而被锁定的余额，暂时无法使用。
• 总余额 (Total Balance): 可用余额与已锁定余额之和，代表账户持有的该币种的总价值。

在开发交易机器人或构建资产管理工具时， /info/balance 端点是一个关键的数据来源。请确保您的 API 请求已正确授权，并且您理解返回数据的格式，以便准确解析和使用余额信息。注意，频繁调用此端点可能会受到 API 速率限制的影响，请合理规划您的请求频率。

参数：

• currency : 货币类型，指定所查询的加密货币或法定货币。例如：
  • BTC : 比特币 (Bitcoin)
  • ETH : 以太坊 (Ethereum)
  • LTC : 莱特币 (Litecoin)
  • KRW : 韩元 (Korean Won)
  • USD : 美元 (United States Dollar)
  • EUR : 欧元 (Euro)
  选择合适的货币类型对于获取准确的价格、交易量和其他相关市场数据至关重要。 请确保您提供的代码或应用支持所选的货币类型。不正确的货币类型可能会导致API请求失败或返回不准确的数据。

响应：

响应包含以下字段，用于提供详细的账户余额信息：

• status : 请求状态码，指示API请求是否成功。例如， 0000 通常表示请求成功完成，其他代码可能表示错误或警告。请查阅API文档以了解所有可能的状态码及其含义。
• data : 包含账户余额详细数据的JSON对象。该对象提供不同类型的余额信息，方便用户了解资金的分布情况。
  • total_{currency} : 账户持有的总余额，包括可用余额、冻结余额和交易中余额。 {currency} 代表具体的货币类型，例如 total_btc 表示总的比特币余额。
  • available_{currency} : 可用于交易或提现的余额，不包括冻结或交易中的资金。 {currency} 同样代表具体的货币类型，例如 available_eth 表示可用的以太坊余额。
  • in_use_{currency} : 由于特定原因被冻结的余额，例如，可能由于司法冻结、安全检查或其他平台规则而被临时限制使用。 {currency} 代表具体的货币类型，例如 in_use_usdt 表示被冻结的USDT余额。
  • trade_{currency} : 正在交易中的余额，例如挂单但尚未成交的资金。这部分资金暂时无法用于其他交易或提现。 {currency} 代表具体的货币类型，例如 trade_bnb 表示交易中的BNB余额。
  • balance_{currency} : 账户的实际余额，通常等于 total_{currency} 。此字段可能在某些情况下与 total_{currency} 有所不同，具体取决于平台的设计和计算方式。 {currency} 代表具体的货币类型，例如 balance_ltc 表示实际的莱特币余额。
  • account_id : 唯一标识账户的ID，用于区分不同的用户账户。
  • trade_fee : 账户的交易手续费率，通常以百分比表示。例如， 0.001 表示0.1%的手续费率。手续费会影响交易的实际成本。

示例：获取比特币 (BTC) 账户余额

通过以下 API 端点，您可以查询您的比特币 (BTC) 账户余额。该请求使用 POST 方法，并需要提供货币类型参数。

POST /info/balance

请求体 (Payload):

currency=BTC

详细说明：

此 API 接口允许用户查询指定加密货币的账户余额。在上面的示例中， currency=BTC 表示我们正在请求比特币（Bitcoin）的余额信息。 您需要将此请求发送到服务器的 /info/balance 端点。请确保您的请求包含正确的 Content-Type header (例如， application/x-www-form-urlencoded ) 以便服务器能够正确解析 payload。

请求参数说明：

• currency (必选): 指定要查询余额的加密货币类型。例如， BTC 代表比特币， ETH 代表以太坊。

可能的响应示例：

成功响应 (HTTP 200 OK):

{
  "status": "success",
  "currency": "BTC",
  "balance": "1.23456789",
  "available": "1.00000000",
  "locked": "0.23456789"
}

错误响应示例 (HTTP 400 Bad Request):

{
  "status": "error",
  "message": "Invalid currency parameter."
}

响应字段说明：

• status : 请求状态，可能的值包括 "success" 和 "error"。
• currency : 返回余额的加密货币类型。
• balance : 账户的总余额。
• available : 可用余额，即可以立即使用的余额。
• locked : 锁定余额，例如正在进行交易或提现的金额。
• message (仅在错误时返回): 错误消息，描述请求失败的原因。

注意事项：

• 请确保 API 密钥或身份验证凭据已正确配置，以便成功访问此端点。
• 不同的加密货币交易所或服务提供商可能需要额外的请求头或参数。请参考具体的 API 文档。
• 建议进行错误处理，以便在请求失败时能够采取适当的措施。
• 根据实际情况，余额可能以字符串或数字形式返回。建议使用适当的数据类型处理余额信息。

交易历史

/info/user_transactions 端点提供了一种查询特定用户交易活动历史记录的途径。通过调用此端点，可以检索与该用户账户相关的各种交易详情，例如买入、卖出、转账、充值和提现等。此功能对于用户追踪其交易行为、进行财务分析以及审计交易记录至关重要。

调用 /info/user_transactions 端点通常需要身份验证，以确保只有授权用户才能访问其自身的交易历史。身份验证机制可能涉及使用 API 密钥、JSON Web Tokens (JWT) 或其他安全凭证。请求可能还需要包含查询参数，例如时间范围（起始日期和结束日期）、交易类型（例如，仅显示买入交易）或交易状态（例如，成功、失败、待处理）。这些参数允许用户根据特定需求过滤和检索交易记录。

返回的数据通常以 JSON 格式呈现，包含每个交易的详细信息。这些详细信息可能包括：

• 交易ID: 唯一标识符，用于追踪特定交易。
• 交易类型: 说明交易的性质，例如“买入”、“卖出”、“充值”、“提现”或“转账”。
• 交易时间戳: 记录交易发生的准确时间。
• 交易金额: 交易涉及的加密货币或法币的数量。
• 交易费用: 与交易相关的费用。
• 交易状态: 指示交易的当前状态，例如“成功”、“失败”、“待处理”或“已取消”。
• 相关资产: 交易涉及的加密货币或法币的符号或名称。
• 交易对手: 如果是转账交易，则显示接收方或发送方的账户信息。
• 交易哈希: 区块链上交易的唯一标识符（如果适用）。

正确使用 /info/user_transactions 端点对于构建透明且用户友好的加密货币平台至关重要。它允许用户全面了解其交易活动，并有助于确保平台内的合规性和问责制。

参数：

• currency : 货币类型。指定要查询交易记录的加密货币类型。例如， BTC 代表比特币， ETH 代表以太坊， KRW 代表韩元（或其他法币）。该参数区分大小写，请确保输入正确的货币代码。
• offset : 分页偏移量。用于分页查询，从指定偏移量开始返回记录。默认为 0 ，表示从第一条记录开始。如果需要获取后续页面的数据，请增加此值。例如，如果已经获取了前20条记录，则将 offset 设置为 20 可以获取接下来的20条记录。
• count : 返回的记录数量。指定每次API调用返回的交易记录条数。默认为 20 ，最大值为 100 。可以根据实际需求调整此值。如果需要获取大量数据，建议多次调用API并使用 offset 参数进行分页。请注意，请求过多数据可能会导致API调用频率限制。
• searchGb : 搜索类型。指定要筛选的交易类型。
  • 0 : 全部。返回所有类型的交易记录，包括买入、卖出、充值和提现。
  • 1 : 买入。仅返回买入类型的交易记录。
  • 2 : 卖出。仅返回卖出类型的交易记录。
  • 3 : 充值。仅返回充值类型的交易记录。
  • 4 : 提现。仅返回提现类型的交易记录。
  该参数允许用户根据交易类型进行精细化查询。

响应：

API响应包含以下关键字段，用于提供交易历史的详细信息：

• status : 请求状态码，指示API请求是否成功完成。例如， 0000 通常表示操作成功，其他代码则可能表示错误或警告。 客户端应用程序应根据此字段判断是否需要进行重试或错误处理。具体错误码的含义需要参考API文档。
• data : 包含交易历史记录的数组，每个元素代表一笔交易。数组中的每一项都包含以下与交易相关的详细信息：
  • transaction_date : 交易时间，通常以ISO 8601格式（例如： YYYY-MM-DDTHH:mm:ssZ ）表示。 精确的时间戳对于审计和历史数据分析至关重要。
  • type : 交易类型，区分买入和卖出操作。 ask 代表卖出（出售加密货币）， bid 代表买入（购买加密货币）。 这有助于快速识别交易方向。
  • units_traded : 交易数量，表示买入或卖出的加密货币的数量。 例如，如果交易的是比特币，则此值可能表示交易的比特币数量，精确到小数点后几位。
  • price : 交易价格，表示每单位加密货币的交易价格。 该价格通常以某种法定货币（如美元或人民币）或其他加密货币表示。
  • total : 总金额，表示交易的总价值，计算方式为 units_traded 乘以 price 。 这是交易的最终价值，不包括手续费。
  • fee : 手续费，表示交易过程中产生的费用。 手续费可能以固定金额或交易总额的百分比表示。 了解手续费对于计算实际利润和成本至关重要。

示例：获取比特币 (BTC) 交易历史记录

本示例展示了如何通过API接口获取用户的比特币 (BTC) 交易历史记录。该接口允许开发者查询特定用户的交易活动，从而实现交易追踪、数据分析等功能。

请求方式： POST

接口地址： /info/user_transactions

请求参数 (Payload):

currency=BTC&count=50

参数说明：

• currency ：指定要查询的加密货币类型，此处为 BTC (比特币)。API可能支持其他加密货币，如ETH (以太坊)、LTC (莱特币)等。
• count ：指定要返回的交易记录数量。此处设置为 50 ，表示返回最近的50条交易记录。根据实际需求，可以调整此数值，但通常存在上限，以避免服务器负载过高。

请求示例说明：

上述Payload表示请求获取用户的比特币 (BTC) 交易记录，最多返回50条。服务器收到请求后，将验证用户身份和权限，然后从数据库或其他数据源检索相应的交易记录，并以JSON或其他格式返回给客户端。

交易 API (Private API)

交易 API (也称为私有 API) 允许用户执行包括但不限于下单、修改订单、取消订单以及查询订单状态等操作。这些 API 接口提供了对用户交易账户的直接访问，因此需要进行严格的身份验证，以确保账户安全和操作的合法性。身份验证通常涉及 API 密钥、签名或其他安全机制，以验证用户的身份并授权其访问权限。为保障交易的安全性，通常会实施速率限制，以防止恶意请求和系统滥用。交易 API 的使用需要谨慎，并充分理解相关的风险和安全措施。

下单

/trade/place 端点是执行交易操作的关键接口，用于在交易所系统中提交新的订单请求。通过此端点，用户可以指定交易对、买卖方向、订单类型、价格和数量等参数，从而实现自动化交易或手动交易。

该端点通常需要身份验证，以确保只有授权用户才能进行下单操作。身份验证方式可能包括API密钥、签名等。在发送请求时，必须包含有效的身份验证信息，否则请求会被拒绝。

订单类型包括限价单、市价单、止损单等。限价单允许用户指定一个期望的价格，只有当市场价格达到或超过该价格时，订单才会被执行。市价单会立即以当前市场最优价格成交。止损单则是在市场价格达到预设的止损价格时触发，用于限制潜在损失。

下单请求中还需要指定交易对，例如 BTC/USDT ，表示比特币兑换USDT。数量则表示要交易的数字货币的数量。买卖方向则指定是买入还是卖出。不同的交易所可能对参数的命名和格式有不同的要求，因此在使用前需要仔细阅读API文档。

成功下单后，交易所会返回一个订单ID，用于跟踪订单的状态。用户可以使用该ID查询订单的成交情况、是否已撤销等信息。下单过程中可能会出现各种错误，例如余额不足、价格超出限制等，交易所会在响应中返回错误代码和错误信息，方便用户进行调试。

参数：

• order_currency : 交易货币类型。指用户希望买入或卖出的数字资产的币种代码，例如： BTC 代表比特币。务必确保此参数与交易所支持的交易对相匹配。
• payment_currency : 结算货币类型。指用户用于购买或接收数字资产的法币或加密货币的币种代码，例如： KRW 代表韩元。这决定了交易的计价单位。
• units : 交易数量。指用户希望买入或卖出的数字资产的数量。该数值必须大于交易所允许的最小交易单位，并符合交易所规定的精度要求。例如，如果最小交易单位为 0.0001 BTC，则 units 必须大于等于 0.0001。
• price : 交易价格 (仅限指定价格交易)。指用户希望买入或卖出的数字资产的单价。仅在 side 参数设置为 limit 时有效。指定的价格必须在交易所允许的价格范围内，并考虑市场深度和波动性。
• type : 交易类型。指定交易的意图， bid 表示买入，即用户希望以指定价格购买 order_currency ； ask 表示卖出，即用户希望以指定价格出售 order_currency 。
• side : 订单类型。指定订单的执行方式， limit 表示指定价格交易，订单将以指定的价格或更好的价格成交； market 表示市价交易，订单将以当前市场最优价格立即成交。使用市价交易时，无需指定 price 参数。

响应：

响应包含以下字段，用于指示请求处理的结果以及返回的相关数据。

• status : 请求状态码，用于标识请求是否成功完成。例如，状态码 0000 通常表示请求已成功处理。其他状态码可能指示不同的错误或状态，具体含义需要参考 API 的文档说明。客户端应用程序应根据此字段的值来判断请求是否成功，并采取相应的处理措施。
• data : 包含订单信息的对象。此对象包含与订单相关的各种详细信息，方便客户端应用程序使用。如果 status 指示请求成功，则此对象应包含有效数据；否则，此对象可能为空或包含错误信息。
  • order_id : 订单 ID，是系统中唯一标识订单的字符串。客户端应用程序可以使用此 ID 来跟踪订单状态、查询订单详情或进行其他与订单相关的操作。该ID通常由服务端生成。

示例：

提交限价买单，以指定价格购买比特币（BTC）：

POST /trade/place

请求参数（Payload）：

order_currency=BTC&payment_currency=KRW&units=0.01&price=50000000&type=bid&side=limit

参数说明：

• order_currency : 指定要购买的加密货币的币种代码，这里是比特币（BTC）。
• payment_currency : 指定用于支付的法定货币或稳定币的币种代码，这里是韩元（KRW）。
• units : 要购买的加密货币的数量，这里是 0.01 BTC。 务必注意交易平台对最小交易单位的限制，通常需要满足最小交易量才能成功下单。
• price : 指定的价格，以支付货币（KRW）计价。 这里设置的价格是 50,000,000 KRW/BTC。如果市场价格高于此价格，订单将不会立即成交，而是挂在订单簿上等待满足条件的交易对手方。
• type : 订单类型，这里是“bid”，表示买单。
• side : 订单方向，这里是“limit”，表示限价单。 限价单允许您指定希望买入或卖出的价格。 只有当市场价格达到您指定的价格时，您的订单才会执行。

注意事项：

• 在实际使用中，您需要替换示例值为您希望使用的实际数值。
• 确认您账户中有足够的韩元（KRW）余额来支付购买 0.01 BTC 的费用。
• 不同的交易所对于参数名称和具体值的格式可能略有差异，请参考您所使用交易所的官方API文档。
• API调用通常需要进行身份验证，例如添加API Key和签名到请求头中。 请务必妥善保管您的API Key，避免泄露。
• 请注意市场波动风险，下单前仔细评估。

取消订单

/trade/cancel 端点允许用户取消先前提交的挂单。这是一个关键的交易功能，尤其是在市场波动剧烈或交易策略需要调整时。通过调用此端点，您可以撤销尚未成交的订单，避免潜在的损失或抓住新的市场机会。

取消订单操作是异步的，这意味着API调用会立即返回一个确认信息，表明取消请求已收到。然而，订单的实际取消可能需要几秒钟才能在交易平台上生效。您可以通过查询订单状态来确认订单是否已成功取消。如果订单已经成交或正在成交过程中，取消请求可能会失败。

使用 /trade/cancel 端点时，通常需要提供订单ID (order ID) 作为参数。订单ID是交易所分配给每个订单的唯一标识符，用于精确指定要取消的订单。一些交易所可能还允许通过其他参数取消订单，例如客户订单ID (client order ID)，这允许您使用自己的ID来跟踪订单。

正确处理取消订单的响应非常重要。API响应通常会包含一个状态代码，指示取消请求是否成功。如果请求失败，响应会提供详细的错误信息，帮助您诊断问题并采取纠正措施。常见的错误包括订单不存在、订单已经成交、或者您的账户没有足够的权限取消订单。

在自动化交易系统中，取消订单是一个常见的操作。例如，如果价格没有达到预期的水平，或者市场情况发生变化，您可能需要取消挂单。合理地使用 /trade/cancel 端点可以提高交易效率并降低风险。

参数：

• type : 订单类型。此参数定义了订单的方向，即您希望是买入（bid）还是卖出（ask）资产。 bid 表示买入订单，即您希望以指定价格购买一定数量的加密货币； ask 表示卖出订单，即您希望以指定价格出售您持有的加密货币。理解订单类型是进行交易的基础，确保您选择了正确的类型以满足您的交易目标。
• order_id : 订单 ID。这是一个唯一的标识符，用于在交易系统中追踪和管理您的订单。每个订单都会被分配一个独一无二的 ID，您可以使用此 ID 查询订单的状态、修改订单或取消订单。订单 ID 对于调试交易问题和确保交易的正确执行至关重要。请妥善保存您的订单 ID，以便在需要时进行参考。

响应：

API响应中包含用于指示请求处理结果的关键字段。这些字段提供了关于请求是否成功以及相关数据的详细信息。

• status : 用于指示请求处理状态的数值代码。例如， 0000 通常表示请求已成功完成。其他状态码可能表示错误、警告或其他特定情况。 详细的状态码定义请参考API文档。
• data : 包含响应数据的字段。其具体内容取决于请求的类型和操作。 对于取消操作， true 值表示取消操作已成功执行。该字段的数据类型和结构会根据API接口的不同而有所差异，可能包含更复杂的数据结构，比如JSON对象或数组。

示例：取消BTC购买订单

取消比特币（BTC）购买订单示例，此操作用于撤销尚未完全成交的买单。

POST /trade/cancel

请求方法： POST ，用于向服务器发送取消订单的请求。

请求路径： /trade/cancel ，指定了取消订单的API端点。

Payload（请求体）：

type=bid&order_id=1234567890

请求参数说明：

• type ：订单类型，此处为 bid ，表示购买订单 (也可能为 ask ，代表出售订单)。
• order_id ：要取消的订单ID，此处为 1234567890 。 订单ID是交易所用于唯一标识每个订单的数字或字符串。

注意：实际API调用可能需要身份验证信息，例如API密钥和签名，这些信息通常包含在请求头中，具体取决于交易所的API安全策略。 请参考交易所的API文档以获取完整的身份验证要求。

示例：假设您的账户中有一个ID为 1234567890 的比特币购买订单尚未完全成交。您可以使用上述请求取消此订单，阻止其进一步成交。

订单详情

/info/orders 接口用于获取特定订单的详细信息。此接口允许用户或系统管理员检索关于特定订单的全面数据，包括订单创建时间、订单状态、订单中包含的商品或服务、支付信息以及任何相关的交易哈希值。正确使用此接口需要提供有效的订单ID作为参数。

通过该接口返回的信息通常包含以下关键字段：

• 订单ID (Order ID): 订单的唯一标识符，用于在系统中追踪和识别订单。
• 订单状态 (Order Status): 指示订单当前所处的状态，例如“已创建”、“待支付”、“已支付”、“已发货”、“已完成”、“已取消”等。不同的状态对应订单处理流程中的不同阶段。
• 创建时间 (Creation Time): 订单创建的时间戳，通常采用UTC时间格式。
• 支付方式 (Payment Method): 用户选择的支付方式，例如信用卡、借记卡、加密货币（如比特币、以太坊等）。
• 支付状态 (Payment Status): 指示支付是否成功，例如“待支付”、“已支付”、“支付失败”、“已退款”等。
• 商品/服务列表 (Item List): 订单中包含的商品或服务列表，包括每个商品或服务的名称、数量、单价和总价。
• 总金额 (Total Amount): 订单的总金额，包括商品/服务的价格、运费、税费等。
• 交易哈希 (Transaction Hash): 如果订单涉及到加密货币支付，则包含相关的交易哈希值，用于在区块链上验证交易。
• 收货地址 (Shipping Address): 如果订单需要发货，则包含收货人的姓名、地址、电话号码等信息。
• 订单备注 (Order Notes): 用户或系统管理员添加的备注信息，例如特殊要求、问题说明等。

在实际应用中，使用此接口需要进行身份验证和授权，以确保只有授权用户才能访问订单信息。为了保护用户隐私和数据安全，应采取必要的安全措施，例如使用HTTPS协议、对敏感数据进行加密存储和传输等。

错误处理

Bithumb REST API 利用 HTTP 状态码和自定义错误代码来传达请求执行的结果。开发者应仔细评估这些代码和相关的错误消息，以确保应用程序能够稳健地处理各种场景。以下列出一些常见的状态码及其含义：

• 0000 : 成功。表示 API 请求已成功处理并返回了预期结果。
• 5100 : 需要 API 密钥。表明请求缺少必要的 API 密钥认证信息。开发者应检查请求头或参数中是否正确包含了有效的 API 密钥。
• 5200 : 无效的 API 密钥。表示提供的 API 密钥无效或已过期。开发者应验证 API 密钥的正确性，并确保其处于活动状态。
• 5300 : 不允许的 IP 地址。指示发起请求的 IP 地址未被授权访问该 API。开发者需要将其 IP 地址添加到 Bithumb 平台的授权列表中。
• 5900 : 不支持的货币类型。表明请求中指定的货币类型不受支持。开发者应检查请求参数，并确保使用 Bithumb API 支持的有效货币代码。
• 5902 : 超过最大请求数量。表示在给定时间段内，API 请求数量超过了允许的最大限制。开发者应实施速率限制策略，以避免超过 API 的调用限制。
• 5903 : 禁止访问。表明由于某种原因，当前用户或应用程序被禁止访问该 API。这可能是由于违反了服务条款或其他安全策略。
• 5909 : 未找到。指示请求的资源不存在或无法找到。开发者应检查请求的 URL 和参数，确保其正确无误。
• 5600 : 交易错误。表示在执行交易时发生了错误。开发者应检查交易参数，例如数量、价格等，并确保其满足交易规则。详细的错误信息通常会包含在响应消息中，以便开发者进行排查。

为了确保应用程序的稳定性和可靠性，开发者必须根据返回的状态码和响应信息采取适当的错误处理措施。例如，当收到需要 API 密钥的错误时，应提示用户提供有效的 API 密钥；当超过最大请求数量时，应实施退避策略并稍后重试；当发生交易错误时，应记录详细的错误信息并通知用户。通过周密的错误处理，可以最大限度地减少 API 集成的潜在问题。