WebSocket API Reference

The ACDC WebSocket API enables real-time subscriptions to chain events. Use WebSocket connections for live updates on blocks, transactions, and other chain events.

Endpoints

Chain	Network	WebSocket URL
Alpha	Mainnet	wss://alpha-ws.ac-dc.network
Alpha	Testnet	wss://alpha-testnet-ws.ac-dc.network
Delta	Mainnet	wss://delta-ws.ac-dc.network
Delta	Testnet	wss://delta-testnet-ws.ac-dc.network

Connection

JavaScript Example

const ws = new WebSocket('wss://delta-ws.ac-dc.network');

ws.onopen = () => {
  console.log('Connected to ACDC WebSocket');

  // Subscribe to new blocks
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'subscribe',
    params: ['newBlocks']
  }));
};

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

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

ws.onclose = () => {
  console.log('Disconnected');
};

Using the SDK

import { AcdcClient } from '@acdc/sdk';

const client = new AcdcClient({
  chain: 'delta',
  network: 'mainnet'
});

// Subscribe to new blocks
client.ws.subscribe('newBlocks', (block) => {
  console.log('New block:', block.number);
});

// Subscribe to address activity
client.ws.subscribe('address', {
  address: 'dx1abc123...'
}, (tx) => {
  console.log('Transaction:', tx.hash);
});

Message Format

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "<method>",
  "params": [<subscription_type>, <options>]
}

Response Format

Subscription Confirmation:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "subscriptionId": "sub_abc123"
  }
}

Subscription Event:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": { ... }
  }
}

Subscription Types

newBlocks

Subscribe to new block headers.

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["newBlocks"]
}

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "number": 1234567,
      "hash": "0xabc123...",
      "parentHash": "0xdef456...",
      "timestamp": 1704067200,
      "txCount": 150,
      "validator": "dx1validator..."
    }
  }
}

newTransactions

Subscribe to pending transactions in the mempool.

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["newTransactions"]
}

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "hash": "0xtx123...",
      "from": "dx1sender...",
      "to": "dx1receiver...",
      "value": "1000000000000000000",
      "nonce": 42
    }
  }
}

address

Subscribe to transactions involving a specific address.

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["address", {
    "address": "dx1abc123...",
    "includeTokenTransfers": true
  }]
}

Options: | Name | Type | Default | Description | |------|------|---------|-------------| | address | string | required | Address to monitor | | includeTokenTransfers | boolean | false | Include token transfers | | direction | string | "all" | "in", "out", or "all" |

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "hash": "0xtx123...",
      "from": "dx1sender...",
      "to": "dx1abc123...",
      "value": "1000000000000000000",
      "direction": "in",
      "blockNumber": 1234567,
      "status": "confirmed"
    }
  }
}

logs

Subscribe to contract event logs.

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["logs", {
    "address": "dx1contract...",
    "topics": ["0xevent_signature..."]
  }]
}

Options: | Name | Type | Default | Description | |------|------|---------|-------------| | address | string | optional | Contract address filter | | topics | array | optional | Event topic filters |

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "address": "dx1contract...",
      "topics": ["0xevent..."],
      "data": "0xdata...",
      "blockNumber": 1234567,
      "transactionHash": "0xtx...",
      "logIndex": 0
    }
  }
}

validatorUpdates

Subscribe to validator set changes (Delta chain only).

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["validatorUpdates"]
}

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "type": "joined",
      "validator": "dx1validator...",
      "stake": "1000000000000000000000000",
      "blockNumber": 1234567
    }
  }
}

governanceEvents

Subscribe to governance proposal events.

Subscribe:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["governanceEvents", {
    "proposalId": 42
  }]
}

Event Payload:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "subscriptionId": "sub_abc123",
    "result": {
      "type": "vote",
      "proposalId": 42,
      "voter": "dx1voter...",
      "vote": "yes",
      "weight": "1000000000000000000000"
    }
  }
}

Managing Subscriptions

Unsubscribe

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "unsubscribe",
  "params": ["sub_abc123"]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": true
}

List Subscriptions

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "listSubscriptions",
  "params": []
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": [
    {
      "subscriptionId": "sub_abc123",
      "type": "newBlocks",
      "created": 1704067200
    },
    {
      "subscriptionId": "sub_def456",
      "type": "address",
      "params": { "address": "dx1abc..." },
      "created": 1704067300
    }
  ]
}

Connection Management

Heartbeat

The server sends periodic ping frames. Clients should respond with pong to maintain the connection. Most WebSocket libraries handle this automatically.

Reconnection

Connections may drop due to network issues. Implement automatic reconnection:

class ReconnectingWebSocket {
  private url: string;
  private ws: WebSocket | null = null;
  private subscriptions: Map<string, object> = new Map();

  constructor(url: string) {
    this.url = url;
    this.connect();
  }

  private connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = () => {
      // Resubscribe to previous subscriptions
      this.subscriptions.forEach((params, type) => {
        this.subscribe(type, params);
      });
    };

    this.ws.onclose = () => {
      // Reconnect after delay
      setTimeout(() => this.connect(), 1000);
    };
  }

  subscribe(type: string, params: object = {}) {
    this.subscriptions.set(type, params);
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method: 'subscribe',
        params: [type, params]
      }));
    }
  }
}

Rate Limits

Tier	Max Subscriptions	Max Messages/sec
Public	10	100
Registered	100	1,000
Enterprise	Unlimited	10,000

Error Handling

Error Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Subscription limit exceeded"
  }
}

Code	Message	Description
-32000	Subscription limit exceeded	Too many active subscriptions
-32001	Invalid subscription type	Unknown subscription type
-32002	Invalid subscription params	Invalid options provided
-32003	Subscription not found	Unknown subscription ID