# Upbit Read API

> Use when adding, reviewing, or debugging Upbit read-only market data integrations, limited to current ticker prices, ticker lists by quote currency, and candle OHLCV data. Includes endpoint selection, response field mapping, and Upbit rate-limit handling. Do not use for orders, accounts, deposits, withdrawals, authenticated Exchange APIs, or trading automation.

- Skill: `dd3ok/upbit-read-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dd3ok/upbit-read-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dd3ok/upbit-read-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dd3ok (https://skillmd.com/u/dd3ok)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dd3ok/upbit-read-api

---


# Upbit Read API

## Mission

Implement or inspect read-only Upbit market-data integrations for:

- current price / ticker snapshots
- ticker lists by quote currency
- candles / OHLCV for chart analysis

Keep the integration read-only. Do not add order, account, deposit, withdrawal, Travel Rule, API-key, or authenticated Exchange API behavior under this skill.

## Preferred Approach

Use a thin `httpx` or equivalent HTTP adapter unless the task explicitly requires the official SDK.

- These APIs are simple unauthenticated REST `GET` endpoints.
- Avoid adding `upbit-sdk` only for ticker/candle reads if a project already has an HTTP client.
- Normalize Upbit responses into local DTOs before passing data to chart, indicator, or briefing services.

Use the official SDK only when the user asks for SDK adoption, typed SDK models, or a wider Upbit integration beyond these read APIs.

## Base URLs

For Korea/Upbit KR:

- `https://api.upbit.com`

For global regions:

- Singapore: `https://sg-api.upbit.com`
- Indonesia: `https://id-api.upbit.com`
- Thailand: `https://th-api.upbit.com`

Use market codes in `{QUOTE}-{BASE}` form, for example `KRW-BTC`, `BTC-ETH`, `USDT-BTC`.

## Supported Endpoints

### Trading Pair List

Use this when the integration needs the supported market universe.

- `GET /v1/market/all`
- Optional params:
  - `is_details=true` when warning/detail fields are needed
- Key fields:
  - `market`
  - `korean_name`
  - `english_name`
  - `market_warning`

### Current Prices By Pair

Use this when the integration already has specific market codes.

- `GET /v1/ticker`
- Params:
  - `markets=KRW-BTC,KRW-ETH`
- Key fields:
  - `market`
  - `trade_price`
  - `opening_price`
  - `high_price`
  - `low_price`
  - `prev_closing_price`
  - `change`
  - `change_price`
  - `change_rate`
  - `signed_change_price`
  - `signed_change_rate`
  - `trade_volume`
  - `acc_trade_price`
  - `acc_trade_price_24h`
  - `acc_trade_volume`
  - `acc_trade_volume_24h`
  - `trade_timestamp`
  - `timestamp`

Map `trade_price` to current/close price. Map `acc_trade_price_24h` or `acc_trade_price` to trading value depending on the requested horizon.

### Ticker List By Quote Currency

Use this when the integration needs all tickers under one or more quote markets.

- `GET /v1/ticker/all`
- Params:
  - Korean API: `quote_currencies=KRW,BTC,USDT`
  - Some older English docs use `quoteCurrencies`; prefer `quote_currencies` for current Korean/global docs.
- Response fields are ticker snapshot fields, same shape as `/v1/ticker`.

Prefer this over calling `/v1/ticker` repeatedly for every pair in a quote market.

### Candles

Use candles as the input for chart analysis and local indicator calculation.

- Seconds: `GET /v1/candles/seconds`
- Minutes: `GET /v1/candles/minutes/{unit}`
- Days: `GET /v1/candles/days`
- Weeks: `GET /v1/candles/weeks`
- Months: `GET /v1/candles/months`
- Years: `GET /v1/candles/years`

Minute units:

- `1`, `3`, `5`, `10`, `15`, `30`, `60`, `240`

Common params:

- `market=KRW-BTC`
- `count=200` maximum per request for recent candles
- `to=<ISO datetime>` for pagination/backfill before a cutoff

Key fields:

- `market`
- `candle_date_time_utc`
- `candle_date_time_kst`
- `opening_price`
- `high_price`
- `low_price`
- `trade_price`
- `candle_acc_trade_price`
- `candle_acc_trade_volume`
- `timestamp`
- `unit` for minute candles

Map `opening_price`, `high_price`, `low_price`, `trade_price`, and `candle_acc_trade_volume` into OHLCV bars. Treat `candle_acc_trade_price` as candle trading value.

## Candle Caveats

- Candles are generated only when trades occurred in that interval.
- Missing intervals are expected and should not be filled silently unless the target analysis explicitly defines a fill policy.
- 1-second candle data has limited retention; current docs state up to 3 months.
- For `to` params containing `+`, `:`, or spaces, rely on HTTP-client params encoding instead of manually concatenating query strings.

## Rate Limits

Upbit applies second-based rate limits by Rate Limit group.

Read-only Quotation REST APIs are measured by IP. The relevant groups are:

- `market`: trading pair list, up to 10 requests/sec
- `ticker`: `/v1/ticker` and `/v1/ticker/all`, up to 10 requests/sec
- `candle`: all candle endpoints, up to 10 requests/sec

Important handling rules:

- Limits are shared within the same group. For example `/v1/ticker` and `/v1/ticker/all` both spend from `ticker`.
- Check the `Remaining-Req` response header after every request.
- Header shape: `group=ticker; min=1800; sec=9`
- Treat `sec` as the remaining requests in the current second. Ignore `min`; official docs mark it as deprecated/fixed.
- On HTTP `429`, back off immediately.
- Repeated limit violations can return HTTP `418` with a temporary IP/account block; stop requests until the block duration passes.
- Requests with an `Origin` header can be subject to a stricter policy for Quotation REST/WebSocket requests. Do not send browser-like `Origin` headers from server-side clients.

Recommended defaults:

- Use one shared limiter per process and per group: `market`, `ticker`, `candle`.
- Cap each group at 8 requests/sec locally, not 10, to leave headroom for concurrent jobs.
- Batch pairs in `/v1/ticker?markets=...` and use `/v1/ticker/all` for quote-market sweeps.
- For candle backfills, page sequentially with `to` and obey the `candle` limiter.
- Log `Remaining-Req`, status code, endpoint group, and market code, but never log credentials or unrelated private data.

## Implementation Checklist

1. Keep the client unauthenticated and read-only.
2. Choose the narrowest endpoint:
   - exact pairs: `/v1/ticker`
   - all pairs under quote market: `/v1/ticker/all`
   - chart bars: candle endpoint by interval
3. Validate market code format before calling the API.
4. Use an HTTP client with structured query params.
5. Normalize Upbit field names at the adapter boundary.
6. Preserve raw payload only if the target project's retention policy allows it.
7. Enforce group-aware rate limiting and parse `Remaining-Req`.
8. Do not compute indicators in the API client. Compute them after candle normalization.

## Official References

- Upbit Developer Center: `https://docs.upbit.com/kr`
- Rate limits: `https://docs.upbit.com/kr/reference/rate-limits`
- Trading pair list: `https://global-docs.upbit.com/reference/listing-market-list`
- Tickers by pair: `https://global-docs.upbit.com/reference/tickers`
- Tickers by quote currency: `https://docs.upbit.com/kr/reference/tickers_by_quote`
- Minute candles: `https://global-docs.upbit.com/reference/list-candles-minutes`
- REST best practices: `https://global-docs.upbit.com/docs/rest-api-best-practice`