Skip to main content
Version: v2

WebSocket Usage

This guide explains how to use the WebSocket API for real-time order updates.

🔌 Connection​

Connect to the WebSocket endpoint:

const ws = new WebSocket('wss://api.n.exchange/orders/');

📝 Subscription​

Subscribe to order updates by sending a JSON message:

ws.send(JSON.stringify({
    subscribe: 'ORDER_REFERENCE_123'
}));

📨 Message Types​

Subscription Confirmation​

{
    "subscribed": "ORDER_REFERENCE_123"
}

Order Status Update​

{
    "unique_reference": "ORDER_REFERENCE_123",
    "status": 13,
    "status_name": [[13, "PAID"]],
    "amount_base": "0.001",
    "amount_quote": "50.00",
    "deposit_currency": "BTC",
    "withdraw_currency": "USD",
    "pair": {
        "name": "BTCUSD",
        "base": "BTC",
        "quote": "USD"
    },
    "created_on": "2024-01-01T12:00:00Z",
    "modified_on": "2024-01-01T12:00:00Z",
    "message_type": "order_status_update",
    "websocket_timestamp": "2024-01-01T12:00:00Z"
}

🚀 Complete Example​

const ws = new WebSocket('wss://api.n.exchange/orders/');

ws.onopen = function() {
    console.log('✅ Connected to WebSocket');

    // Subscribe to an order
    ws.send(JSON.stringify({
        subscribe: 'ORDER_REFERENCE_123'
    }));
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);

    if (data.subscribed) {
        console.log(`✅ Subscribed to: ${data.subscribed}`);
    } else if (data.message_type === 'order_status_update') {
        console.log('🔄 Order Update:', data);

        // Handle different statuses
        switch(data.status) {
            case 13:
                console.log('✅ Order PAID');
                break;
            case 14:
                console.log('🚀 Order PRE-RELEASE');
                break;
            case 15:
                console.log('📤 Order RELEASED');
                break;
            case 16:
                console.log('🎉 Order COMPLETED');
                break;
            default:
                console.log(`Status: ${data.status}`);
        }
    }
};

ws.onerror = function(error) {
    console.error('❌ WebSocket error:', error);
};

ws.onclose = function() {
    console.log('🔌 WebSocket connection closed');
};

📊 Status Codes​

CodeStatusDescription
0CANCELEDOrder was canceled
6INITIATED REFUNDRefund process started
7REFUND FAILEDRefund failed
8REFUNDEDOrder was refunded
9PENDING KYCWaiting for KYC verification
11INITIALOrder created, waiting for deposit
12UNCONFIRMED PAYMENTDeposit detected, waiting for confirmation
13PAIDDeposit confirmed
14PRE-RELEASEPreparing to release funds
15RELEASEDWithdraw transaction broadcasted
16COMPLETEDOrder completed successfully

🔧 Error Handling​

ws.onerror = function(error) {
    console.error('WebSocket error:', error);
};

ws.onclose = function(event) {
    if (event.code === 1000) {
        console.log('Connection closed normally');
    } else {
        console.log('Connection closed unexpectedly');
        // Implement reconnection logic
    }
};

🔄 Reconnection​

function connect() {
    const ws = new WebSocket('wss://api.n.exchange/orders/');

    ws.onopen = function() {
        console.log('✅ Reconnected');
        // Resubscribe to orders
        ws.send(JSON.stringify({
            subscribe: 'ORDER_REFERENCE_123'
        }));
    };

    ws.onclose = function() {
        console.log('🔌 Connection lost, reconnecting...');
        setTimeout(connect, 5000); // Retry after 5 seconds
    };

    return ws;
}

📱 Browser Example​

<!DOCTYPE html>
<html>
<head>
    <title>WebSocket Order Updates</title>
</head>
<body>
    <h1>Order Updates</h1>
    <div id="messages"></div>

    <script>
        const ws = new WebSocket('wss://api.n.exchange/orders/');
        const messagesDiv = document.getElementById('messages');

        ws.onopen = function() {
            addMessage('✅ Connected to WebSocket');

            // Subscribe to an order
            ws.send(JSON.stringify({
                subscribe: 'ORDER_REFERENCE_123'
            }));
        };

        ws.onmessage = function(event) {
            const data = JSON.parse(event.data);

            if (data.subscribed) {
                addMessage(`✅ Subscribed to: ${data.subscribed}`);
            } else if (data.message_type === 'order_status_update') {
                addMessage(`🔄 Order Update: ${data.unique_reference} - Status: ${data.status}`);
            }
        };

        ws.onerror = function(error) {
            addMessage('❌ WebSocket error');
        };

        ws.onclose = function() {
            addMessage('🔌 WebSocket connection closed');
        };

        function addMessage(text) {
            const div = document.createElement('div');
            div.textContent = new Date().toLocaleTimeString() + ': ' + text;
            messagesDiv.appendChild(div);
        }
    </script>
</body>
</html>

🔒 Security​

  • WebSocket connections use WSS (secure WebSocket) in production
  • No authentication is required for public order updates
  • Consider implementing rate limiting for high-frequency connections

📞 Support​

For issues with WebSocket connections:

  1. Check if the server is running
  2. Verify the WebSocket URL is correct
  3. Check browser console for errors
  4. Ensure your network allows WebSocket connections