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