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., 주문, 매수, 잔고, 체결, 호가)
• 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 "매수", ask as "매도", balance as "보유 잔고".

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

Account Balance Fields

Each entry from accounts list:

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:

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)

`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

Order States

Order Fee Fields

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:

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

Deposit / Withdraw States

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:

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

Price Direction Enum (change, ask_bid)

Units & Formats

Day boundaries (openingprice, acctrade_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.

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