Upbit API调用详解：数据、交易接口一网打尽

40 2025-02-13 02:42:05

Upbit API 调用教程：解锁韩国第一交易所的数据与交易接口

Upbit 是韩国最大的加密货币交易所之一，拥有庞大的交易量和丰富的交易对。对于希望进行量化交易、数据分析或开发相关应用的开发者来说，掌握 Upbit 的 API 调用至关重要。本文将深入探讨 Upbit API 的各个方面，包括账户认证、常用 API 接口、调用示例以及注意事项，助您快速上手 Upbit API 的使用。

1. Upbit API 概览

Upbit API 是一套强大的工具，旨在为开发者提供全面的加密货币交易和管理功能。它涵盖了以下几个核心领域，并提供了精细化的数据访问和控制能力：

行情数据 (Market Data): 提供实时的、历史的以及统计性的市场数据。这包括但不限于：
- 最新成交价格 (Last Traded Price)：当前市场上的最新成交价格。
- 交易量 (Volume)：指定时间段内的交易总量，可以按分钟、小时、天等粒度查询。
- 订单簿深度 (Order Book Depth)：买单和卖单的挂单情况，揭示市场的供需关系。
- 最高价和最低价 (Highest and Lowest Price)：指定时间段内的最高和最低成交价格。
- 开盘价和收盘价 (Open and Close Price)：指定时间段内的开盘和收盘价格。
- 实时Tick数据：详细的每笔成交记录，包括成交时间、价格和数量。
账户信息 (Account Information): 允许用户查询与其Upbit账户相关的各种信息，例如：
- 账户余额 (Account Balance)：各种加密货币和法定货币的余额。
- 交易历史 (Trade History)：已完成的交易记录，包括交易时间、币种、价格、数量和手续费等详细信息。
- 未成交订单 (Open Orders)：尚未完全成交的订单列表，包括订单类型、价格、数量和状态。
- 资金划转记录：充值和提现的记录，包括时间、金额和状态。
交易下单 (Order Placement): 提供灵活的下单功能，支持各种订单类型：
- 市价单 (Market Order)：以当前市场最优价格立即成交的订单。
- 限价单 (Limit Order)：以指定价格成交的订单，只有当市场价格达到或超过指定价格时才会成交。
- 止损单 (Stop Order)：当市场价格达到指定止损价时，触发市价卖出订单。
- 止损限价单 (Stop Limit Order)：当市场价格达到指定止损价时，触发限价卖出订单。
- 冰山订单：将大额订单拆分成多个小额订单，以减少对市场的影响。
订单管理 (Order Management): 允许用户管理其未成交订单：
- 查询订单状态 (Order Status)：查询指定订单的详细状态，例如已成交数量、剩余数量、平均成交价格等。
- 取消未成交订单 (Cancel Open Orders)：取消尚未完全成交的订单。
- 批量取消订单：一次性取消多个订单。

Upbit API 遵循 RESTful 架构原则，这意味着它使用标准的 HTTP 方法（如 GET、POST 和 DELETE）来发送请求并接收响应。API 响应的数据格式主要为 JSON (JavaScript Object Notation)，这是一种轻量级的数据交换格式，易于解析和处理。为了安全地访问 API，通常需要使用 API 密钥和身份验证机制，例如 JWT (JSON Web Token) 或 OAuth 2.0。

2. 账户认证与 API 密钥获取

使用 Upbit API 之前，必须拥有一个已完成身份验证的 Upbit 账户。身份验证完成后，即可在 Upbit 平台生成专属的 API 密钥，用于安全地访问和操作您的账户数据。

登录 Upbit 账户: 访问 Upbit 官方网站 (upbit.com) 并使用您的账户凭据进行登录。请确保使用安全的网络环境，并启用双重验证以增强账户安全性。
定位至 API 管理页面: 登录后，在账户设置或个人资料页面中查找 "Open API 管理"、"API 密钥" 或类似命名的选项。不同时期 Upbit 界面可能略有差异，但通常位于安全设置或开发者选项下。进入该页面，以开始 API 密钥的创建流程。
创建 API 密钥: 在 API 管理页面，根据页面提示创建新的 API 密钥。创建过程中，系统可能会要求您提供额外的账户信息或进行安全验证。成功创建后，系统将生成以下两个至关重要的密钥：
- Access Key (访问密钥): 类似于您的账户用户名，用于唯一标识您的 Upbit 账户。所有 API 请求都需要携带此密钥，以便 Upbit 服务器识别请求的来源。请妥善保管此密钥，避免泄露。
- Secret Key (安全密钥): 类似于您的账户密码，用于对您的 API 请求进行签名，确保请求的完整性和安全性。Secret Key 必须严格保密，切勿分享给他人或存储在不安全的地方。一旦泄露，可能导致您的账户遭受未授权访问和资金损失。请务必将其视为高度敏感信息。
API 密钥创建后，请立即妥善保存 Access Key 和 Secret Key。 Upbit 通常只显示 Secret Key 一次，并且不会再次提供。丢失 Secret Key 后，您需要重新生成新的 API 密钥。

