# cdcx

A CLI, MCP server, and terminal dashboard for the [Crypto.com Exchange API](https://exchange-docs.crypto.com/exchange/v1/rest-ws/index.html). Single binary, zero runtime dependencies.

95 REST endpoints across 11 API groups, dynamically generated from the Crypto.com Exchange OpenAPI spec. Real-time WebSocket streaming. Full-screen TUI dashboard. Paper trading. Works as a standalone CLI, an MCP tool server for AI agents, or an interactive terminal.

> **Caution:** This software interacts with the live Crypto.com Exchange and can execute real financial transactions. Test with `cdcx paper` before using real funds.

## Install

```bash
curl -sSfL https://raw.githubusercontent.com/crypto-com/cdcx-cli/main/install.sh | sh
```

**From source:**

```bash
cargo install --git https://github.com/crypto-com/cdcx-cli.git --bin cdcx
```

---

## Why cdcx?

### For AI Agents

Every response is structured JSON. 95 MCP tools with typed parameters, enum validation, safety enforcement, and schema discovery — all generated from the OpenAPI spec at runtime. Your LLM can trade, analyze markets, manage positions, and orchestrate trading bots without custom tooling.

```bash
cdcx mcp config --enable trade,account
```

Compatible with Claude Code, Cursor, Claude Desktop, Codex, Github Copilot, Gemini CLI, and other MCP clients. Includes 13 agent skill files in `skills/` for guided workflows.

Things you can ask your AI agent:

> *"What's the current BTC price and 24h volume?"*

> *"Paper trade BTC for a few rounds and show me the P&L"*

> *"Place an OTOCO bracket on BTC_USDT: entry at 70000, stop-loss at 65000, take-profit at 75000"*

### For the Command Line

Every endpoint is a command. `--help` on everything. `--dry-run` to preview. `--output json` for scripting. Tab completion. Profiles for multi-account.

```bash
cdcx market ticker BTC_USDT -o table
cdcx trade order BUY BTC_USDT 0.001 --dry-run
cdcx stream ticker BTC_USDT ETH_USDT
cdcx paper buy BTC_USDT --quantity 0.01
```

### For the Dashboard

Full-screen terminal trading interface. 6 tabs, real-time streaming, candlestick charts, heatmap mode, split screen, order workflows. Zero flicker.

```bash
cdcx tui
```

Press `p` to toggle paper mode. Press `O` for OTOCO bracket orders. Press `?` for all shortcuts.

---

## Quick Start

Public market data works without credentials:

```bash
cdcx market ticker BTC_USDT -o table
cdcx market book BTC_USDT --depth 10 -o table
cdcx market candlestick BTC_USDT --timeframe 1h -o table
```

Paper trading works without credentials:

```bash
cdcx paper init --balance 50000
cdcx paper buy BTC_USDT --quantity 0.01
cdcx paper positions
cdcx paper balance
```

For trading, set credentials:

```bash
export CDCX_API_KEY="your-key"
export CDCX_API_SECRET="your-secret"
cdcx account summary
```

---

## MCP Server

Expose the Exchange API as MCP tools for AI agents:

```bash
cdcx mcp                                    # Start server (reads config)
cdcx mcp config                             # Show current config
cdcx mcp config --enable trade,account      # Enable service groups
cdcx mcp config --allow-dangerous           # Allow withdrawals, cancel-all
cdcx mcp config --reset                     # Reset to defaults (market only)
```

Service groups: `market`, `account`, `trade`, `advanced`, `margin`, `staking`, `funding`, `fiat`, `otc`, `bot`, `stream`

Configuration is stored in `~/.config/cdcx/mcp.toml` and persists across updates.

> **Note:** `account` also exposes historical endpoints (orders, trades, transactions). `funding` covers wallet deposit/withdrawal endpoints. Paper trading is a CLI-only feature and has no MCP tools.

### Safety Model

| Tier | Behavior | Examples |
|------|----------|---------|
| **read** | No confirmation | `market ticker`, `market book` |
| **sensitive_read** | No confirmation | `account summary`, `bot list` |
| **mutate** | Requires `acknowledged: true` | `trade order`, `bot create`, `bot pause` |
| **dangerous** | Requires `--allow-dangerous` | `trade cancel-all`, `bot terminate`, `wallet withdraw` |

### Plugin Installation

Install cdcx as a one-click plugin from your AI coding tool's marketplace.

**Claude Code:**

```bash
claude plugin marketplace add crypto-com/cdcx-cli
claude plugin install cdcx-cli@cdcx-cli
```

**Codex:**

1. Open Plugins and click **+ Add more**:

   ![Codex plugin list](site/img/codex-plugin-list.png)

2. Add the marketplace source `crypto-com/cdcx-cli`:

   ![Add marketplace](site/img/codex-add-marketplace.png)

3. Enable the `cdcx-cli` plugin — it appears under your marketplace dropdown:

   ![cdcx-cli enabled](site/img/codex-cdcx-cli.png)

Or via the CLI:

```bash
codex plugin marketplace add crypto-com/cdcx-cli
```

**Other:** Open Settings > MCP Servers, add:

```json
{
  "cdcx": {
    "command": "npx",
    "args": ["-y", "@cryptocom/cdcx-cli@latest", "mcp"]
  }
}
```

Then configure services with `cdcx mcp config --enable trade,account`.

### Switching Profiles for MCP

The MCP server reads `CDCX_PROFILE` from the environment to select which config profile to use. Set it in your MCP client's env config.

**Claude Code** (`~/.claude/settings.json`):

```json
{
  "env": {
    "CDCX_PROFILE": "uat"
  }
}
```

**Other MCP clients** — add `"env"` to the server definition:

```json
{
  "cdcx": {
    "command": "npx",
    "args": ["-y", "@cryptocom/cdcx-cli@latest", "mcp"],
    "env": {
      "CDCX_PROFILE": "prod"
    }
  }
}
```

This selects the matching `[profiles.<name>]` section from `~/.config/cdcx/config.toml`.

### Agent Skills

13 skill files in `skills/` covering:

| Skill | Purpose |
|-------|---------|
| `cdcx-market-intel` | Market analysis and price discovery |
| `cdcx-portfolio-intel` | Portfolio analysis and risk assessment |
| `cdcx-execution` | Order placement with safety checks |
| `cdcx-advanced` | OCO, OTO, OTOCO contingency orders |
| `cdcx-paper-strategy` | Paper trading strategy testing |
| `cdcx-wallet-ops` | Deposits, withdrawals, network management |
| `cdcx-auth-setup` | Credential configuration |
| `cdcx-autonomy-levels` | Safety tier configuration |
| `cdcx-check-balance` | Balance and credential verification |
| `cdcx-place-limit-order` | Limit order workflow with preflight checks |
| `cdcx-isolated-margin` | Isolated margin trading (equity/RWA perpetuals) |
| `recipe-morning-brief` | Daily market briefing workflow |
| `recipe-emergency-flatten` | Emergency position flattening |

---

## CLI Reference

### Market Data (public)

```bash
cdcx market ticker                     # All tickers
cdcx market ticker BTC_USDT            # Single instrument
cdcx market book BTC_USDT --depth 20   # Order book
cdcx market trades BTC_USDT            # Recent trades
cdcx market candlestick BTC_USDT --timeframe 1h
cdcx market instruments                # All instruments
```

### Trading (requires auth)

```bash
cdcx trade order BUY BTC_USDT 0.001 --type LIMIT --price 50000
cdcx trade open-orders
cdcx trade cancel --order-id ORDER_ID
cdcx trade cancel-all
```

### Advanced Orders

```bash
cdcx advanced create-oto --instrument-name BTC_USDT ...
cdcx advanced create-otoco --instrument-name BTC_USDT ...
cdcx advanced open-orders
```

### Trading Bots

```bash
cdcx bot create DCA --notify-on-bot-change true --json '{"settings": {"is_basket": false, "allocations": [{"instrument_name": "BTC_USDT", "allocated_percentage": "100"}], "investment_currency": "USDT", "side": "BUY", "type": "MARKET", "quantity": "0.01", "investment_frequency_mode": "FIXED_DURATION", "investment_frequency": 300000, "max_order": "10"}}'
cdcx bot list --bot-types DCA --state RUNNING
cdcx bot pause 123 --bot-type DCA
cdcx bot resume 123 --bot-type DCA
cdcx bot update 123 --bot-type GRID --json '{"settings": {"stop_price": "50000"}}'
cdcx bot executions 123
cdcx bot terminate 123 --bot-type DCA
```

Bot types: `DCA`, `TWAP`, `GRID`, `FUNDING_ARBITRAGE`. Complex settings are passed via `--json`.

### Paper Trading

Local paper trading engine with live market prices. No auth required.

```bash
cdcx paper init --balance 50000        # Create account
cdcx paper buy BTC_USDT --quantity 0.01   # Market buy
cdcx paper sell BTC_USDT --quantity 0.01  # Market sell
cdcx paper buy BTC_USDT --quantity 0.01 --price 65000  # Limit buy
cdcx paper positions                   # Portfolio + P&L
cdcx paper history                     # Trade history
cdcx paper balance                     # Account balance
cdcx paper reset --balance 100000      # Reset account
```

### Streaming (WebSocket)

```bash
cdcx stream ticker BTC_USDT ETH_USDT  # Real-time tickers
cdcx stream book BTC_USDT             # Order book updates
cdcx stream trades BTC_USDT           # Trade executions
cdcx stream orders                    # Your order updates (auth)
cdcx stream positions                 # Position changes (auth)
```

### Account

```bash
cdcx account summary                   # Balances
cdcx account positions                 # Open positions
cdcx trade fee-rate                    # Fee rates
```

### History / Wallet / Staking / Fiat / Margin

```bash
cdcx history orders                    cdcx wallet deposit-address --currency BTC
cdcx history trades                    cdcx wallet deposit-history
cdcx history transactions              cdcx wallet withdrawal-history
cdcx staking instruments               cdcx fiat accounts
cdcx staking positions                 cdcx margin transfer --dry-run
```

---

## Interactive Dashboard

```bash
cdcx tui                               # Launch
cdcx tui --theme amber                 # With theme
cdcx tui --setup                       # Setup wizard
```

### Features

- **6 tabs:** Market, Portfolio, Orders, History, Watchlist, Positions
- **Real-time streaming:** WebSocket ticker, order book, candlestick, trade channels
- **Sparklines:** 24h Braille-dot price charts inline per instrument
- **Heatmap mode:** rows glow red/green by 24h performance
- **Candlestick charts:** volume bars, 9 timeframes, streaming updates, time axis
- **Multi-chart compare:** up to 4 instruments side by side
- **Split screen:** table + chart, auto-updates on selection
- **Order book detail:** cumulative depth bars, buy/sell pressure bar
- **Order workflows:** place order, OCO, OTOCO, cancel
- **Live portfolio P&L:** session P&L in status bar, cash vs position breakdown in Portfolio tab
- **Paper mode:** toggle `p` to trade against local paper engine with unrealized/realized P&L
- **Instrument picker:** search-as-you-type overlay
- **Price alerts:** set thresholds with terminal bell notification
- **Ticker tape:** scrolling top movers banner
- **6 themes:** terminal-pro, cyber-midnight, monochrome, neon, micky-d, amber + custom TOML
- **Mouse support:** click to select, scroll, double-click to detail
- **Export:** `y` copies table as CSV to clipboard

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `1`-`6` / `Tab` | Switch tabs |
| `Enter` | Instrument detail (book + trades) |
| `k` | Candlestick chart |
| `m` | Compare charts (up to 4) |
| `h` | Toggle heatmap |
| `i` | Instrument spotlight |
| `\` | Split screen (table + chart) |
| `[ / ]` | Cycle chart timeframe |
| `s / S` | Sort / reverse sort |
| `/` | Search instruments |
| `t` | Place order |
| `o` | OCO order (stop-loss + take-profit) |
| `O` | OTOCO order (entry + SL + TP) |
| `c` | Cancel orders |
| `p` | Toggle LIVE / PAPER mode |
| `!` | Set price alert |
| `y` | Copy to clipboard (CSV) |
| `,` | Settings (theme, MCP services) |
| `?` | Help overlay |
| `q` | Quit |

---

## Configuration

### Credentials

Resolved in order: flags > `CDCX_API_KEY`/`CDCX_API_SECRET` env > `CDC_API_KEY`/`CDC_API_SECRET` env > `~/.config/cdcx/config.toml` profile.

Empty or whitespace-only env vars are treated as unset and fall through to the config file.

```bash
cdcx setup                             # Interactive credential setup
cdcx --profile uat account summary     # Use named profile
cdcx auth list                         # Show all profiles with auth status
```

### MCP Config

`~/.config/cdcx/mcp.toml` (managed via `cdcx mcp config` or TUI settings):

```toml
services = ["market", "trade", "account"]
allow_dangerous = false
```

### TUI Config

`~/.config/cdcx/tui.toml`:

```toml
theme = "terminal-pro"
tick_rate_ms = 250
watchlist = ["BTC_USDT", "ETH_USDT", "SOL_USDT", "CRO_USDT"]

[themes.my-theme]
bg = "#1a1a2e"
accent = "#00d4ff"
positive = "#00ff88"
negative = "#ff4444"
```

### Global Flags

| Flag | Description |
|------|-------------|
| `-o, --output` | Output format: `json` (default), `table`, `ndjson` |
| `--dry-run` | Preview request without executing |
| `--env` | Environment: `production` (default), `uat` |
| `--profile` | Config profile name |
| `--yes` | Skip confirmation prompts |
| `-v, --verbose` | Verbose output |

---

## Architecture

```
crates/cdcx-core/       # API client, auth, signing, schema, OpenAPI parser, paper engine
crates/cdcx-cli/        # CLI binary, dispatch, MCP server, setup
crates/cdcx-tui/        # Terminal dashboard (ratatui + crossterm)
schemas/                # CLI overlay files (command aliases, positional args, defaults)
skills/                 # Agent skill files for guided workflows
site/                   # Marketing site (single HTML file)
```

- **OpenAPI sole source:** All API commands and MCP tools are generated from the exchange's OpenAPI spec at runtime (24h cache). Thin TOML overlay files in `schemas/` add CLI-only metadata (positional args, defaults, command aliases). No hand-maintained endpoint definitions.
- **Single binary:** ~11MB, no runtime dependencies
- **Zero flicker:** ratatui double-buffer character-level diffing

## Development

```bash
cargo test                             # Run all tests
cargo build --release                  # Build release binary
cargo run -- market ticker BTC_USDT    # Run from source
cargo run -- tui                       # TUI from source
```

### Git hooks

Install once per clone to catch CI failures locally:

```bash
./hooks/install.sh
```

- `pre-commit` runs `cargo fmt --check` + `cargo clippy -- -D warnings`
- `pre-push` runs the full test suite (skipped for doc-only pushes)

The toolchain is pinned to `stable` via `rust-toolchain.toml`; run `rustup update stable` if your local clippy is older than CI's.

## License

Dual-licensed under [MIT](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE).