korbit-cli

command module

v1.0.0 Latest Latest Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/korbit-official/korbit-cli

Links

Open Source Insights

README ¶

korbit-cli

English · 한국어

Korbit Developer Portal · API Docs

A command-line client for the Korbit Open API v2 — market data, trading, and API-key management for the Korbit cryptocurrency exchange, in a single self-contained binary.

korbit-cli is agent-first: built so AI agents can interface with Korbit reliably on your behalf — through an Agent Skill or MCP — and just as usable from your own shell.

Why korbit-cli?

Single binary. One static Go binary — no runtime, no dependencies.
Safe by default. Order sizing, decimal strings, enum values, and id rules are validated before anything is sent, and order placement is idempotent, so a retry can never place a second order.
Keys handled for you. Onboard through a registration link — no secret to paste anywhere. The private key is generated locally and never leaves your machine, with optional macOS Keychain storage.
Human and script friendly. Every command prints a clean human view; add --json (or --compact) for one machine-readable document, with predictable exit codes.

Install

One line downloads the latest release for your platform, verifies its SHA-256, and puts korbit on your PATH:

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

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

The binary then manages itself — korbit self update, korbit self doctor, korbit self uninstall.

Prefer to manage it yourself? Download a release binary, or install from source with go install github.com/korbit-official/korbit-cli@latest.

Quickstart

# 1. Generate an ED25519 keypair and start setup. The private key stays in the local keystore.
korbit setup --name trading-bot

# 2. `setup` prints a registration link — open it, review the prefilled public key,
#    permissions, and IP allowlist, and confirm with MFA. setup then detects the new key,
#    binds it, and runs a health check automatically.

Then trade:

korbit ticker btc_krw
korbit balance --currencies krw,btc
korbit order place --symbol btc_krw --side buy --type limit --price 100000000 --qty 0.001
korbit order get --symbol btc_krw --client-order-id <id from the place output>
korbit order cancel --symbol btc_krw --order-id 123456

What you can do

Area	Commands
Market data (public)	`ticker` `orderbook` `trades` `candles` `pairs` `ticksize` `currencies` `time`
Orders & fills	`order place` `order get` `order cancel` `order open` `order history` `fills`
Account	`balance` `fees` `whoami`
Deposits & withdrawals	`deposit …` `withdraw …` `krw deposit/withdraw …`
Real-time	`tui` `monitor`
Keys & setup	`setup` `doctor` `ip` `key …` `keystore …`
Local sandbox	`sandbox …`
Meta	`commands` `logs` `license` `mcp serve`

Run korbit --help for the full list and korbit <command> --help for the details of any command.

Terminal dashboard

korbit tui opens a full-screen, interactive dashboard — the quickest way to watch the Korbit market from your terminal. It streams live prices, the order book, recent trades, and a candlestick chart, and switches symbols as you browse. Sign in with --key <name> to also see your balances and open orders update live.

korbit tui                     # watch the market
korbit tui --key trading-bot   # also show your balances and orders

Real-time stream

korbit monitor streams the WebSocket API as one JSON object per line — public market data and, signed with your key, your own orders, trades, and balances. It reconnects and backfills gaps automatically, can filter or reshape the output with a built-in --jq program, and can synthesize real-time OHLCV candles (--candles) that the WebSocket API itself does not offer.

korbit monitor --symbols btc_krw --ticker --json
korbit monitor --symbols btc_krw --candles 1,60 --candle-history 100 --json
korbit monitor --symbols btc_krw --my-orders --my-assets --json

Use it from an AI agent

korbit-cli is designed to be driven by an AI agent as well as by you, via two integration paths that share the same validated, journaled, safe command surface.

Agent Skill — teaches an agent to operate the CLI safely across research, monitoring, trading, funding, setup, and debugging. Install it with korbit agent skill install --all, then korbit agent skill doctor to verify.
MCP server — korbit mcp serve exposes every endpoint as a Model Context Protocol tool for hosts like Claude and Codex. Add --read-only for market data only.

# Register the MCP server (one key per server)
claude mcp add --transport stdio korbit -- korbit mcp serve --key trading
codex  mcp add korbit -- korbit mcp serve --key trading

For Claude Desktop without a terminal, install the server as a drag-and-drop .mcpb bundle from the release page — it includes the binary.

Test without real money

Dry-run — add --dry-run to any command to print the exact request that would be sent, without sending it. On order place it also runs a customer-protection preflight that warns about risky orders (slippage, fat-finger prices, unfillable sizes, and more).
Local sandbox — korbit sandbox start runs a single-file local mock of the API with a real signature verifier, so you can exercise signing and the full order flow without touching production or real funds:

