upbit

Upbit 技能

所有 Upbit REST API 交互都使用 upbit CLI 二进制文件。

⚠️ 入门设置 — 缺少凭据时

如果未设置 UPBIT_ACCESS_KEY / UPBIT_SECRET_KEY，或经过身份验证的命令返回 401：

在同一轮中，严格按以下顺序完成所有操作：

1. 调用 bash("curl -s https://api.ipify.org") 获取出站 IP。
2. 在回复文本中写出以下设置说明（将 <ip> 替换为步骤 1 获取的实际 IP）：

---

步骤 1 — 在 Upbit 上将此 IP 添加到允许列表

Upbit 只接受来自你明确允许的 IP 地址的 API 调用。添加此 IP：

<ip>

步骤 2 — 创建 API 密钥

1. 登录 upbit.com → 个人资料 → API 관리（API 管理）
2. 点击 API 키 발급（签发 API 密钥）
3. 系统提示输入 IP 时，粘贴 <ip>
4. 启用以下权限范围：
   • 자산조회（查看资产）— 始终必需
   • 주문조회（查看订单）— 必需
   • 주문생성（下单）— 交易时必需
   • 출금（提现）— 仅在需要提现功能时启用
5. 完成双重身份验证和电子邮件验证，然后复制你的 Access Key 和 Secret Key

步骤 3 — 输入密钥

在下方的安全输入卡片中输入你的 Access Key 和 Secret Key。

---

语言行为

检测用户使用的语言，并据此回复：

• 韩语用户：用韩语回复，并使用 references/glossary.md 中的韩语术语（例如：주문、매수、잔고、체결、호가）
• 英语用户：用英语回复，并使用同一术语表中的英语术语
• 混合/不明确：使用最近一条消息的语言

解释 API 字段或命令输出时，始终使用术语表将字段名称翻译成用户使用的语言。例如，如果用户用韩语提问，应将 bid 解释为“매수”，将 ask 解释为“매도”，将 balance 解释为“보유 잔고”。

翻译术语或解释响应字段时，加载 references/glossary.md。

设置

如果未安装 upbit 或未配置凭据，加载 references/setup.md 并按照其中的步骤操作。

检查是否可以使用 upbit：

upbit --version

身份验证

私有端点需要凭据。建议通过 CLI 配置：

upbit config set

凭据会保存到 ~/.upbit/config，并自动用于所有 CLI 命令。

也可以通过环境变量设置：

export UPBIT_ACCESS_KEY=<your-access-key>
export UPBIT_SECRET_KEY=<your-secret-key>

或者在每条命令中直接传入：

upbit <resource> <command> --access-key <key> --secret-key <secret>

私有（需要身份验证）：accounts、api-keys、orders、withdraws、deposits、travel-rule、wallet-status 公开（无需身份验证）：tickers、orderbooks、trades、candles、trading-pairs

安全规则 — 写入操作

执行任何写入操作前，展示完整命令，并要求用户输入 CONFIRM。

写入操作：

• orders create、orders cancel、orders cancel-and-new、orders cancel-by-uuids、orders cancel-open
• withdraws create-withdrawal、withdraws create-krw-withdrawal、withdraws cancel-withdrawal
• deposits deposit-krw、deposits create-coin-address
• travel-rule verify-deposit-by-txid、travel-rule verify-deposit-by-uuid

orders test-create 是试运行 — 无需输入 CONFIRM。

Upbit 领域概念

市场交易对格式

• 字段名称：market
• 格式：{QUOTE}-{BASE} — 先写报价货币，再写基础资产
• 分隔符：连字符（-），不是斜杠（/）
• 始终使用大写
• 报价货币：KRW、BTC、USDT
• 不是 {BASE}-{QUOTE} 或 {BASE}/{QUOTE} — Upbit 使用的顺序与大多数交易所的惯例相反

市场	含义
KRW-BTC	以 KRW 计价的 BTC；Upbit 使用 KRW-BTC，而不是 BTC/KRW 或 BTC-KRW
KRW-ETH	以 KRW 计价的 ETH
KRW-XRP	以 KRW 计价的 XRP
BTC-ETH	以 BTC 计价的 ETH
USDT-XRP	以 USDT 计价的 XRP

账户余额字段

accounts list 中的每个条目：

字段	描述
currency	资产代码（例如：KRW、BTC、ETH）
balance	可用余额（不包括任何未完成订单中的金额）
locked	当前锁定在未完成订单或提现中的余额
avg_buy_price	平均买入价格（十进制字符串）
unit_currency	avg_buy_price 的计价货币（例如：KRW、BTC）

持仓总额 = balance + locked

订单类型（ord_type）

ord_type	描述	必填	不得设置
limit	按指定价格下限价单	price、volume	—
price	市价买入 — 花费固定的报价金额	price	volume
market	市价卖出 — 卖出固定数量的基础资产	volume	price
best	按最佳可用价格成交（参见下方规则）	参见下方	参见下方

best 订单规则：

• time_in_force 必须为 ioc 或 fok（不得为 post_only）
• 如果 side=bid（买入）：必须设置 price，不得设置 volume
• 如果 side=ask（卖出）：必须设置 volume，不得设置 price

post_only 与 smp_type 冲突：两者互斥，不要同时设置。

方向值

side	含义
bid	买入
ask	卖出

订单状态

状态	含义
wait	等待成交
watch	等待预留（止损单）
done	已全部成交
cancel	已取消

订单手续费字段

字段	描述
reserved_fee	下单时预留的手续费总额
paid_fee	已收取的手续费（针对部分成交）
remaining_fee	reserved_fee - paid_fee
locked	此订单锁定的金额（买入时为报价货币，卖出时为基础资产）

首次下单

