WebSocket API Overview

Overview

The Hathor WebSocket API enables real-time, bidirectional communication with a full node.

Unlike HTTP APIs, WebSocket connections provide:

• Continuous event streaming
• Low-latency server push updates
• Efficient state synchronization
• Built-in flow control mechanisms

This API is designed for applications that require live data, such as wallets, explorers, and mining clients.

Available Endpoints

The WebSocket API is composed of three specialized endpoints:

Endpoint	Path	Purpose
Admin WebSocket	/ws	Wallet events, subscriptions, and metrics
Event WebSocket	/event_ws	Reliable event streaming with replay
Mining WebSocket	/mining	JSON-RPC mining protocol

Connection

The WebSocket URL is derived from the full node HTTP base URL:

HTTP	WebSocket
https://node.example.com/v1a/	wss://node.example.com/v1a/ws/

Rules:

• http → ws
• https → wss
• /ws/ is appended to the base path

Message Structure

All messages are JSON objects with a mandatory type field:

{
  "type": "<message_type>"
}

Message types may use namespaced formats:

"stream:history:vertex"

Message Direction

All messages are defined from the server perspective:

Direction	Meaning
Client → Server	Commands / Requests
Server → Client	Events / Responses

Keepalive

Client → Server

{ 
  "type": "ping" 
}

Server → Client

{ 
  "type": "pong" 
}

Capability Discovery

{
  "type": "capabilities",
  "capabilities": ["history-streaming"]
}

Admin WebSocket (/ws)

The Admin WebSocket provides real-time interaction with wallet data, network metrics, and transaction history.

It supports:

• Address-based subscriptions for wallet updates
• Live balance and transaction notifications
• Network statistics streaming
• Transaction history streaming with flow control and acknowledgments

Example Flow

The general connection flow would be:

1. Connect to /ws
2. Receive capabilities
3. Subscribe to addresses
4. Receive wallet and network events
5. Optionally request history streaming

Subscription Example

Subscribe

{
  "type": "subscribe_address",
  "address": "<base58-address>"
}

Unsubscribing

{
  "type": "unsubscribe_address",
  "address": "<base58-address>"
}

Key Events

• dashboard:metrics → Network statistics
• network:new_tx_accepted → New transaction or block
• wallet:output_received → Incoming funds
• wallet:output_spent → Outgoing funds
• wallet:balance_updated → Balance changes
• wallet:address_history → Address activity updates

History Streaming

Supports streaming transaction history via:

• request:history:xpub
• request:history:manual

Includes:

• Flow control via window-size
• Acknowledgment via request:history:ack
• Stream lifecycle events (begin, vertex, end)

Event WebSocket (/event_ws)

The Event WebSocket provides reliable, ordered event streaming from the full node.

It is designed for:

• Processing blockchain events in sequence
• Replaying events from a specific position
• Ensuring delivery reliability through flow control

Features include:

• Event replay using last_ack_event_id
• Strong ordering guarantees
• Sliding window flow control
• Full coverage of node-level events

Example Flow

1. Connect to /event_ws
2. Send START_STREAM
3. Receive events
4. Send ACK
5. Stop with STOP_STREAM

Start Streaming

{
  "type": "START_STREAM",
  "last_ack_event_id": null,
  "window_size": 10
}

Acknowledge Events

{
  "type": "ACK",
  "ack_event_id": 100,
  "window_size": 10
}

Stop Streaming

{
  "type": "STOP_STREAM"
}

Event Example

{
  "type": "EVENT",
  "peer_id": "node-1",
  "network": "mainnet",
  "latest_event_id": 123,
  "stream_id": "abc"
}

Event Types

• NEW_VERTEX_ACCEPTED
• VERTEX_METADATA_CHANGED
• VERTEX_REMOVED
• REORG_STARTED
• REORG_FINISHED
• TOKEN_CREATED
• NC_EVENT
• FULL_NODE_CRASHED

Mining WebSocket (/mining)

The Mining WebSocket implements a JSON-RPC 2.0 protocol for interacting with the mining system.

It allows clients to:

• Retrieve block templates
• Submit mined blocks
• Receive updates when templates change
• Continue mining efficiently using optimistic mode

JSON-RPC Format

Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "method.name",
  "params": {}
}

Response

{
  "id": "1",
  "result": {},
  "error": null
}

Methods

mining.refresh

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "mining.refresh",
  "params": []
}

mining.submit

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "mining.submit",
  "params": {
    "hexdata": "<block-hex>",
    "optimistic": true
  }
}

Notifications

mining.notify

{
  "method": "mining.notify",
  "params": []
}

Block Template Fields

• data: Serialized block
• reward: Mining reward
• weight: Difficulty target
• timestamp_*: Valid time range
• parents: Required references
• height: Block height

Flow Control

Flow control is implemented using a sliding window mechanism.

Key Concepts

• window_size: Maximum unacknowledged messages
• ack: Last processed message
• Server pauses when window is full

Where It Applies

Endpoint	Usage
Admin WebSocket	History streaming
Event WebSocket	Event streaming

Summary

The Hathor WebSocket API enables:

• Real-time blockchain interaction
• Reliable event processing
• Flexible wallet integrations
• Mining protocol support

Deep Dive

For a complete low-level protocol specification: WebSocket Protocol Reference