# 코빗 Open API LLM 가이드

> 코빗 Open API v2를 빠르게 사용할 수 있도록 구현 중심으로 정리한 가이드입니다. AI 코딩 에이전트에 이 URL을 전달하면 별도의 개발자 문서 없이도 코빗 API 클라이언트, 시세 수집기, 트레이딩 봇을 만들 수 있도록 작성되었습니다. 투자 자문이 아닙니다.

출처: https://docs.korbit.co.kr/. 엔드포인트별 전체 스펙은 문서 하단에 링크된 그룹별 Markdown 파일을 참조하세요.

운영 환경으로 전환하기 전에 이 가이드의 모든 내용을 로컬 샌드박스 — 실제 자금이 들지 않는 이 API의 모의 서버 — 에서 실행해 볼 수 있습니다. 이 가이드 끝의 로컬 샌드박스 섹션을 참조하세요.

## 통합 방법 두 가지

시작하기 전에 경로를 선택하세요:

- **공식 CLI(korbit-cli) 사용.** 요청 서명, 멱등 주문 요청, 재시도, 시계 동기화, 로컬 액션 저널 — 이 가이드가 신중히 다루라고 안내하는 바로 그 부분들 — 을 이미 처리하는 단일 정적 바이너리입니다. 환경에서 바이너리를 실행할 수 있거나 MCP를 지원한다면 이 경로가 위험이 더 낮으며, 이 가이드의 나머지는 선택적 참고 자료가 됩니다. 명령을 셸로 호출하거나 MCP 서버를 실행해 구동합니다. 설치와 사용법은 아래 [공식 CLI로 구현하기](cli.md) 섹션을 참조하세요.
- **직접 클라이언트 구현.** 셸 호출이 불가능한 런타임에 내장하거나 와이어 프로토콜을 완전히 제어해야 한다면, 이 문서의 레퍼런스를 직접 구현하세요. 필요한 모든 것이 여기 있습니다. 공식 CLI는 오픈 소스이며 참조 구현으로도 쓸 수 있습니다 — 먼저 이 문서를 따르고, 패턴의 구체적인 구현이 필요할 때 소스를 참고하세요. [참조 구현으로 소스 읽기](cli.md#참조-구현으로-소스-읽기)를 보세요.

## 에이전트 사용 지침

이 문서를 기반으로 소프트웨어를 구현할 때 따라야 할 지침:

- 이 문서를 1차 API 컨텍스트로 사용합니다. 엔드포인트 경로, HTTP method, 파라미터 이름, 인증 규칙, enum 값은 그대로 보존해야 합니다.
- API secret / private key는 그 자체로 전부입니다 — 이를 가진 사람은 누구나 거래와 출금이 가능합니다. 런타임에 환경 변수 또는 secret manager(환경이 제공하는 안전한 저장소)에서 읽고, secret·잔고·주문 수량을 코드에 하드코딩하지 않습니다.
- secret은 서명에만 흘러가고 그 외 어디에도 가지 않습니다. secret, private key, `X-KAPI-KEY`, `signature`를 로그·출력·커밋하거나 채팅/알림 채널, LLM 프롬프트, 제3자, 코빗이 아닌 호스트로 보내지 않습니다. 자격 증명이 프롬프트에 직접 붙여넣어진 경우 저장하지 말고, 런타임에 읽을 환경 변수나 secret 저장소로 제공하도록 사용자에게 요청합니다.
- 먼저 로컬 샌드박스(가이드 끝의 로컬 샌드박스 섹션 참조)에서 개발·테스트하고, 사용자가 봇의 동작을 확인한 뒤에만 운영 base URL로 전환합니다.
- 가격, 수량, 상대자산(quote currency, `symbol`의 두 번째 항목) 금액은 부동소수가 아닌 BigDecimal/문자열 기반 십진 연산으로 다룹니다.
- 요청 ID, `clientOrderId`, `orderId`, 상태 전이, API 오류 코드를 로그로 남기되, 자격 증명과 서명은 마스킹합니다.
- 네트워크 오류와 HTTP 429에는 재시도와 백오프를 적용합니다. 주문 요청은 반드시 `clientOrderId`로 멱등성을 보장한 뒤에만 재시도합니다.
- `clientOrderId`는 36자 이하, 정규식 `[0-9a-zA-Z.:_-]{1,36}`에 부합하도록 생성합니다. 신청마다 충돌에 강한 ID를 하나 발급하고(네임스페이스 + 타임스탬프/유일 접미사) **자신의 저장소에 영속화**한 뒤 재시도 시 저장된 ID를 재사용하세요 — 주문의 price/quantity에서 유도하지 마세요. `clientOrderId`는 해제되지 않으므로 반복 사용 시 거부됩니다(리질리언스 #1 참고).
- API 키는 사용자가 코빗 개발자 포털에서 직접 생성합니다 — 키 발급에는 본인 인증이 필요하므로 에이전트가 대신 생성할 수 없습니다. 설정 안내를 작성할 때는 봇에 필요한 최소 권한으로만 키를 발급하고(예: 트레이딩 봇은 조회·주문 권한만 필요하며 출금 권한은 불필요) IP 허용 목록을 설정하도록 사용자에게 안내합니다.
- 실시간 시세와 주문 이벤트는 WebSocket, 스냅샷·주문 요청·취소·재접속 후 리커버리는 REST를 사용합니다.

## Base URL

```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
```

모든 REST 시간 값은 Unix timestamp (ms) 단위입니다.

정상 REST 응답은 다음 형태입니다.

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

목록 엔드포인트는 `data`가 배열이고, 취소처럼 별도 데이터가 없는 액션은 `{"success": true}`만 반환될 수 있습니다.

## API 키와 권한

API 키는 코빗 개발자센터(https://developers.korbit.co.kr)에서 발급합니다. 권한과 IP 허용 목록을 지정할 수 있고, 발급 후 1년간 유효합니다. 권한/IP 변경은 적용에 최대 약 1분이 소요될 수 있습니다.

서명 방식은 두 가지를 지원합니다.

- `HMAC-SHA256`: 코빗이 secret key를 발급합니다. 서명은 16진수 문자열입니다.
- `ED25519`: 사용자가 발급 시 ED25519 공개키를 등록하고, 개인키로 서명합니다. 서명은 Base64이며 query/body에 넣을 때 URL 인코딩해야 합니다.

`ED25519` 키는 사용자가 직접 키 페어를 생성해 공개키만 코빗에 등록하고, 개인키는 소스 관리 밖(환경 변수 또는 secret 저장소)에 보관합니다.

Node.js:

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

const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
  publicKeyEncoding: { type: "spki", format: "pem" },   // 코빗에 등록
  privateKeyEncoding: { type: "pkcs8", format: "pem" },  // 비밀 유지, 서명에 사용
});
```

OpenSSL:

```sh
openssl genpkey -algorithm ED25519 -out private_key.pem       # 비밀 유지
openssl pkey -in private_key.pem -pubout -out public_key.pem  # 코빗에 등록
```