Phemex Cli

Trade on Phemex (USDT-M futures, Coin-M futures, Spot) — place orders, manage positions, check balances, stream real-time market data, and query historical d...

Security Scan

The skill's requirements and instructions line up with a CLI client for Phemex, but it asks you to store/use exchange API keys and installs an npm package (which can run install scripts) — so proceed with normal caution.

Purpose & Capability

Name/description match the declared requirements: the skill needs the phemex-cli binary and PHEMEX_API_KEY/PHEMEX_API_SECRET, which are exactly what a Phemex trading CLI requires.

Instruction Scope

SKILL.md stays on-topic: it documents CLI commands, streaming, and credential loading from environment or ~/.phemexrc. It does not instruct the agent to read unrelated system files or exfiltrate data to unexpected endpoints. Note: it recommends persisting credentials in ~/.phemexrc, which is functionally reasonable but a sensitive action the user should handle carefully.

Install Mechanism

Install uses the npm package phemex-cli (creates the phemex-cli binary). This is an expected install route, but npm package installs can run arbitrary install scripts (postinstall) and will execute code on the host during install — verify package provenance (registry publisher, GitHub repo, package.json) before installing.

Credentials

Requested env vars are PHEMEX_API_KEY and PHEMEX_API_SECRET (primaryEnv = PHEMEX_API_KEY) — these are appropriate and sufficient for trading. No unrelated credentials are requested. The skill also mentions ~/.phemexrc as an alternate credential store (expected but sensitive).

Persistence & Privilege

always:false (normal). The skill can be invoked autonomously (platform default). That is expected, but because the skill can place real trades, allowing autonomous invocation without restrictions could result in unintended orders — consider limiting autonomous use or requiring explicit user confirmation for trade operations.

Assessment

This skill appears to be a straightforward wrapper around the phemex-cli tool, but you should take ordinary precautions before installing/using it: 1) Verify the npm package and GitHub repo (publisher, recent commits, issues) to reduce supply-chain risk—npm packages can run install scripts. 2) Prefer using environment variables over storing keys in plaintext files; if you do use ~/.phemexrc, set strict file permissions (chmod 600) and keep the file private. 3) Create API keys with minimal required permissions (e.g., read-only key for market queries; separate key with trading enabled only when you intend to place trades; do not enable withdrawals). 4) If you do not want the agent to place trades autonomously, disable autonomous invocation for this skill in your agent settings or require explicit confirmation for any trading command. 5) Before a global npm install, inspect the package.json and any postinstall scripts in the package source. These steps will reduce the main risks (credential exposure and malicious install-time scripts).

Phemex Trading

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

What's New in v2.0.0

Standalone CLI release — phemex-cli is now a standalone package (previously bundled with phemex-trade-mcp). Leaner install, no MCP dependencies.

1. WebSocket streaming — phemex-cli subscribe ticker|trade|orderbook --symbol SYMBOL for real-time market data.
2. list_symbols tool — Discover all available trading pairs, filtered by contract type.
3. Config file (~/.phemexrc) — Store API credentials persistently. No need to export env vars every session.
4. --help for every tool — Run phemex-cli <tool> --help to see parameters, defaults, and usage examples inline.
5. Friendly field names — API field suffixes (closeRp, fundingRateRr) are mapped to readable names (closePrice, fundingRate). Use --raw to get the original names.
6. 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-cli@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 CLI 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)

• transfer_funds — Move funds between spot and futures. Example: phemex-cli transfer_funds --currency USDT --amount 100 --direction spot_to_futures
• get_transfer_history — Transfer history. Example: phemex-cli get_transfer_history --currency USDT --limit 20

Utility

• list_symbols — List all available trading symbols, grouped by contract type.

# List all symbols (linear, inverse, spot)
phemex-cli list_symbols

# Only USDT-M perpetual futures
phemex-cli list_symbols --contractType linear

# Only Coin-M perpetual futures
phemex-cli list_symbols --contractType inverse

# Only spot pairs
phemex-cli list_symbols --contractType spot

Example output:

{
  "linear": ["BTCUSDT", "ETHUSDT", "SOLUSDT", "BNBUSDT", ...],
  "inverse": ["BTCUSD", "ETHUSD", ...],
  "spot": ["BTCUSDT", "ETHUSDT", ...]
}

Use list_symbols to discover valid symbol names before trading. This avoids "invalid symbol" errors.

Streaming (WebSocket, no auth needed)

Subscribe to real-time market data streams. Output is JSON to stdout, logs to stderr.

# Stream price ticker
phemex-cli subscribe ticker --symbol BTCUSDT

# Stream live trades
phemex-cli subscribe trade --symbol SOLUSDT

# Stream order book updates
phemex-cli subscribe orderbook --symbol ETHUSDT

Features: auto-reconnect with exponential backoff, Ctrl+C for graceful shutdown.

Error messages

Errors return structured JSON with actionable guidance. Examples:

Invalid symbol:

phemex-cli get_ticker --symbol INVALIDXXX

{
  "error": "Invalid symbol: INVALIDXXX",
  "code": 6001,
  "suggestion": "Symbol \"INVALIDXXX\" is not recognized. Check spelling and contract type.",
  "tip": "Run \"phemex-cli list_symbols\" to see all available symbols."
}

Common typo (BTCUSD instead of BTCUSDT):

phemex-cli get_ticker --symbol BTCUSD

{
  "error": "Invalid symbol: BTCUSD",
  "code": 6001,
  "suggestion": "Did you mean BTCUSDT? For USDT perpetuals, use symbols ending in USDT (e.g. BTCUSDT).",
  "tip": "Run \"phemex-cli list_symbols\" to see all available symbols."
}

Order quantity too large:

{
  "error": "Order quantity too large",
  "code": "TE_QTY_TOO_LARGE",
  "suggestion": "The order quantity exceeds the maximum allowed for BTCUSDT.",
  "tip": "Reduce --orderQty or check the symbol's max order size on Phemex."
}

Other enhanced errors: insufficient balance, invalid API key, rate limiting, invalid leverage, order not found — all include suggestion and tip fields.

Safety rules

1. Always confirm before placing orders. Before calling place_order, show the user exactly what the order will do: symbol, side, quantity, type, price. Ask for confirmation.
2. Always confirm before cancelling all orders. Before calling cancel_all_orders, list the open orders first and confirm with the user.
3. Explain leverage changes. Before calling set_leverage, explain the implications (higher leverage = higher liquidation risk).
4. Show context before trading. Before suggesting a trade, show current positions and account balance so the user can make an informed decision.
5. Never auto-trade. Do not place orders without explicit user instruction.

Common workflows

Check a price

phemex-cli get_ticker --symbol BTCUSDT

Discover available symbols

phemex-cli list_symbols --contractType linear

Place a market buy (USDT-M futures)

phemex-cli place_order --symbol BTCUSDT --side Buy --orderQty 0.01 --ordType Market

Place a limit sell (Coin-M futures)

phemex-cli place_order --symbol BTCUSD --side Sell --orderQty 10 --ordType Limit --price 100000 --contractType inverse

Buy spot

phemex-cli place_order --symbol BTCUSDT --side Buy --orderQty 10 --ordType Market --contractType spot --qtyType ByQuote

Check positions

phemex-cli get_positions --currency USDT

Stream real-time prices

phemex-cli subscribe ticker --symbol BTCUSDT

Get help for any command

phemex-cli place_order --help

Setup

Option 1: Config file (recommended)

Create ~/.phemexrc — credentials persist across sessions without exporting env vars:

# ~/.phemexrc
PHEMEX_API_KEY=your-api-key
PHEMEX_API_SECRET=your-api-secret
PHEMEX_API_URL=https://api.phemex.com

# Optional: max order value limit (USD)
PHEMEX_MAX_ORDER_VALUE=1000

That's it. All phemex-cli commands will pick up these values automatically.

Option 2: Environment variables

export PHEMEX_API_KEY=your-api-key
export PHEMEX_API_SECRET=your-api-secret
export PHEMEX_API_URL=https://api.phemex.com

Configuration priority

Settings are loaded in this order (highest priority first):

1. Command-line arguments
2. Environment variables
3. ~/.phemexrc config file
4. Defaults (testnet URL)

This means env vars always override the config file, so you can safely keep production creds in ~/.phemexrc and temporarily override with PHEMEX_API_URL=https://testnet-api.phemex.com phemex-cli ... for testing.

Steps

1. Create a Phemex account at https://phemex.com
2. Create an API key (Account → API Management)
3. Save credentials to ~/.phemexrc or export as environment variables
4. Verify: phemex-cli list_symbols --contractType linear should return symbols
5. Optionally set PHEMEX_API_URL (defaults to testnet https://testnet-api.phemex.com for safety; set to https://api.phemex.com for real trading)
6. Optionally set PHEMEX_MAX_ORDER_VALUE to limit maximum order size (USD)