掌握Upbit API：10分钟构建你的专属量化交易策略！

时间：2025-03-06 03:45:05 阅读：29

Upbit 平台 API 接口支持详解

Upbit 是韩国领先的加密货币交易所，为开发者提供了强大的 API 接口，允许他们以编程方式访问平台上的各种功能，例如交易、市场数据、账户管理等。理解和有效利用这些 API 接口，对于开发交易机器人、数据分析工具以及集成 Upbit 功能到第三方应用至关重要。

API 接口概览

Upbit API 接口主要分为以下几个类别，每个类别都提供了丰富的功能，以满足不同用户的需求：

  • 市场 API (Market API): 提供全面且深入的实时和历史市场数据服务。 这包括详细的交易对信息（如交易代码、交易对名称、最小交易单位等）、最新的成交价格、成交量（包括最近24小时成交量、累计成交量等）、以及深度订单簿信息（买单和卖单的挂单价格和数量），便于用户进行精确的市场分析和决策。 用户可以通过此API获取特定时间段内的历史K线数据、逐笔成交记录等。
  • 交易 API (Trade API): 允许用户执行包括创建订单（限价单、市价单等）、取消未成交订单、修改订单价格或数量、以及查询订单状态等所有交易相关操作。用户可以通过此API自动化交易策略，高效管理交易活动。 此API通常需要身份验证，以确保交易安全。
  • 账户 API (Account API): 允许用户安全地查询其Upbit账户的各种信息，例如账户余额（包括可用余额和冻结余额）、详细的交易历史记录（包括成交时间、成交价格、成交数量、手续费等）、以及锁定资产信息（例如，在进行中的订单中锁定的资产）。 此API通常需要严格的身份验证和权限控制，以保障用户账户的安全。
  • WebSocket API: 提供低延迟、高效率的实时数据流服务。 通过WebSocket连接，用户可以实时接收成交价格更新、实时订单簿变化、以及其他市场数据的推送，无需频繁请求API，从而更快地响应市场变化。 WebSocket API 非常适合对实时性要求高的交易策略，例如高频交易、套利交易等。

身份验证与权限

在使用 Upbit API 接口之前，必须进行严格的身份验证。Upbit 采用行业标准的 JWT (JSON Web Token) 作为其身份验证的核心机制。这种机制确保只有经过授权的用户才能访问API资源。要启动身份验证流程，开发者需要在 Upbit 平台上创建独特的 API 密钥对，其中包含两个关键组件：Access Key 和 Secret Key。Access Key 扮演着用户的身份标识符的角色，而 Secret Key 则用于对 API 请求进行数字签名，从而保障请求的完整性和真实性，防止恶意篡改。

API 密钥的安全性至关重要。在使用 API 密钥时，开发者必须采取一切必要措施来妥善保管 Secret Key，避免泄露给未经授权的第三方。一旦 Secret Key 泄露，恶意攻击者可能会利用它来冒充您的身份，从而对您的 Upbit 账户进行非法操作，例如未经授权的交易或敏感数据访问，导致严重的经济损失和安全风险。最佳实践包括使用安全的密钥管理系统、定期轮换密钥以及避免将密钥硬编码到应用程序代码中。

Upbit API 接口实施精细化的权限控制机制，进一步增强安全性。在创建 API 密钥时，开发者需要根据实际需求仔细选择所需的权限范围。例如，如果应用程序仅需要查询实时的市场数据，则完全不需要勾选任何与交易相关的权限。采用最小权限原则，即仅授予应用程序所需的最小权限集，能够显著降低潜在的安全风险。即使 API 密钥被泄露，攻击者也只能执行有限的操作，从而将损害降到最低。

市场 API 接口

查询市场代码

GET /market/all

此接口旨在提供 Upbit 交易所所有可交易市场代码的完整清单。通过发送一个简单的 GET 请求到 /market/all 端点，您可以获取详细的市场信息。返回的数据结构是一个 JSON 数组，其中每个元素代表一个可交易的市场。每个市场对象都包含以下关键属性，方便您进行数据解析和利用。

返回的 JSON 数组中，每个对象包含以下字段：

  • market : 这是一个字符串，表示唯一的市场代码，例如 "KRW-BTC"。市场代码遵循一定的命名规则，通常由两个部分组成，分别代表报价货币和基础货币。例如，"KRW-BTC" 表示用韩元（KRW）报价的比特币（BTC）市场。
  • korean_name : 这是一个字符串，表示市场在韩语中的名称。例如，"비트코인" 代表比特币。此字段主要面向韩语用户，方便他们识别和搜索特定的加密货币市场。
  • english_name : 这是一个字符串，表示市场在英语中的名称。例如，"Bitcoin" 代表比特币。此字段为国际用户提供通用的市场名称，有助于消除语言障碍。
  • market_warning : （可选）这是一个字符串，表示市场的警告级别。可能的值包括 NONE （无警告）、 CAUTION （注意）或 DANGER （危险）。如果存在警告，请务必谨慎交易。

