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