--- name: phemex-trade description: Trade on Phemex (USDT-M futures, Coin-M futures, Spot) — place orders, manage positions, check balances, and query market data. Use when the user wants to (1) check crypto prices or market data on Phemex, (2) place, amend, or cancel orders, (3) view account balances or positions, (4) set leverage or switch position modes, (5) transfer funds between spot and futures wallets, or (6) any task involving the Phemex exchange. homepage: https://github.com/betta2moon/phemex-trade-mcp metadata: { "openclaw": { "emoji": "📈", "requires": { "bins": ["phemex-cli"], "env": ["PHEMEX_API_KEY", "PHEMEX_API_SECRET"] }, "primaryEnv": "PHEMEX_API_KEY", "install": [ { "id": "phemex-trade-mcp", "kind": "node", "package": "phemex-trade-mcp", "bins": ["phemex-cli"], "label": "Install Phemex CLI (node)", }, ], }, } ---

Phemex Trading

Trade on Phemex via the phemex-cli tool. Supports USDT-M futures, Coin-M futures, and Spot markets.

What's New in v1.2.0

1. list_symbols tool — Discover all available trading pairs, filtered by contract type. No more guessing symbol names.
2. Config file (~/.phemexrc) — Store API credentials persistently. No need to export env vars every session.
3. --help for every tool — Run phemex-cli --help to see parameters, defaults, and usage examples inline.
4. Friendly field names — API field suffixes (closeRp, fundingRateRr) are mapped to readable names (closePrice, fundingRate). Use --raw to get the original names.
5. Enhanced error messages — Errors now include suggestion and tip fields with actionable guidance instead of raw API codes.

Before you start

Ensure you have the latest version installed:

npm install -g phemex-trade-mcp@latest

How to call tools

phemex-cli <tool_name> --param1 value1 --param2 value2

Or with JSON args:

phemex-cli <tool_name> '{"param1":"value1","param2":"value2"}'

Output is always JSON. Credentials are loaded from environment variables or ~/.phemexrc (see Setup).

Tool help

Every tool supports --help with full parameter docs and examples:

phemex-cli place_order --help

Output:

Usage: phemex-cli place_order [options]

Place an order (Market, Limit, Stop, StopLimit)

Required Parameters:
  --symbol <string>          Trading pair (e.g. BTCUSDT)
  --side <string>            Buy or Sell
  --orderQty <number>        Quantity. linear: base amount (0.01 = 0.01 BTC). ...
  --ordType <string>         Order type: Market, Limit, Stop, StopLimit

Optional Parameters:
  --price <number>           Limit price (required for Limit/StopLimit)
  --timeInForce <string>     GoodTillCancel, PostOnly, ... [default: GoodTillCancel]
  --reduceOnly <boolean>     Only reduce position [default: false]
  ...

Examples:
  phemex-cli place_order --symbol BTCUSDT --side Buy --orderQty 0.01 --ordType Market
  phemex-cli place_order --symbol BTCUSDT --side Sell --orderQty 0.01 --ordType Limit --price 90000 --timeInForce PostOnly

More help examples:

phemex-cli get_ticker --help        # see params for price ticker
phemex-cli get_klines --help        # see resolution values for candlesticks
phemex-cli set_leverage --help      # see leverage param format
phemex-cli transfer_funds --help    # see direction values
phemex-cli list_symbols --help      # see contractType filter

Friendly field names

By default, output uses readable field names:

phemex-cli get_ticker --symbol BTCUSDT

{
  "closePrice": "70549.9",
  "openPrice": "70192.7",
  "highPrice": "70750",
  "lowPrice": "69160",
  "markPrice": "70549.9",
  "fundingRate": "-0.00003417",
  "volume": "5303.525",
  "turnover": "371204351.5978"
}

Use --raw to get original API field names (for scripts that depend on old format):

phemex-cli get_ticker --symbol BTCUSDT --raw

{
  "closeRp": "70549.9",
  "openRp": "70192.7",
  "highRp": "70750",
  "lowRp": "69160",
  "markPriceRp": "70549.9",
  "fundingRateRr": "-0.00003417",
  "volumeRq": "5303.525",
  "turnoverRv": "371204351.5978"
}

Field name mapping reference:

| Suffix | Meaning | Example | Mapped to | |--------|---------|---------|-----------| | Rp | Real Price | closeRp | closePrice | | Rv | Real Value | accountBalanceRv | accountBalance | | Rr | Real Rate | fundingRateRr | fundingRate | | Rq | Real Quantity | volumeRq | volume |

Contract types

Every tool accepts an optional --contractType flag:

• linear (default) — USDT-M perpetual futures. Symbols end in USDT (e.g. BTCUSDT).
• inverse — Coin-M perpetual futures. Symbols end in USD (e.g. BTCUSD).
• spot — Spot trading. Symbols end in USDT (e.g. BTCUSDT). The server auto-prefixes s for the API.

Tools

Market data (no auth needed)

• get_ticker — 24hr price ticker. Example: phemex-cli get_ticker --symbol BTCUSDT
• get_orderbook — Order book (30 levels). Example: phemex-cli get_orderbook --symbol BTCUSDT
• get_klines — Candlestick data. Example: phemex-cli get_klines --symbol BTCUSDT --resolution 3600 --limit 100
• get_recent_trades — Recent trades. Example: phemex-cli get_recent_trades --symbol BTCUSDT
• get_funding_rate — Funding rate history. Example: phemex-cli get_funding_rate --symbol .BTCFR8H --limit 20

Account (read-only, auth required)

• get_account — Balance and margin info. Example: phemex-cli get_account --currency USDT
• get_spot_wallet — Spot wallet balances. Example: phemex-cli get_spot_wallet
• get_positions — Current positions with PnL. Example: phemex-cli get_positions --currency USDT
• get_open_orders — Open orders. Example: phemex-cli get_open_orders --symbol BTCUSDT
• get_order_history — Closed/filled orders. Example: phemex-cli get_order_history --symbol BTCUSDT --limit 50
• get_trades — Trade execution history. Example: phemex-cli get_trades --symbol BTCUSDT --limit 50

Trading (auth required)

• place_order — Place an order (Market, Limit, Stop, StopLimit). Key params: --symbol, --side (Buy/Sell), --orderQty, --ordType, --price (Limit/StopLimit), --stopPx (Stop/StopLimit), --timeInForce (GoodTillCancel/PostOnly/ImmediateOrCancel/FillOrKill), --reduceOnly, --posSide (Long/Short/Merged), --stopLoss, --takeProfit, --qtyType (spot only). orderQty units differ by contract type:

- linear (USDT-M): orderQty = base currency amount (e.g. 0.01 = 0.01 BTC). To buy 10 USDT worth, calculate qty = 10 / current price. - inverse (Coin-M): orderQty = number of contracts as integer (e.g. 10 = 10 contracts). Each contract has a fixed USD value (e.g. 1 USD/contract for BTCUSD). - spot: depends on --qtyType. ByBase (default) = base currency (e.g. 0.01 = 0.01 BTC). ByQuote = quote currency (e.g. 50 = 50 USDT worth of BTC). - Example: phemex-cli place_order --symbol BTCUSDT --side Buy --orderQty 0.01 --ordType Market

• amend_order — Modify an open order. Example: phemex-cli amend_order --symbol BTCUSDT --orderID xxx --price 95000
• cancel_order — Cancel one order. Example: phemex-cli cancel_order --symbol BTCUSDT --orderID xxx
• cancel_all_orders — Cancel all orders for a symbol. Example: phemex-cli cancel_all_orders --symbol BTCUSDT
• set_leverage — Set leverage. Example: phemex-cli set_leverage --symbol BTCUSDT --leverage 10
• switch_pos_mode — Switch OneWay/Hedged. Example: phemex-cli switch_pos_mode --symbol BTCUSDT --targetPosMode OneWay

Transfers (auth required)

...