重要提示： 请注意，市场代码的可用性和相关信息可能会根据 Upbit 交易所的政策和市场情况进行调整。建议您定期查询此接口，以获取最新的市场代码列表。在进行任何交易之前，请仔细阅读 Upbit 交易所的相关条款和风险提示。

示例：

[ { "market": "KRW-BTC", "korean_name": "비트코인", "english_name": "Bitcoin", "market_warning": "NONE" }, { "market": "KRW-ETH", "korean_name": "이더리움", "english_name": "Ethereum", "market_warning": "NONE" }, { "market": "BTC-LTC", "korean_name": "라이트코인", "english_name": "Litecoin", "market_warning": "NONE" } ]

查询最新成交价

GET /ticker

该接口用于查询指定加密货币交易市场的最新成交价格信息。支持同时查询多个市场代码，市场代码之间使用英文逗号分隔，以此提高数据获取效率。

请求参数：

  • markets (必选): 指定需要查询的市场代码，多个市场代码用英文逗号分隔。例如： KRW-BTC,KRW-ETH,USDT-XRP 。市场代码通常由交易对的计价货币和标的货币组成。

示例：

GET /ticker?markets=KRW-BTC,KRW-ETH

此请求将查询韩元计价的比特币 (KRW-BTC) 和韩元计价的以太坊 (KRW-ETH) 的最新成交价格。

返回结果：

返回结果是一个 JSON 数组，每个元素代表一个市场代码的最新成交价信息。数组中的每个对象包含以下字段： 

[
  {
    "market": "KRW-BTC",
    "trade_date": "20231027",
    "trade_time": "102030",
    "trade_price": 40000000,
    "trade_volume": 0.01,
    "ask_bid": "ASK",
    "prev_closing_price": 39000000,
    "change": "RISE",
    "change_price": 1000000,
    "signed_change_price": 1000000,
    "change_rate": 0.0256410256,
    "signed_change_rate": 0.0256410256,
    "high_price": 40500000,
    "low_price": 38500000,
    "trade_timestamp": 1698382830000,
    "acc_trade_price": 10000000000,
    "acc_trade_volume": 250,
    "highest_52_week_price": 50000000,
    "highest_52_week_date": "2023-05-01",
    "lowest_52_week_price": 20000000,
    "lowest_52_week_date": "2022-12-25",
    "timestamp": 1698382830000
  }
]

字段说明：

  • market : 市场代码 (例如: KRW-BTC)。
  • trade_date : 最近交易日期 (YYYYMMDD 格式)。
  • trade_time : 最近交易时间 (HHMMSS 格式)。
  • trade_price : 最新成交价格。
  • trade_volume : 最新成交量。
  • ask_bid : 卖单/买单类型 (ASK: 卖单, BID: 买单)。
  • prev_closing_price : 前日收盘价。
  • change : 价格变动类型 (RISE: 上涨, FALL: 下跌, EVEN: 不变)。
  • change_price : 价格变动绝对值。
  • signed_change_price : 带符号的价格变动绝对值 (上涨为正, 下跌为负)。
  • change_rate : 价格变动百分比。
  • signed_change_rate : 带符号的价格变动百分比 (上涨为正, 下跌为负)。
  • high_price : 当日最高价。
  • low_price : 当日最低价。
  • trade_timestamp : 最新交易时间戳 (Unix 时间戳，毫秒)。
  • acc_trade_price : 累计成交总额。
  • acc_trade_volume : 累计成交量。
  • highest_52_week_price : 52 周最高价。
  • highest_52_week_date : 52 周最高价日期 (YYYY-MM-DD 格式)。
  • lowest_52_week_price : 52 周最低价。
  • lowest_52_week_date : 52 周最低价日期 (YYYY-MM-DD 格式)。
  • timestamp : 服务器时间戳 (Unix 时间戳，毫秒)。

错误处理：

如果请求失败，服务器将返回相应的 HTTP 错误代码和错误信息。 常见的错误包括：

  • 400 Bad Request: 请求参数错误，例如 `markets` 参数缺失或格式不正确。
  • 404 Not Found: 指定的市场代码不存在。
  • 500 Internal Server Error: 服务器内部错误。