重要提示: 请妥善保管您的 Secret Key。不要将它分享给任何人，也不要将其存储在公共代码仓库中。Secret Key 泄露可能导致您的账户被盗用。

3. 常用 API 接口详解

以下是一些常用的 Upbit API 接口，以及它们的用途、请求方法、参数说明和返回数据结构示例。这些接口涵盖了市场数据查询、交易下单、账户信息管理等核心功能，能够满足大多数开发者的需求。

3.1. 行情数据接口

3.1.1. 获取市场行情数据 (Ticker)

此接口用于获取指定交易对的实时行情数据，包括最新成交价、最高价、最低价、成交量等。

API Endpoint: /v1/ticker
请求方法: GET
请求参数:
- markets (必选): 以逗号分隔的交易对代码列表 (例如: KRW-BTC,KRW-ETH)。

返回数据示例:


[
  {
    "market": "KRW-BTC",
    "trade_date": "20231027",
    "trade_time": "103000",
    "trade_date_kst": "20231027",
    "trade_time_kst": "193000",
    "trade_timestamp": 1698402600000,
    "opening_price": 40000000.0,
    "high_price": 40500000.0,
    "low_price": 39800000.0,
    "trade_price": 40200000.0,
    "prev_closing_price": 39900000.0,
    "change": "RISE",
    "change_price": 300000.0,
    "change_rate": 0.007518796992481203,
    "signed_change_price": 300000.0,
    "signed_change_rate": 0.007518796992481203,
    "trade_volume": 10.5,
    "acc_trade_price": 1000000000.0,
    "acc_trade_volume": 25.0,
    "highest_52_week_price": 50000000.0,
    "highest_52_week_date": "2023-01-01",
    "lowest_52_week_price": 30000000.0,
    "lowest_52_week_date": "2022-07-01",
    "timestamp": 1698402600000
  }
]

3.1.2. 获取K线数据 (Candles)

此接口用于获取指定交易对的K线数据，可以指定K线的时间粒度，如分钟、日、周、月等。K线数据对于技术分析至关重要。

API Endpoint: /v1/candles/{unit}
请求方法: GET
请求参数:
- market (必选): 交易对代码 (例如: KRW-BTC)。
- unit (必选): K线时间粒度 (minutes/{minute}, days, weeks, months)。
- minute (可选，仅当 unit 为 minutes 时): 分钟单位 (1, 5, 15, 30, 60, 240)。
- count (可选): 返回K线数量，默认为1，最大为200。
- to (可选): 返回的最后的K线时间 (yyyy-MM-dd'T'HH:mm:ssZ 或 yyyy-MM-dd HH:mm:ss)。

返回数据示例 (日K线):


[
  {
    "market": "KRW-BTC",
    "candle_date_time_utc": "2023-10-26T00:00:00",
    "candle_date_time_kst": "2023-10-26T09:00:00",
    "opening_price": 39500000.0,
    "high_price": 40200000.0,
    "low_price": 39000000.0,
    "trade_price": 39800000.0,
    "timestamp": 1698280800000,
    "candle_acc_trade_price": 5000000000.0,
    "candle_acc_trade_volume": 125.0,
    "unit": 1
  }
]

3.2. 交易接口

3.2.1. 下单 (Orders)

此接口用于提交买单或卖单。需要身份验证 (Authentication) 才能使用。

API Endpoint: /v1/orders
请求方法: POST
请求参数:
- market (必选): 交易对代码 (例如: KRW-BTC)。
- side (必选): 订单类型 (bid: 买单, ask: 卖单)。
- volume (可选): 订单数量 (市价买单时不需要)。
- price (可选): 订单价格 (市价卖单时不需要)。
- ord_type (必选): 订单类型 (limit: 限价单, price: 市价买单, market: 市价卖单)。
- identifier (可选): 订单ID (用于区分订单)。

返回数据示例:


{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "side": "bid",
  "ord_type": "limit",
  "price": "40000000.0",
  "avg_price": "0.0",
  "state": "wait",
  "market": "KRW-BTC",
  "created_at": "2023-10-27T10:00:00+00:00",
  "volume": "0.001",
  "remaining_volume": "0.001",
  "reserved_fee": "8.0",
  "remaining_fee": "8.0",
  "paid_fee": "0.0",
  "locked": "40008.0",
  "executed_volume": "0.0",
  "trades_count": 0
}

3.2.2. 取消订单 (Order)

此接口用于取消未成交的订单。需要身份验证 (Authentication) 才能使用。

API Endpoint: /v1/order
请求方法: DELETE
请求参数:
- uuid (必选): 订单 UUID。或者
- identifier (必选): 订单 identifier。

返回数据示例:


