openmm

Open-source market making for AI agents. Multi-exchange trading, grid strategies, and real-time market data. CLI + MCP + Skills.

# OpenMM — Open-Source Market Making for AI Agents

OpenMM is an open-source market making framework — multi-exchange support, grid strategies, real-time market data, and automated trading. One CLI for everything.

**GitHub:** https://github.com/3rd-Eye-Labs/OpenMM
**MCP Server:** https://github.com/QBT-Labs/OpenMM-MCP
**Docs:** https://deepwiki.com/3rd-Eye-Labs/OpenMM

## What is OpenMM?

- **Multi-Exchange** — MEXC, Gate.io, Kraken, Bitget
- **Grid Trading** — Automated grid strategies with dynamic spacing, sizing, and volatility adjustment
- **Market Data** — Tickers, orderbooks, recent trades across all exchanges
- **Order Management** — Limit/market orders, cancel, list open orders
- **Cardano DEX** — Pool discovery, aggregated prices via Iris Protocol
- **CLI + MCP** — Use via command line or as MCP server for AI agents
- **Open Source** — MIT licensed, fully customizable

## Quick Start

### Option A: CLI

```bash
# Install
npm install -g @3rd-eye-labs/openmm

# Set exchange credentials as environment variables
export MEXC_API_KEY="your_api_key"
export MEXC_SECRET="your_secret_key"

# Check balances
openmm balance --exchange mexc

# Get ticker price
openmm ticker --exchange mexc --symbol BTC/USDT

# Start grid trading (dry run first)
openmm trade --strategy grid --exchange mexc --symbol INDY/USDT --dry-run
```

### Option B: MCP Server

Run `npx @qbtlabs/openmm-mcp` to start a local MCP server over stdio. This exposes all 13 tools to any MCP-compatible client.

```json
{
  "mcpServers": {
    "openmm": {
      "command": "npx",
      "args": ["@qbtlabs/openmm-mcp"],
      "env": {
        "MEXC_API_KEY": "your_key",
        "MEXC_SECRET": "your_secret"
      }
    }
  }
}
```

Only include env vars for exchanges you want to use.

### Option C: As Library

```typescript
import { OpenMM } from '@3rd-eye-labs/openmm';

const mm = new OpenMM({
  exchange: 'mexc',
  apiKey: process.env.MEXC_API_KEY,
  secret: process.env.MEXC_SECRET
});

const orderbook = await mm.getOrderbook('BTC/USDT');
```

---

## Environment Setup

Exchange credentials are configured via environment variables — keys are stored locally and never sent to the server. Add them to your `.env` file or export them in your shell:

```env
# MEXC (API key + secret)
MEXC_API_KEY=your_mexc_api_key
MEXC_SECRET=your_mexc_secret_key

# Gate.io (API key + secret)
GATEIO_API_KEY=your_gateio_api_key
GATEIO_SECRET=your_gateio_secret_key

# Bitget (API key + secret + passphrase set when creating the API key)
BITGET_API_KEY=your_bitget_api_key
BITGET_SECRET=your_bitget_secret_key
BITGET_PASSPHRASE=your_bitget_passphrase

# Kraken (API key + secret)
KRAKEN_API_KEY=your_kraken_api_key
KRAKEN_SECRET=your_kraken_secret_key
```

### Symbol Format
- Use standard format: `BTC/USDT`, `ETH/USDT`, `INDY/USDT`, `ADA/EUR`, `BTC/USD`
- The CLI automatically converts to exchange-specific format
- Kraken supports both USD/EUR fiat pairs and USDT pairs

---

## Core Tools

### Balance & Portfolio

Check account balances on any connected exchange. Query each exchange separately — there is no cross-exchange aggregate command.

```bash
# Get all balances
openmm balance --exchange mexc
openmm balance --exchange gateio
openmm balance --exchange bitget
openmm balance --exchange kraken

# Get specific asset balance
openmm balance --exchange mexc --asset BTC
openmm balance --exchange mexc --asset USDT
openmm balance --exchange kraken --asset ADA
openmm balance --exchange kraken --asset EUR

# JSON output (useful for scripting)
openmm balance --exchange mexc --json
openmm balance --exchange bitget --json
```

**Options:**
- `-e, --exchange <exchange>` — Exchange to query (required)
- `-a, --asset <asset>` — Specific asset to query (optional)
- `--json` — Output in JSON format

### Market Data

Real-time prices, orderbooks, and trade history. Use `--symbol` with the standard `BASE/QUOTE` format. Kraken uses fiat pairs like `ADA/EUR` and `BTC/USD` alongside crypto pairs.

