# Korbit Open API LLM Guide

> Compact, implementation-oriented guide to Korbit Open API v2. Paste this URL into an AI coding agent so the agent can build a Korbit API client, market-data collector, or trading bot without first reading the full developer docs. This is not investment advice.

Source: https://docs.korbit.co.kr/. Full per-endpoint reference: see the per-group Markdown files linked at the bottom.

You can run everything in this guide against a local sandbox — a no-real-money mock of this API — before switching to production. See the Local Sandbox section at the end of this guide.

## Two ways to integrate

Before you start, pick a path:

- **Use the official CLI (korbit-cli).** A single static binary that already handles request signing, idempotent order placement, retries, clock-sync, and a local action journal — the exact things this guide warns you to get right. If your environment can run a binary or speak MCP, this is the lower-risk path, and the rest of this guide becomes optional reference. Drive it by shelling out to its commands or by running its MCP server. See the [Build with the official CLI](cli.md) section below for install and usage.
- **Build your own client.** If you are embedding in a runtime where shelling out isn't viable, or you want full control over the wire protocol, implement directly against the reference in this document. Everything you need is here. The official CLI is open source and doubles as a reference implementation — rely on this document first, and read that source whenever a concrete implementation of a pattern would help. See [Using the source as a reference implementation](cli.md#using-the-source-as-a-reference-implementation).

## Agent Instructions

When building software from this document:

- Use this document as the primary API context. Preserve endpoint paths, HTTP methods, parameter names, authentication rules, and enum values exactly.
- The API secret / private key is everything — whoever holds it can trade and withdraw. Read it at runtime from the environment or a secret manager (use whatever secure store your environment provides); never hard-code it, balances, or order sizes.
- Secrets flow into signing and nowhere else: never log, print, commit, or send the secret, private key, `X-KAPI-KEY`, or `signature` to any chat/notification channel, LLM prompt, third party, or non-Korbit host. If a credential is pasted to you inline, do not persist it — have the user supply it through the environment or a secret store you read at runtime.
- Develop and test against the local sandbox (see the Local Sandbox section) first; switch to the production base URLs only after the user has verified the bot's behavior.
- Use decimal-safe arithmetic (BigDecimal / strings) for prices, quantities, and KRW amounts. Do not use floating point for order math.
- Log request IDs, `clientOrderId`, `orderId`, status transitions, and API error codes — but redact credentials and signatures.
- Add retry and backoff for network failures and HTTP 429. Do not blindly retry order placement without idempotency via `clientOrderId`.
- Generate `clientOrderId` values that are at most 36 characters and match `[0-9a-zA-Z.:_-]{1,36}`. Mint one collision-resistant id per placement (namespace + a timestamp/unique suffix), **persist it in your own store**, and reuse the stored id on retry — don't derive it from the order's price/quantity, since a `clientOrderId` never frees up and a repeat would be rejected (see Resilience #1).
- API keys are created by the user in the Korbit Developers portal — key creation requires human identity verification, so an agent cannot create one. In setup instructions, tell the user to scope the key to the minimum permissions the bot needs (e.g. a trading bot needs read and order permissions, not withdrawal) and to set an IP allowlist.
- Prefer WebSocket for real-time market and order events. Use REST for snapshots, order placement, cancellation, reconciliation, and recovery after reconnect.

## Base URLs

```text
REST:        https://api.korbit.co.kr
WS public:   wss://ws-api.korbit.co.kr/v2/public
WS private:  wss://ws-api.korbit.co.kr/v2/private
```

All REST timestamps are Unix timestamps in milliseconds.

Successful REST responses look like:

```json
{"success": true, "data": {}}
```

For list endpoints `data` is an array. For action endpoints (e.g. cancel) a successful response may be `{"success": true}` with no `data`.

## API Keys and Permissions

API keys are created in the Korbit Developers portal (https://developers.korbit.co.kr). Keys can be configured with permissions and IP allowlists. Keys are valid for one year from creation. Permission / IP changes can take up to about one minute to apply.

Two signing modes are supported:

- `HMAC-SHA256`: Korbit provides a secret key. Signature is hex.
- `ED25519`: user provides an ED25519 public key at key creation and signs with the private key. Signature is Base64; URL-encode it when sending in query/body.

For an `ED25519` key you generate the pair yourself and register only the public key with Korbit; keep the private key out of source control (env var or secret store).

Node.js:

```js
import { generateKeyPairSync } from "node:crypto";

const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
  publicKeyEncoding: { type: "spki", format: "pem" },   // register this with Korbit
  privateKeyEncoding: { type: "pkcs8", format: "pem" },  // keep secret; sign with this
});
```

OpenSSL:

```sh
openssl genpkey -algorithm ED25519 -out private_key.pem       # keep secret
openssl pkey -in private_key.pem -pubout -out public_key.pem  # register with Korbit
```