{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "side": "bid",
  "ord_type": "limit",
  "price": "40000000.0",
  "state": "cancel",
  "market": "KRW-BTC",
  "created_at": "2023-10-27T10:00:00+00:00",
  "volume": "0.001",
  "remaining_volume": "0.0",
  "reserved_fee": "0.0",
  "remaining_fee": "0.0",
  "paid_fee": "0.0",
  "locked": "0.0",
  "executed_volume": "0.0",
  "trades_count": 0
}

3.3. 账户接口

3.3.1. 获取账户信息 (Accounts)

此接口用于获取用户的账户余额信息，包括持有的币种、数量等。需要身份验证 (Authentication) 才能使用。

API Endpoint: /v1/accounts
请求方法: GET
请求参数: 无

返回数据示例:


[
  {
    "currency": "KRW",
    "balance": "1000000.0",
    "locked": "0.0",
    "avg_buy_price": "0.0",
    "avg_buy_price_modified": false,
    "unit_currency": "KRW"
  },
  {
    "currency": "BTC",
    "balance": "0.005",
    "locked": "0.0",
    "avg_buy_price": "39000000.0",
    "avg_buy_price_modified": false,
    "unit_currency": "KRW"
  }
]

提示: 在使用交易和账户相关的API接口时，务必先完成API Key的申请，并按照Upbit的API文档进行身份验证。请仔细阅读Upbit的API文档，了解更多接口的详细信息和使用方法，以确保您的交易安全和稳定。

3.1. 获取市场代码 (Market Codes)

接口: GET /v1/market/all
用途: 获取 Upbit 交易所所有可交易的市场代码列表。市场代码是交易对的唯一标识符，由两部分组成：交易市场代码（base currency code）和交易标的代码(target currency code)。例如， KRW-BTC 表示在韩元 (KRW) 市场交易比特币 (BTC)。交易所会提供不同类型的市场，例如法币市场、BTC 市场和 ETH 市场，每种市场都支持不同的加密货币交易对。
参数:
- is_details : (可选) 指示是否返回市场的详细信息。如果设置为 true ，则 API 将返回有关每个市场的额外信息，例如市场名称（market name）和警告信息（warning message，若有）。如果设置为 false （默认值），则仅返回市场代码列表。使用此参数可以更详细地了解每个可交易市场。

示例:

GET 请求 https://api.upbit.com/v1/market/all?is_details=true 用于获取所有交易市场的详细信息。

此 API 端点返回一个 JSON 数组，数组中每个元素代表一个交易市场。每个元素（市场对象）包含多个关键字段，例如：

market : 字符串类型，表示 Upbit 交易所中唯一的市场代码，例如 "KRW-BTC" 。市场代码由交易货币对组成， KRW 代表韩元， BTC 代表比特币。
korean_name : 字符串类型，表示该市场在韩语中的名称，例如 "비트코인" 。
english_name : 字符串类型，表示该市场在英语中的名称，例如 "Bitcoin" 。
market_warning : 字符串类型，表示市场警告类型。可能的值包括 "NONE" (无警告), "CAUTION" (注意), 或 "DANGER" (危险)，反映了Upbit对该市场交易风险的评估。

is_details=true 参数用于请求包含详细信息的市场数据。如果省略此参数或设置为 false ，则返回的信息可能较少，可能只包含 market 和 korean_name 字段。

3.2. 获取蜡烛图数据 (Candle Data)

接口: GET /v1/candles/{unit}
用途: 获取指定加密货币交易对的蜡烛图数据，该数据是进行技术分析的基础。蜡烛图能够清晰地展示一段时间内资产的价格变动情况，包括开盘价、收盘价、最高价和最低价，是交易者常用的分析工具。
参数:
- market : (必需) 市场代码，明确指定需要查询的交易市场。例如， KRW-BTC 代表韩元 (KRW) 计价的比特币 (BTC) 交易对。交易所通常使用特定的代码格式来标识不同的交易市场，务必使用交易所支持的正确代码。
- unit : (必需) 蜡烛图的时间单位，定义了每根蜡烛代表的时间跨度。支持多种时间单位，包括分钟、天、周和月。
  - minutes/{n} : 表示 n 分钟的蜡烛图，其中 n 可以是 1, 3, 5, 15, 30, 60 等整数。例如， minutes/1 表示 1 分钟蜡烛图，每根蜡烛代表 1 分钟内的价格变动。
  - days : 表示天蜡烛图，每根蜡烛代表一天的价格变动。
  - weeks : 表示周蜡烛图，每根蜡烛代表一周的价格变动。
  - months : 表示月蜡烛图，每根蜡烛代表一个月的价格变动。
- to : (可选) 查询的结束时间，允许指定查询的时间范围。时间格式必须符合 API 的要求，通常为 ISO 8601 标准格式，如 YYYY-MM-DDTHH:mm:ssZ (例如： 2023-10-27T10:00:00Z ，UTC时间) 或 YYYY-MM-DD HH:mm:ss (例如： 2023-10-27 10:00:00 ，本地时间)。如果不提供此参数，API 通常会返回最近的蜡烛图数据。
- count : (可选) 返回的蜡烛图数量，控制 API 返回的数据量。最大值为 200，避免一次性请求过多数据导致服务器压力过大。默认为 1，表示只返回最新的一个蜡烛图数据。根据分析需求，可以调整此参数以获取更多历史数据。

