WebSocket Setup

Quick Start

For quick integration, follow these steps:

1. Connect to wss://ws.noodles.fi/ws/coin-update

2. Send periodic pings every 30 seconds to keep connection alive

3. Subscribe using the room-based format (recommended)

4. Handle messages by checking the type field

5. Implement reconnection: On disconnect, automatically reconnect and resubscribe to your channels

Endpoints

wss://ws.noodles.fi/ws/coin-update

CORS Validation

• Web browser connections must pass CORS validation based on the Origin header.

• Contact @hiephho on Telegram for whitelisting your domain.

• If CORS validation fails, the server will send 403 Forbidden status code and close the connection.

Available Rooms

The WebSocket service supports four main data rooms:

1. TRADES - Real-time trading transaction data

2. COIN_UPDATES - Real-time coin updates for coins (price, price change, volume, maker, etc.)

3. OHLC - Candlestick/OHLC data for various time intervals

Coin ID Format

All coin identifiers follow the format: {package}::{module}::{type}

Examples:

• SUI: 0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI

• USDC: 0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC

Message Protocol

Message Types

Type	Direction	Purpose
ping	Client → Server	Keep connection alive
pong	Server → Client	Ping response
subscribe	Client → Server	Subscribe to a channel
unsubscribe	Client → Server	Unsubscribe from a channel
data	Server → Client	Real-time data or acknowledgments
error	Server → Client	Error messages

Client Message Format

{
  "type": "subscribe|unsubscribe|ping",
  "room": "ROOM_NAME",
  "data": {
    // Room-specific data
  }
}

Examples:

Subscribe to trades for a single coin:

{
  "type": "subscribe",
  "room": "TRADES",
  "data": {
    "coin": "0x2::sui::SUI"
  }
}

Subscribe to coin statistic updates for multiple coins:

{
  "type": "subscribe",
  "room": "COIN_UPDATES",
  "data": {
    "coins": [
      "0x2::sui::SUI",
      "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
    ]
  }
}

Subscribe to OHLC data:

{
  "type": "subscribe",
  "room": "OHLC",
  "data": {
    "coin": "0x2::sui::SUI",
    "bucket": 5
  }
}

Server Message Format

{
  "type": "data|error|pong|subscribe|unsubscribe",
  "channel": "CHANNEL_NAME",
  "room": "ROOM_NAME",
  "data": { ... },
  "error": "error_message"
}

Subscription Confirmation

When you subscribe or unsubscribe, the server sends a confirmation message:

{
  "type": "subscribe",
  "data": {
    "action": "subscribe",
    "channels": ["TRADES-0x2::sui::SUI"],
    "room": "TRADES"
  }
}

Error Handling

Common Error Messages

Error	Description	Resolution
"Invalid channel format"	Channel name doesn't follow expected format	Check channel naming convention
"Invalid coin"	Coin ID is not valid	Verify coin ID format
"Invalid room"	Unsupported room type	Use TRADES, COIN_UPDATES, OHLC, or ALERTS
"Invalid bucket"	Unsupported time bucket for OHLC	Use supported time intervals (1, 5, 15, 30, 60, 240, 1440, 10080, 43200)
"Invalid coins format"	Coins array format is incorrect	Ensure coins is an array of valid coin IDs
"Invalid wallet"	Wallet address is not valid	Verify wallet address format
"Invalid message format"	Message JSON is malformed	Check JSON syntax
"Unsupported message type"	Unknown message type	Use ping, subscribe, or unsubscribe

Connection Errors

• Rate Limit Exceeded: Temporary IP blocking due to too many connection attempts (http status 429)

• Origin Not Allowed: CORS validation failure (http status 403)

• Connection Timeout: Network connectivity issues

Rate Limits

• Maximum Connections per IP: 20

• Maximum Connection Attempts per Minute: 30

• Blocking Duration: 10 minutes for IPs exceeding limits

Integration Examples

JavaScript/Web Browser

// Connect to WebSocket
const ws = new WebSocket('wss://ws.noodles.fi/ws/coin-update');

// Connection opened
ws.onopen = function() {
    console.log('Connected to Noodles WebSocket');
    
    // Send ping to keep connection alive
    ws.send(JSON.stringify({
        type: 'ping'
    }));
    
    // Subscribe to USDC trading data (new format - recommended)
    ws.send(JSON.stringify({
        type: 'subscribe',
        room: 'TRADES',
        data: {
            coin: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC'
        }
    }));
};

// Handle incoming messages
ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    switch(message.type) {
        case 'data':
            handleDataMessage(message);
            break;
        case 'error':
            console.error('WebSocket error:', message.error);
            break;
        case 'pong':
            console.log('Received pong from server');
            break;
    }
};

function handleDataMessage(message) {
    const { channel, room, data } = message;
    
    // Check if it's a subscription confirmation
    if (data && data.action && (data.action === 'subscribe' || data.action === 'unsubscribe')) {
        console.log(`${data.action} confirmed for room ${data.room}:`, data.channels);
        return;
    }
    
    // Handle data based on room type
    if (room === 'TRADES' || channel?.startsWith('TRADES-')) {
        console.log('Trading data:', data);
    } else if (room === 'COIN_UPDATES' || channel?.startsWith('COIN_UPDATES-')) {
        console.log('Price update:', data);
    } else if (room === 'OHLC' || channel?.startsWith('OHLC.')) {
        console.log('OHLC data:', data);
    } else if (room === 'ALERTS' || channel?.startsWith('ALERTS.')) {
        console.log('Wallet alert:', data);
    }
}

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

// Connection closed
ws.onclose = function(event) {
    console.log('WebSocket connection closed:', event.code, event.reason);
};

// Unsubscribe from a channel 
function unsubscribe(room, coin, bucket) {
    const message = {
        type: 'unsubscribe',
        room: room,
        data: {}
    };
    
    if (room === 'TRADES' || room === 'OHLC') {
        message.data.coin = coin;
        if (room === 'OHLC' && bucket) {
            message.data.bucket = bucket;
        }
    } else if (room === 'COIN_UPDATES') {
        message.data.coins = Array.isArray(coin) ? coin : [coin];
    }
    
    ws.send(JSON.stringify(message));
}

// Example usage:
// unsubscribe('TRADES', '0x2::sui::SUI');
// unsubscribe('OHLC', '0x2::sui::SUI', 5);
// unsubscribe('COIN_UPDATES', ['0x2::sui::SUI', '0xdba...::usdc::USDC']);

For more detailed examples including TypeScript integrations, see the individual room documentation pages.