ws-go-server/README.md

BTClock Go Server

A high-performance data service for the BTClock, providing real-time Bitcoin data through WebSocket connections.

Features

• Real-time Bitcoin price updates
• Mempool fee rate monitoring
• Block height tracking
• WebSocket API (v1 and v2)
• Docker support
• Graceful shutdown handling
• Modular architecture

Prerequisites

• Go 1.21 or later
• Docker and Docker Compose (optional)

Installation

Local Development

1. Clone the repository:

git clone https://github.com/yourusername/btclock-go-server.git
cd btclock-go-server

2. Install dependencies:

go mod download

3. Run the server:

go run main.go

Docker Deployment

1. Build and run using Docker Compose:

docker-compose up --build

Configuration

The server can be configured using environment variables:

Variable	Description	Default
PORT	Server port	80

API Documentation

WebSocket API v2

Connect to ws://your-server/api/v2/ws for the latest API version.

Subscribe to Events

Send a binary message with the following structure:

{
  "type": "subscribe",
  "eventType": "price",
  "currencies": ["USD", "EUR"]
}

Available event types:

• price: Bitcoin price updates
• mempool-fee-rate: Mempool fee rate updates
• mempool-block: New block notifications

Unsubscribe from Events

{
  "type": "unsubscribe",
  "eventType": "price",
  "currencies": ["USD", "EUR"]
}

WebSocket API v1

Connect to ws://your-server/api/v1/ws for the legacy API version.

Automatically subscribes to:

• blockheight-v1: Block height updates
• blockfee-v1: Fee rate updates
• price-v1: Price updates

Project Structure

.
├── broker/         # Event broker implementation
├── clients/        # External service clients
├── handlers/       # WebSocket request handlers
├── models/         # Data models
├── modules/        # Service modules
├── static/         # Static web assets
├── websocket/      # WebSocket utilities
├── main.go         # Application entry point
├── Dockerfile      # Docker configuration
└── docker-compose.yaml

Development

Testing

Run the test suite:

go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.