upbit

Upbit スキル

すべての Upbit REST API とのやり取りには、upbit CLI バイナリを使用してください。

言語の動作

ユーザーの言語を検出し、それに応じて応答してください。

• 韓国語のユーザー：韓国語で応答し、references/glossary.md の韓国語用語（例：주문、매수、잔고、체결、호가）を使用してください
• 英語のユーザー：英語で応答し、同じ用語集の英語用語を使用してください
• 複数言語が混在する場合／曖昧な場合：直近のメッセージの言語に従ってください

API フィールドやコマンド出力を説明するときは、用語集を使ってフィールド名を必ずユーザーの言語に翻訳してください。たとえば、ユーザーが韓国語で質問した場合、bid は「매수」、ask は「매도」、balance は「보유 잔고」と説明してください。

用語の翻訳やレスポンスフィールドの説明を行う場合は、references/glossary.md を読み込んでください。

セットアップ

upbit がインストールされていない場合、または認証情報が設定されていない場合は、references/setup.md を読み込んで、記載されている手順に従ってください。

upbit が利用可能で、最小バージョン要件を満たしているか確認してください。

upbit --version

v1.0.0 以降が必要です。 古い場合は、続行する前にアップグレードしてください。

npm install -g @upbit-official/upbit-cli@latest

必須リクエストヘッダー

API を呼び出すすべての upbit コマンドの最後の引数として、必ず --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}' を追加してください。 これは、パブリック（tickers、orderbooks、trades、candles、trading-pairs）とプライベート（accounts、orders、withdraws、deposits、travel-rule、api-keys、wallet-status、pockets）の両方のエンドポイントを含む、API を呼び出すすべての実行に適用されます。

upbit <resource> <command> [flags] --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'

{metadata.version} はプレースホルダーです。文字列のまま送信しないでください。 コマンドを実行する前に、{metadata.version} を上記のフロントマターにある、このスキルの metadata.version フィールドの値に置き換えてください。

対象外（API リクエストを行わないため、ヘッダーは省略してください）：upbit --version、upbit config set、upbit config show、upbit config path、インストール／シェルのスニペット（npm install、node --version、curl、export ...）。

認証

プライベートエンドポイントには認証情報が必要です。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> --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'

プライベート（認証が必要）：accounts、api-keys、orders、withdraws、deposits、travel-rule、wallet-status、pockets パブリック（認証不要）：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
• pockets transfer、pockets universal-transfer

orders test-create はドライランのため、CONFIRM は不要です。

Upbit のドメイン概念

マーケットペアの形式

• フィールド名：market
• 形式：{QUOTE}-{BASE} — クオート通貨が先、ベース資産が後
• 区切り文字：ハイフン（-）。スラッシュ（/）ではありません
• 常に大文字
• クオート通貨：KRW、BTC、USDT
• {BASE}-{QUOTE} や {BASE}/{QUOTE} ではありません — Upbit は、ほとんどの取引所で使われる一般的な順序とは逆の順序を採用しています

マーケット	意味
KRW-BTC	KRW建ての BTC。Upbit では BTC/KRW や BTC-KRW ではなく、KRW-BTC を使用します
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

ポケット

韓国（KR）のみ — ポケットはUpbit Koreaでのみ利用できます。グローバルサービスではサポートされていません。

ポケットを使うと、ユーザーは単一のUpbitアカウント内で資産を用途ごとに分けられます。各ポケットはuuidで識別されます。

• メインポケット：アカウントとともに自動作成されます。外部からの入出金を含むアカウントの標準取引を処理し、アカウント内のすべてのポケットに対するマスター権限を持つことができます。
• サブポケット：特定の目的のためにユーザーが作成します。APIキーの権限範囲内で独立して動作しますが、外部からの入出金はできません。サブポケットの資産を外部へ移動するには、専用のキーを使ってpockets transferを実行してください。

すべてのpocketsコマンドには、2種類の権限のいずれかが必要です。それぞれ利用できるポケットの種類は1つだけなので、1つのAPIキーで両方のコマンドグループを呼び出すことはできません。

コマンド	権限	呼び出し可能なキー
list、retrieve-balance、list-api-keys、universal-transfer、list-universal-transfers	ポ켓관리（ポケット管理）	メインポケットのキーのみ
transfer、list-transfers	자산이전（資産移動）	サブポケットのキーのみ

retrieve-balanceはサブポケットの残高を読み取りますが、メインポケットのキーを使って呼び出す点に注意してください。 コマンド構文とパラメーターの詳細については、references/pockets.mdおよび公式概要（https://docs.upbit.com/kr/reference/pocket-overview）を参照してください。

注文タイプ（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の競合：この2つは相互に排他的です。両方を設定しないでください。

売買方向の値

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" --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'

出金 — 複数チェーン対応の資産

USDTなど複数のネットワークで利用可能な資産では、ブロックチェーンを指定するためにnet_typeが必要です。出金前にwithdraws list-coin-addressesを使って、対応ネットワークとアドレスを確認してください。

upbit withdraws list-coin-addresses --currency "USDT" --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'

出金 — セカンダリアドレス

一部の資産では、メインアドレスに加えてセカンダリアドレス（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	サポート対象外

ローソク足の単位と上限

• 分足ローソク足：サポートされる単位は 1, 3, 5, 10, 15, 30, 60, 240 のみです
• 秒足ローソク足：データの保持期間は最大 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	基軸資産の数量	10 進文字列（例："0.01"）
price（指値）	クォート通貨建ての単価	10 進文字列（例："140000000"）
price（成行買い）	使用するクォート通貨の合計額	10 進文字列（例："10000"）
手数料フィールド	クォート通貨の金額	10 進文字列
timestamp	UNIX エポックからのミリ秒数	整数
created_at / done_at	KST オフセット付き ISO 8601	文字列（例：2024-01-01T09:00:00+09:00）
trade_date	UTC の日付	文字列 yyyyMMdd
trade_time	UTC の時刻	文字列 HHmmss（24 時間表記）
手数料率	10 進数（0.05% = "0.0005"）	10 進文字列

日付の境界（opening_price、acc_trade_price など）は、KST ではなく UTC 00:00 を基準とします。

コマンドリファレンス

リソースのフラグについて詳しく知りたい場合は、対応するリファレンスファイルをお読みください。

リソース	サブコマンド	リファレンス
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
pockets	list, retrieve-balance, transfer, list-transfers, universal-transfer, list-universal-transfers, list-api-keys	references/pockets.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 --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'                   # kr (default)
upbit accounts list --environment sg --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'  # sg | id | th
upbit accounts list --base-url <url> --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'  # custom base URL