**Ticker — current price, bid/ask, spread, volume:**

```bash
# MEXC
openmm ticker --exchange mexc --symbol BTC/USDT
openmm ticker --exchange mexc --symbol ETH/USDT --json

# Bitget (Cardano tokens)
openmm ticker --exchange bitget --symbol SNEK/USDT
openmm ticker --exchange bitget --symbol BTC/USDT --json

# Kraken (fiat pairs)
openmm ticker --exchange kraken --symbol ADA/EUR
openmm ticker --exchange kraken --symbol BTC/USD --json
```

**Order Book — bid/ask depth:**

```bash
# MEXC - BTC/USDT with default 10 levels
openmm orderbook --exchange mexc --symbol BTC/USDT

# Bitget - top 5 levels for SNEK
openmm orderbook --exchange bitget --symbol SNEK/USDT --limit 5

# Kraken - ADA/EUR with 10 levels
openmm orderbook --exchange kraken --symbol ADA/EUR --limit 10

# Gate.io - JSON output
openmm orderbook --exchange gateio --symbol BTC/USDT --json
```

**Recent Trades — latest executions with buy/sell breakdown:**

```bash
# MEXC - default 20 trades
openmm trades --exchange mexc --symbol BTC/USDT

# Bitget - 50 trades for SNEK
openmm trades --exchange bitget --symbol SNEK/USDT --limit 50

# Kraken - ADA/EUR trades
openmm trades --exchange kraken --symbol ADA/EUR

# Gate.io - JSON output
openmm trades --exchange gateio --symbol ETH/USDT --json
```

**Options (shared across ticker, orderbook, trades):**
- `-e, --exchange <exchange>` — Exchange to query (required)
- `-s, --symbol <symbol>` — Trading pair symbol (required)
- `-l, --limit <limit>` — Number of levels/trades (orderbook default: 10, trades default: 20)
- `--json` — Output in JSON format

### Order Management

Place and manage orders on any supported exchange. Orders use your exchange API credentials configured via environment variables.

```bash
# List all open orders
openmm orders list --exchange mexc
openmm orders list --exchange gateio
openmm orders list --exchange bitget

# List open orders for a specific pair
openmm orders list --exchange bitget --symbol SNEK/USDT
openmm orders list --exchange kraken --symbol ADA/EUR --limit 5

# Get specific order by ID
openmm orders get --exchange mexc --id 123456 --symbol BTC/USDT
openmm orders get --exchange bitget --id 1385288398060044291 --symbol SNEK/USDT
openmm orders get --exchange kraken --id OQN3UE-LRH6U-MPLZ5I --symbol ADA/EUR

# Create limit buy order
openmm orders create --exchange mexc --symbol BTC/USDT --side buy --type limit --amount 0.001 --price 50000
openmm orders create --exchange bitget --symbol SNEK/USDT --side buy --type limit --amount 10000 --price 0.00001
openmm orders create --exchange kraken --symbol ADA/EUR --side buy --type limit --amount 50 --price 0.45

# Create market sell order
openmm orders create --exchange mexc --symbol BTC/USDT --side sell --type market --amount 0.001
openmm orders create --exchange bitget --symbol SNEK/USDT --side sell --type market --amount 5000

# Cancel order by ID (symbol is required)
openmm orders cancel --exchange mexc --id C02__626091255599874048060 --symbol INDY/USDT
openmm orders cancel --exchange bitget --id 1385288398060044291 --symbol SNEK/USDT
openmm orders cancel --exchange kraken --id OQN3UE-LRH6U-MPLZ5I --symbol ADA/EUR
```

**Create Options:**
- `-e, --exchange <exchange>` — Exchange to use (required)
- `-s, --symbol <symbol>` — Trading pair (required)
- `--side <side>` — Order side: buy/sell (required)
- `--type <type>` — Order type: market/limit (required)
- `--amount <amount>` — Order amount in base currency (required)
- `--price <price>` — Order price (required for limit orders, ignored for market)
- `--json` — Output in JSON format

**Exchange notes:**
- **Bitget** — 6 decimal price precision for SNEK/NIGHT pairs, 2 decimal quantity precision. Requires passphrase.
- **Kraken** — Minimum order value 5 EUR/USD. Supports major fiat pairs (EUR, USD, GBP).
- **MEXC/Gate.io** — Minimum order value 1 USDT per order.

### Grid Trading

The grid strategy places buy and sell orders at intervals around the current center price. As price oscillates, orders fill and the grid automatically recreates