MetaAPI - Complete API Documentation

Single forex trading API for all your MetaTrader accounts

Account Management API

Manage MetaTrader accounts - create, read, update, deploy, and delete accounts.

GET /api/accounts

Get all accounts with optional filtering and pagination.

Query Parameters

limit number Optional. Maximum number of accounts to return
offset number Optional. Number of accounts to skip
query string Optional. Search query to filter accounts
state string Optional. Filter by account state (e.g., 'DEPLOYED')
Example Request 
GET /api/accounts?limit=10&offset=0&state=DEPLOYED
Example Response 
{
  "success": true,
  "data": [
    {
      "_id": "account-id-123",
      "name": "My Trading Account",
      "login": "12345678",
      "server": "MetaQuotes-Demo",
      "platform": "mt5",
      "state": "DEPLOYED",
      "connectionId": "conn-id-456",
      "createdAt": "2024-01-15T10:00:00Z",
      "lastUpdated": "2024-01-15T10:00:00Z"
    }
  ],
  "count": 1
}
GET /api/accounts/:accountId

Get a specific account by ID.

Example Response 
{
  "success": true,
  "data": {
    "_id": "account-id-123",
    "name": "My Trading Account",
    "login": "12345678",
    "server": "MetaQuotes-Demo",
    "platform": "mt5",
    "state": "DEPLOYED",
    "connectionId": "conn-id-456"
  }
}
POST /api/accounts

Create a new MetaTrader account.