注意事项：

  • 请务必检查 `markets` 参数的格式是否正确，市场代码是否有效。
  • 接口返回的数据是实时数据，但由于网络延迟等因素，可能存在一定的延迟。
  • 建议缓存接口返回的数据，避免频繁请求。

查询订单簿信息

GET /orderbook

该接口允许用户查询指定市场代码的订单簿信息。订单簿是任何交易平台的核心组成部分，它实时记录了当前市场上所有买单（bid）和卖单（ask）的价格和数量。通过该接口，用户可以获取指定交易对的实时市场深度数据，从而更好地了解市场供需关系。

可以一次性查询多个市场代码的订单簿信息，市场代码之间使用英文逗号分隔。市场代码通常由两个部分组成：交易货币和计价货币，例如 KRW-BTC 表示使用韩元（KRW）购买比特币（BTC）。支持批量查询可以简化数据获取过程，提高效率，特别是在需要同时监控多个市场动态的情况下。

示例：

GET /orderbook?markets=KRW-BTC,KRW-ETH

上述示例请求将返回韩元比特币交易对（ KRW-BTC ）和韩元以太坊交易对（ KRW-ETH ）的订单簿信息。通过分析这两个市场的订单簿数据，用户可以对比特币和以太坊在韩国市场的供需情况进行评估。

返回结果包含买单（Bid Orders）和卖单（Ask Orders）的深度信息。买单代表用户希望以特定价格购买资产的订单，卖单则代表用户希望以特定价格出售资产的订单。深度信息通常包括多个档位的价格和数量，例如，最高买入价和相应的买入量，最低卖出价和相应的卖出量。这些数据对于进行技术分析、制定交易策略至关重要，也有助于识别潜在的市场支撑位和阻力位。

交易 API 接口

下单

POST /orders

该接口用于提交交易订单。用户需提供市场代码（market）、交易方向（side）、订单数量（volume）、价格（price）以及订单类型（ord_type）等关键信息。 市场代码指定交易的市场，如 KRW-BTC 代表韩元对比特币市场。 交易方向 side 指定买入（bid）或卖出（ask）。订单数量 volume 定义了交易的加密货币数量，需要根据交易所精度进行调整。价格 price 则根据订单类型进行解读，在限价单中代表期望成交的价格。

订单类型 ord_type 支持多种形式，包括：

  • 市价单（market）： 以当前市场最优价格立即成交，只需指定交易数量 volume ，无需指定价格 price 。
  • 限价单（limit）： 指定交易价格 price ，只有当市场价格达到或优于指定价格时才会成交。
  • 止损单（stop_loss）： 当市场价格达到预设的止损价时，系统自动以市价单进行交易，用于控制潜在损失。 需要配置触发价格。
  • 止损限价单（stop_limit）： 当市场价格达到预设的止损价时，系统自动挂出限价单。需要配置触发价格和限价单价格。

下单请求的参数必须符合交易所的规范，例如数量精度和价格精度，否则可能导致下单失败。请务必参考API文档获取详细的参数说明。

示例：

{ "market": "KRW-BTC", "side": "bid", "volume": "0.001", "price": "39000000", "ord_type": "limit" }

该示例表示在 KRW-BTC 市场，以3900万韩元的价格，买入0.001个比特币，并且采用的是限价单。

请注意，实际的API调用可能需要身份验证（例如，使用API密钥）和其他安全措施。具体的安全措施和身份验证方式请参考交易所的API文档。

撤单

DELETE /order

该接口用于撤销指定订单。通过发送 DELETE 请求至 /order 路由实现订单撤销功能。 为保证操作的准确性，务必在请求中包含需要撤销订单的唯一识别符，即订单 UUID（Universally Unique Identifier）。

订单 UUID 是一个128位的标识符，用于在系统中唯一标识一个订单。 通常情况下，该 UUID 在创建订单时由系统生成并返回给用户，用户需要妥善保存该 UUID 以便后续进行订单查询、修改或撤销等操作。 未提供有效的订单 UUID 将导致撤单请求失败。

在发起撤单请求前，请确保您已仔细核对订单 UUID 的准确性。 错误的 UUID 可能导致撤销其他订单，造成不必要的损失。 系统通常会进行权限验证，确保请求用户有权撤销该订单。

请求示例： 


DELETE /order?order_uuid=a1b2c3d4-e5f6-7890-1234-567890abcdef

