MEXC Futures SDK

A TypeScript SDK for MEXC Futures trading with REST API and WebSocket support.

⚠️ DISCLAIMER: This SDK uses browser session tokens and reverse-engineered endpoints. MEXC does not officially support futures trading through API. Use at your own risk.

Features

• ✅ REST API - Complete trading functionality
• ✅ WebSocket - Real-time market data and account updates
• ✅ TypeScript - Full type definitions
• ✅ Auto-reconnect - Reliable WebSocket connections
• ✅ Error handling - Comprehensive error management

Installation

npm install mexc-futures-sdk

Quick Start

REST API

import { MexcFuturesClient } from "mexc-futures-sdk";

const client = new MexcFuturesClient({
  authToken: "WEB_YOUR_TOKEN_HERE", // Get from browser Developer Tools
});

// Get ticker data
const ticker = await client.getTicker("BTC_USDT");
console.log("BTC Price:", ticker.data.lastPrice);

// Place a market order
const order = await client.submitOrder({
  symbol: "BTC_USDT",
  price: 50000,
  vol: 0.001,
  side: 1, // 1=open long, 3=open short
  type: 5, // 5=market order
  openType: 1, // 1=isolated margin
  leverage: 10,
});

WebSocket

import { MexcFuturesWebSocket } from "mexc-futures-sdk";

const ws = new MexcFuturesWebSocket({
  apiKey: "YOUR_API_KEY",
  secretKey: "YOUR_SECRET_KEY",
  autoReconnect: true,
});

// Connect and login
ws.on("connected", () => {
  ws.login(false).then(() => {
    console.log("Login successful");
    ws.subscribeToAll(); // Subscribe to all private data
  });
});

// Handle trading events
ws.on("orderUpdate", (data) => {
  console.log("Order Update:", data.orderId, data.symbol, data.state);
});

ws.on("positionUpdate", (data) => {
  console.log("Position:", data.symbol, data.holdVol, data.pnl);
});

ws.on("assetUpdate", (data) => {
  console.log("Balance:", data.currency, data.availableBalance);
});

await ws.connect();

Authentication

REST API - Browser Session Token

1. Login to MEXC futures in your browser
2. Open Developer Tools (F12) → Network tab
3. Make any request to futures.mexc.com
4. Find the authorization header (starts with "WEB...")
5. Copy the token value

WebSocket - API Keys

1. Go to MEXC API Management
2. Create API Key and Secret
3. Enable futures trading permissions

WebSocket Events

Private Data Events

Event	Description	Data
orderUpdate	Order status changes	Order details, state, fills
orderDeal	Order executions	Trade details, fees, profit
positionUpdate	Position changes	Size, PnL, margin, liquidation price
assetUpdate	Balance changes	Available, frozen, position margin
stopOrder	Stop-loss/take-profit	Stop prices for positions
liquidateRisk	Liquidation warnings	Margin ratio, liquidation price

Public Data Events (Optional)

Event	Description	Data
tickers	All symbol prices	Price, volume, change for all symbols
ticker	Single symbol price	Real-time price updates
depth	Order book	Bids and asks
kline	Candlestick data	OHLCV data
deal	Recent trades	Trade executions

WebSocket Subscription Options

Option 1: All Private Data (Recommended)

ws.on("login", () => {
  ws.subscribeToAll(); // Get all trading events
});

Option 2: Filtered by Symbols

ws.on("login", () => {
  ws.subscribeToMultiple([
    {
      filter: "order",
      rules: ["BTC_USDT", "ETH_USDT"], // Only these symbols
    },
    {
      filter: "position",
      rules: ["BTC_USDT", "ETH_USDT"],
    },
    {
      filter: "asset", // All balance updates
    },
  ]);
});

Option 3: Public Market Data

// Subscribe to market data
ws.subscribeToAllTickers(); // All symbol prices
ws.subscribeToTicker("BTC_USDT"); // Single symbol
ws.subscribeToDepth("BTC_USDT"); // Order book
ws.subscribeToKline("BTC_USDT", "Min1"); // 1-minute candles

Order Types and Parameters

Order Sides

• 1 = Open long position
• 2 = Close short position
• 3 = Open short position
• 4 = Close long position

Order Types

• 1 = Limit order
• 5 = Market order
• 3 = IOC (Immediate or Cancel)
• 4 = FOK (Fill or Kill)

Order States (WebSocket)

• 1 = New
• 2 = Pending
• 3 = Filled
• 4 = Cancelled

Example Orders

