Openmm

Name: Openmm
Author: dvcrn

ASecurity

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

33 stars

0 votes

0 copies

2 views

Added 9/5/2026

businesstypescriptgoshellbashgitapidocumentation

Works with

cliapimcp

Security Analysis

A96/100

mediumInstalls packages at runtime which could introduce malicious dependencies

Scanned 9/5/2026

Install to Claude Code

$npx -y skills add dvcrn/openclaw-skills-marketplace --skill openmm --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Openmm?

Add the live security badge to your README — it updates automatically with every re-scan.

[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/dvcrn-openmm/badge)](https://www.skillsdirectory.com/skills/dvcrn-openmm)

More formats (shields.io, HTML) on the badges page.

Download with Pro

Files

SKILL.md

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

> Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links.

# 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 — capturing the spread on each cycle. Total orders = levels x 2.

```bash
# Start grid with defaults (5 levels, 2% spacing, $50 per order)
openmm trade --strategy grid --exchange mexc --symbol INDY/USDT

# Dry run — preview the grid without placing real orders
openmm trade --strategy grid --exchange bitget --symbol SNEK/USDT --dry-run

# Custom grid configuration
openmm trade --strategy grid --exchange mexc --symbol INDY/USDT \
  --levels 5 \
  --spacing 0.02 \
  --size 50 \
  --max-position 0.6 \
  --safety-reserve 0.3

# Geometric spacing — tighter near center, wider at edges
openmm trade --strategy grid --exchange kraken --symbol BTC/USD \
  --levels 10 \
  --spacing 0.005 \
  --spacing-model geometric \
  --spacing-factor 1.5 \
  --size-model pyramidal \
  --size 50

# Volatility-based spread adjustment — grid widens in volatile markets
openmm trade --strategy grid --exchange mexc --symbol INDY/USDT \
  --levels 10 \
  --spacing 0.005 \
  --spacing-model geometric \
  --spacing-factor 1.3 \
  --size-model pyramidal \
  --size 5 \
  --volatility

# Volatility with custom thresholds (tighter sensitivity)
openmm trade --strategy grid --exchange kraken --symbol SNEK/EUR \
  --levels 5 \
  --spacing 0.01 \
  --size 5 \
  --volatility \
  --volatility-low 0.01 \
  --volatility-high 0.03

# Load configuration from a JSON profile
openmm trade --strategy grid --exchange gateio --symbol SNEK/USDT \
  --grid-profile ./profiles/balanced-geometric.json
```

**Strategy output on startup:**
```
Starting Trading Strategy
Strategy: GRID
Exchange: KRAKEN
Symbol: BTC/USD
Grid Levels: 10 per side (20 total)
Grid Spacing: 0.3%
Spacing Model: geometric
Spacing Factor: 1.3
Size Model: pyramidal
Order Size: $50
Max Position: 80%
Safety Reserve: 20%

Strategy initialized successfully
Grid Configuration:
  Levels: 10 per side (20 total orders)
  Spacing Model: geometric
  Base Spacing: 0.30%
  Spacing Factor: 1.3
  Size Model: pyramidal
  Base Size: $50
Strategy is now running!
Press Ctrl+C to stop the strategy gracefully
```

**Graceful shutdown:** Press `Ctrl+C`. The system cancels all open orders, disconnects from the exchange, and displays final status.

**Required Parameters:**
- `--strategy grid` — Specifies grid trading strategy
- `--exchange <exchange>` — Exchange to trade on (mexc, bitget, gateio, kraken)
- `--symbol <symbol>` — Trading pair (e.g., INDY/USDT, SNEK/USDT, ADA/EUR)

**Grid Parameters:**
- `--levels <number>` — Grid levels each side (default: 5, max: 10, total orders = levels x 2)
- `--spacing <decimal>` — Base price spacing between levels (default: 0.02 = 2%)
- `--size <number>` — Base order size in quote currency (default: 50)
- `--confidence <decimal>` — Minimum price confidence to trade (default: 0.6)
- `--deviation <decimal>` — Price deviation to trigger grid recreation (default: 0.015)
- `--debounce <ms>` — Delay between grid adjustments (default: 2000ms)
- `--max-position <decimal>` — Maximum position size as % of balance (default: 0.8)
- `--safety-reserve <decimal>` — Safety reserve as % of balance (default: 0.2)
- `--dry-run` — Simulate trading without placing real orders

**Dynamic Grid Parameters:**
- `--spacing-model <model>` — linear, geometric, or custom (default: linear)
- `--spacing-factor <number>` — Geometric spacing multiplier per level (default: 1.3)
- `--size-model <model>` — flat, pyramidal, or custom (default: flat)
- `--grid-profile <path>` — Load complete grid configuration from a JSON profile

**Volatility Parameters:**
- `--volatility` — Enable volatility-based dynamic spread adjustment
- `--volatility-low <decimal>` — Low volatility threshold (default: 0.02). Below this, spacing stays normal.
- `--volatility-high <decimal>` — High volatility threshold (default: 0.05). Above this, spacing is widened maximally.

**Exchange notes for grid:**
- **MEXC/Gate.io** — Minimum 1 USDT per order. Ensure `--size` / `--levels` >= 1.
- **Bitget** — Minimum 1 USDT per order. Price precision: 6 decimals for SNEK/NIGHT. Requires passphrase.
- **Kraken** — Minimum 5 EUR/USD per order. Ensure `--size` / `--levels` >= 5.

### Cardano DEX Integration

OpenMM integrates with Cardano DEX liquidity pools via the Iris Protocol. Supported tokens: **INDY** (Indigo Protocol), **SNEK** (Snek Token), **NIGHT** (Midnight), **MIN** (Minswap).

Prices are calculated by fetching TOKEN/ADA from on-chain DEX pools (weighted by TVL), then multiplying by ADA/USDT from CEX price feeds (MEXC, Coingecko) to produce a TOKEN/USDT price.

**Discover liquidity pools:**

```bash
# Find all pools for a token
openmm pool-discovery discover INDY

# Top 5 pools for SNEK
openmm pool-discovery discover SNEK --limit 5

# Filter by minimum TVL
openmm pool-discovery discover INDY --min-liquidity 50000

# Show all pools (ignore limit)
openmm pool-discovery discover NIGHT --show-all
```

**Get live prices from pools:**

```bash
openmm pool-discovery prices NIGHT
openmm pool-discovery prices SNEK
openmm pool-discovery prices INDY
```

**List supported tokens:**

```bash
openmm pool-discovery supported
```

**Compare DEX vs CEX prices:**

```bash
openmm price-comparison --symbol SNEK
openmm price-comparison --symbol INDY
```

---

## Safety Rules

### Always dry-run first

Before executing any grid strategy, preview the grid to see what orders will be placed:

```bash
openmm trade --strategy grid --exchange mexc --symbol INDY/USDT --dry-run
```

### Confirm before execution

For AI agents using MCP:
1. **Always show the trade plan** — display what will be executed
2. **Get explicit confirmation** — never auto-execute without user approval
3. **Use `dryRun: true`** — the MCP `start_grid_strategy` tool defaults to dry-run mode

### Risk management

Grid strategy has built-in risk controls:
- `--max-position 0.6` — Use max 60% of balance for trading (default: 80%)
- `--safety-reserve 0.3` — Keep 30% as safety reserve (default: 20%)
- `--confidence 0.8` — Require 80% price confidence before trading (default: 60%)

Total allocation is automatically capped regardless of the size model used. The grid recreates when orders are filled and adjusts to significant price movements (configurable via `--deviation`).

---

## CLI Reference

### Balance & Market Data
| Command | Description |
|---------|-------------|
| `balance` | Get balances for an exchange |
| `ticker` | Get current price, bid/ask, spread, volume |
| `orderbook` | Get orderbook depth (bids/asks) |
| `trades` | Get recent trades |
| `price-comparison` | Compare DEX vs CEX prices for Cardano tokens |

### Orders
| Command | Description |
|---------|-------------|
| `orders list` | List open orders (all or by symbol) |
| `orders get` | Get specific order by ID |
| `orders create` | Place a limit or market order |
| `orders cancel` | Cancel an order by ID |

### Trading
| Command | Description |
|---------|-------------|
| `trade --strategy grid` | Start grid trading strategy |

### Cardano
| Command | Description |
|---------|-------------|
| `pool-discovery discover` | Discover DEX liquidity pools for a token |
| `pool-discovery supported` | List supported Cardano tokens (INDY, SNEK, NIGHT, MIN) |
| `pool-discovery prices` | Get live aggregated pool prices |

---

## Supported Exchanges

| Exchange | Trading | Grid | Market Data | Min Order | Notes |
|----------|---------|------|-------------|-----------|-------|
| MEXC | ✅ | ✅ | ✅ | 1 USDT | API key + secret |
| Gate.io | ✅ | ✅ | ✅ | 1 USDT | API key + secret |
| Bitget | ✅ | ✅ | ✅ | 1 USDT | API key + secret + passphrase |
| Kraken | ✅ | ✅ | ✅ | 5 EUR/USD | API key + secret, fiat pairs supported |
| Binance | 🔜 | 🔜 | 🔜 | — | Coming soon |
| Coinbase | 🔜 | 🔜 | 🔜 | — | Coming soon |
| OKX | 🔜 | 🔜 | 🔜 | — | Coming soon |

---

## Tips for Agents

- **Check balances first** — always run `openmm balance --exchange <ex>` before trading
- **Use `--dry-run`** — preview grid strategies before placing real orders
- **Use `BASE/QUOTE` format** — e.g. `BTC/USDT`, `ADA/EUR`, `SNEK/USDT`
- **Query each exchange separately** — there is no cross-exchange aggregate command
- **Handle rate limits** — exchanges have API limits, space out requests
- **Store credentials securely** — use environment variables, never commit `.env` files
- **Respect minimum order values** — MEXC/Gate.io/Bitget: 1 USDT, Kraken: 5 EUR/USD
- **Use `--max-position` and `--safety-reserve`** — built-in risk controls for grid strategies
- **Bitget requires passphrase** — set via `BITGET_PASSPHRASE` env var (created when generating the API key)
- **Use `--json` for parsing** — all commands support `--json` for structured output

---

## MCP Tools (via OpenMM-MCP)

When using OpenMM as an MCP server, these 13 tools are available:

### Market Data
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_ticker` | Real-time price, bid/ask, spread, volume | `exchange`, `symbol` |
| `get_orderbook` | Order book depth (bids/asks) | `exchange`, `symbol`, `limit?` |
| `get_trades` | Recent trades with buy/sell summary | `exchange`, `symbol`, `limit?` |

### Account
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_balance` | Account balances (all or filtered by asset) | `exchange`, `asset?` |
| `list_orders` | Open orders (all or by symbol) | `exchange`, `symbol?` |

### Trading
| Tool | Description | Parameters |
|------|-------------|------------|
| `create_order` | Place limit or market order | `exchange`, `symbol`, `type`, `side`, `amount`, `price?` |
| `cancel_order` | Cancel order by ID | `exchange`, `symbol`, `orderId` |
| `cancel_all_orders` | Cancel all open orders for a pair | `exchange`, `symbol` |

### Strategy
| Tool | Description | Parameters |
|------|-------------|------------|
| `start_grid_strategy` | Calculate and place grid orders (defaults to dry-run) | `exchange`, `symbol`, `levels?`, `spacing?`, `orderSize?`, `spacingModel?`, `sizeModel?`, `dryRun?` |
| `stop_strategy` | Cancel all orders for a pair, stopping the grid | `exchange`, `symbol` |
| `get_strategy_status` | Grid status with open orders, price, and spread | `exchange`, `symbol` |

### Cardano
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_cardano_price` | Aggregated token price from DEX pools (TOKEN/USDT via ADA bridge) | `symbol` |
| `discover_pools` | Discover Cardano DEX liquidity pools for a token | `symbol` |

### MCP Resources
| URI | Description |
|-----|-------------|
| `exchanges://list` | Supported exchanges with credential requirements |
| `strategies://grid` | Grid trading strategy documentation |
| `strategies://grid/profiles` | Example grid profiles (conservative/moderate/aggressive) |

### MCP Prompts
| Prompt | Description |
|--------|-------------|
| `market_analysis` | Analyze ticker + orderbook + trades for a trading pair |
| `portfolio_overview` | Summarize balances and open orders across an exchange |
| `grid_setup_advisor` | Recommend grid config based on market analysis and balance |

---

## Sub-Skills

For specific workflows, load these sub-skills:

| Skill | Description |
|-------|-------------|
| `openmm-exchange-setup` | Configure exchange API credentials step-by-step |
| `openmm-grid-trading` | Grid strategy creation and management |
| `openmm-portfolio` | Balance tracking and order overview across exchanges |

---

## Links

- **GitHub:** https://github.com/3rd-Eye-Labs/OpenMM
- **MCP Server:** https://github.com/QBT-Labs/OpenMM-MCP
- **npm:** https://www.npmjs.com/package/@3rd-eye-labs/openmm
- **Documentation:** https://deepwiki.com/3rd-Eye-Labs/OpenMM
- **Discord:** https://discord.gg/qbtlabs

---

## About

OpenMM is built by [3rd Eye Labs](https://github.com/3rd-Eye-Labs) and [QBT Labs](https://qbtlabs.io).

**License:** MIT

Attribution

dvcrn

View source More from dvcrn →

SSkills DirectorySkills Directory

Know which skills are safe — weekly.

Best new skills + every skill we flagged as malicious. From the team that scanned 103,619.

Join free

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

Comments (0)

No comments yet. Be the first to comment!

--- name: openmm description: "Open-source market making for AI agents. Multi-exchange trading, grid strategies, and real-time market data. CLI + MCP + Skills." --- > Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links. # 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 — capturing the spread on each cycle. Total orders = levels x 2. ```bash # Start grid with defaults (5 levels, 2% spacing, $50 per order) openmm trade --strategy grid --exchange mexc --symbol INDY/USDT # Dry run — preview the grid without placing real orders openmm trade --strategy grid --exchange bitget --symbol SNEK/USDT --dry-run # Custom grid configuration openmm trade --strategy grid --exchange mexc --symbol INDY/USDT \ --levels 5 \ --spacing 0.02 \ --size 50 \ --max-position 0.6 \ --safety-reserve 0.3 # Geometric spacing — tighter near center, wider at edges openmm trade --strategy grid --exchange kraken --symbol BTC/USD \ --levels 10 \ --spacing 0.005 \ --spacing-model geometric \ --spacing-factor 1.5 \ --size-model pyramidal \ --size 50 # Volatility-based spread adjustment — grid widens in volatile markets openmm trade --strategy grid --exchange mexc --symbol INDY/USDT \ --levels 10 \ --spacing 0.005 \ --spacing-model geometric \ --spacing-factor 1.3 \ --size-model pyramidal \ --size 5 \ --volatility # Volatility with custom thresholds (tighter sensitivity) openmm trade --strategy grid --exchange kraken --symbol SNEK/EUR \ --levels 5 \ --spacing 0.01 \ --size 5 \ --volatility \ --volatility-low 0.01 \ --volatility-high 0.03 # Load configuration from a JSON profile openmm trade --strategy grid --exchange gateio --symbol SNEK/USDT \ --grid-profile ./profiles/balanced-geometric.json ``` **Strategy output on startup:** ``` Starting Trading Strategy Strategy: GRID Exchange: KRAKEN Symbol: BTC/USD Grid Levels: 10 per side (20 total) Grid Spacing: 0.3% Spacing Model: geometric Spacing Factor: 1.3 Size Model: pyramidal Order Size: $50 Max Position: 80% Safety Reserve: 20% Strategy initialized successfully Grid Configuration: Levels: 10 per side (20 total orders) Spacing Model: geometric Base Spacing: 0.30% Spacing Factor: 1.3 Size Model: pyramidal Base Size: $50 Strategy is now running! Press Ctrl+C to stop the strategy gracefully ``` **Graceful shutdown:** Press `Ctrl+C`. The system cancels all open orders, disconnects from the exchange, and displays final status. **Required Parameters:** - `--strategy grid` — Specifies grid trading strategy - `--exchange <exchange>` — Exchange to trade on (mexc, bitget, gateio, kraken) - `--symbol <symbol>` — Trading pair (e.g., INDY/USDT, SNEK/USDT, ADA/EUR) **Grid Parameters:** - `--levels <number>` — Grid levels each side (default: 5, max: 10, total orders = levels x 2) - `--spacing <decimal>` — Base price spacing between levels (default: 0.02 = 2%) - `--size <number>` — Base order size in quote currency (default: 50) - `--confidence <decimal>` — Minimum price confidence to trade (default: 0.6) - `--deviation <decimal>` — Price deviation to trigger grid recreation (default: 0.015) - `--debounce <ms>` — Delay between grid adjustments (default: 2000ms) - `--max-position <decimal>` — Maximum position size as % of balance (default: 0.8) - `--safety-reserve <decimal>` — Safety reserve as % of balance (default: 0.2) - `--dry-run` — Simulate trading without placing real orders **Dynamic Grid Parameters:** - `--spacing-model <model>` — linear, geometric, or custom (default: linear) - `--spacing-factor <number>` — Geometric spacing multiplier per level (default: 1.3) - `--size-model <model>` — flat, pyramidal, or custom (default: flat) - `--grid-profile <path>` — Load complete grid configuration from a JSON profile **Volatility Parameters:** - `--volatility` — Enable volatility-based dynamic spread adjustment - `--volatility-low <decimal>` — Low volatility threshold (default: 0.02). Below this, spacing stays normal. - `--volatility-high <decimal>` — High volatility threshold (default: 0.05). Above this, spacing is widened maximally. **Exchange notes for grid:** - **MEXC/Gate.io** — Minimum 1 USDT per order. Ensure `--size` / `--levels` >= 1. - **Bitget** — Minimum 1 USDT per order. Price precision: 6 decimals for SNEK/NIGHT. Requires passphrase. - **Kraken** — Minimum 5 EUR/USD per order. Ensure `--size` / `--levels` >= 5. ### Cardano DEX Integration OpenMM integrates with Cardano DEX liquidity pools via the Iris Protocol. Supported tokens: **INDY** (Indigo Protocol), **SNEK** (Snek Token), **NIGHT** (Midnight), **MIN** (Minswap). Prices are calculated by fetching TOKEN/ADA from on-chain DEX pools (weighted by TVL), then multiplying by ADA/USDT from CEX price feeds (MEXC, Coingecko) to produce a TOKEN/USDT price. **Discover liquidity pools:** ```bash # Find all pools for a token openmm pool-discovery discover INDY # Top 5 pools for SNEK openmm pool-discovery discover SNEK --limit 5 # Filter by minimum TVL openmm pool-discovery discover INDY --min-liquidity 50000 # Show all pools (ignore limit) openmm pool-discovery discover NIGHT --show-all ``` **Get live prices from pools:** ```bash openmm pool-discovery prices NIGHT openmm pool-discovery prices SNEK openmm pool-discovery prices INDY ``` **List supported tokens:** ```bash openmm pool-discovery supported ``` **Compare DEX vs CEX prices:** ```bash openmm price-comparison --symbol SNEK openmm price-comparison --symbol INDY ``` --- ## Safety Rules ### Always dry-run first Before executing any grid strategy, preview the grid to see what orders will be placed: ```bash openmm trade --strategy grid --exchange mexc --symbol INDY/USDT --dry-run ``` ### Confirm before execution For AI agents using MCP: 1. **Always show the trade plan** — display what will be executed 2. **Get explicit confirmation** — never auto-execute without user approval 3. **Use `dryRun: true`** — the MCP `start_grid_strategy` tool defaults to dry-run mode ### Risk management Grid strategy has built-in risk controls: - `--max-position 0.6` — Use max 60% of balance for trading (default: 80%) - `--safety-reserve 0.3` — Keep 30% as safety reserve (default: 20%) - `--confidence 0.8` — Require 80% price confidence before trading (default: 60%) Total allocation is automatically capped regardless of the size model used. The grid recreates when orders are filled and adjusts to significant price movements (configurable via `--deviation`). --- ## CLI Reference ### Balance & Market Data | Command | Description | |---------|-------------| | `balance` | Get balances for an exchange | | `ticker` | Get current price, bid/ask, spread, volume | | `orderbook` | Get orderbook depth (bids/asks) | | `trades` | Get recent trades | | `price-comparison` | Compare DEX vs CEX prices for Cardano tokens | ### Orders | Command | Description | |---------|-------------| | `orders list` | List open orders (all or by symbol) | | `orders get` | Get specific order by ID | | `orders create` | Place a limit or market order | | `orders cancel` | Cancel an order by ID | ### Trading | Command | Description | |---------|-------------| | `trade --strategy grid` | Start grid trading strategy | ### Cardano | Command | Description | |---------|-------------| | `pool-discovery discover` | Discover DEX liquidity pools for a token | | `pool-discovery supported` | List supported Cardano tokens (INDY, SNEK, NIGHT, MIN) | | `pool-discovery prices` | Get live aggregated pool prices | --- ## Supported Exchanges | Exchange | Trading | Grid | Market Data | Min Order | Notes | |----------|---------|------|-------------|-----------|-------| | MEXC | ✅ | ✅ | ✅ | 1 USDT | API key + secret | | Gate.io | ✅ | ✅ | ✅ | 1 USDT | API key + secret | | Bitget | ✅ | ✅ | ✅ | 1 USDT | API key + secret + passphrase | | Kraken | ✅ | ✅ | ✅ | 5 EUR/USD | API key + secret, fiat pairs supported | | Binance | 🔜 | 🔜 | 🔜 | — | Coming soon | | Coinbase | 🔜 | 🔜 | 🔜 | — | Coming soon | | OKX | 🔜 | 🔜 | 🔜 | — | Coming soon | --- ## Tips for Agents - **Check balances first** — always run `openmm balance --exchange <ex>` before trading - **Use `--dry-run`** — preview grid strategies before placing real orders - **Use `BASE/QUOTE` format** — e.g. `BTC/USDT`, `ADA/EUR`, `SNEK/USDT` - **Query each exchange separately** — there is no cross-exchange aggregate command - **Handle rate limits** — exchanges have API limits, space out requests - **Store credentials securely** — use environment variables, never commit `.env` files - **Respect minimum order values** — MEXC/Gate.io/Bitget: 1 USDT, Kraken: 5 EUR/USD - **Use `--max-position` and `--safety-reserve`** — built-in risk controls for grid strategies - **Bitget requires passphrase** — set via `BITGET_PASSPHRASE` env var (created when generating the API key) - **Use `--json` for parsing** — all commands support `--json` for structured output --- ## MCP Tools (via OpenMM-MCP) When using OpenMM as an MCP server, these 13 tools are available: ### Market Data | Tool | Description | Parameters | |------|-------------|------------| | `get_ticker` | Real-time price, bid/ask, spread, volume | `exchange`, `symbol` | | `get_orderbook` | Order book depth (bids/asks) | `exchange`, `symbol`, `limit?` | | `get_trades` | Recent trades with buy/sell summary | `exchange`, `symbol`, `limit?` | ### Account | Tool | Description | Parameters | |------|-------------|------------| | `get_balance` | Account balances (all or filtered by asset) | `exchange`, `asset?` | | `list_orders` | Open orders (all or by symbol) | `exchange`, `symbol?` | ### Trading | Tool | Description | Parameters | |------|-------------|------------| | `create_order` | Place limit or market order | `exchange`, `symbol`, `type`, `side`, `amount`, `price?` | | `cancel_order` | Cancel order by ID | `exchange`, `symbol`, `orderId` | | `cancel_all_orders` | Cancel all open orders for a pair | `exchange`, `symbol` | ### Strategy | Tool | Description | Parameters | |------|-------------|------------| | `start_grid_strategy` | Calculate and place grid orders (defaults to dry-run) | `exchange`, `symbol`, `levels?`, `spacing?`, `orderSize?`, `spacingModel?`, `sizeModel?`, `dryRun?` | | `stop_strategy` | Cancel all orders for a pair, stopping the grid | `exchange`, `symbol` | | `get_strategy_status` | Grid status with open orders, price, and spread | `exchange`, `symbol` | ### Cardano | Tool | Description | Parameters | |------|-------------|------------| | `get_cardano_price` | Aggregated token price from DEX pools (TOKEN/USDT via ADA bridge) | `symbol` | | `discover_pools` | Discover Cardano DEX liquidity pools for a token | `symbol` | ### MCP Resources | URI | Description | |-----|-------------| | `exchanges://list` | Supported exchanges with credential requirements | | `strategies://grid` | Grid trading strategy documentation | | `strategies://grid/profiles` | Example grid profiles (conservative/moderate/aggressive) | ### MCP Prompts | Prompt | Description | |--------|-------------| | `market_analysis` | Analyze ticker + orderbook + trades for a trading pair | | `portfolio_overview` | Summarize balances and open orders across an exchange | | `grid_setup_advisor` | Recommend grid config based on market analysis and balance | --- ## Sub-Skills For specific workflows, load these sub-skills: | Skill | Description | |-------|-------------| | `openmm-exchange-setup` | Configure exchange API credentials step-by-step | | `openmm-grid-trading` | Grid strategy creation and management | | `openmm-portfolio` | Balance tracking and order overview across exchanges | --- ## Links - **GitHub:** https://github.com/3rd-Eye-Labs/OpenMM - **MCP Server:** https://github.com/QBT-Labs/OpenMM-MCP - **npm:** https://www.npmjs.com/package/@3rd-eye-labs/openmm - **Documentation:** https://deepwiki.com/3rd-Eye-Labs/OpenMM - **Discord:** https://discord.gg/qbtlabs --- ## About OpenMM is built by [3rd Eye Labs](https://github.com/3rd-Eye-Labs) and [QBT Labs](https://qbtlabs.io). **License:** MIT