注意事项：

  • 部分交易平台可能对撤单操作存在时间限制。 例如，在订单完全成交前的一段时间内允许撤单，超过该时间则不允许撤单。
  • 在市场波动剧烈的情况下，撤单请求可能无法立即执行，存在一定的延迟。
  • 成功的撤单请求通常会返回一个状态码 200 OK ， 并包含撤单成功的相关信息。 如果撤单失败，则会返回相应的错误码和错误信息，例如 400 Bad Request (无效的订单 UUID) 或 403 Forbidden (无权撤销该订单)。

查询订单

GET /order

该接口用于查询特定订单的详细信息。为了成功检索订单，您需要提供唯一的订单 UUID（通用唯一识别码）。UUID 是一个 128 位的标识符，旨在保证在分布式系统中创建信息的唯一性，确保能够准确地定位和获取您所请求的订单数据。订单 UUID 通常在订单创建成功后返回，请妥善保管此 UUID，以便后续查询订单状态或详情。通过提供订单 UUID，系统能够精确定位并返回与该订单关联的所有信息，例如订单状态、商品明细、支付信息、物流跟踪等。请确保您提供的 UUID 准确无误，避免因 UUID 错误导致查询失败。

账户 API 接口

查询账户余额

GET /accounts

该接口用于查询账户余额。它提供了一个全面的视图，展示用户在平台上的所有币种的可用余额、锁定余额以及平均买入价格等关键信息。返回结果是一个JSON数组，数组中的每个元素代表一种币种的余额信息。

请求方法： GET

请求路径： /accounts

请求参数： 无

响应格式： JSON

响应字段说明：

  • currency : 币种代码 (例如, KRW, BTC, ETH)。
  • balance : 可用余额，表示该币种当前可以使用的数量。
  • locked : 锁定余额，表示该币种当前被锁定无法使用的数量 (例如，用于挂单交易)。
  • avg_buy_price : 平均买入价格，指持有该币种的平均成本价格，以计价货币 ( unit_currency ) 计价。
  • avg_buy_price_modified : 平均买入价格是否被修改过，用于标记平均买入价格是否由于某些特殊原因（例如，拆分、合并）而被手动调整过。 true 表示被修改过， false 表示未被修改。
  • unit_currency : 计价货币代码，表示平均买入价格所使用的货币单位 (例如，KRW)。

示例：

[
{
"currency": "KRW",
"balance": "1000000",
"locked": "0",
"avg_buy_price": "0",
"avg_buy_price_modified": false,
"unit_currency": "KRW"
},
{
"currency": "BTC",
"balance": "0.005",
"locked": "0",
"avg_buy_price": "40000000",
"avg_buy_price_modified": false,
"unit_currency": "KRW"
}
]

示例说明：

上述示例展示了用户账户中韩元 (KRW) 和比特币 (BTC) 的余额信息。用户拥有 1,000,000 KRW 可用余额，没有锁定余额。同时，用户拥有 0.005 BTC 可用余额，也没有锁定余额。BTC 的平均买入价格为 40,000,000 KRW。

WebSocket API

Upbit 交易所提供 WebSocket API，旨在为用户提供高效、实时的市场数据流服务。相较于传统的 REST API 轮询方式，WebSocket API 采用双向通信协议，允许服务器主动推送数据至客户端，从而显著降低延迟，提供更接近实时的市场信息。

通过 WebSocket API，用户可以订阅多种实时数据类型，包括但不限于：最新的成交价格（交易价格）、实时更新的订单簿信息（买单和卖单的深度数据）、交易量统计、以及其他市场相关的关键指标。这些数据对于高频交易者、量化交易团队和需要快速响应市场变化的投资者至关重要。

与传统的 API 接口轮询相比，使用 WebSocket API 主要优势在于降低服务器压力和提高数据响应速度。轮询 API 需要客户端定期发送请求以获取最新数据，这会增加服务器的负载，并且受到轮询频率的限制，无法保证数据的实时性。而 WebSocket API 建立持久连接后，数据由服务器主动推送，减少了客户端的请求数量，降低了服务器负担，同时也确保了用户可以及时接收到最新的市场数据。

要成功连接 Upbit 的 WebSocket API，需要进行身份验证以确保安全性，并防止未经授权的访问。身份验证通常涉及使用 API 密钥和签名机制。完成身份验证后，用户可以通过发送订阅消息来指定需要接收的数据类型和对应的市场代码（例如，BTC/KRW、ETH/BTC 等）。订阅消息通常采用 JSON 格式，包含指定数据类型和市场代码的参数。

错误处理