// Market order
await client.submitOrder({
  symbol: "BTC_USDT",
  price: 50000, // Required even for market orders
  vol: 0.001,
  side: 1, // Open long
  type: 5, // Market
  openType: 1, // Isolated margin
  leverage: 10,
});

// Limit order with stop-loss
await client.submitOrder({
  symbol: "BTC_USDT",
  price: 49000,
  vol: 0.001,
  side: 1, // Open long
  type: 1, // Limit
  openType: 1, // Isolated margin
  leverage: 10,
  stopLossPrice: 45000,
  takeProfitPrice: 55000,
});

// Close position
await client.submitOrder({
  symbol: "BTC_USDT",
  price: 51000,
  vol: 0.001,
  side: 4, // Close long
  type: 5, // Market
  openType: 1,
  positionId: 12345, // Position to close
});

Error Handling

The SDK provides comprehensive error handling with user-friendly error messages and specific error types.

Error Types

import {
  MexcAuthenticationError,
  MexcSignatureError,
  MexcApiError,
  MexcNetworkError,
  MexcValidationError,
  MexcRateLimitError,
  MexcFuturesError,
} from "mexc-futures-sdk";

Handling Different Error Types

try {
  const asset = await client.getAccountAsset("USDT");
  console.log("Success:", asset);
} catch (error) {
  if (error instanceof MexcAuthenticationError) {
    console.log("❌ Authentication failed. Please update your WEB token.");
  } else if (error instanceof MexcSignatureError) {
    console.log("❌ Signature verification failed. Get a fresh WEB token.");
  } else if (error instanceof MexcRateLimitError) {
    console.log("❌ Rate limit exceeded. Please wait before retrying.");
    if (error.retryAfter) {
      console.log(`Retry after ${error.retryAfter} seconds`);
    }
  } else if (error instanceof MexcNetworkError) {
    console.log("❌ Network error. Check your internet connection.");
  } else if (error instanceof MexcValidationError) {
    console.log(`❌ Validation error: ${error.message}`);
  } else if (error instanceof MexcApiError) {
    console.log(`❌ API error (${error.statusCode}): ${error.message}`);
  }

  // Get detailed error information for debugging
  if (error instanceof MexcFuturesError) {
    console.log("Error details:", error.getDetails());
  }
}

User-Friendly Error Messages

All errors provide user-friendly messages through getUserFriendlyMessage():

try {
  await client.submitOrder({...});
} catch (error) {
  if (error instanceof MexcFuturesError) {
    console.log(error.getUserFriendlyMessage());
    // Example: "❌ Authentication failed. Your authorization token may be expired or invalid. Please update your WEB token from browser Developer Tools."
  }
}

Common Error Scenarios

Error Type	Common Causes	Solutions
MexcAuthenticationError	Invalid/expired WEB token	Get fresh token from browser
MexcSignatureError	Token authentication failed	Update WEB token
MexcRateLimitError	Too many requests	Wait and retry
MexcNetworkError	Connection issues	Check internet connection
MexcValidationError	Invalid parameters	Check request parameters

WebSocket Error Handling

ws.on("error", (error) => {
  console.error("WebSocket error:", error);
});

ws.on("disconnected", ({ code, reason }) => {
  console.log("Disconnected:", code, reason);
});

Logging Levels

Set logLevel to control error verbosity:

const client = new MexcFuturesClient({
  authToken: "WEB_YOUR_TOKEN",
  logLevel: "INFO", // "SILENT", "ERROR", "WARN", "INFO", "DEBUG"
});

• ERROR: Only error messages
• INFO: User-friendly error messages
• DEBUG: Detailed error information for debugging

Complete Example

See examples/websocket.ts for a complete working example with:

• Connection management
• Event handlers for all data types
• Error handling
• Graceful shutdown

# Run the example
npm install
ts-node examples/websocket.ts

API Reference

REST Methods

• getTicker(symbol) - Get ticker data
• getContractDetail(symbol?) - Get contract info
• getContractDepth(symbol, limit?) - Get order book
• submitOrder(params) - Place order
• cancelOrder(orderIds) - Cancel orders
• getOrderHistory(params) - Get order history
• getPositionHistory(params) - Get position history
• getAssets() - Get account balance

WebSocket Methods

• connect() - Connect to WebSocket
• login(subscribe?) - Login and optionally auto-subscribe
• subscribeToAll() - Subscribe to all private data
• subscribeToMultiple(filters) - Subscribe with filters
• subscribeToTicker(symbol) - Market data subscriptions
• disconnect() - Close connection

Support

This is an unofficial SDK. Use at your own risk. For issues and feature requests, please open a GitHub issue.

License

MIT