Legacy — API v1

This documents the legacy v1 API. New integrations should use API v2.

This guide is not currently usable

The examples on this page will not work as written. The endpoint requires authentication that this guide does not cover, and connections originating from third-party origins are rejected.

Do not build against this guide. Use Webhooks or order polling instead.

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

Code	Status	Description
0	CANCELED	Order was canceled
6	INITIATED REFUND	Refund process started
7	REFUND FAILED	Refund failed
8	REFUNDED	Order was refunded
9	PENDING KYC	Waiting for KYC verification
11	INITIAL	Order created, waiting for deposit
12	UNCONFIRMED PAYMENT	Deposit detected, waiting for confirmation
13	PAID	Deposit confirmed
14	PRE-RELEASE	Preparing to release funds
15	RELEASED	Withdraw transaction broadcasted
16	COMPLETED	Order 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
• 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