Upbit API 接口在交互过程中会返回各种错误代码，这些错误代码是开发者诊断和解决问题的关键依据。为了确保应用程序的稳定性和可靠性，开发者必须针对不同的错误代码实施相应的处理策略，包括但不限于重试机制、详细的错误日志记录以及针对特定错误的应对措施。准确理解和处理这些错误代码是构建健壮Upbit API应用的基础。

以下列出一些常见的Upbit API错误代码及其含义，以及开发者应采取的应对策略：

  • 400 Bad Request : 此错误表示客户端发送的请求包含无效的参数。这意味着请求的格式不正确，或者某些必需的参数缺失或无效。开发者应仔细检查请求参数，确保其符合API文档的要求。例如，检查参数的数据类型、取值范围和格式是否正确。
  • 401 Unauthorized : 此错误表明客户端提供的身份验证信息无效。通常，这意味着API密钥不正确或已过期，或者请求中缺少必要的身份验证标头。开发者应验证API密钥的有效性，并确保所有请求都包含正确的身份验证信息。请注意，Upbit API使用特定的身份验证机制，开发者需要仔细阅读API文档并正确配置身份验证。
  • 429 Too Many Requests : 此错误表示客户端在短时间内发送了过多的请求，触发了Upbit的请求频率限制（也称为限流）。为了避免此错误，开发者应实施请求频率控制机制，例如使用令牌桶算法或漏桶算法来限制API请求的发送速率。开发者应仔细阅读Upbit API文档，了解具体的请求频率限制，并根据实际情况调整应用程序的请求频率。开发者可以考虑使用指数退避策略进行重试，以避免在短时间内再次触发限流。
  • 500 Internal Server Error : 此错误表明Upbit服务器在处理请求时遇到了内部错误。这通常是服务器端的问题，客户端无法直接解决。在这种情况下，开发者应记录错误信息，并稍后重试请求。如果错误持续发生，开发者应联系Upbit技术支持寻求帮助。服务器内部错误可能由多种原因引起，例如数据库连接问题、代码错误或服务器资源不足。

除了上述错误代码，Upbit API还可能返回其他错误代码。开发者应仔细阅读API文档，了解所有可能的错误代码及其含义，并根据实际情况实施相应的错误处理策略。一个良好的错误处理机制可以显著提高应用程序的稳定性和用户体验。

API 使用注意事项

  • 限流： Upbit API 接口对请求频率设有严格限制，以保障服务器稳定运行。开发者必须谨慎设计应用程序，合理控制API请求的频率，避免瞬间高并发请求，建议采用指数退避算法或令牌桶算法等策略。过度频繁的请求可能导致IP地址被临时或永久封禁，影响业务的正常运行。请务必查阅Upbit官方文档，了解具体的限流规则和最佳实践。
  • 数据安全： 妥善保管API密钥至关重要。API密钥是访问Upbit API接口的唯一凭证，泄露可能导致资金损失或数据泄露。建议将API密钥存储在安全的环境中，如服务器端的环境变量或加密的配置文件，避免直接暴露在客户端代码中。定期更换API密钥也是一种有效的安全措施。启用IP白名单功能，限制API密钥只能从指定的IP地址访问，可以进一步增强安全性。
  • 错误处理： 完善的错误处理机制对于构建健壮的应用程序至关重要。API调用过程中可能会出现各种错误，例如网络连接问题、参数错误、服务器内部错误等。开发者需要捕获API返回的错误信息，并根据不同的错误类型采取相应的处理措施，例如重试、记录日志、向用户显示错误信息等。详细的错误信息可以帮助开发者快速定位和解决问题，提高应用程序的稳定性和可靠性。
  • 数据更新： 加密货币市场数据具有高度实时性。开发者需要定期更新数据，以确保应用程序显示的信息是最新的。不同的API接口的数据更新频率可能不同，例如Tick数据更新频率可能高于Order Book数据。建议根据应用程序的需求，选择合适的API接口和数据更新频率。使用WebSocket API可以实现实时数据推送，避免频繁的轮询请求，提高效率。
  • API 文档： 仔细阅读Upbit官方API文档是使用Upbit API接口的基础。API文档包含了API接口的详细说明，例如接口地址、请求参数、返回数据格式、错误代码等。开发者需要充分理解API文档，才能正确使用API接口，避免出现错误。Upbit官方API文档通常会定期更新，开发者需要关注最新的文档内容，及时了解API接口的变化。

通过合理且安全地使用Upbit API接口，开发者可以构建各种创新的加密货币交易工具和应用，例如量化交易系统、行情分析工具、自动化交易机器人等，从而提升交易效率、优化交易策略，并最终在竞争激烈的市场中获取优势。

相关文章