upbit

Upbit Skill

Use the upbit CLI binary for all Upbit REST API interactions.

Language Behavior

Detect the user's language and respond accordingly:

Korean user: respond in Korean, use Korean terminology from references/glossary.md (e.g., order, buy, balance, execution, order book)
English user: respond in English, use English terminology from the same glossary
Mixed/ambiguous: follow the language of the most recent message

When explaining API fields or command output, always translate field names into the user's language using the glossary. For example, if the user asks in Korean, explain bid as "buy", ask as "sell", balance as "held balance".

Load references/glossary.md when translating terminology or explaining response fields.

Setup

If upbit is not installed or credentials are not configured, load references/setup.md and follow the steps there.

Check if upbit is available and meets the minimum version:

upbit --version

Requires v1.0.0+. If older, upgrade before continuing:

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

Required Request Header

Always append --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}' as the last argument to every upbit command that calls the API. This applies to all API-calling invocations — both public (tickers, orderbooks, trades, candles, trading-pairs) and private (accounts, orders, withdraws, deposits, travel-rule, api-keys, wallet-status, pockets) endpoints.

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

{metadata.version} is a placeholder — never send it literally. Before running any command, substitute {metadata.version} with this skill's version from the metadata.version field in the front matter above.

Excluded (these do not make API requests, so omit the header): upbit --version, upbit config set, upbit config show, upbit config path, and installation/shell snippets (npm install, node --version, curl, export ...).

Authentication

Private endpoints require credentials. Configure via the CLI (recommended):

upbit config set

Credentials are saved to ~/.upbit/config and automatically used for all CLI commands.

Alternatively, set via environment variables:

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

Or pass inline per command:

upbit <resource> <command> --access-key <key> --secret-key <secret> --header 'X-Upbit-Initiator: upbit-cli-skill/{metadata.version}'

Private (require auth): accounts, api-keys, orders, withdraws, deposits, travel-rule, wallet-status, pockets Public (no auth): tickers, orderbooks, trades, candles, trading-pairs

Safety Rule — Write Operations

Before executing any write operation, show the full command and ask the user to type CONFIRM.

Write operations:

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 is a dry-run — no CONFIRM needed.

Upbit Domain Concepts

Market Pair Format

Field name: market
Format: {QUOTE}-{BASE} — quote currency first, base asset second
Delimiter: hyphen (-), not slash (/)
Always uppercase
Quote currencies: KRW, BTC, USDT
Not {BASE}-{QUOTE} or {BASE}/{QUOTE} — Upbit reverses the conventional order used by most exchanges

Market	Meaning
`KRW-BTC`	BTC priced in KRW; Upbit uses `KRW-BTC`, not `BTC/KRW` or `BTC-KRW`
`KRW-ETH`	ETH priced in KRW
`KRW-XRP`	XRP priced in KRW
`BTC-ETH`	ETH priced in BTC
`USDT-XRP`	XRP priced in USDT

Account Balance Fields

Each entry from accounts list:

Field	Description
`currency`	Asset code (e.g., `KRW`, `BTC`, `ETH`)
`balance`	Available balance (not in any open order)
`locked`	Balance currently locked in open orders or withdrawals
`avg_buy_price`	Average purchase price (decimal string)
`unit_currency`	Currency `avg_buy_price` is denominated in (e.g., `KRW`, `BTC`)

Total holdings = balance + locked

Pockets

Korea (KR) only — pockets are available exclusively on Upbit Korea. They are not supported on the global service.

A pocket lets a user split assets within a single Upbit account for separate purposes. Each pocket is identified by a uuid.

Main pocket: created automatically with the account. Handles the account's default trading including external deposits/withdrawals, and can hold master authority over every pocket in the account.
Sub-pocket: created by the user for a specific purpose. Operates independently within its API key's permission scope, but external deposits/withdrawals are blocked. To move a sub-pocket's assets out, use its own key with pockets transfer.

Every pockets command requires one of two permissions, and each is only available on one pocket type — so a single API key can never call both groups:

Commands	Permission	Callable from
`list`, `retrieve-balance`, `list-api-keys`, `universal-transfer`, `list-universal-transfers`	Pocket management (pocket management)	Main pocket key only
`transfer`, `list-transfers`	Asset transfer (asset transfer)	Sub-pocket key only

Note that retrieve-balance reads a sub-pocket's balance but is still called with the main pocket key. See references/pockets.md for full command syntax and parameters, and https://docs.upbit.com/kr/reference/pocket-overview for the official overview.

Order Types (`ord_type`)

`ord_type`	Description	Required	Must NOT set
`limit`	Limit order at specified price	`price`, `volume`	—
`price`	Market buy — spend a fixed quote amount	`price`	`volume`
`market`	Market sell — sell a fixed base amount	`volume`	`price`
`best`	Best available price (see rules below)	see below	see below

best order rules:

