canonical: https://jentic.com/apis/bithumb.com/bithumb

# Bithumb API

Bithumb is South Korea's leading cryptocurrency exchange. Bithumb publishes its own OpenAPI 3.1.0 definitions, embedded per endpoint inside its reference documentation at apidocs.bithumb.com rather than as one downloadable file; the specification served here is a curated, agent-optimized Jentic variant that assembles 24 operations into a single validated document, including the still-live legacy /public paths that the current vendor documentation omits. The unified surface covers both the legacy public paths and the newer v1 surface, providing tickers, order books, transaction histories, and OHLC candles at minute, daily, weekly, and monthly granularity. Authenticated v1 and v2 endpoints support trading, account management, KRW withdrawals, and workflows specific to the Korean market.

## For AI agents

Read Bithumb market data (tickers, order books, candles) and place authenticated trades on the Korean crypto exchange. 24 endpoints across the legacy, v1, and v2 surfaces; private calls carry a per-request JWT signed from an API access key and secret key.

## Scope

Does not handle KYC onboarding, Korean banking onramps, or tax reporting - use for market data and authenticated trading on Bithumb only.

## Capabilities

- Read the latest ticker for a Korean Won pair via `/public/ticker/{order_currency}_{payment_currency}` or `/v1/ticker`
- Pull the order book for a symbol via `/public/orderbook/{order_currency}_{payment_currency}`
- Retrieve recent transactions for a symbol via `/public/transaction_history`
- Fetch OHLC candles at minute, day, week, or month granularity via `/v1/candles`/* endpoints
- List the full set of supported markets via `/v1/market/all`
- Submit authenticated trading and account management requests against the v1 and v2 private surfaces

## Use cases

### Korean Won market data ingestion

Crypto research teams ingest KRW-denominated market data because the Bithumb book often diverges from USD venues during local market hours, creating arbitrage signals known as the Kimchi Premium. The `/public/ticker`, `/public/orderbook`, and `/v1/candles` endpoints return this data without authentication, so a scheduled job can pull tickers every minute and write them to a research warehouse.

Example prompt: Pull 1-minute candles for BTC_KRW over the last 60 minutes via `/v1/candles/minutes/1` and write them to the research warehouse

### Multi-venue arbitrage feed

Traders building a multi-venue arbitrage feed include Bithumb because the KRW book frequently quotes a different price than USD venues. The `/public/ticker` endpoint returns the closing, opening, high, low, and volume fields needed for cross-venue spread monitoring, and `/v1/orderbook` gives the depth needed to size an arbitrage trade. Refresh cadences of 1-5 seconds are typical and stay within published rate limits.

Example prompt: Every second, pull `/public/ticker` for BTC_KRW and compare the close field to the BTC_USDT close on another venue; alert when the spread exceeds 2 percent

### Authenticated trading on the v1 private surface

Korean residents and licensed entities place orders on Bithumb's v1 private endpoints by signing a JWT for each request from their API access key and secret key. The same OpenAPI surface that exposes the public market data also describes the authenticated trading operations, so the same client library can read tickers and submit orders. KYC and Korean banking onboarding sit outside the API surface and must be completed in the Bithumb UI first.

Example prompt: After KYC, submit a limit buy order on BTC_KRW at 1 percent below the current ticker close and confirm acknowledgement

### Agent integration via Jentic for Korean crypto market data

An AI agent that needs a Korean Won price reference calls Jentic with the intent 'get a btc krw price'. Jentic returns the Bithumb `/public/ticker` operation with its path-parameter schema. For authenticated calls, your API access key and secret key stay in your own Jentic One instance and are used to authorize the call at execution time, so the agent can place an order without ever holding them.

Example prompt: Search Jentic for 'get btc krw ticker', load the public ticker schema, and execute against order_currency=BTC, payment_currency=KRW

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/public/ticker/{order_currency}_{payment_currency}` | Return the latest ticker for a KRW pair on the legacy public surface |
| GET | `/public/orderbook/{order_currency}_{payment_currency}` | Return the order book for a KRW pair |
| GET | `/public/transaction_history/{order_currency}_{payment_currency}` | Return recent transactions for a KRW pair |
| GET | `/v1/market/all` | List the full set of supported markets |
| GET | `/v1/candles/minutes/{unit}` | Return minute-granularity OHLC candles |
| GET | `/v1/candles/days` | Return daily OHLC candles |
| GET | `/v1/ticker` | Return the v1 ticker for a market |
| GET | `/v1/trades/ticks` | Return recent v1 trade ticks |

## Key resources

- **Public Legacy** — Tickers, order books, and transaction history under the /public path with no authentication
- **Public v1** — Markets list, candles at minute, day, week, and month, and v1 ticker and trades endpoints
- **Private** — JWT-authenticated /v1 endpoints for account and balance lookup, order placement, cancellation and lookup, and KRW withdrawals
- **Private v2** — Two JWT-authenticated /v2 endpoints that place and cancel orders in batches

## Why Jentic

- **Setup:** Wiring the Bithumb API by hand means signing a fresh JWT for every private call from your access key and secret key, targeting the api.bithumb.com host across its public and v1 endpoints, and handling retries yourself. Through Jentic you install once, import Bithumb from the API Directory, store your access key and secret key once, and your agent calls it.
- **Permission scoping:** Bithumb public endpoints put the currency pair in the URL path (`/public/ticker/{order_currency}_{payment_currency}`), while trading targets travel in the request body, so limit the agent to the operations it needs, such as reading a ticker or the market list. You choose the operations it may call, so trading actions are not included unless you add them.
- **Credential handling:** Your Bithumb API access key and secret key are stored once, encrypted, by your own Jentic One instance and used to authorize the request at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the BTC KRW ticker' or 'list Bithumb markets', and Jentic returns the matching public or authenticated operation with its input and response schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Binance API** — Global crypto exchange with broader symbol coverage and USDT pairs.
- **Kraken API** — US-friendly exchange with comparable REST trading and market data.
- **Bitfinex API** — Established exchange with USD pairs and a deep margin book.
- **Bittrex API** — Secondary exchange useful as a cross-venue reference for arbitrage feeds.

## FAQ

### Does Bithumb publish an official OpenAPI specification?

Yes, though not as a single downloadable file. Each reference page at apidocs.bithumb.com embeds an 'OpenAPI definition' JSON block declaring openapi 3.1.0, title open_api_public, version 2.1.5, and the obvious whole-document paths on that host return 404. The specification Jentic serves here is a curated, agent-optimized variant at the same version 2.1.5: it assembles 24 operations into one validated document and keeps the legacy /public paths, which still answer requests but are absent from the current vendor documentation.

### Is there a Bithumb MCP server?

Yes. Bithumb publishes an official MCP server, @bithumb-official/bithumb-mcp, as part of its AI Trade Kit, with documented setup for Claude Code, Codex, Cursor and other clients. You can also connect Bithumb directly through Jentic: your agent gets the full 24-endpoint surface from the spec without loading another server's tool definitions into its context, your access key and secret key are held by your own Jentic One instance instead of an MCP config entry or a shell profile variable, and your rules decide which operations the agent may call.

### What authentication does the Bithumb API use?

Private endpoints take an Authorization: Bearer header carrying a JWT that the caller signs for each request from a Bithumb API access key and secret key, using HMAC-SHA256 over access_key, nonce and timestamp claims, plus a SHA-512 query_hash where the request has query parameters. There is no long-lived static token to paste. Public market data endpoints need no credential at all: 13 of the 24 operations are open. Through Jentic the access key and secret key are held encrypted by your own Jentic One instance and used at execution time.

### Can I read KRW market data without an account?

Yes. The `/public/ticker`, `/public/orderbook`, `/public/transaction_history`, `/v1/market/all`, `/v1/candles`/* and `/v1/ticker` endpoints are all public. They return Korean Won pair data without authentication, so a research pipeline can pull tickers and candles without onboarding.

### What are the rate limits for the Bithumb API?

Bithumb documents per-second request caps by API type: 150 requests per second for the Public API and 140 for the Private API, with order-related requests such as create and cancel capped at 10 per second. Exceeding a cap gets the request throttled, so back off with exponential delay before retrying.

### How do I get a BTC_KRW price through Jentic?

Install Jentic One, import Bithumb from the API Directory, then search for 'get btc krw ticker', load the `/public/ticker` operation schema, and execute with order_currency=BTC and payment_currency=KRW. The response close field is the latest trade price. On the v1 surface the same figure comes from `/v1/ticker` with the markets query parameter set to KRW-BTC.

### What candle intervals does the v1 API support?

The v1 candles surface exposes minute, day, week, and month endpoints: `/v1/candles/minutes/{unit}`, `/v1/candles/days`, `/v1/candles/weeks`, and `/v1/candles/months.` The minute endpoint accepts a unit path parameter for the granularity, with an enum of 1, 3, 5, 10, 15, 30, 60 and 240 and a default of 1.

### Can I limit what my agent is allowed to do with the Bithumb API?

Yes. Because you run Jentic One yourself, you decide which Bithumb operations the agent may call, so you can allow only the public read endpoints such as `/public/ticker/{order_currency}_{payment_currency}`, `/public/orderbook`, and `/v1/market/all` while withholding the authenticated v1 and v2 trading operations. Trading and account actions are excluded unless you explicitly add them, and your bearer token is injected at execution time only for the operations you enable. This keeps a market-data agent scoped to reading KRW tickers and candles with no ability to place orders.