Mining/docs/api/index.md

API Overview

The Mining Platform provides a comprehensive RESTful API for managing cryptocurrency miners programmatically.

Base URL

All API endpoints are prefixed with the configured namespace (default: /api/v1/mining):

http://localhost:8080/api/v1/mining

You can customize the namespace when starting the server:

miner-ctrl serve --namespace /custom/path

Swagger Documentation

Interactive API documentation is available via Swagger UI when the server is running:

http://localhost:8080/api/v1/mining/swagger/index.html

The Swagger specification is also available in multiple formats:

• JSON: /docs/swagger.json
• YAML: /docs/swagger.yaml

Authentication

Currently, the API does not require authentication. This is suitable for local/trusted networks.

For production deployments, consider:

• Running behind a reverse proxy with authentication
• Implementing API key authentication
• Using OAuth2/JWT for multi-user scenarios

API Versioning

The API follows semantic versioning:

• Current Version: v1
• Endpoint Format: /api/v{version}/mining/{endpoint}
• Backward Compatibility: Maintained within major versions

Content Type

All requests and responses use JSON:

Content-Type: application/json

Response Format

All API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error context
    }
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	Usage
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content to return
400	Bad Request	Invalid request parameters
404	Not Found	Resource not found
409	Conflict	Resource already exists or conflicting state
500	Internal Server Error	Server-side error
503	Service Unavailable	Service temporarily unavailable

Rate Limiting

Currently, there is no rate limiting implemented. For production use, consider:

• Implementing rate limits at the reverse proxy level
• Using nginx limit_req module
• Implementing application-level rate limiting

CORS

Cross-Origin Resource Sharing (CORS) is enabled by default for all origins. To restrict:

# Start server with CORS restrictions (future feature)
miner-ctrl serve --cors-origin "https://example.com"

WebSocket Support

Real-time updates are available via WebSocket connection:

ws://localhost:8080/api/v1/mining/ws

The WebSocket provides:

• Real-time miner statistics
• Live hashrate updates
• Event notifications (miner start/stop/crash)

Example JavaScript client:

const ws = new WebSocket('ws://localhost:8080/api/v1/mining/ws');

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

Pagination

List endpoints support pagination via query parameters:

GET /api/v1/mining/miners?page=1&limit=10

Response includes pagination metadata:

{
  "success": true,
  "data": {
    "items": [ /* ... */ ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 42,
      "pages": 5
    }
  }
}

Filtering and Sorting

List endpoints support filtering and sorting:

GET /api/v1/mining/miners?status=running&sort=hashrate&order=desc

Common parameters:

• status: Filter by status (running, stopped, error)
• type: Filter by miner type (xmrig, etc.)
• sort: Sort field (name, hashrate, uptime)
• order: Sort order (asc, desc)

Date and Time Format

All timestamps use ISO 8601 format with UTC timezone:

2025-12-31T23:59:59Z

Field Naming

API fields use camelCase naming:

{
  "minerName": "xmrig",
  "hashRate": 4520,
  "acceptedShares": 42
}

Data Models

SystemInfo

System information and installed miners.

{
  "os": "linux",
  "arch": "amd64",
  "goVersion": "go1.24.0",
  "totalMemory": 16777216,
  "installedMiners": [
    {
      "type": "xmrig",
      "version": "6.21.0",
      "installed": true,
      "path": "/home/user/.local/share/lethean-desktop/miners/xmrig"
    }
  ]
}

Config

Miner configuration object.

{
  "pool": "stratum+tcp://pool.supportxmr.com:3333",
  "wallet": "YOUR_WALLET_ADDRESS",
  "algo": "rx/0",
  "threads": 4,
  "cpuPriority": 3,
  "cuda": {
    "enabled": false,
    "devices": []
  },
  "opencl": {
    "enabled": false,
    "devices": []
  }
}

PerformanceMetrics

Real-time miner statistics.

{
  "hashrate": 4520.5,
  "hashrateAvg": 4485.2,
  "shares": {
    "accepted": 42,
    "rejected": 0,
    "invalid": 0
  },
  "uptime": 8215,
  "connection": {
    "pool": "pool.supportxmr.com:3333",
    "uptime": 8215,
    "ping": 45,
    "failures": 0
  },
  "cpu": {
    "usage": 95.5,
    "temperature": 65.2
  },
  "gpu": [
    {
      "id": 0,
      "name": "NVIDIA GeForce RTX 3080",
      "hashrate": 95234.5,
      "temperature": 68.5,
      "fanSpeed": 75,
      "powerUsage": 220
    }
  ]
}

HashratePoint

Historical hashrate data point.

{
  "timestamp": "2025-12-31T12:00:00Z",
  "hashrate": 4520.5,
  "resolution": "10s"
}

MiningProfile

Saved mining configuration.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "XMR - SupportXMR",
  "description": "Monero mining on SupportXMR pool",
  "minerType": "xmrig",
  "config": { /* Config object */ },
  "createdAt": "2025-12-31T10:00:00Z",
  "updatedAt": "2025-12-31T12:00:00Z"
}

Error Codes

Common error codes returned by the API:

Code	Description
MINER_NOT_FOUND	Specified miner not found
MINER_ALREADY_RUNNING	Miner is already running
MINER_NOT_INSTALLED	Miner software not installed
INVALID_CONFIG	Invalid configuration provided
POOL_UNREACHABLE	Cannot connect to mining pool
PROFILE_NOT_FOUND	Mining profile not found
PROFILE_ALREADY_EXISTS	Profile with same name exists
INVALID_WALLET	Invalid wallet address format
INSUFFICIENT_RESOURCES	System resources insufficient

Examples

See the Endpoints page for detailed examples of each API endpoint.

Client Libraries

JavaScript/TypeScript

const BASE_URL = 'http://localhost:8080/api/v1/mining';

async function startMiner(config) {
  const response = await fetch(`${BASE_URL}/miners/xmrig`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(config)
  });
  return response.json();
}

async function getMiners() {
  const response = await fetch(`${BASE_URL}/miners`);
  return response.json();
}

Python

import requests

BASE_URL = 'http://localhost:8080/api/v1/mining'

def start_miner(config):
    response = requests.post(
        f'{BASE_URL}/miners/xmrig',
        json=config
    )
    return response.json()

def get_miners():
    response = requests.get(f'{BASE_URL}/miners')
    return response.json()

Go

import (
    "bytes"
    "encoding/json"
    "net/http"
)

const baseURL = "http://localhost:8080/api/v1/mining"

func startMiner(config map[string]interface{}) error {
    data, _ := json.Marshal(config)
    resp, err := http.Post(
        baseURL+"/miners/xmrig",
        "application/json",
        bytes.NewBuffer(data),
    )
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    return nil
}

cURL

# Start miner
curl -X POST http://localhost:8080/api/v1/mining/miners/xmrig \
  -H "Content-Type: application/json" \
  -d '{"pool":"stratum+tcp://pool.supportxmr.com:3333","wallet":"YOUR_WALLET","algo":"rx/0"}'

# Get miners
curl http://localhost:8080/api/v1/mining/miners

# Get stats
curl http://localhost:8080/api/v1/mining/miners/xmrig/stats

Next Steps

• Browse the API Endpoints for detailed documentation
• Try the interactive Swagger UI
• See the Development Guide for contributing