time_in_force must be ioc or fok (NOT post_only)
If side=bid (buy): requires price, must omit volume
If side=ask (sell): requires volume, must omit price

post_only + smp_type conflict: these two are mutually exclusive — do not set both.

Side Values

`side`	Meaning
`bid`	Buy
`ask`	Sell

Order States

State	Meaning
`wait`	Pending execution
`watch`	Pending reservation (stop order)
`done`	Fully executed
`cancel`	Cancelled

Order Fee Fields

Field	Description
`reserved_fee`	Total fee reserved when order was placed
`paid_fee`	Fee already charged (for partial fills)
`remaining_fee`	`reserved_fee - paid_fee`
`locked`	Amount locked for this order (quote currency for buys, base asset for sells)

First-Time Order Placement

Before placing an order on an unfamiliar market, run orders retrieve-chance to confirm:

Minimum order amount (bid.min_total, ask.min_total)
Supported order types (bid_types, ask_types)
Fee rates (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}'

Withdrawal — Multi-Chain Assets

For assets available on multiple networks (e.g., USDT), net_type is required to specify the blockchain. Use withdraws list-coin-addresses to see supported networks and addresses before withdrawing:

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

Withdrawal — Secondary Address

Some assets require a secondary address (Destination Tag, Memo, etc.) in addition to the main address. Always check the registered address via withdraws list-coin-addresses to see if secondary_address is present before sending.

Withdrawal — Address Not Registered (`withdraw_address_not_registered`)

When withdraws create-withdrawal returns a 400 error with name: withdraw_address_not_registered, the address has not been registered in the Upbit Open API withdrawal allowlist.

To register a withdrawal address, visit the allowlist management page for your environment:

Environment	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

After registering, run withdraws list-coin-addresses to confirm the address appears before retrying.

Deposit / Withdraw States

State	Meaning
`PROCESSING`	In progress
`ACCEPTED`	Completed
`CANCELLED`	Cancelled
`REJECTED`	Rejected
`TRAVEL_RULE_SUSPECTED`	Awaiting Travel Rule verification
`REFUNDING`	Refund in progress
`REFUNDED`	Refund completed

When a deposit is in TRAVEL_RULE_SUSPECTED state, use travel-rule commands to verify.

Wallet Status

wallet-status list returns per-asset network status:

`wallet_state`	Meaning
`working`	Both deposits and withdrawals available
`withdraw_only`	Deposits suspended
`deposit_only`	Withdrawals suspended
`paused`	Both suspended
`unsupported`	Not supported

Candle Units & Limits

Minute candles: supported units are 1, 3, 5, 10, 15, 30, 60, 240 only
Second candles: data retention is 3 months maximum (older queries return empty array)
count: default 1, max 200 per request

Trade Pagination

count: max 500 per request
cursor: pass sequential_id from last result to page forward
days_ago: integer 1–7 (UTC-based day offset)

Ticker Key Fields

Field	Description
`trade_price`	Current (last) price
`acc_trade_price_24h`	24-hour accumulated trade value
`acc_trade_volume_24h`	24-hour accumulated trade volume
`change`	`RISE`, `EVEN`, or `FALL` vs. previous day close
`signed_change_price`	Signed absolute change (negative if falling)
`highest_52_week_price` / `lowest_52_week_price`	52-week range

Price Direction Enum (`change`, `ask_bid`)

`change` value	Meaning
`RISE`	Price higher than previous close
`EVEN`	Same as previous close
`FALL`	Price lower than previous close

`ask_bid` value	Meaning
`ASK`	Trade initiated by a sell order
`BID`	Trade initiated by a buy order

Units & Formats

Value	Unit	Format
`volume`	Base asset quantity	Decimal string (e.g., `"0.01"`)
`price` (limit)	Per-unit price in quote currency	Decimal string (e.g., `"140000000"`)
`price` (market buy)	Total quote amount to spend	Decimal string (e.g., `"10000"`)
Fee fields	Quote currency amount	Decimal string
`timestamp`	Milliseconds since epoch	Integer
`created_at` / `done_at`	ISO 8601 with KST offset	String (e.g., `2024-01-01T09:00:00+09:00`)
`trade_date`	UTC date	String `yyyyMMdd`
`trade_time`	UTC time	String `HHmmss` (24-hour)
Fee rates	Decimal (0.05% = `"0.0005"`)	Decimal string

Day boundaries (opening_price, acc_trade_price, etc.) are based on UTC 00:00, not KST.

Command Reference

When you need detailed flag information for a resource, read the corresponding reference file.

Resource	Subcommands	Reference
`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`
Output & Filtering	--format, --transform, GJSON, debug, auto-paging	`references/output.md`
Korean ↔ English Glossary	Term translations, field name Korean ↔ English mapping	`references/glossary.md`
CLI Setup & Credentials	Installation, environment selection, API key setup, config set	`references/setup.md`

For flags not listed in reference files, run: upbit <resource> <command> --help

Environment

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