💡API

The API is currently in beta, which means that breaking changes may be introduced

1. Overview

The WebSocket API provides real-time updates about various accounts (e.g., UpdateAccountInformationDTO, UpdateHistoryDTO, UpdateOpenPositionsDTO). Clients can subscribe to one or more accounts and automatically receive new data whenever it’s published.

Communication uses STOMP (Simple Text Oriented Messaging Protocol) over a standard WebSocket. You can use any STOMP client library that supports WebSockets (e.g., @stomp/stompjs in Node.js or JavaScript).

Do not forget to add the 'Socket' feature to the account from which you want to receive real-time data. If the feature is not added, no updates will be sent for this account. Socket

---

2. Connection & Authentication

• Endpoint: wss://api.metacopier.io/ws/api/v1

• Authentication:

  • Each client must provide an api-key in the STOMP CONNECT headers.

  • Example STOMP connect header:

    "api-key": "YOUR_API_KEY"

  • If the api-key is missing or invalid, the connection will be rejected.

---

3. Subscribe Flow

After a successful STOMP CONNECT:

1. SUBSCRIBE to a private queue destination such as:

   /user/queue/accounts/changes

   or any other user-specific route your server is configured to send messages to.

   • This tells the server: “Send updates for my session to me at this address.”

2. SEND a JSON body to "/app/subscribe" that indicates which accounts you want:

   • If you send an empty list, it means “subscribe me to all accounts that my api-key can access.”

   • If you send a non-empty list (["uuid1", "uuid2"]), you only receive updates for those specific accounts.

Example Subscription Request

{
  "accountIds": []
}

(Empty array => all accounts)

STOMP Frame

SEND
destination:/app/subscribe
content-type:application/json

{
  "accountIds": []
}
^@

---

4. Messages & Destinations

• Receiving Updates:

  • You will receive messages on your private user queue (e.g. "/user/queue/accounts/changes").

  • The server sends a copy of each relevant update (based on your subscription) to only your session.

• Message Types:

  1. UpdateAccountInformationDTO

  2. UpdateHistoryDTO (contains a list of PositionDTO)

  3. UpdateOpenPositionsDTO (contains a list of PositionDTO)

(See Data Format for details.)

---

5. Data Format (DTOs)

The server wraps each outgoing message in a MessageWrapper object with two fields:

1. type – This is the simple name of the DTO class. For example:

   • "UpdateAccountInformationDTO"

   • "UpdateOpenPositionsDTO"

   • "UpdateHistoryDTO"

2. data – The actual DTO (serialized as JSON).

Example JSON Messages

1. UpdateAccountInformationDTO

   {
     "type": "UpdateAccountInformationDTO",
     "data": {
       "accountId": "11111111-1111-1111-1111-111111111111",
       "info": {
         "id": "11111111-1111-1111-1111-111111111111",
         "balance": 1000.0,
         "equity": 980.5,
         "leverage": 100,
         "profitThisMonth": 25.0,
         "currency": "USD",
         "connected": true,
         "fallbackMode": false,
         "compatibilityMode": false,
         "status": "active",
         "drawdown": 2.5,
         "riskLimitsStatus": [],
         "profitTargetsStatus": [],
         "isInvestorPassword": false,
         "brokeTimeOffsetToUtc": 2,
         "latencyInMs": 120,
         "openPositions": true,
         "pendingOrders": false,
         "positionMismatch": false,
         "proxy": {},
         "wrongCredentials": false,
         "pendingApprovals": [],
         "timestamp": "2025-02-13T12:00:00Z",
         "lastConnectedTimestamp": "2025-02-13T11:55:00Z",
         "lastCTraderTokenRefreshed": "2025-02-13T11:00:00Z",
         "allSymbolsInfoLoaded": true,
         "hftMode": false
       }
     }
   }

2. UpdateHistoryDTO (history positions only for the last 24h)

   {
     "type": "UpdateHistoryDTO",
     "data": {
       "accountId": "22222222-2222-2222-2222-222222222222",
       "history": [
         {
           "id": "pos-123",
           "dealType": "...",
           "openTime": "2025-02-13T09:30:00Z",
           "closeTime": "2025-02-13T10:00:00Z",
           "openPrice": 1.2345
           // ...
         }
       ]
     }
   }

3. UpdateOpenPositionsDTO

   {
     "type": "UpdateOpenPositionsDTO",
     "data": {
       "accountId": "33333333-3333-3333-3333-333333333333",
       "openPositions": [
         {
           "id": "pos-456",
           "symbol": "EURUSD",
           "openPrice": 1.1200,
           "closePrice": null,
           "volume": 0.1
           // ...
         }
       ]
     }
   }

Identifying the DTO

Since "type" is now the class simple name, you can simply check:

• "UpdateAccountInformationDTO" => The "data" field is an UpdateAccountInformationDTO