示例: 获取Upbit交易所的1分钟蜡烛图数据

以下示例展示了如何使用 GET 请求从Upbit交易所的API获取指定交易对的1分钟蜡烛图数据。该API端点允许开发者检索历史价格数据，这对于技术分析和算法交易至关重要。

请求URL:

GET https://api.upbit.com/v1/candles/minutes/1?market=KRW-BTC&count=10

参数说明:

/minutes/1 : 指定请求1分钟周期的蜡烛图数据。Upbit API支持多种时间周期，如3分钟、5分钟、15分钟、30分钟、60分钟和240分钟，只需更改URL中的数字即可。
market : 指定交易市场。 KRW-BTC 表示韩元（KRW）计价的比特币（BTC）交易对。可以使用Upbit API支持的任何交易对。
count : 指定返回的蜡烛图数量。在此示例中， count=10 表示请求最近的10个1分钟蜡烛图数据。 count 参数允许调整返回的数据量，以满足不同的分析需求。

响应数据:

上述请求将返回一个JSON数组，其中每个元素代表一个1分钟蜡烛图。每个蜡烛图包含以下字段：

market : 交易市场代码（例如：KRW-BTC）。
candle_date_time_utc : 蜡烛图的UTC时间。
candle_date_time_kst : 蜡烛图的韩国标准时间（KST）。
opening_price : 开盘价。
high_price : 最高价。
low_price : 最低价。
trade_price : 收盘价（最新成交价）。
timestamp : Unix时间戳。
candle_acc_trade_price : 累计成交总额。
candle_acc_trade_volume : 累计成交量。
unit : 分钟单位 (本例中为 1)。

使用场景:

技术分析：利用历史价格数据进行图表分析，识别趋势和模式。
算法交易：根据市场数据自动执行交易策略。
数据可视化：将蜡烛图数据可视化，更直观地了解市场动态。

3.3. 获取当前价格 (Ticker)

该接口提供对特定市场当前价格信息的实时查询功能，是进行交易决策和市场分析的重要数据来源。

接口: GET /v1/ticker
用途: 获取指定交易市场的最新成交价格、交易量、最高价、最低价等信息。适用于监控市场动态、计算盈亏、以及构建自动化交易策略。
参数:
- markets : (必需) 需要查询的市场代码列表。多个市场代码之间使用英文逗号分隔。市场代码通常由交易双方的币种符号组成，例如 KRW-BTC,KRW-ETH 表示查询韩元(KRW)对比特币(BTC)以及韩元(KRW)对以太坊(ETH)的市场价格。确保市场代码的准确性，否则API将返回错误信息。
返回值:
API将返回一个JSON格式的数据，其中包含指定市场的详细行情信息。具体字段可能包括：
- market : 市场代码 (例如：KRW-BTC)
- trade_date : 最近成交日期 (UTC)
- trade_time : 最近成交时间 (UTC)
- trade_price : 最近成交价格
- trade_volume : 最近成交量
- high_price : 24小时内最高价
- low_price : 24小时内最低价
- prev_closing_price : 昨日收盘价
- change : 涨跌类型 (例如: EVEN, RISE, FALL)
- change_price : 涨跌价格
- change_rate : 涨跌幅度
- signed_change_price : 涨跌价格 (带符号，正数为涨，负数为跌)
- signed_change_rate : 涨跌幅度 (带符号，正数为涨，负数为跌)
- trade_timestamp : 最近成交时间戳 (毫秒)
- acc_trade_price : 24小时内累计成交额
- acc_trade_volume : 24小时内累计成交量
- highest_52_week_price : 52周最高价
- highest_52_week_date : 52周最高价日期
- lowest_52_week_price : 52周最低价
- lowest_52_week_date : 52周最低价日期
- timestamp : API请求时间戳 (毫秒)
请注意，具体的返回值字段可能因交易所而异，请参考API文档以获取最准确的信息。

示例:

请求：

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

响应 (示例)：

[
  {
    "market": "KRW-BTC",
    "trade_date": "20231027",
    "trade_time": "103000",
    "trade_price": 40000000,
    "trade_volume": 0.01,
    ...
  },
  {
    "market": "KRW-ETH",
    "trade_date": "20231027",
    "trade_time": "103000",
    "trade_price": 2800000,
    "trade_volume": 0.05,
    ...
  }
]

注意事项:
- 务必正确填写市场代码。
- 频繁请求可能会受到API限流限制，请合理控制请求频率。
- 确保网络连接正常，避免因网络问题导致数据获取失败。

示例: 获取Upbit交易所BTC和ETH韩元市场行情