korbit sandbox start          # download + run the sandbox, import its seeded key
korbit whoami --key sandbox    # signed calls now hit the local mock
korbit sandbox stop

Add --paper --fresh to sandbox start for paper trading: market data is mirrored live from production Korbit while fills stay simulated — real prices, no real money. By default only the bundle's built-in fixture pairs are seeded; add --all-pairs (korbit sandbox start --paper --all-pairs --fresh) to seed every launched production pair from a live snapshot, so the sandbox carries production's tradable pair set. The first such start takes a few seconds longer; the snapshot is then cached beside the database, so repeated starts (including --fresh) reseed in well under a second. --fresh recreates the disposable sandbox database, which is also how you switch back; to restart an existing paper sandbox keeping its balances and orders, run korbit sandbox start --paper without --fresh (korbit sandbox start --help has the detail).

The sandbox bundle is separately licensed (Korbit's own software) — korbit sandbox license prints the terms; use it for local development and testing only.

Safety

Idempotent placement. Every order place carries a clientOrderId (auto-minted and echoed). Reuse it via --client-order-id to retry the same order — Korbit processes it once, and the CLI reconciles rather than blindly resending.
Client-side sizing. limit → --price + --qty; market/best buy → --amt (KRW to spend); market/best sell → --qty. Amounts are decimal strings, passed through untouched — no floating point.
No accidental double-spends. Reads and cancels auto-retry on transient errors; money-moving writes (order place, withdrawals, KRW transfers) are never auto-retried.

Keys & storage

You can add multiple keys; select one per command with --key (or set a default with korbit key use). Both ED25519 and HMAC-SHA256 keys are supported. Private keys are stored encrypted on disk by default, or in your OS keychain, and all state lives under ~/.korbit-cli/. Manage keys with korbit key … and move them between backends with korbit keystore migrate.

License

Licensed under the Apache License, Version 2.0 (SPDX-License-Identifier: Apache-2.0). See LICENSE for the full text. korbit license prints this notice with links to the license, disclaimer, and Open API terms.

Disclaimer — read DISCLAIMER.md before using this tool.

The local sandbox bundle (korbit sandbox …) is not covered by this license — it is Korbit's proprietary software under its own separate terms. The CLI only downloads and runs it from the Official Source; read its terms with korbit sandbox license.

Documentation ¶

Overview ¶

Command korbit is a command-line client for the Korbit Open API v2 — market data, ED25519-signed trading, and key management — built as a stable, JSON-in/JSON-out tool surface for AI agents.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
internal
accountseq Package accountseq centralizes the accountSeq selection policy shared by REST operations and private WebSocket subscriptions.	Package accountseq centralizes the accountSeq selection policy shared by REST operations and private WebSocket subscriptions.
agentskill Package agentskill installs and inspects the bundled Korbit Agent Skill on disk.	Package agentskill installs and inspects the bundled Korbit Agent Skill on disk.
botapi Package botapi is the monitor command's JavaScript bot runtime: a goja event loop on a dedicated script goroutine, an asynchronous Promise-based korbit.* API generated from the command spec, and a script-local SQLite db.* surface — so a small script passed via --init/--where/--on can be a complete trading bot.	Package botapi is the monitor command's JavaScript bot runtime: a goja event loop on a dedicated script goroutine, an asynchronous Promise-based korbit.* API generated from the command spec, and a script-local SQLite db.* surface — so a small script passed via --init/--where/--on can be a complete trading bot.
callrec Package callrec is the single home of the CLI's journaling POLICY plus the journal-backed korbit.Recorder that enacts it.	Package callrec is the single home of the CLI's journaling POLICY plus the journal-backed korbit.Recorder that enacts it.
candles Package candles derives live OHLC candle series from the two sources the Korbit API offers — the REST candles endpoint and the public trade stream — because the API has no candle WebSocket channel.	Package candles derives live OHLC candle series from the two sources the Korbit API offers — the REST candles endpoint and the public trade stream — because the API has no candle WebSocket channel.
cli Package cli wires the declarative spec into a cobra command tree, parses and validates input, and enforces the output contract: one JSON document on stdout, diagnostics and one structured error on stderr, and the documented exit codes.	Package cli wires the declarative spec into a cobra command tree, parses and validates input, and enforces the output contract: one JSON document on stdout, diagnostics and one structured error on stderr, and the documented exit codes.
cli/agentskillcmd Package agentskillcmd implements the `agent skill …` builtins: install the bundled Agent Skill onto disk for each supported agent, and a doctor that reports install/drift/PATH health.	Package agentskillcmd implements the `agent skill …` builtins: install the bundled Agent Skill onto disk for each supported agent, and a doctor that reports install/drift/PATH health.
cli/clienv Package clienv is the seam between the cli command tree and the command subpackages it dispatches into.	Package clienv is the seam between the cli command tree and the command subpackages it dispatches into.
cli/doctorcmd Package doctorcmd implements the `doctor` command: a read-only assessment of whether the current key configuration can reach and trade on Korbit, with a fix named for every problem.	Package doctorcmd implements the `doctor` command: a read-only assessment of whether the current key configuration can reach and trade on Korbit, with a fix named for every problem.
cli/keymgmtcmd Package keymgmtcmd implements the key & keystore management commands — `setup`, the `key` group (add/bind/use/rename/remove/list/show/set-base-url/ set-default-account-seq), and the `keystore` group (status/migrate/default).	Package keymgmtcmd implements the key & keystore management commands — `setup`, the `key` group (add/bind/use/rename/remove/list/show/set-base-url/ set-default-account-seq), and the `keystore` group (status/migrate/default).
cli/monitorcmd Package monitorcmd implements the `monitor` command — the CLI's one streaming command and its experimental JavaScript bot runtime.	Package monitorcmd implements the `monitor` command — the CLI's one streaming command and its experimental JavaScript bot runtime.
cli/probe Package probe holds the endpoint-soundness and reachability primitives the cli's onboarding and diagnostic commands share (ip, doctor, setup, key set-base-url, mcp): base-URL validation, the public-IP probe and its allowlist report, the REST/WebSocket reachability smoke test, and the IP-allowlist error classifier.	Package probe holds the endpoint-soundness and reachability primitives the cli's onboarding and diagnostic commands share (ip, doctor, setup, key set-base-url, mcp): base-URL validation, the public-IP probe and its allowlist report, the REST/WebSocket reachability smoke test, and the IP-allowlist error classifier.
cli/sandboxcmd Package sandboxcmd implements the `sandbox …` builtin group: the lifecycle manager for the local Korbit API Sandbox.	Package sandboxcmd implements the `sandbox …` builtin group: the lifecycle manager for the local Korbit API Sandbox.
cli/selfcmd Package selfcmd implements the `self install\|update\|uninstall\|doctor` builtins: the CLI-facing layer over internal/selfupdate.	Package selfcmd implements the `self install\|update\|uninstall\|doctor` builtins: the CLI-facing layer over internal/selfupdate.
cli/setupui Package setupui is the interactive terminal front-end for the `setup` command.	Package setupui is the interactive terminal front-end for the `setup` command.
cli/textout Package textout holds the command-agnostic human-output toolkit: the table, key/value and number-formatting primitives the cli's human-readable mode is built from, plus the TextFormatter seam a command's result type implements to render itself.	Package textout holds the command-agnostic human-output toolkit: the table, key/value and number-formatting primitives the cli's human-readable mode is built from, plus the TextFormatter seam a command's result type implements to render itself.
cli/tuicmd Package tuicmd implements the `tui` command — the interactive, full-screen trading terminal (the human sibling of monitor).	Package tuicmd implements the `tui` command — the interactive, full-screen trading terminal (the human sibling of monitor).
clock Package clock holds one session's (or process's) estimate of the Korbit server clock — the single piece of shared state behind every signed request — and the one operation that measures and installs it.	Package clock holds one session's (or process's) estimate of the Korbit server clock — the single piece of shared state behind every signed request — and the one operation that measures and installs it.
cmdmeta Package cmdmeta is the command-surface vocabulary AND the per-value validation engine over it, shared by the operation catalog and the command descriptors: value kinds, the flag and positional shapes, sections, response-field hints, auth, the safety classification, and NormalizeValue/CoerceValue (validate one value against its kind).	Package cmdmeta is the command-surface vocabulary AND the per-value validation engine over it, shared by the operation catalog and the command descriptors: value kinds, the flag and positional shapes, sections, response-field hints, auth, the safety classification, and NormalizeValue/CoerceValue (validate one value against its kind).
config Package config resolves the CLI home directory and loads config.json.	Package config resolves the CLI home directory and loads config.json.
fslock Package fslock provides an advisory, cross-process file lock used to serialize read-modify-write cycles over the CLI's on-disk state.	Package fslock provides an advisory, cross-process file lock used to serialize read-modify-write cycles over the CLI's on-disk state.
i18n Package i18n owns every locale decision in the program: which display languages exist, which one is active, and how a localized string is looked up.	Package i18n owns every locale decision in the program: which display languages exist, which one is active, and how a localized string is looked up.
ids Package ids mints client order ids and enforces the Korbit clientOrderId charset.	Package ids mints client order ids and enforces the Korbit clientOrderId charset.
indicators Package indicators provides technical-analysis indicator helpers — moving averages, oscillators, bands, and volume studies — for trading bots.	Package indicators provides technical-analysis indicator helpers — moving averages, oscillators, bands, and volume studies — for trading bots.
journal Package journal is the CLI's local action journal: a SQLite database under the CLI home that records what the tool did, in three linked tables.	Package journal is the CLI's local action journal: a SQLite database under the CLI home that records what the tool did, in three linked tables.
jqfilter Package jqfilter compiles a jq program (github.com/itchyny/gojq) and runs it over a stream of JSON documents to filter and/or transform them.	Package jqfilter compiles a jq program (github.com/itchyny/gojq) and runs it over a stream of JSON documents to filter and/or transform them.
keys Package keys manages named API keys: the registry (keys.json) and the lifecycle commands over it (add/bind/use/remove/rename/set-base-url/resolve).	Package keys manages named API keys: the registry (keys.json) and the lifecycle commands over it (add/bind/use/remove/rename/set-base-url/resolve).
keystore Package keystore stores private key material, addressed by key name.	Package keystore stores private key material, addressed by key name.
keystore/keystoretest Package keystoretest provides an in-memory keystore.Keystore for tests that need to exercise migration and error paths without touching a platform keyring (which isn't available or deterministic in unit tests).	Package keystoretest provides an in-memory keystore.Keystore for tests that need to exercise migration and error paths without touching a platform keyring (which isn't available or deterministic in unit tests).
korbit Package korbit is the wire layer (L0) plus the L1 primitive client for the Korbit Open API v2.	Package korbit is the wire layer (L0) plus the L1 primitive client for the Korbit Open API v2.
logging Package logging is the CLI's leveled diagnostic logger, built on log/slog.	Package logging is the CLI's leveled diagnostic logger, built on log/slog.
netbind Package netbind resolves the outbound networking flags (--bind / --family) into a Binder that pins where the CLI's connections come from and which IP family they use, so a customer on a multi-homed host can pin traffic to a link (reliability) and spread calls across source IPs to raise the effective rate limit (the public endpoints are rate-limited per source IP).	Package netbind resolves the outbound networking flags (--bind / --family) into a Binder that pins where the CLI's connections come from and which IP family they use, so a customer on a multi-homed host can pin traffic to a link (reliability) and spread calls across source IPs to raise the effective rate limit (the public endpoints are rate-limited per source IP).
ops Package ops is the L2 operations layer: the Korbit Open API v2 with THIS CLI's guarantees layered on top of the L1 primitive client (internal/korbit).	Package ops is the L2 operations layer: the Korbit Open API v2 with THIS CLI's guarantees layered on top of the L1 primitive client (internal/korbit).
output Package output owns the CLI's stdout/stderr contract.	Package output owns the CLI's stdout/stderr contract.
progname Package progname holds the program's invoked name — the basename of the executable as it was run.	Package progname holds the program's invoked name — the basename of the executable as it was run.
rawapi Package rawapi is a statically-typed layer over the wire client with one function per REST endpoint.	Package rawapi is a statically-typed layer over the wire client with one function per REST endpoint.
sandbox Package sandbox is the lifecycle manager for the local Korbit API Sandbox: it runs the single-file mock under Deno — the CLI-managed pinned Deno by default, or a system `deno` — handing Deno the Official-Source bundle URL to fetch and cache itself, runs/stops/inspects it as a managed background server, and imports the seeded ED25519 key into the normal keystore so a user goes from nothing to a signed, working local exchange in one command.	Package sandbox is the lifecycle manager for the local Korbit API Sandbox: it runs the single-file mock under Deno — the CLI-managed pinned Deno by default, or a system `deno` — handing Deno the Official-Source bundle URL to fetch and cache itself, runs/stops/inspects it as a managed background server, and imports the seeded ED25519 key into the normal keystore so a user goes from nothing to a signed, working local exchange in one command.
sandbox/deno Package deno manages a pinned, checksum-verified Deno runtime that korbit-cli downloads on demand to run the local API sandbox.	Package deno manages a pinned, checksum-verified Deno runtime that korbit-cli downloads on demand to run the local API sandbox.
selfupdate Package selfupdate owns the on-disk install layout and the self-update mechanics behind the `self install\|update\|uninstall\|doctor` commands.	Package selfupdate owns the on-disk install layout and the self-update mechanics behind the `self install\|update\|uninstall\|doctor` commands.