{
  "markdown": "# bitmex-cli\n\n![license](https://img.shields.io/badge/license-MIT-green)\n\nThe official BitMEX command-line interface for interacting with the [BitMEX](https://www.bitmex.com) exchange. Execute trades, query market data, and manage your account from the terminal. Supports integration with AI coding agents for automation.\n\nSingle binary, no runtime dependencies. 134 commands with structured JSON output and real-time streaming covering every REST and WebSocket endpoint. Built-in [MCP](https://modelcontextprotocol.io) server for direct agent integration.\n\nCompatible with major AI coding agents including Claude, Codex, Cursor, Copilot, Gemini, and others. Automate workflows such as market monitoring, order execution, and portfolio reporting — all from a single prompt.\n\n---\n\n> [!WARNING]\n> **⚠️ WARNING — PLEASE READ BEFORE USE**\n>\n> This is experimental software that interacts with the live BitMEX exchange and can execute real financial transactions that may result in loss of funds. Use of this tool is subject to the [BitMEX Terms of Service](https://www.bitmex.com/terms).\n>\n> BitMEX services are not available in all jurisdictions — you are responsible for ensuring your use complies with applicable laws.\n>\n> Use `--testnet` to test safely with no real money at risk. Read [DISCLAIMER.md](DISCLAIMER.md) before using with real funds or AI agents.\n\n\n## Get Started with AI\n\nGetting started is easy! Paste the following into your AI agent to set up bitmex-cli for your BitMEX trading account:\n\n```\nSet up bitmex-cli for my BitMEX trading account.\n\n## Install\nRun: tmpfile=\"$(mktemp)\" && curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh -o \"$tmpfile\" && sh \"$tmpfile\"\n\n## Account Setup\nIf I don't have a BitMEX account yet, walk me through:\n1. Sign up at https://www.bitmex.com/register\n2. Complete identity verification\n3. Deposit funds\n\n## API Key\nGuide me to https://www.bitmex.com/app/apiKeys to create an API key with\n\"Order\" and \"Account\" permissions (add \"Withdraw\" only if I need withdrawals).\nAsk me to choose:\n- Share my key and secret with you, and run: bitmex auth set --api-key <KEY> --api-secret <SECRET>\n- Or keep keys private: ask me to open a terminal and run `bitmex auth add` myself (do NOT run this for me — it requires an interactive terminal)\n\n## Verify\nRun: bitmex account me -o json\n\n## MCP (optional)\nAsk me if I want to set up the built-in MCP server (`bitmex mcp`), which\nlets you (the AI agent) call bitmex commands directly as tools without subprocess wrappers\n— smoother integration for agents that support MCP.\n\n## What's Next\nUse the bitmex-* skills available to you and ask me what I want to do. Offer these:\n- Morning market brief (prices, funding rates, positions)\n- Start a DCA bot (dollar-cost average into a position)\n- Launch a grid trading bot (buy dips, sell rallies automatically)\n- Scan for funding rate carry opportunities\n- Monitor my positions and P&L\nAnd suggest starting with --testnet to practice safely before using real funds.\n```\n\n## Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Testnet](#testnet)\n- [Commands](#commands)\n- [API Keys & Configuration](#api-keys--configuration)\n- [MCP Server](#mcp-server)\n- [WebSocket Streaming](#websocket-streaming)\n- [AI Agents](#ai-agents)\n- [Contributing](#contributing)\n- [License & Disclaimer](#license--disclaimer)\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install BitMEX/tap/bitmex-cli\n```\n\n### Install script\n\n```bash\ncurl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh | sh\n```\n\nDownloads a pre-built binary for your platform (macOS/Linux, x86_64/arm64), verifies the SHA256 checksum, and installs to `~/.local/bin`. No Rust or build tools needed. No `sudo` required. Requires `curl`, `tar`, and `sha256sum` (or `shasum`). Override the install location with `BITMEX_INSTALL_DIR`.\n\n### GitHub Releases\n\nDownload binaries directly from [Releases](https://github.com/BitMEX/bitmex-cli/releases).\n\n### From source (requires Rust)\n\n```bash\n# Install Rust if needed\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Build and install\ncargo install --path .\n```\n### Verify\n\n```bash\nbitmex --version\n```\n\n## Quick Start\n\n```bash\n# Public market data — no auth needed\nbitmex market instrument --symbol XBTUSD -o json\nbitmex market orderbook XBTUSD --depth 10 -o json\nbitmex market trades --symbol XBTUSD --count 20 -o json\nbitmex market funding --symbol XBTUSD -o json\n\n# Set up credentials (stored securely in OS keychain)\nbitmex auth add\n\n# Account data\nbitmex account me -o json\nbitmex wallet balance -o json\nbitmex position list -o json\n\n# Place a limit buy (use --testnet first!)\nbitmex order buy XBTUSD 100 --price 50000 --validate -o json   # dry-run\nbitmex order buy XBTUSD 100 --price 50000 -o json               # live\n```\n\n## Testnet\n\nAll commands accept `--testnet` to target `https://testnet.bitmex.com` instead of mainnet. Use this to validate workflows without risking real funds:\n\n```bash\nbitmex --testnet market instrument --active -o json\nbitmex --testnet order buy XBTUSD 100 --price 50000 -o json\n```\n\nTestnet requires separate API keys from [testnet.bitmex.com](https://testnet.bitmex.com).\n\n## Commands\n\nEvery command returns structured JSON with `-o json`. All commands support `--help`.\n\n### Market data (no auth)\n\n```bash\nbitmex market instrument [--symbol XBTUSD] [--active] [--indices]\nbitmex market quote [--symbol XBTUSD] [--bucketed] [--bin-size 1h]\nbitmex market trades [--symbol XBTUSD] [--count 100]\nbitmex market orderbook XBTUSD [--depth 25]\nbitmex market funding [--symbol XBTUSD]\nbitmex market liquidation [--symbol XBTUSD]\nbitmex market settlement [--symbol XBTUSD]\nbitmex market insurance\nbitmex market stats\nbitmex market leaderboard [--method notional|roe]\nbitmex market composite-index [--symbol .BXBT]\nbitmex announce list\nbitmex announce urgent\n```\n\n### Orders (auth required)\n\n```bash\nbitmex order buy  XBTUSD 100 --price 50000 [--order-type Limit] [--validate]\nbitmex order sell XBTUSD 100 --price 52000 [--tif GoodTillCancel]\nbitmex order buy  XBTUSD 100 --price 50000 --strategy Long   # Hedge Mode leg\nbitmex order sell XBTUSD 100 --price 52000 --strategy Short  # Hedge Mode leg\nbitmex order amend --order-id <id> --price 51000\nbitmex order cancel --order-id <id>\nbitmex order cancel-all [--symbol XBTUSD]\nbitmex order cancel-after 60000        # Dead Man's Switch (ms)\nbitmex order list [--symbol XBTUSD]\n```\n\n100% position-closing orders — `orderQty` is omitted, so they track the full\nposition dynamically (BitMEX renders them as SL/TP 100%). `--side sell` closes a\nlong, `--side buy` closes a short. `--trigger` is required with `--stop-px`/`--tp-px`.\n\n```bash\nbitmex order close XBTUSD --side sell --stop-px 50000 --trigger mark   # Stop-Loss 100%\nbitmex order close XBTUSD --side sell --tp-px 60000 --trigger last     # Take-Profit 100%\nbitmex order close XBTUSD --side sell --stop-px 50000 --tp-px 60000 --trigger mark  # OCO bracket\nbitmex order close XBTUSD --side sell                                  # market close 100%\n```\n\nPegged orders price relative to the live market. `chase` and `trailing-stop` are guided\nwrappers that set the right `ordType`/`execInst` and enforce the offset **sign rule**\nlocally (a wrong sign is rejected before it reaches the exchange).\n\n```bash\n# Pegged limit — Fixed price relative to the touch (PrimaryPeg = near, MarketPeg = far)\nbitmex order buy XBTUSD 100 --order-type Pegged --exec-inst Fixed \\\n    --peg-price-type PrimaryPeg --peg-offset-value -1\n\n# Chaser — re-prices to follow the top of book. Buy offset <= 0, Sell offset >= 0.\nbitmex order chase XBTUSD Buy  100 --offset -1              # ChaserClassic (default)\nbitmex order chase XBTUSD Sell 100 --offset  1 --bothways  # ChaserBothways\n\n# Trailing stop — stopPx trails the market. Sell offset <= 0, Buy offset >= 0.\nbitmex order trailing-stop XBTUSD Sell 100 --offset -100                     # Stop\nbitmex order trailing-stop XBTUSD Sell 100 --offset -100 --limit-price 49000 # StopLimit\n\n# Amend a live peg's offset without cancel/replace\nbitmex order amend --order-id <id> --peg-offset-value -2\n```\n\nSee [Order Types & Execution Instructions](https://support.bitmex.com/hc/en-gb/articles/6911327963293)\nfor the full peg/chaser reference.\n\n### Positions (auth required)\n\n```bash\nbitmex position list [--symbol XBTUSD]          # table shows the `strategy` column\nbitmex position leverage XBTUSD 10\nbitmex position cross-leverage XBTUSD 5\nbitmex position isolate XBTUSD --enabled\nbitmex position risk-limit XBTUSD 20000000000\nbitmex position transfer-margin XBTUSD 100000   # satoshis\n```\n\n### Hedge Mode (MultiWay) (auth required)\n\nHedge Mode lets you hold independent Long and Short positions on the same\ncontract instead of netting into one. It is an account-level setting and applies\nto uncapped derivatives only. Switching is rejected while the account has open\norders or isolated-margin positions.\n\n```bash\nbitmex account position-mode multiway   # enable Hedge Mode (alias: hedge)\nbitmex account position-mode oneway      # back to One-Way (netting)\nbitmex position mode multiway            # alias for `account position-mode`\n```\n\nOnce enabled, tag each order leg with its strategy:\n\n```bash\nbitmex order buy  XBTUSD 100 --price 50000 --strategy Long\nbitmex order sell XBTUSD 100 --price 52000 --strategy Short\n```\n\nSee [What is Hedge Mode](https://support.bitmex.com/hc/en-gb/articles/32985620308381-What-is-Hedge-Mode)\nand [How traders use Hedge Mode](https://support.bitmex.com/hc/en-gb/articles/36691242524317-How-can-traders-use-Hedge-Mode-to-improve-their-trading-and-strategies).\n\n### Execution history (auth required)\n\n```bash\nbitmex execution list [--symbol XBTUSD] [--count 100]\nbitmex execution trade-history [--symbol XBTUSD]\n```\n\n### Wallet (auth required)\n\n```bash\nbitmex wallet balance [--currency XBt]\nbitmex wallet history [--currency XBt]\nbitmex wallet summary\nbitmex wallet deposit [--currency XBt]\nbitmex wallet assets\nbitmex wallet networks\nbitmex wallet withdraw --currency XBt --network Bitcoin --address <addr> --amount <sats>\nbitmex wallet transfer --currency XBt --amount <sats>\n```\n\n### Account (auth required)\n\n```bash\nbitmex account me\nbitmex account margin\nbitmex account commission\nbitmex account volume\nbitmex account affiliate\nbitmex account csa\nbitmex account execution-history\nbitmex account preferences --prefs '{\"locale\":\"en-US\"}'\nbitmex account margining-mode REGULAR_MARGIN\n```\n\n### Staking (auth required)\n\n```bash\nbitmex staking status\nbitmex staking instruments\nbitmex staking unstake <symbol> <amount>\nbitmex staking pending-unstake\n```\n\n### Other command groups\n\n```bash\nbitmex subaccount add <name>\nbitmex api-key list\nbitmex chat read [--channel-id 1]\nbitmex chat post \"Hello\"\nbitmex guild info\nbitmex bots strategies\nbitmex bots instances\nbitmex notifications alerts\nbitmex address list\nbitmex referral list\nbitmex porl nonce\n```\n\n### Credentials\n\n```bash\nbitmex auth add                           # interactive wizard — recommended\nbitmex auth set --profile trading         # non-interactive upsert\nbitmex auth list                          # list all profiles\nbitmex auth show [--profile <name>]       # show masked key + storage source\nbitmex auth use <name>                    # change active profile\nbitmex auth delete --profile <name>       # remove a profile\nbitmex auth reset                         # clear the default profile\n```\n\n## API Keys & Configuration\n\n### Credential storage\n\nCredentials are stored in the **OS native keychain** (macOS Keychain, Linux Secret Service, Windows Credential Manager). The config file `~/Library/Application Support/bitmex/config.toml` (macOS) or `~/.config/bitmex/config.toml` (Linux) holds only non-sensitive metadata — profile names, testnet flag, active profile.\n\nOn headless systems without a keychain, add `--no-keychain` (or set `BITMEX_NO_KEYCHAIN=1`) to fall back to plaintext storage in the config file.\n\n### Profiles\n\nA profile bundles an API key/secret pair and a testnet flag under a name:\n\n```bash\n# Add profiles interactively\nbitmex auth add                           # guided wizard\nbitmex auth add --profile testnet --testnet\n\n# Switch between profiles\nbitmex auth use trading\nbitmex --profile trading order list       # override for a single command\n```\n\nCredential resolution order (highest wins):\n1. `--api-key` / `--api-secret` flags\n2. `BITMEX_API_KEY` / `BITMEX_API_SECRET` env vars\n3. `--profile <name>` flag → OS keychain\n4. `active_profile` from config → OS keychain\n5. Plaintext config file fallback (when keychain unavailable)\n\n### Environment variables\n\n```bash\nexport BITMEX_API_KEY=\"your-key\"\nexport BITMEX_API_SECRET=\"your-secret\"\nexport BITMEX_PROFILE=\"trading\"           # select profile by name\nexport BITMEX_NO_KEYCHAIN=1               # force plaintext fallback (CI/Docker)\n```\n\n### Required BitMEX API permissions\n\n| Command group | Required permissions |\n|---|---|\n| market, announce, chat (read) | None (public) |\n| account, execution, position (read) | Order |\n| order (place/cancel) | Order |\n| wallet | Withdraw |\n| staking, apikey, porl | Account |\n\n## MCP Server\n\n`bitmex-cli` includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes CLI commands as tools directly to AI agents — no subprocess wrappers needed.\n\n```bash\nbitmex mcp\nbitmex mcp -s market,account          # restrict to specific groups\nbitmex mcp -s all --allow-dangerous   # all commands including order placement\nbitmex mcp -s all --port 3000         # run as standalone HTTP server\n```\n\n### Recommended: HTTP mode (credentials stay private)\n\nRunning the MCP server as a standalone HTTP process means your API credentials are loaded from the OS keychain by your own terminal session — they are never passed to or visible by the AI agent.\n\n**Step 1** — Store your credentials in the keychain:\n\n```bash\nbitmex auth add --profile trading         # interactive wizard\nbitmex auth add --profile testnet --testnet\n```\n\n**Step 2** — Start the MCP server in a terminal:\n\n```bash\nbitmex mcp -s all --allow-dangerous --profile trading --port 3000\n```\n\nCredentials are resolved from the keychain once at startup. The AI agent connects over HTTP and never sees the key or secret.\n\n**Step 3** — Point your MCP client at the running server:\n\n```json\n{\n  \"mcpServers\": {\n    \"bitmex\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:3000/mcp\"\n    }\n  }\n}\n```\n\nFor Claude Code:\n\n```bash\nclaude mcp add --transport http bitmex http://127.0.0.1:3000/mcp\n```\n\n### Subprocess mode (stdio)\n\nIf you prefer the client to spawn the server automatically, add it to your MCP config. Credentials can be passed via a named profile (read from the keychain at each call) or explicitly via environment variables.\n\n**Using a keychain profile:**\n\n```json\n{\n  \"mcpServers\": {\n    \"bitmex\": {\n      \"command\": \"bitmex\",\n      \"args\": [\"mcp\", \"-s\", \"all\", \"--profile\", \"trading\"]\n    }\n  }\n}\n```\n\n**Using environment variables (CI / Docker / no keychain):**\n\n```json\n{\n  \"mcpServers\": {\n    \"bitmex\": {\n      \"command\": \"bitmex\",\n      \"args\": [\"mcp\", \"-s\", \"all\"],\n      \"env\": {\n        \"BITMEX_API_KEY\": \"your-key\",\n        \"BITMEX_API_SECRET\": \"your-secret\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** In subprocess mode the MCP client config contains credentials. Use HTTP mode to keep credentials out of config files and away from AI agents.\n\n## WebSocket Streaming\n\nStream real-time data as NDJSON to stdout:\n\n```bash\n# Public topics\nbitmex ws trade:XBTUSD\nbitmex ws orderBookL2_25:XBTUSD\nbitmex ws funding instrument\n\n# Private topics (require --auth)\nbitmex ws --auth position order execution margin\n\n# Multiple topics\nbitmex ws trade:XBTUSD orderBookL2_25:XBTUSD quote:XBTUSD\n```\n\nUse `--testnet` to stream from testnet:\n\n```bash\nbitmex --testnet ws trade:XBTUSD\n```\n\n## AI Agents\n\nEvery command returns structured JSON with `-o json`. The built-in MCP server exposes commands as tools directly to AI agents.\n\n| Resource | Description |\n|----------|-------------|\n| [AGENTS.md](AGENTS.md) | Full integration guide — installation, auth, invocation, error handling, safety |\n| [CONTEXT.md](CONTEXT.md) | Compact runtime context for tool-using agents |\n| [agents/tool-catalog.json](agents/tool-catalog.json) | 134 commands with parameter schemas and `dangerous` flags |\n| [agents/error-catalog.json](agents/error-catalog.json) | Error categories with retry guidance |\n| [skills/](skills/) | 49 workflow skills — DCA bots, grid trading, market briefs, risk operations |\n\n## Interactive Shell\n\n```bash\nbitmex shell\n```\n\nRuns an interactive REPL with command history at `~/.config/bitmex/history`.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License & Disclaimer\n\nMIT — see [LICENSE](LICENSE).\n\n**This software interacts with a live financial exchange and can result in real monetary loss. It is provided as-is with no warranty. You are solely responsible for all trading decisions and outcomes.**\n\nUse of this tool is subject to the [BitMEX Terms of Service](https://www.bitmex.com/terms). Read [DISCLAIMER.md](DISCLAIMER.md) before use.\n",
  "bytes": 17137,
  "sha": "749e22903f7ad578f6bba19f952945aaa8c7e75fc9a032fafad6a0359b97f7dd",
  "repo_slug": "bitmex/bitmex-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bitmex_bitmex_cli_3ec3fc20/readme"
}