通过发送HTTP GET请求至Upbit API的行情接口，可以获取指定交易对的实时数据。

请求URL： GET https://api.upbit.com/v1/ticker?markets=KRW-BTC,KRW-ETH

参数说明：

markets : 必需参数，指定要查询的交易市场代码。多个市场代码之间用英文逗号分隔。在本示例中， KRW-BTC 代表韩元计价的比特币市场， KRW-ETH 代表韩元计价的以太坊市场。您可以根据需要调整此参数以查询其他交易对。

响应数据：

API将返回JSON格式的数据，其中包含以下关键字段：

market : 市场代码 (例如： KRW-BTC )
trade_date : 最新交易日期 (UTC) (例如： 20231027 )
trade_time : 最新交易时间 (UTC) (例如： 073000 )
trade_date_kst : 最新交易日期 (KST，韩国标准时间) (例如： 20231027 )
trade_time_kst : 最新交易时间 (KST，韩国标准时间) (例如： 163000 )
trade_timestamp : 最新交易时间戳 (Unix timestamp in milliseconds)
opening_price : 开盘价
high_price : 最高价
low_price : 最低价
trade_price : 最新成交价
prev_closing_price : 前日收盘价
change : 涨跌状态 ( EVEN : 保留, RISE : 上涨, FALL : 下跌)
change_price : 涨跌额
change_rate : 涨跌率
signed_change_price : 符号位涨跌额
signed_change_rate : 符号位涨跌率
trade_volume : 最新成交量
acc_trade_price : 累计成交价
acc_trade_price_24h : 24小时累计成交价
acc_trade_volume : 累计成交量
acc_trade_volume_24h : 24小时累计成交量
highest_52_week_price : 52周最高价
highest_52_week_date : 52周最高价日期
lowest_52_week_price : 52周最低价
lowest_52_week_date : 52周最低价日期
timestamp : 时间戳 (Unix timestamp in milliseconds)

返回的 JSON 数据将包含每个指定市场的最新价格、交易量以及其他相关市场信息。请注意，API响应的结构可能会根据Upbit的更新而有所变化，建议查阅Upbit官方API文档以获取最准确的信息。

3.4. 获取账户信息 (Accounts)

接口: GET /v1/accounts
用途: 获取您在Upbit交易所的账户余额信息，包括可用余额、锁定余额以及各种加密货币和法币的持有情况。
参数: 无。该接口不需要任何请求参数。
权限: 需要身份验证。必须提供有效的API密钥和Secret密钥进行身份验证，才能访问此接口。请确保您的API密钥已启用账户查询权限。
响应:
成功响应将返回一个JSON数组，其中包含每个账户的详细信息。

每个账户对象可能包含以下字段：
- currency : 货币代码 (例如: KRW, BTC, ETH)。
- balance : 可用余额 (字符串类型)。
- locked : 锁定余额 (字符串类型)。锁定余额通常表示挂单中或提现中的金额。
- avg_buy_price : 平均买入价 (字符串类型)。
- avg_buy_price_modified : 是否修改过平均买入价 (布尔类型)。
- unit_currency : 计价货币 (字符串类型, 通常与 currency 相同)。
示例:
```
[
  {
    "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.001",
    "avg_buy_price": "60000000",
    "avg_buy_price_modified": false,
    "unit_currency": "KRW"
  }
]
    
```
错误处理:
如果发生错误，API将返回一个包含错误代码和错误消息的JSON对象。常见的错误包括：
- 401 Unauthorized : 身份验证失败。请检查API密钥和Secret密钥是否正确，以及API密钥是否具有访问账户信息的权限。
- 429 Too Many Requests : 请求过于频繁。请遵守API的速率限制。

示例:

GET https://api.upbit.com/v1/accounts

为了成功调用此接口，身份验证是必不可少的。您需要在 HTTP 请求头中显式地包含 Authorization 字段。该字段的值应为包含您的 Access Key 和使用 Secret Key 生成的 JSON Web Token (JWT) 的字符串。JWT 的生成过程涉及使用您的 Secret Key 对包含必要信息的声明（claims）进行签名，从而确保请求的安全性与完整性。请求头示例如下：

Authorization: Bearer JWT_TOKEN

其中， JWT_TOKEN 是您使用 Access Key 和 Secret Key 生成的 Base64 编码的 JWT 字符串。请务必妥善保管您的 Secret Key，避免泄露，以防止未经授权的访问。

以下是 JWT 生成过程的更详细说明：

准备声明 (Claims)： JWT 包含一组声明，声明是关于实体（通常是用户）和其它数据的声明。对于 Upbit API，您需要包含必要的声明，例如 API 的访问权限。
创建 JWT Header： JWT Header 通常包含两个部分：类型（typ）和算法（alg）。类型是 "JWT"，算法是用于签名的算法，例如 "HS256" (HMAC SHA256)。
Base64 编码： 分别对 Header 和 Claims 进行 Base64 编码。
生成签名： 使用您的 Secret Key 和指定的算法对编码后的 Header 和 Claims 进行签名。签名是使用 Base64 编码的 Header、一个句点 (.)、Base64 编码的 Claims，以及您的 Secret Key 生成的 HMAC 值。
构建 JWT： 将 Base64 编码的 Header、一个句点 (.)、Base64 编码的 Claims 和签名连接起来，形成最终的 JWT 字符串。

