AlisChain WebSocket API Documentation

Overview

The WebSocket API provides real-time updates and interactions for the AlisChain platform.

Base URL: wss://api.alischain.com/ws

Authentication

// Connect and authenticate
const ws = new WebSocket('wss://api.alischain.com/ws');
ws.onopen = () => {
    ws.send(JSON.stringify({
        type: 'auth',
        token: 'YOUR_JWT_TOKEN'
    }));
};

Events

Claim Updates

Subscribe to Claim Updates

ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'claims',
    filters: {
        status: ['pending', 'verified', 'rejected'],
        categories: ['news', 'science']
    }
}));

Receive Claim Updates

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'claim_update') {
        console.log('Claim update:', data);
        // {
        //     type: 'claim_update',
        //     claim_id: 'string',
        //     status: 'verified|rejected|pending',
        //     confidence_score: number,
        //     timestamp: string
        // }
    }
};

Verification Requests

Subscribe to Verification Requests

ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'verifications',
    filters: {
        categories: ['news', 'science'],
        min_reputation: 100
    }
}));

Receive Verification Requests

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'verification_request') {
        console.log('Verification needed:', data);
        // {
        //     type: 'verification_request',
        //     claim_id: 'string',
        //     text: 'string',
        //     category: 'string',
        //     deadline: string
        // }
    }
};

User Statistics

Subscribe to User Stats

ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'user_stats',
    user_id: 'string'
}));

Receive User Stats Updates

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'user_stats_update') {
        console.log('Stats update:', data);
        // {
        //     type: 'user_stats_update',
        //     user_id: 'string',
        //     reputation: number,
        //     stake: number,
        //     rewards: {
        //         total: number,
        //         pending: number
        //     }
        // }
    }
};

Token Events

Subscribe to Token Events

ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'tokens',
    events: ['transfer', 'stake', 'reward']
}));

Receive Token Events

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'token_event') {
        console.log('Token event:', data);
        // {
        //     type: 'token_event',
        //     event_type: 'transfer|stake|reward',
        //     amount: number,
        //     from: 'string',
        //     to: 'string',
        //     timestamp: string
        // }
    }
};

System Status

Subscribe to System Status

ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'system_status'
}));

Receive System Status Updates

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'system_status') {
        console.log('System status:', data);
        // {
        //     type: 'system_status',
        //     status: 'operational|degraded|maintenance',
        //     components: {
        //         api: 'operational|degraded|down',
        //         blockchain: 'operational|degraded|down',
        //         verification: 'operational|degraded|down'
        //     },
        //     message: 'string'
        // }
    }
};

Error Handling

Connection Errors

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

ws.onclose = (event) => {
    console.log('WebSocket closed:', event.code, event.reason);
    // Implement reconnection logic
    setTimeout(connectWebSocket, 5000);
};

Message Errors

// Error response format
{
    type: 'error',
    code: 'string',
    message: 'string',
    details: {}
}

Rate Limits

Event Type	Rate Limit
Subscribe	10 per minute
Message	100 per minute
Verification	30 per minute

SDK Integration

Python SDK

from alischain import WebSocketClient

async def handle_updates(update):
    print(f"Received update: {update}")

client = WebSocketClient('YOUR_API_KEY')
client.subscribe('claims', callback=handle_updates)
client.connect()

JavaScript SDK

import { WebSocketClient } from '@alischain/sdk';

const client = new WebSocketClient('YOUR_API_KEY');

client.on('claim_update', (update) => {
    console.log('Claim update:', update);
});

client.connect();

Best Practices

1. Connection Management
2. Implement exponential backoff for reconnections
3. Monitor connection health with ping/pong

4. Handle clean disconnections

5. Event Handling

6. Process events asynchronously
7. Implement event queuing for high-frequency updates

8. Handle out-of-order messages

9. Error Handling

10. Log all errors for debugging
11. Implement circuit breakers for repeated failures

12. Handle reconnection gracefully

13. Performance

14. Limit subscription scope
15. Batch message processing
16. Implement message debouncing

Examples

Real-time Dashboard

const dashboard = new WebSocketDashboard({
    apiKey: 'YOUR_API_KEY',
    channels: ['claims', 'user_stats', 'system_status'],
    onUpdate: (data) => updateUI(data)
});

dashboard.connect();

Verification Worker

async def verification_worker():
    client = WebSocketClient('YOUR_API_KEY')

    async def handle_verification(request):
        result = await verify_claim(request.claim_id)
        await client.send_verification(result)

    client.subscribe('verifications', callback=handle_verification)
    await client.connect()

---

Last update: 2024-12-08