WebSocket API

The Cloud Service WebSocket API provides real-time notifications for blockchain events, enabling applications to react instantly to new blocks, transactions, and other network activity.

Connection

WebSocket URL

ws://localhost:16181
wss://localhost:16181  # With SSL (if configured)

Enable WebSocket

Add to your cs.conf:

wsport=16181
wsallowip=127.0.0.1
wsallowip=192.168.1.0/24

Basic Connection

const WebSocket = require('ws');

const ws = new WebSocket('ws://localhost:16181');

ws.on('open', () => {
    console.log('Connected to Cloud Service WebSocket');
});

ws.on('close', () => {
    console.log('Disconnected from Cloud Service WebSocket');
});

ws.on('error', (error) => {
    console.error('WebSocket error:', error);
});

ws.on('message', (data) => {
    const message = JSON.parse(data);
    console.log('Received:', message);
});

---

Message Format

Request Format

{
    "action": "subscribe|unsubscribe",
    "channel": "channel_name",
    "params": {
        "key": "value"
    }
}

Response Format

{
    "status": "success|error",
    "channel": "channel_name",
    "data": { ... }
}

---

Channels

new-blocks

Subscribe to new block notifications.

Subscribe:

{
    "action": "subscribe",
    "channel": "new-blocks"
}

Notification:

{
    "channel": "new-blocks",
    "data": {
        "hash": "0000...",
        "height": 524289,
        "time": 1234567890,
        "txCount": 1500,
        "size": 1250000,
        "difficulty": 12345678.90
    }
}

---

new-transactions

Subscribe to new transaction notifications.

Subscribe:

{
    "action": "subscribe",
    "channel": "new-transactions"
}

Notification:

{
    "channel": "new-transactions",
    "data": {
        "txid": "txid",
        "size": 250,
        "fee": 0.0001,
        "inputs": [
            {
                "address": "csc1q...",
                "value": 100.0
            }
        ],
        "outputs": [
            {
                "address": "csc1q...",
                "value": 50.0
            },
            {
                "address": "csc1q...",
                "value": 49.9999
            }
        ]
    }
}

---

address-transactions

Subscribe to transactions for specific addresses.

Subscribe:

{
    "action": "subscribe",
    "channel": "address-transactions",
    "params": {
        "addresses": ["csc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"]
    }
}

Notification:

{
    "channel": "address-transactions",
    "data": {
        "txid": "txid",
        "address": "csc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "type": "received|sent",
        "amount": 10.5,
        "confirmations": 0,
        "time": 1234567890
    }
}

---

mempool

Subscribe to mempool changes.

Subscribe:

{
    "action": "subscribe",
    "channel": "mempool"
}

Notification:

{
    "channel": "mempool",
    "data": {
        "action": "added|removed",
        "txid": "txid",
        "size": 250,
        "fee": 0.0001
    }
}

---

mining-info

Subscribe to mining information updates.

Subscribe:

{
    "action": "subscribe",
    "channel": "mining-info"
}

Notification:

{
    "channel": "mining-info",
    "data": {
        "blocks": 524288,
        "currentBlockWeight": 4000000,
        "currentBlockTx": 150,
        "difficulty": 12345678.90,
        "networkHashPs": 5000000000000000,
        "pooledTx": 250
    }
}

---

Complete Example

Node.js Application

const WebSocket = require('ws');

class CSCoinWebSocket {
    constructor(url = 'ws://localhost:16181') {
        this.url = url;
        this.ws = null;
        this.subscriptions = new Map();
    }

    connect() {
        return new Promise((resolve, reject) => {
            this.ws = new WebSocket(this.url);

            this.ws.on('open', () => {
                console.log('Connected');
                resolve();
            });

            this.ws.on('message', (data) => {
                const message = JSON.parse(data);
                this.handleMessage(message);
            });

            this.ws.on('error', reject);
            this.ws.on('close', () => {
                console.log('Disconnected');
            });
        });
    }

    subscribe(channel, params, callback) {
        const subscription = {
            action: 'subscribe',
            channel: channel,
            params: params || {}
        };

        this.subscriptions.set(channel, callback);
        this.ws.send(JSON.stringify(subscription));
    }

    handleMessage(message) {
        const { channel, data } = message;
        if (this.subscriptions.has(channel)) {
            this.subscriptions.get(channel)(data);
        }
    }

    disconnect() {
        if (this.ws) {
            this.ws.close();
        }
    }
}

// Usage
const cscWS = new CSCoinWebSocket();

cscWS.connect().then(() => {
    // Subscribe to new blocks
    cscWS.subscribe('new-blocks', {}, (data) => {
        console.log('New block:', data);
    });

    // Subscribe to address transactions
    cscWS.subscribe('address-transactions', {
        addresses: ['csc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh']
    }, (data) => {
        console.log('Address transaction:', data);
    });
});

Python Example

import asyncio
import websockets
import json

async def cscoin_websocket():
    uri = "ws://localhost:16181"
    
    async with websockets.connect(uri) as websocket:
        # Subscribe to new blocks
        await websocket.send(json.dumps({
            "action": "subscribe",
            "channel": "new-blocks"
        }))
        
        # Listen for messages
        async for message in websocket:
            data = json.loads(message)
            print(f"Received: {data}")

asyncio.get_event_loop().run_until_complete(cscoin_websocket())

---

Authentication

For private channels, include authentication token:

{
    "action": "auth",
    "token": "your_auth_token"
}

---

Rate Limiting

Channel	Limit
new-blocks	~720 messages/day
new-transactions	Unlimited
address-transactions	Unlimited
mempool	1000 messages/min
mining-info	~720 messages/day

---

Error Handling

Common Errors

Error	Description
invalid_channel	Channel doesn't exist
invalid_params	Missing or invalid parameters
rate_limit_exceeded	Too many messages
auth_required	Authentication required

Error Response

{
    "status": "error",
    "error": {
        "code": "invalid_channel",
        "message": "Channel 'invalid' does not exist"
    }
}

---

Next Steps

• API Overview — Back to overview
• RPC Commands — Complete RPC reference
• REST API — REST endpoints