请注意，不同的编程语言和平台都有相应的 JWT 库可以帮助您简化 JWT 的生成过程。强烈建议使用这些库，而不是手动实现 JWT 的生成。

3.5. 下单 (Orders)

接口: POST /v1/orders
描述: 用于提交买入或卖出指定加密货币的订单请求。通过此接口，用户可以创建限价单或市价单，参与市场交易。
用途: 允许用户在指定市场中进行加密货币的买卖操作。
参数:
- market : (必需) 市场代码，精确指定交易的市场。例如， KRW-BTC 表示韩元 (KRW) 交易比特币 (BTC) 的市场。
- side : (必需) 订单方向，指示是买入还是卖出。 bid 表示买入订单，即希望以指定价格购买加密货币； ask 表示卖出订单，即希望以指定价格出售加密货币。
- volume : (必需) 订单数量，指定希望买入或卖出的加密货币数量。数量应为正数，并符合交易所规定的最小交易单位。
- price : (条件必需) 订单价格，仅在限价单 ( limit ) 中需要指定。表示希望买入或卖出的目标价格。对于市价单，该字段通常被忽略或设置为 null 。
- ord_type : (必需) 订单类型，定义订单的执行方式。
  - limit : 限价单，以指定的价格或更好的价格成交。如果市场价格未达到指定价格，订单将挂单等待成交。
  - price : 市价买入单，以当前市场最优价格立即买入指定数量的加密货币。在这种类型的订单中，用户指定希望支付的总金额，系统会根据当前市场价格计算可以购买的数量。
  - market : 市价卖出单，以当前市场最优价格立即卖出指定数量的加密货币。用户指定希望卖出的加密货币数量，系统会以当前市场价格尽快卖出。
请求头:
- Content-Type : application/ ，指定请求体的格式为 JSON。
- Authorization : 包含身份验证信息的头部，通常是 JWT (JSON Web Token) 或 API Key。
权限: 需要有效的身份验证凭证。未经验证的请求将被拒绝。

请求示例:


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

响应示例 (成功):


{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "side": "bid",
  "ord_type": "limit",
  "price": "50000000",
  "avg_price": "0",
  "state": "wait",
  "market": "KRW-BTC",
  "created_at": "2023-10-27T10:00:00+00:00",
  "volume": "0.001",
  "remaining_volume": "0.001",
  "reserved_fee": "0",
  "remaining_fee": "0",
  "paid_fee": "0",
  "locked": "0.001",
  "executed_volume": "0"
}

响应字段说明:
- uuid : 订单的唯一标识符。
- side : 订单方向 ( bid 或 ask )。
- ord_type : 订单类型 ( limit , price , 或 market )。
- price : 订单价格。
- avg_price : 平均成交价格。
- state : 订单状态 (例如, wait , done , cancel )。
- market : 市场代码。
- created_at : 订单创建时间。
- volume : 订单数量。
- remaining_volume : 剩余未成交数量。
- reserved_fee : 预留的手续费。
- remaining_fee : 剩余未支付的手续费。
- paid_fee : 已支付的手续费。
- locked : 锁定的资金量。
- executed_volume : 已成交数量。
错误处理: 接口可能会返回各种HTTP状态码，例如 400 Bad Request (请求参数错误), 401 Unauthorized (未授权), 403 Forbidden (权限不足), 429 Too Many Requests (请求频率过高) 等。应根据状态码和响应体中的错误信息进行相应的处理。

示例:

本示例展示了如何使用 HTTP POST 方法向 Upbit API 的 /v1/orders 端点提交一个限价买单。

请求 URL:

POST https://api.upbit.com/v1/orders

请求头:

Content-Type: application/

请求体 (JSON 格式):

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

字段解释:

market : 交易市场代码。例如， KRW-BTC 表示韩元 (KRW) 交易比特币 (BTC) 的市场。
side : 订单类型， bid 表示买入， ask 表示卖出。
volume : 订单数量。在本例中，购买 0.001 个比特币。
price : 订单价格。本例中，设定价格为 50,000,000 韩元。
ord_type : 订单类型， limit 表示限价单。限价单允许您指定购买或出售加密货币的价格。其他类型包括 price (市价买入指定价格), market (市价) 等。

重要提示：除了上述请求头，您还需要在请求头中添加 Authorization 字段以进行身份验证。 Authorization 字段通常包含一个 Bearer token，该 token 是通过 Upbit OpenAPI 密钥和秘密密钥生成的 JWT (JSON Web Token)。请务必参考Upbit的官方API文档以获取关于认证和授权的详细信息，并确保你的API密钥具有足够的权限来执行订单操作。