• "UpdateHistoryDTO" => The "data" field is an UpdateHistoryDTO

• "UpdateOpenPositionsDTO" => The "data" field is an UpdateOpenPositionsDTO

For example (in JavaScript/Node):

if (message.type === 'UpdateAccountInformationDTO') {
  // parse message.data as UpdateAccountInformationDTO
} else if (message.type === 'UpdateHistoryDTO') {
  // parse message.data as UpdateHistoryDTO
} else if (message.type === 'UpdateOpenPositionsDTO') {
  // parse message.data as UpdateOpenPositionsDTO
}

This ensures you always know which DTO you’re handling without guessing based on field names.

---

6. Example Client Code (Node.js)

Here is a simplified Node.js example using @stomp/stompjs and ws:

npm install @stomp/stompjs ws

const { Client } = require('@stomp/stompjs');
const WebSocket = require('ws');

const client = new Client({
  // Where to connect
  brokerURL: "wss://api.metacopier.io/ws/api/v1",
  // Provide your API key in the STOMP headers here
  connectHeaders: {
    // e.g. 'api-key': 'YOUR_API_KEY_HERE'
    'api-key': 'REPLACE_WITH_YOUR_API_KEY'
  },

  debug: (str) => console.log('[STOMP DEBUG]', str),
  reconnectDelay: 5000,

  // For Node.js, pass in the WebSocket factory
  webSocketFactory: () => new WebSocket('wss://api.metacopier.io/ws/api/v1')
});

client.onConnect = (frame) => {
  console.log('Connected via STOMP:', frame.headers);

  // 1) Subscribe to user-specific updates
  client.subscribe('/user/queue/accounts/changes', (message) => {
    console.log('RAW message =>', message.body);
    try {
      const data = JSON.parse(message.body);
      if (data.type === 'UpdateAccountInformationDTO') {
        console.log('Received UpdateAccountInformationDTO:', data.data);
      } else if (data.type === 'UpdateOpenPositionsDTO') {
        console.log('Received UpdateOpenPositionsDTO:', data.data);
      } else if (data.type === 'UpdateHistoryDTO') {
        console.log('Received UpdateHistoryDTO:', data.data);
      } else {
        console.log('Unknown payload type:', data);
      }
    } catch (err) {
      console.error('Failed to parse JSON', err);
    }
  });

  // 2) Send a subscription request to /app/subscribe
  //    If you want to subscribe to all accessible accounts, pass an empty array:
  const request = {
    accountIds: []
  };

  client.publish({
    destination: '/app/subscribe',
    body: JSON.stringify(request)
  });
};

client.onStompError = (frame) => {
  console.error('Broker error:', frame.headers['message'], frame.body);
};

client.activate();

1. brokerURL: Points to the WebSocket/STOMP endpoint.

2. connectHeaders: Replace 'REPLACE_WITH_YOUR_API_KEY' with your own API key.

3. subscribe: We subscribe to "/user/queue/accounts/changes", which is a private user queue (messages are sent only to your session).

4. publish: We send a JSON body to "/app/subscribe" specifying which account IDs we want ([] means all).

5. message handling: We parse the JSON body. Because the server sends a MessageWrapper with a type field, we switch on data.type to see whether it’s an UpdateAccountInformationDTO, UpdateHistoryDTO, or UpdateOpenPositionsDTO.

That’s all you need to connect, authenticate, subscribe, and receive real-time data!

---

7. Error Handling & Disconnects

1. Invalid API Key: If your api-key is wrong or expired, the server will send a STOMP ERROR frame or close the socket. Check logs for the cause.

2. Connection Loss: If the server or network goes down, your client might attempt to reconnect (reconnectDelay=5000 means it tries every 5 seconds).

3. Disconnect: The client can call client.deactivate() (in @stomp/stompjs) or close the WebSocket to end the session.

4. Server may forcibly close the connection if you exceed concurrency limits or do not have permission for certain accounts.

---

8. Connection Limits

1. Global or Per-API-Key Limits: We may enforce a maximum number of concurrent WebSocket sessions per API key (or a global total). If you try to exceed these limits, the server will reject additional connections.

2. Disconnect on Excess: If your API key opens more than the allowed sessions, the newest or oldest connection might be forcibly disconnected, or the server might send an ERROR frame.

3. IP-Based Limits: We may also optionally limit the number of connections from a single IP address to prevent abuse.

4. What This Means for You: If you encounter frequent disconnects or ERROR frames mentioning concurrency, verify how many clients are simultaneously connecting with your API key/IP.

5. Contact Support: If you need higher concurrency or have special requirements, reach out to the support team.

---

Conclusion

This WebSocket STOMP API allows real-time account updates. Once connected (with a valid api-key), you send a subscription message specifying which account(s) you want, and you receive JSON-encoded DTOs for relevant updates.

If you have any further questions or need more details, please contact our support team. Enjoy building real-time solutions with the WebSocket API!