upbit

Upbit Skill

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

⚠️ Onboarding — when credentials are missing

When UPBIT_ACCESS_KEY / UPBIT_SECRET_KEY are not set, or an authenticated command returns 401:

In a single turn, do ALL of the following in this exact order:

1. Call bash("curl -s https://api.ipify.org") to get the outbound IP.
2. Write the setup instructions below in your reply text (substitute <ip> with the real IP from step 1):

---

Step 1 — Allowlist this IP on Upbit

Upbit only accepts API calls from IP addresses you explicitly allow. Add this IP:

<ip>

Step 2 — Create an API key

1. Log in to upbit.com → profile → API 관리 (API Management)
2. Click API 키 발급 (Issue API Key)
3. When prompted for an IP, paste <ip>
4. Enable scopes:

• 자산조회 (View assets) — always required
• 주문조회 (View orders) — required
• 주문생성 (Place orders) — required to trade
• 출금 (Withdraw) — only if you want withdrawal support

1. Complete 2FA + email verification, then copy your Access Key and Secret Key

Step 3 — Enter your keys

Enter your Access Key and Secret Key in the secure input card below.

---

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:

upbit --version

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>

Private (require auth): accounts, api-keys, orders, withdraws, deposits, travel-rule, wallet-status 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

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

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"

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"

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 (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.

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

Environment

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