4. 身份验证：生成 JWT (JSON Web Token)

为了安全地访问 Upbit API 中需要身份验证的接口，必须使用您的 Access Key 和 Secret Key 生成 JWT (JSON Web Token)。 JWT 是一种开放标准 (RFC 7519)，它定义了一种紧凑且自包含的方式，用于作为 JSON 对象在各方之间安全地传输信息。在 Upbit API 的上下文中，JWT 用于验证请求的来源，确保只有授权的用户才能访问受保护的资源。

以下是一个 Python 示例，演示如何生成 JWT。这个示例使用了 PyJWT 库，如果您的环境中没有安装，需要先使用 pip 安装： pip install pyjwt 。

import jwt
import uuid
import hashlib

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"

payload = {
    'access_key': access_key,
    'nonce': str(uuid.uuid4()),
}

jwt_token = jwt.encode(payload, secret_key, algorithm="HS256")
authorization_token = f"Bearer {jwt_token}"

print(authorization_token)

请务必将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为您的实际 Upbit Access Key 和 Secret Key。 Access Key 和 Secret Key 可以从 Upbit 开放平台的 API 密钥管理页面获取。 nonce 字段是一个一次性使用的随机字符串，用于防止重放攻击。每次生成 JWT 时，都应该生成一个新的 uuid 作为 nonce 值。 HS256 是 HMAC-SHA256 算法，用于对 JWT 进行签名，保证其完整性和真实性。

生成 JWT 后，需要将其添加到 HTTP 请求头的 Authorization 字段中，作为 Bearer Token 进行身份验证。例如：

Authorization: Bearer YOUR_JWT_TOKEN

在发送 API 请求时，将完整的 Authorization 头部添加到请求中。服务端会验证 JWT 的签名和内容，如果验证通过，则允许访问受保护的 API 接口。如果验证失败，则会返回错误信息。

5. 调用示例：Python

以下是一个 Python 示例，演示如何使用 requests 库调用 Upbit API 获取账户信息。此示例展示了身份验证流程，通过生成 JWT (JSON Web Token) 来安全地访问 Upbit 的 /v1/accounts 接口，从而获取用户账户信息。

import requests import jwt import uuid

access_key = "YOUR_ACCESS_KEY" secret_key = "YOUR_SECRET_KEY"

请务必将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为您的真实 Upbit API 密钥。这两个密钥是您访问 Upbit API 的凭证，请妥善保管，切勿泄露。

def get_accounts(): payload = { 'access_key': access_key, 'nonce': str(uuid.uuid4()), } jwt_token = jwt.encode(payload, secret_key, algorithm="HS256") authorization_token = f"Bearer {jwt_token}"

get_accounts 函数负责构建请求的身份验证部分。 payload 包含 access_key 和一个唯一的 nonce (随机字符串)，用于防止重放攻击。 jwt.encode 函数使用您的 secret_key 和 HS256 算法对 payload 进行签名，生成 JWT。最终，将 JWT 封装在 Authorization header 中，格式为 "Bearer {jwt_token}"。

headers = {"Authorization": authorization_token}

此步骤创建包含身份验证信息的 HTTP 请求头。 Authorization header 告知 Upbit API 请求的身份已验证。

res = requests.get("https://api.upbit.com/v1/accounts", headers=headers)

使用 requests.get 方法向 Upbit API 的 /v1/accounts 端点发送 GET 请求。请求头包含了身份验证信息。 res 对象包含了服务器的响应。

return res.()

res.() 方法将服务器返回的 JSON 格式的响应数据解析为 Python 字典或列表，方便后续处理。

accounts = get_accounts() print(accounts)

调用 get_accounts 函数获取账户信息，并将结果打印到控制台。输出结果将包含您的 Upbit 账户的详细信息，例如账户余额、币种等。请注意，你需要安装 `requests` 和 `PyJWT` 库才能运行此代码。可以使用 `pip install requests pyjwt` 命令进行安装。

6. 错误处理与应对

Upbit API在交互过程中，会通过返回不同HTTP状态码和错误信息，来指示请求的处理结果以及可能出现的问题。理解并妥善处理这些错误信息对于构建健壮的应用至关重要。以下是一些常见的HTTP状态码及其含义，以及针对Upbit API的错误处理建议：