在不熟悉的市场下单前，运行 orders retrieve-chance 以确认：

• 最小订单金额（bid.min_total、ask.min_total）
• 支持的订单类型（bid_types、ask_types）
• 手续费率（bid_fee、ask_fee、maker_bid_fee、maker_ask_fee）

upbit orders retrieve-chance --market "KRW-BTC"

提现 — 多链资产

对于可在多个网络上使用的资产（例如：USDT），必须通过 net_type 指定区块链。提现前，使用 withdraws list-coin-addresses 查看支持的网络和地址：

upbit withdraws list-coin-addresses --currency "USDT"

提现 — 二级地址

除主地址外，某些资产还需要二级地址（Destination Tag、Memo 等）。发送前，务必通过 withdraws list-coin-addresses 检查已登记地址，确认是否存在 secondary_address。

提现 — 地址未登记（withdraw_address_not_registered）

当 withdraws create-withdrawal 返回包含 name: withdraw_address_not_registered 的 400 错误时，表示该地址尚未登记在 Upbit Open API 提现白名单中。

如需登记提现地址，请访问对应环境的白名单管理页面：

环境	URL
KR	https://www.upbit.com/mypage/open_api_management/withdraw_access_register
SG	https://sg.upbit.com/mypage/open_api_management/withdraw_access_register
ID	https://id.upbit.com/mypage/open_api_management/withdraw_access_register
TH	https://th.upbit.com/mypage/open_api_management/withdraw_access_register

登记后，运行 withdraws list-coin-addresses，确认地址已显示后再重试。

充值 / 提现状态

状态	含义
PROCESSING	处理中
ACCEPTED	已完成
CANCELLED	已取消
REJECTED	已拒绝
TRAVEL_RULE_SUSPECTED	等待 Travel Rule 验证
REFUNDING	退款处理中
REFUNDED	已退款

当充值处于 TRAVEL_RULE_SUSPECTED 状态时，使用 travel-rule 命令进行验证。

钱包状态

wallet-status list 返回每种资产的网络状态：

wallet_state	含义
working	充值和提现均可用
withdraw_only	暂停充值
deposit_only	暂停提现
paused	充值和提现均暂停
unsupported	不受支持

K 线单位与限制

• 分钟 K 线：仅支持单位 1, 3, 5, 10, 15, 30, 60, 240
• 秒 K 线：数据最多保留 3 个月（查询更早的数据将返回空数组）
• count：默认值为 1，每次请求最多 200 条

交易分页

• count：每次请求最多 500 条
• cursor：传入最后一条结果的 sequential_id，以获取下一页
• days_ago：整数 1–7（基于 UTC 的日偏移量）

行情关键字段

字段	说明
trade_price	当前（最新）价格
acc_trade_price_24h	24 小时累计交易金额
acc_trade_volume_24h	24 小时累计交易量
change	相对于前一日收盘价的 RISE、EVEN 或 FALL
signed_change_price	带符号的绝对涨跌额（下跌时为负数）
highest_52_week_price / lowest_52_week_price	52 周价格范围

价格方向枚举（change、ask_bid）

change 值	含义
RISE	价格高于前一日收盘价
EVEN	与前一日收盘价相同
FALL	价格低于前一日收盘价

ask_bid 值	含义
ASK	由卖单发起的交易
BID	由买单发起的交易

单位与格式

值	单位	格式
volume	基础资产数量	十进制字符串（例如，"0.01"）
price（限价）	计价货币中的单位价格	十进制字符串（例如，"140000000"）
price（市价买入）	要花费的计价货币总额	十进制字符串（例如，"10000"）
费用字段	计价货币金额	十进制字符串
timestamp	自纪元起的毫秒数	整数
created_at / done_at	带 KST 偏移量的 ISO 8601 格式	字符串（例如，2024-01-01T09:00:00+09:00）
trade_date	UTC 日期	字符串 yyyyMMdd
trade_time	UTC 时间	字符串 HHmmss（24 小时制）
费率	十进制数（0.05% = "0.0005"）	十进制字符串

日期边界（opening_price、acc_trade_price 等）基于 UTC 00:00，而非 KST。

命令参考

需要了解资源的详细标志信息时，请阅读对应的参考文件。

资源	子命令	参考
orders	create, test-create, retrieve, list-open, list-closed, list-by-uuids, cancel, cancel-and-new, cancel-by-uuids, cancel-open, retrieve-chance	references/orders.md
tickers	list-by-quote-currencies, list-by-trading-pairs	references/tickers.md
candles	list-minutes, list-days, list-weeks, list-months, list-years, list-seconds	references/candles.md
orderbooks	list, list-instruments	references/orderbooks.md
trades	list	references/trades.md
trading-pairs	list	references/trading-pairs.md
withdraws	retrieve, list, cancel-withdrawal, create-withdrawal, create-krw-withdrawal, list-coin-addresses, retrieve-chance	references/withdraws.md
deposits	retrieve, list, create-coin-address, deposit-krw, list-coin-addresses, retrieve-chance, retrieve-coin-address	references/deposits.md
travel-rule	list-vasps, verify-deposit-by-txid, verify-deposit-by-uuid	references/travel-rule.md
accounts / api-keys / wallet-status	list	references/account.md
输出与筛选	--format, --transform, GJSON, debug, auto-paging	references/output.md
韩语 ↔ 英语术语表	术语翻译、字段名称韩语 ↔ 英语映射	references/glossary.md
CLI 设置与凭据	安装、环境选择、API 密钥设置、config set	references/setup.md

对于参考文件中未列出的标志，请运行：upbit <resource> <command> --help

环境

upbit accounts list                   # kr (default)
upbit accounts list --environment sg  # sg | id | th
upbit accounts list --base-url <url>  # custom base URL