Example Request Body 
{
  "name": "New Trading Account",
  "login": "87654321",
  "password": "your-password",
  "server": "MetaQuotes-Demo",
  "platform": "mt5",
  "application": "MetaApi"
}
Example Response 
{
  "success": true,
  "data": {
    "_id": "new-account-id",
    "name": "New Trading Account",
    "login": "87654321",
    "server": "MetaQuotes-Demo",
    "platform": "mt5",
    "state": "CREATED",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "message": "Account created successfully"
}
PUT /api/accounts/:accountId

Update an existing account.

Example Request Body 
{
  "name": "Updated Account Name",
  "password": "new-password"
}
DELETE /api/accounts/:accountId

Delete an account.

POST /api/accounts/:accountId/deploy

Deploy an account to start receiving real-time data.

POST /api/accounts/:accountId/undeploy

Undeploy an account to stop receiving real-time data.

Trading Operations API

Execute trades, get positions, orders, and portfolio information.

GET /api/health

Health check endpoint to verify API connectivity.

Example Response 
{
  "success": true,
  "status": "ok",
  "timestamp": "2024-01-15T10:00:00.000Z"
}
GET /api/positions

Get all open positions with risk calculations.

Example Response 
{
  "success": true,
  "data": [
    {
      "id": "123456789",
      "symbol": "EURUSD",
      "type": "POSITION_TYPE_BUY",
      "volume": 0.1,
      "openPrice": 1.08500,
      "currentPrice": 1.08650,
      "profit": 15.00,
      "swap": 0.00,
      "commission": -0.70,
      "unrealizedProfit": 14.30,
      "stopLoss": 1.08000,
      "takeProfit": 1.09000,
      "risk": {
        "exposure": 10850.00,
        "riskPercent": 2.5,
        "riskAmount": 271.25
      }
    }
  ],
  "count": 1
}
GET /api/dashboard

Get complete dashboard data including account info, positions, and portfolio risk.

Example Response 
{
  "success": true,
  "data": {
    "account": {
      "balance": 10000.00,
      "equity": 10150.00,
      "margin": 850.00,
      "freeMargin": 9300.00,
      "marginLevel": 1194.12,
      "profit": 150.00,
      "currency": "USD"
    },
    "positions": [...],
    "portfolio": {
      "totalExposure": 10850.00,
      "totalRisk": 271.25,
      "riskPercent": 2.71,
      "diversification": 3,
      "longPositions": 2,
      "shortPositions": 1
    }
  }
}
GET /api/orders

Get all pending orders.

Example Response 
{
  "success": true,
  "data": [
    {
      "id": "987654321",
      "symbol": "GBPUSD",
      "type": "ORDER_TYPE_BUY_LIMIT",
      "volume": 0.1,
      "openPrice": 1.25000,
      "stopLoss": 1.24500,
      "takeProfit": 1.26000,
      "currentPrice": 1.24800,
      "state": "ORDER_STATE_PLACED"
    }
  ],
  "count": 1
}
POST /api/orders

Place a new market or pending order.

Request Body

symbol string Required. Trading symbol (e.g., 'EURUSD')
volume number Required. Order volume in lots
type string Order type: 'MARKET', 'LIMIT', 'STOP', 'STOP_LIMIT'
action string Trade action: 'BUY', 'SELL'
stopLoss number Optional. Stop loss price
takeProfit number Optional. Take profit price
Example Request Body 
{
  "symbol": "EURUSD",
  "volume": 0.1,
  "type": "MARKET",
  "action": "BUY",
  "stopLoss": 1.08000,
  "takeProfit": 1.09000
}
Example Response 
{
  "success": true,
  "data": {
    "orderId": "123456789",
    "requestId": "req-123",
    "symbol": "EURUSD",
    "volume": 0.1,
    "type": "ORDER_TYPE_BUY",
    "openPrice": 1.08500,
    "stopLoss": 1.08000,
    "takeProfit": 1.09000
  }
}

Market Data API

Get current prices, historical data, and symbol specifications.

GET /api/prices/:symbol

Get current price for a specific symbol.

Example Request 
GET /api/prices/EURUSD
Example Response 
{
  "success": true,
  "data": {
    "symbol": "EURUSD",
    "bid": 1.08500,
    "ask": 1.08520,
    "spread": 0.00020,
    "time": "2024-01-15T10:00:00Z"
  }
}
POST /api/prices/multiple

Get prices for multiple symbols at once.

Example Request Body 
{
  "symbols": ["EURUSD", "GBPUSD", "USDJPY", "XAUUSD"]
}
GET /api/prices/popular/all

Get prices for popular symbols (EURUSD, GBPUSD, USDJPY, XAUUSD, XAGUSD).

Market Watch API: Additional endpoints available under /api/marketwatch
GET /api/marketwatch/symbols

Get all symbols from Market Watch.

GET /api/marketwatch/symbols/specs

Get Market Watch symbols with full specifications.

GET /api/marketwatch/prices

Get current prices for all Market Watch symbols.

GET /api/marketwatch/symbol/:symbol/spec

Get specification for a specific symbol (contract size, pip value, etc.).

GET /api/marketwatch/symbol/:symbol/price

Get current price for a specific symbol from Market Watch.

GET /api/marketwatch/dashboard

Get complete Market Watch dashboard data with all symbols and prices.

Risk Management API

Prop trading risk management features - trackers, statistics, and equity charts.

GET /api/risk/tracker-events

Get tracker events by time range.

Query Parameters

startTime string ISO datetime string for start time
endTime string ISO datetime string for end time
GET /api/risk/tracker-events/stream

Stream tracker events in real-time via Server-Sent Events (SSE).

SSE Connection 
const eventSource = new EventSource('/api/risk/tracker-events/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Tracker event:', data);
};
GET /api/risk/accounts/:accountId/trackers

Get all trackers for an account.

POST /api/risk/accounts/:accountId/trackers

Create a new risk tracker.

Example Request Body 
{
  "name": "Daily Loss Limit",
  "type": "dailyLossLimit",
  "period": "DAY",
  "value": 500.00,
  "enabled": true
}
GET /api/risk/accounts/:accountId/trackers/:id

Get a specific tracker by ID.

PUT /api/risk/accounts/:accountId/trackers/:id

Update a tracker.

DELETE /api/risk/accounts/:accountId/trackers/:id

Delete a tracker.