400 Bad Request ：此状态码表明客户端发送的请求存在错误。常见原因包括：
- 请求参数缺失或格式不正确。请仔细检查API文档，确认所有必需参数都已提供，并且符合规定的数据类型和格式。
- 请求体（Request Body）的内容不符合API的要求。例如，JSON格式错误、字段类型不匹配等。
- URL编码错误。特殊字符未正确进行URL编码可能导致服务器无法正确解析请求。
应对策略： 仔细审查请求参数，参照API文档进行修正，并使用合适的工具（如Postman）进行测试验证。
401 Unauthorized ：表明客户端未经过身份验证或提供的身份验证信息无效。
- API密钥（Access Key）或安全密钥（Secret Key）不正确。请确认密钥是否正确复制，并且与Upbit账户中的密钥一致。
- IP白名单限制。如果你的Upbit账户启用了IP白名单，请确保发起API请求的IP地址已添加到白名单中。
- 权限不足。某些API端点可能需要特定的权限才能访问。请检查你的API密钥是否具有足够的权限。
应对策略： 重新检查API密钥，确认IP白名单设置，并验证密钥是否拥有访问所需API端点的权限。
429 Too Many Requests ：表示客户端在单位时间内发送的请求数量超过了Upbit API的速率限制。Upbit为了保护服务器稳定，对API请求频率进行了限制。
- 超出每分钟/每秒的请求次数限制。不同API端点可能具有不同的速率限制。
- 未采用合适的重试策略。在遇到速率限制错误时，应避免立即重试，而是应该等待一段时间后再尝试。
应对策略： 实施合理的速率限制策略，例如使用队列来控制请求发送速度。当收到 429 错误时，根据 Retry-After 响应头中的指示，等待指定时间后再重试。考虑使用指数退避算法来避免进一步的速率限制。
500 Internal Server Error ：表明Upbit服务器内部发生了错误，导致无法完成请求。
- 服务器故障或维护。Upbit服务器可能暂时不可用。
- 未知错误。服务器遇到未预期的错误情况。
应对策略： 由于 500 错误通常是服务器端的问题，客户端无法直接解决。建议稍后重试请求。如果错误持续发生，请联系Upbit官方支持。

除了以上常见的错误码，Upbit API还可能返回其他特定的错误信息，例如订单相关的错误（如资金不足、订单数量超出限制等）。在编写代码时，务必全面考虑各种可能的错误情况，并实现相应的错误处理逻辑，包括：

日志记录： 记录所有API请求和响应，包括状态码、错误信息和请求参数。这有助于诊断问题和排查错误。
异常处理： 使用try-except (Python) 或 try-catch (Java, C++) 等机制捕获API请求中可能出现的异常，并进行处理。
错误重试： 对于临时性错误（如 429 或 500 ），可以采用重试机制，但需要注意避免过度重试导致服务器压力过大。
用户通知： 当发生严重错误时，及时通知用户，并提供相应的解决方案或建议。

通过周全的错误处理，可以显著提高应用程序的稳定性和可靠性，确保用户获得良好的使用体验。

7. 注意事项

请求频率限制： Upbit API 实施了严格的请求频率限制机制，旨在保障所有用户的服务质量和系统稳定性。过度频繁地发送请求可能导致服务器过载，从而触发 429 Too Many Requests 错误。务必仔细查阅 Upbit 官方文档中关于请求频率限制的具体规定，并根据您的应用场景，设计合理的请求策略，例如实施指数退避算法或使用队列来平滑请求峰值。建议在代码中加入错误处理机制，以便在接收到 429 错误时，能够自动进行重试，并在重试失败后进行适当的延迟，避免对服务器造成进一步的压力。
数据精度： 加密货币市场具有高度波动性，价格和交易量的数据通常具有极高的精度。为了避免在数据处理过程中出现精度损失，强烈建议使用能够精确表示浮点数的 decimal 数据类型（或其他类似的高精度数据类型），而非传统的 float 或 double 类型。精度损失可能导致交易决策失误或财务计算错误，尤其是在高频交易或量化交易策略中，微小的精度差异都可能产生显著的影响。在进行数据存储时，也应选择支持高精度数值存储的数据库或文件格式。
API 版本： 为了不断改进服务质量和功能，Upbit API 会定期进行更新和升级。这些更新可能包含新的接口、功能增强、性能优化或安全漏洞修复。务必密切关注 Upbit 官方发布的公告、开发者文档和更新日志，以便及时了解最新的 API 版本信息和相关变更。定期检查您的应用程序，确保其与最新的 API 版本兼容，并充分利用新版本提供的功能，提升应用的性能和安全性。不兼容的 API 版本可能导致程序运行异常或功能失效。
安全性： API 密钥是访问 Upbit API 的重要凭证，务必采取一切必要的措施来保护您的 API 密钥，防止泄露或滥用。切勿将 API 密钥硬编码到您的应用程序代码中，更不要将其提交到公共代码仓库（如 GitHub）。建议将 API 密钥存储在安全的位置，例如环境变量、配置文件或密钥管理系统中。在客户端应用程序中，避免直接暴露 API 密钥，而应通过服务器端代理请求。定期轮换 API 密钥，并启用 Upbit 提供的安全功能，例如 IP 地址白名单和交易权限限制，以进一步增强安全性。一旦发现 API 密钥泄露，应立即禁用旧密钥并生成新的密钥。

币安API权限管控：交易安全终极指南，你的资金安全了吗？

17 2025-03-08