bybit-official-trading-cli

Official Bybit V5 CLI for AI agents.

Bring Bybit trading to Claude Code, OpenClaw, Cursor, Windsurf, and Codex — every V5 endpoint, safety-first defaults, JSON I/O.

Install

npm i -g bybit-official-trading-cli@latest

Post-install auto-registers a 30-line bootstrap SKILL.md to any detected AI agent platform (~/.claude/skills/, ~/.openclaw/skills/, ~/.cursor/skills/, ~/.windsurf/skills/, ~/.codex/skills/).

Opt-out with BYBIT_CLI_NO_SKILL_REGISTER=1. Manually manage with bybit-cli install-skill / uninstall-skill.

First run (for AI agents)

bybit-cli agent-briefing

Prints ~300 words on auth setup, safety, and how to explore commands. That's the single entry point — read it and you're ready.

Auth

export BYBIT_API_KEY=<your key>
export BYBIT_API_SECRET=<your secret>
export BYBIT_ENV=testnet   # or leave unset for mainnet

For RSA (uploaded public key on Bybit):

export BYBIT_API_KEY=<your key>
export BYBIT_API_PRIVATE_KEY_PATH=/path/to/private.pem

Discovery

bybit-cli catalog                         # JSON list of ~435 commands across ~30 domains
bybit-cli <domain> <cmd> --json-schema    # JSON Schema for one command
bybit-cli <domain> <cmd> --help           # human-readable help

Safety (mainnet writes)

Guard	Flag / command
Confirmation gate	--yes (required on mainnet)
Per-order cap	--cap-usd 500
Rolling 1h total cap	--cap-usd-total-hour 2000
Rolling 1h order count	--max-orders-per-hour 20
Kill-switch	bybit-cli kill-switch / enable-switch
Restricted endpoints	Withdraw/transfer/fiat/p2p need --enable-advanced-money-ops
Idempotency	orderLinkId auto-injected (deterministic across retries)
Supply-chain check	bybit-cli verify (SHA256 vs Bybit's manifest)

Update

bybit-cli self-update              # install latest from npm
bybit-cli self-update --dry-run    # test network + permissions

Silence update-available prompts with BYBIT_CLI_NO_UPDATE_CHECK=1.

Output shape

All commands return JSON to stdout:

{"retCode":0,"retMsg":"OK","result":{...},"cli":{"env":"testnet"}}

• retCode=0 = success; non-zero = error
• cli.env — mainnet or testnet
• cli.hint — plain-English cause on error
• cli.retry — true if safe to auto-retry
• cli.nextSteps — specific commands to unblock

Add --pretty for indented output.

macOS TLS caveat

If you see fetch failed: unable to get local issuer certificate:

export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem

Node's fetch doesn't read the macOS keychain by default.

Platform support

• v1 targets macOS + Linux. Windows deferred to v2.
• Requires Node 20.6+.

Architecture

• Commands auto-generated from Bybit's OpenAPI 3.1 spec (operationId → CLI subcommand). Generator lives in the internal repo; only src/generated/ is included in this repo.
• Runtime modules under src/runtime/: credentials, signer (HMAC), rsa-signer, client, handler, plus safety layer (confirm, cap-check, kill-switch, whitelist, order-link, fingerprint).
• Distribution: single dist/index.js bundle (~1.3 MB) + skill/SKILL.md + scripts/postinstall.js.

Supply chain

bybit-cli verify fetches Bybit's official manifest at https://api.bybit.com/ai-manifest/cli/manifest and checks SHA256 of the local bundle against it. The manifest is signed by Bybit's internal release pipeline — separate credentials from npm publish (see docs/release-flow.md for the double-key trust model).

Third-party auditors can independently verify install integrity without trusting the CLI:

# 1) Fetch the official manifest
curl -sS https://api.bybit.com/ai-manifest/cli/manifest

# 2) Fetch the exact npm tarball users install
curl -sSL "$(npm view bybit-official-trading-cli@latest dist.tarball)" -o /tmp/x.tgz

# 3) Compute SHA256 of dist/index.js and compare against manifest
tar xzOf /tmp/x.tgz package/dist/index.js | shasum -a 256
tar xzOf /tmp/x.tgz package/skill/SKILL.md | shasum -a 256

License

MIT