공식 CLI로 구현하기#

korbit-cli는 코빗 Open API v2 전체 — 시세, 트레이딩, 잔고, 입출금, 키 관리 — 를 명령으로 노출하는 단일 정적 바이너리입니다(Go, 런타임 설치 불필요). AI 에이전트를 위한 안정적인 도구 표면으로 먼저 설계되었으며, 사람이 사용하기에도 동일하게 적합합니다.

에이전트가 이를 우선해야 하는 이유: CLI는 이 가이드의 나머지 부분이 신중히 구현하라고 안내하는 일들을 이미 처리합니다 — 요청 서명, 멱등 주문 요청(모든 주문이 clientOrderId를 가지며 재시도 시 재사용되어 응답 유실이 이중 주문으로 이어지지 않음), 백오프 기반 자동 재시도, 시계 동기화, 전송 전에 검증되는 십진 안전 사이징, 그리고 수행한 모든 작업의 로컬 액션 저널. 키는 CLI 자체 키스토어에 보관되며, private key는 기기를 벗어나지 않고 출력되지도 않습니다. 이 경로를 택하면 이 가이드의 대부분은 선택적 참고 자료가 됩니다.

언제 사용하나#

CLI 사용 — 환경에서 바이너리를 실행할 수 있거나 Model Context Protocol(MCP)을 지원할 때. 대부분의 에이전트에 권장되는 기본 경로이며, 서명·멱등성·재시도 실수의 전체 부류를 설계상 제거합니다.
직접 클라이언트 구현(이 가이드의 나머지) — 셸 호출이 불가능한 런타임에 내장하거나, 와이어 프로토콜을 완전히 제어해야 할 때.

설치#

한 줄이면 됩니다 — 최신 릴리스를 내려받아 SHA-256을 검증하고 korbit을 PATH에 추가합니다:

# Linux / macOS
curl -fsSL https://docs.korbit.co.kr/install.sh | sh

# Windows (PowerShell)
irm https://docs.korbit.co.kr/install.ps1 | iex

설치된 바이너리는 korbit self update로 제자리에서 스스로 업데이트하고 korbit self doctor로 자체 상태를 점검합니다. 직접 관리하려면 릴리스 바이너리를 내려받거나 go install github.com/korbit-official/korbit-cli@latest를 실행하세요('korbit-cli' 바이너리가 생성됩니다 — 원하면 'korbit'으로 이름을 바꾸세요).

도움말과 예제의 명령 이름은 바이너리 파일명을 따르므로, 어떤 이름으로 설치하든 아래의 korbit … 예제는 그대로 유효합니다. 빠른 시작과 전체 명령 레퍼런스는 저장소를 참조하세요: https://github.com/korbit-official/korbit-cli

구동 방식#

CLI를 구동하는 방법은 두 가지이며, 모두 동일하게 검증·서명·저널링된 경로를 거칩니다:

셸 명령. 명령을 실행하고 출력을 파싱합니다 — 명령마다 하나의 기계 판독용 문서를 얻으려면 --json을 전달하세요. 모든 명령·플래그·enum·종료 코드의 전체 기계 판독용 카탈로그는 korbit commands --json으로 얻으며, 표면을 추측하기보다 이를 우선하세요.
MCP 서버. MCP를 지원하는 호스트(Codex, Claude Desktop, Claude Code 등)에서는 번들된 MCP 서버를 실행해 모든 엔드포인트를 MCP 도구로 노출합니다 — 명령과 동일한 검증·서명·재시도를 거칩니다:

korbit mcp serve --key <name>

CLI에는 여러 사용 사례 — 설정, dry-run 우선 주문 흐름, 멱등 주문, 모니터링, 자금 이동, 디버깅 — 에 걸쳐 안전한 워크플로와 안전 규칙을 가르치는 Agent Skill도 포함됩니다. CLI로 설치하세요(korbit agent skill install) — Claude, Codex 또는 둘 다.

샌드박스와 안전성#

CLI는 다음 섹션에서 설명하는 로컬 샌드박스(korbit sandbox start, --paper --fresh를 붙이면 실시간 프로덕션 시장 데이터로 페이퍼 트레이딩)를 그대로 실행할 수 있어, 운영에 손대기 전에 모의 서버에서 개발할 수 있습니다. 주문 요청은 기본적으로 멱등이며, 자금을 옮기는 쓰기 요청은 결코 자동 재시도되지 않고, 서명된 모든 호출은 로컬에 저널링되어 다시 재생할 수 있습니다.

지켜야 할 한 가지 경계: 스트리밍 봇을 만들기 위한 CLI의 스크립팅 훅은 실험적이며 변경될 수 있습니다 — 아직 이를 기반으로 장기 운영 봇을 만들지 말고, 안정 표시가 될 때까지 일회성 명령으로만 취급하세요.

참조 구현으로 소스 읽기#

이 부분은 다른 경로 — CLI를 구동하는 대신 직접 클라이언트를 구현하는 경우 — 를 위한 것입니다. korbit-cli는 오픈 소스이며, 그 소스는 이 가이드의 어려운 부분들에 대한 동작하는 참조입니다: 동일하게 서명·검증·멱등 처리되는 경로를 Go로 구현하므로, 각 관심사가 어떻게 처리되는지 읽고 포팅할 수 있습니다. 저장소: https://github.com/korbit-official/korbit-cli.

각 관심사의 위치(경로는 저장소 루트 기준):

관심사	소스
요청 서명(HMAC-SHA256 / ED25519)	`internal/korbit/client.go`
`clientOrderId` 생성(UUIDv7, 문자셋)	`internal/ids/ids.go`
주문 신청 + 응답 유실 복구	`internal/ops/op_place.go`
재시도 / 백오프, HTTP 429	`internal/korbit/retry.go`
틱 사이즈 스냅, 십진 계산	`internal/ops/tick.go`
수수료 여유분, 최소 주문 금액 검사	`internal/ops/account_ops.go`, `internal/ops/preplace.go`
WebSocket 기반 실시간 어카운트 상태 — 주문·잔고·체결, REST 폴링 불필요	`internal/stream/state/state.go`
처리중 주문 잔여수량 반영	`internal/stream/state/localhold.go`
서명 시각 동기화(`/v2/time`, 드리프트)	`internal/clock/syncer.go`
어카운트(`accountSeq`) 지정	`internal/accountseq/accountseq.go`
WebSocket 스트림, 재연결, 백필	`internal/stream/session.go`

레이트 리밋은 직접 구현해야 하는 항목입니다. korbit-cli는 레이트 리밋을 반응적으로만 처리합니다: HTTP 429가 오면 Retry-After를 준수(없으면 백오프)하되 호출당 예산 안에서만 하고, 이후 오류를 그대로 노출합니다(internal/korbit/retry.go). 요청 속도를 미리 추적해 한도 아래로 유지하지는 않습니다. 봇이 사전적 레이트 리밋 관리 — 공개·주문·취소 호출에 걸친 버킷별 예산 관리(Rate Limit 참조) — 가 필요하면 직접 클라이언트에 구현하세요.