@dotswap/dex

DotSwap DEX command-line tool for managing BTC wallets, querying liquidity pools and account assets, and executing instant swap transactions — all from your terminal. Also runs as an MCP server, enabling direct integration with AI clients like Cursor and Claude Desktop.

Features

Wallet & Account

| Command | Description | |---------|-------------| | dex wallet add | Import a wallet via BIP39 mnemonic or WIF private key, encrypted and stored locally | | dex wallet list | List all saved wallets | | dex wallet show | Show details of a specific wallet | | dex auth login | Select a wallet and configure network, API Host, and X-API-Key (supports --flags and env vars for non-interactive use) | | dex auth status | Show current authentication configuration | | dex auth logout | Clear authentication configuration | | dex account overview | View account asset overview | | dex account balance-stat | View balance history statistics for a specific token |

Trading & Liquidity (Taker)

| Command | Description | |---------|-------------| | dex pool list | List liquidity pools associated with the current address | | dex swap history | View swap history with status filtering and pagination | | dex swap quick | Get a quote and submit a swap transaction in one step |

Market Making (Maker)

| Command | Description | |---------|-------------| | dex liquidity clmm calc | Calculate CLMM parameters and generate a ready-to-run clmm add command | | dex liquidity clmm list | List CLMM liquidity positions; supports --apr 1d\|7d\|30d | | dex liquidity clmm add | Add CLMM liquidity to a price range (use tick indexes from clmm calc) | | dex liquidity clmm remove | Remove CLMM liquidity by percentage | | dex liquidity sided calc | Calculate sided parameters and generate a ready-to-run sided add command (with market price validation) | | dex liquidity sided list | List sided positions (matched + pending) | | dex liquidity sided add | Submit a sided liquidity order (use tick indexes from sided calc) | | dex liquidity sided update | Update a pending sided order | | dex liquidity sided cancel | Cancel a sided order (MATCHING status) | | dex liquidity sided remove | Remove a matched sided position |

AI Integration (MCP)

| Command | Description | |---------|-------------| | dex mcp | Start MCP HTTP server (default port 3000) | | dex mcp --readonly | Start in read-only mode, disabling trade operations | | dex mcp --stdio | Start in stdio mode for Claude Desktop integration |

Supported Platforms

| Platform | Architecture | |----------|-------------| | macOS | Apple Silicon (M1/M2/M3) | | macOS | Intel | | Linux | x64 | | Windows | x64 |

Installation

Requires Node.js >= 14. LTS version recommended.

npm install -g @dotswap/dex

Verify installation:

dex version

Quick Start

A Note on Private Key Security

This tool offers two login methods. Choose based on how much you trust your local environment:

| Method | Best For | Steps | |--------|----------|-------| | Method 1: Import Wallet (recommended) | Trusted local environment, prefer convenience | wallet add → auth login | | Method 2: Manual Address Input (no private key) | Concerned about local security, prefer not to store keys in any tool | auth login directly |

Method 1 note: Your private key is AES-encrypted and stored only in a local file — it is never uploaded to any server. The tool does not read your private key during normal operation.

Method 1: Import Wallet (Recommended)

Step 1: Import your wallet

dex wallet add

Supports BIP39 mnemonic and WIF private key import. The key is encrypted and stored locally only — never transmitted to any server.

Step 2: Login

dex auth login

Select a wallet, configure network, API Host, and X-API-Key.

Method 2: Manual Address Input (No Private Key)

If you prefer not to store your private key in any tool, skip wallet add and run:

dex auth login

Without an imported wallet, auth login will prompt you to manually enter the following (all public information — no private key required):

• BTC address and public key
• Ordinals address and public key
• API Host and X-API-Key

Once configured, all query and trading features are fully available.

3. Common Commands

# List liquidity pools
dex pool list

# Account asset overview
dex account overview

# Swap history
dex swap history

# All commands
dex --help

MCP HTTP Server

Start an MCP (Model Context Protocol) HTTP server to enable AI editors like Cursor to access CLI functionality via HTTP.

# Start HTTP server (default port 3000)
dex mcp --port 3000

# Start in read-only mode
dex mcp --port 3000 --readonly

Configure Cursor by adding to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dotswap-dex": {
      "url": "http://127.0.0.1:3000/streamable-http"
    }
  }
}

See QUICKSTART.md for detailed setup instructions.

Full Documentation

After installation, view the complete guide:

cat $(npm root -g)/@dotswap/dex/QUICKSTART.md

Uninstall

npm uninstall -g @dotswap/dex