GET /api/risk/accounts/:accountId/trackers/:id/statistics

Get period statistics for a tracker.

GET /api/risk/accounts/:accountId/equity-chart

Get equity chart data for an account.

Real-time Streaming API

Stream real-time price updates via Server-Sent Events (SSE) or WebSocket.

GET /api/stream/sse

Server-Sent Events endpoint for real-time price streaming.

JavaScript Example 
const eventSource = new EventSource('/api/stream/sse');

eventSource.onmessage = (event) => {
  const priceData = JSON.parse(event.data);
  console.log('Price update:', priceData);
  // {
  //   "symbol": "EURUSD",
  //   "bid": 1.08500,
  //   "ask": 1.08520,
  //   "spread": 0.00020,
  //   "time": "2024-01-15T10:00:00Z",
  //   "equity": 10000.00
  // }
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
};
GET /api/stream/stats

Get streaming service statistics.

Example Response 
{
  "success": true,
  "data": {
    "websocketClients": 5,
    "sseClients": 3,
    "trackerEventClients": 2,
    "totalClients": 10,
    "isListening": true,
    "symbolsTracked": 15,
    "trackerEventsTracked": 50
  }
}
POST /api/stream/start

Start listening to price updates for specified symbols.

Example Request Body 
{
  "symbols": ["EURUSD", "GBPUSD", "USDJPY", "XAUUSD"]
}
Example Response 
{
  "success": true,
  "message": "Streaming started"
}

WebSocket API

Real-time bidirectional communication using WebSocket protocol.

WebSocket Endpoint: ws://localhost:3000/ws or wss://your-domain.com/ws
WS /ws

Connect to WebSocket server for real-time price updates.

JavaScript Connection Example 
const ws = new WebSocket('ws://localhost:3000/ws');

// Connection opened
ws.onopen = () => {
  console.log('WebSocket connected');
  
  // Send subscribe message
  ws.send(JSON.stringify({
    type: 'subscribe',
    symbols: ['EURUSD', 'GBPUSD']
  }));
};

// Listen for messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
  
  // Price update format:
  // {
  //   "symbol": "EURUSD",
  //   "bid": 1.08500,
  //   "ask": 1.08520,
  //   "spread": 0.00020,
  //   "time": "2024-01-15T10:00:00Z",
  //   "equity": 10000.00
  // }
};

// Handle errors
ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

// Connection closed
ws.onclose = () => {
  console.log('WebSocket disconnected');
};

WebSocket Message Types

Client → Server Messages

subscribe object Subscribe to symbol updates
unsubscribe object Unsubscribe from symbols
ping object Keep connection alive
Subscribe Message 
{
  "type": "subscribe",
  "symbols": ["EURUSD", "GBPUSD", "USDJPY"]
}
Unsubscribe Message 
{
  "type": "unsubscribe",
  "symbols": ["EURUSD"]
}
Ping Message 
{
  "type": "ping"
}

Server → Client Messages

initial object Initial prices sent on connection
price object Real-time price update
status object Connection status update
pong object Response to ping
subscribed object Confirmation of subscription
unsubscribed object Confirmation of unsubscription
Price Update Message 
{
  "symbol": "EURUSD",
  "bid": 1.08500,
  "ask": 1.08520,
  "spread": 0.00020,
  "time": "2024-01-15T10:00:00Z",
  "equity": 10000.00
}
Initial Prices Message 
{
  "type": "initial",
  "prices": [
    {
      "symbol": "EURUSD",
      "bid": 1.08500,
      "ask": 1.08520,
      "spread": 0.00020,
      "time": "2024-01-15T10:00:00Z"
    },
    {
      "symbol": "GBPUSD",
      "bid": 1.26500,
      "ask": 1.26520,
      "spread": 0.00020,
      "time": "2024-01-15T10:00:00Z"
    }
  ]
}
Status Message 
{
  "type": "status",
  "status": "connected",
  "message": "Real-time streaming connected"
}