Skip to content

Latest commit

 

History

History
246 lines (188 loc) · 20.2 KB

API.md

File metadata and controls

246 lines (188 loc) · 20.2 KB

SolarMiner REST API

This document is the entry point for developers who want to build another frontend, automate a SolarMiner node, or integrate the software into a physical product.

Canonical API description

Every executable HTTP service generates an OpenAPI 3 description directly from its Spring controllers and DTOs. The generated document is the canonical source for exact parameter types, required fields, enum values, request bodies, response schemas and downloadable files.

Resource Relative URL
Interactive Swagger UI /swagger-ui.html
OpenAPI JSON /v3/api-docs
OpenAPI YAML /v3/api-docs.yaml

For the default Docker Compose deployment these URLs are available on:

Service Host port Intended use
SolarMiner Node 8080 Primary integration API and bundled frontend
Currency Rates 8081 Historical, read-only financial market data
SolarMiner Core 8082 Trusted low-level miner control
PC Agent not included in Compose Experimental local CPU/GPU mining agent; 8084 in the development profile

Examples:

curl http://localhost:8080/v3/api-docs.yaml
curl http://localhost:8080/api/start-info
curl "http://localhost:8081/api/v1/public/exchange-rates?date=2026-07-19&timezone=Europe%2FBerlin"

OpenAPI-compatible tools can use the YAML or JSON URL to generate clients for TypeScript, Java, Kotlin, Swift, C#, Python and other platforms. Always generate against the exact SolarMiner release that the product ships with.

Integration contract

  • API requests and responses use JSON unless an operation explicitly declares a file response.
  • Entity identifiers are UUID strings. Calendar dates use ISO YYYY-MM-DD; timestamps and chart time values must be interpreted according to their generated schema.
  • locale accepts a language tag such as de or en. currency uses an uppercase currency code such as EUR, USD or CHF where the endpoint supports it. timeZone/timezone uses an IANA zone such as Europe/Berlin.
  • Successful delete and command endpoints commonly return 204 No Content; data queries normally return 200 OK with JSON.
  • Clients must branch on the HTTP status code. The error-body layout is not yet a versioned contract and may differ between validation failures and services.
  • Most Node and Core paths are currently unversioned. Treat endpoint or DTO changes as compatibility-sensitive. The Currency Rates API already uses /api/v1.
  • CORS is a browser restriction, not API authentication. A separate browser frontend should be served from the node origin, use a reverse proxy, or explicitly configure its allowed origin.
  • There is currently no universal authentication boundary in front of these APIs. Never expose Node, Core, PC Agent, or Swagger UI directly to the Internet. A physical product should place them on a trusted device network and add authentication/TLS at its gateway.
  • Prefer the Node API on port 8080 for product integrations. Call Core directly only when low-level miner control is deliberately required. Do not couple external clients to MariaDB or InfluxDB schemas.

SolarMiner Node API

The Node API is the recommended surface for frontends and appliance integrations. Base URL in the default deployment: http://<node>:8080.

Sites and dashboard

Controller sources: StartInfoController, DashboardController

Method Path Purpose
GET /api/start-info List configured PV sites and the current site limit.
GET /api/pv-site/{siteId}/dashboard/init Load dashboard identity data, miners and pools.
GET /api/pv-site/{siteId}/dashboard/live Load current energy, mining and financial values for a locale and currency.
GET /api/pv-site/{siteId}/dashboard/charts Load live/history chart series and mining-controller history for a time zone and cluster.

PV-site details

Controller source: PVSiteDetailsController

Method Path Purpose
GET /api/pv-site/{siteId}/details Load the complete editable site view.
POST /api/pv-site/{siteId}/details/pv-devices Add one or more selected logical components from a PV device.
DELETE /api/pv-site/{siteId}/details/pv-devices/{deviceId} Remove a configured PV device/component from the site.
PUT /api/pv-site/{siteId}/details Update site name, time zone and financial base settings.
POST /api/pv-site/{siteId}/details/panel-groups Create a panel group and its single geographic position.
PUT /api/pv-site/{siteId}/details/panel-groups/{panelGroupId} Update an existing panel group.
DELETE /api/pv-site/{siteId}/details/panel-groups/{panelGroupId} Delete a panel group.
POST /api/pv-site/{siteId}/details/prices/{priceType} Add a dated electricity-price or feed-in-tariff entry.
DELETE /api/pv-site/{siteId}/details/prices/{priceType}/{validFrom} Delete a dated tariff entry.
PUT /api/pv-site/{siteId}/details/miners/{minerId}/cost Update a miner's acquisition cost.

Mining, pools and clusters

Controller sources: MiningController, MinerDetailsController, ClusterConfigController

Method Path Purpose
GET /api/pv-site/{siteId}/mining Load clusters, connected/unassigned miners, pools and fee distribution.
GET /api/pv-site/{siteId}/mining/live Load uncached live miner values. Each row includes the current display name; PC-Agent renames therefore reach the mining UI without reconnecting the Agent.
POST /api/pv-site/{siteId}/mining/referral Validate and save a referral code for this site.
DELETE /api/pv-site/{siteId}/mining/referral Remove the site's referral code.
GET /api/pv-site/{siteId}/mining/miners/discovery Scan a requested subnet for supported miners.
POST /api/pv-site/{siteId}/mining/miners Connect a discovered or manually entered miner to the site.
DELETE /api/pv-site/{siteId}/mining/miners/{minerId} Remove a miner from the site and system.
POST /api/pv-site/{siteId}/mining/pools Connect a mining pool to the site.
DELETE /api/pv-site/{siteId}/mining/pools/{poolId} Remove a mining pool from the site and system.
POST /api/pv-site/{siteId}/mining/clusters/{clusterName}/start Start cluster automation.
POST /api/pv-site/{siteId}/mining/clusters/{clusterName}/stop Stop cluster automation.
POST /api/pv-site/{siteId}/mining/clusters/{clusterName}/miners Assign currently unassigned miners to a cluster.
POST /api/pv-site/{siteId}/mining/clusters/{clusterName}/miners/remove Remove selected miners from a cluster without deleting them.
POST /api/pv-site/{siteId}/mining/miners/{minerId}/power-targets Update safe power limits and hardware lock timings for a miner.
GET /api/pv-site/{siteId}/mining/miners/{minerId} Load detailed telemetry and historical analytics for one miner.
GET /api/pv-site/{siteId}/mining/configs/{configName} Load one controller DSL configuration.
POST /api/pv-site/{siteId}/mining/configs Create or update a controller DSL configuration.
POST /api/pv-site/{siteId}/mining/configs/simulate Run the real controller DSL against preset or historical input data.

Setup

Controller source: SetupController

Method Path Purpose
GET /api/setup/catalog Load setup capabilities, providers and required fields.
POST /api/setup/catalog/refresh Refresh remotely supplied setup capabilities.
GET /api/setup/pv-devices/profiles Search compatible PV profiles, optionally by provider and name query.
POST /api/setup/pv-devices/discover Discover PV devices and matching logical component profiles, including SunSpec.
GET /api/setup/pv-devices/network Suggested private IPv4 subnet prefix for discovery; operators can override it with solarminer.discovery.subnet-prefix / SOLARMINER_DISCOVERY_SUBNET_PREFIX.
POST /api/setup/pv-devices/scan Bounded PV discovery with {devices, subnetPrefix, checkedHosts, totalHosts, complete}. Supports AUTO, MODBUS_TCP, REST_API; request fields are providerId, subnetPrefix, port, slaveId.
POST /api/setup/options/{kind}/{providerId}/validate Validate one provider selection and its credentials/settings.
POST /api/setup Create a PV site from the completed setup request.

PV scans cover addresses .1–.254 of an explicit private IPv4 prefix (for example 192.168.1.), with 24 concurrent host probes and a 25-second deadline. complete:false means some hosts were not fully checked; an empty result is not proof that no devices exist. Concurrent scans receive HTTP 429 until in-flight probes have stopped. Invalid/public prefixes, invalid ports and invalid device IDs receive HTTP 400 before network access. AUTO checks Modbus port 502 and HTTP ports 80/443/8080/8123; a specified protocol honors the requested port, and Modbus honors slaveId. The legacy /discover response remains an array and defaults to Modbus when no provider is given, but cannot convey completion metadata.

REST discovery only uses GET entries and requires the returned payload to parse for the profile. A 401/403 is not sufficient to identify a device; protected APIs remain available through manual setup. TLS certificate validation remains enabled. In Docker, the suggested interface may belong to the container network; configure the LAN prefix or enter it in setup. When opened through a private IPv4 Node address, the UI uses that address's prefix as its suggestion. Scans are local read probes, not device-control or mining activation commands.

PV REST and Modbus/TCP profiles

Controller source: PVConfigController

REST profiles:

Method Path Purpose
GET /api/config/pv/rest/catalog List REST templates and local/community profiles.
POST /api/config/pv/rest/profiles Create a REST profile from a template.
GET /api/config/pv/rest/profiles/{name} Load a REST profile.
PUT /api/config/pv/rest/profiles/{name} Save/rename a REST profile.
DELETE /api/config/pv/rest/profiles/{name} Delete a REST profile.
GET /api/config/pv/rest/profiles/{name}/export Download a REST profile as JSON.
POST /api/config/pv/rest/profiles/import Import a REST profile from JSON.
POST /api/config/pv/rest/community/{name} Download a community REST profile into local storage.
POST /api/config/pv/rest/test Test a REST device connection and parsed values.

Modbus/TCP profiles:

Method Path Purpose
GET /api/config/pv/modbus/tcp/catalog List Modbus templates and local/community profiles.
POST /api/config/pv/modbus/tcp/profiles Create a Modbus profile from a template.
GET /api/config/pv/modbus/tcp/profiles/{name} Load a Modbus profile.
PUT /api/config/pv/modbus/tcp/profiles/{name} Save/rename a Modbus profile.
DELETE /api/config/pv/modbus/tcp/profiles/{name} Delete a Modbus profile.
GET /api/config/pv/modbus/tcp/profiles/{name}/export Download a Modbus profile as JSON.
POST /api/config/pv/modbus/tcp/profiles/import Import a Modbus profile from JSON.
POST /api/config/pv/modbus/tcp/community/{name} Download a community Modbus profile into local storage.
POST /api/config/pv/modbus/tcp/test Test Modbus registers, fingerprints and parsed values.

Finance

Controller source: FinanceController

Method Path Purpose
GET /api/pv-site/{siteId}/finance Load finance KPIs, history, tariffs and the BTC sales ledger for a date range.
GET /api/pv-site/{siteId}/finance/export/{reportType} Export a CSV or PDF report; supported report types are defined by the generated enum/schema and controller validation.
POST /api/pv-site/{siteId}/finance/sales Add a realized Bitcoin sale to the ledger.
DELETE /api/pv-site/{siteId}/finance/sales Delete the matching Bitcoin sale from the ledger.

Lightning wallet

Controller source: LightningWalletController

Method Path Purpose
GET /api/lightning-wallet Load balance, liquidity, address, transactions and backend connection status.
POST /api/lightning-wallet/pay Pay a Lightning target, optionally with an explicit satoshi amount.
POST /api/lightning-wallet/withdraw/onchain Send an on-chain withdrawal with an explicit fee rate.
POST /api/lightning-wallet/connection/toggle Toggle the public-backend WebSocket connection.

SolarMiner Core API

Core is a low-level hardware service. Base URL in the default deployment: http://<node>:8082. Requests carry MinerDetails plus an optional/detected mining OS. Credential payloads are sensitive and must never be logged by an integrating gateway.

Controller source: MinerController

Method Path Purpose
POST /api/miners/check-standard-credentials Test known default credentials against a miner.
POST /api/miners/check-custom-credentials Test credentials supplied in MinerDetails.
POST /api/miners/identify-os Detect miner firmware/OS from an IPv4 address; the body is a JSON string.
POST /api/miners/start Start mining.
POST /api/miners/stop Stop the miner.
POST /api/miners/pause Pause mining while retaining its configuration.
POST /api/miners/resume Resume mining.
POST /api/miners/pool-target Change pool URL, worker and optional referral routing.
POST /api/miners/power-target Set an absolute power target in watts.
POST /api/miners/power-target/increment Increase the current power target by watts.
POST /api/miners/power-target/decrement Decrease the current power target by watts.
POST /api/miners/stats Query current miner telemetry and fee routing.
GET /api/miners/dev-fee/overview Return the current developer-fee and referral hashrate distribution.
GET /api/miners/dev-fee/referral/validate Validate a referral code against the public SolarMiner backend.

TWENTY_ONE_ENERGY is a local 21energy heater adapter. It is registered in Core and can be discovered and monitored through the same miner lifecycle. A newly connected heater is always monitoring-only: Core rejects start, pause, resume, power and pool-write requests until a model/firmware-specific capability record and measured level-to-watt map have been verified. This is intentional; a successful network probe is not permission to produce heat or replace a pool configuration.

Currency Rates API

The Currency Rates API is read-only and already versioned under /api/v1. The Node defaults to the central public base URL, https://currency.solarminer.app. A local or self-hosted endpoint is only used when explicitly supplied via CURRENCY_MICRO_SERVICE_URL.

Controller source: PublicDataController (in the separate currency-service repository)

Method Path Purpose
GET /api/v1/public/bitcoin-stats Get Bitcoin price, difficulty, hashrate, subsidy and fee statistics for a local date/time zone.
GET /api/v1/public/exchange-rates Get all stored USD-based exchange rates for a local date/time zone.
GET /api/v1/public/exchange-rates/convert Get one historical conversion rate between two currencies.
GET /api/v1/public/coin-prices Get current or dated USD prices keyed by btc, xmr, prl, rvn and etc.
GET /api/v1/public/mining-networks Get the latest complete price/network snapshots for Monero, Pearl, Ravencoin and Ethereum Classic.
GET /api/v1/public/mining-networks/{coin} Get one snapshot by canonical key or ticker alias; unknown coins return 404.

Mining-network snapshots use canonical keys monero, pearl, ravencoin and ethereumclassic. Hashrate is H/s, target block time is seconds, reward is native coin per block and price is USD per coin. Each response includes collection time, age, upstream source names and a stale flag. The service retains the last complete snapshot after an upstream failure; it becomes stale after two hours instead of replacing missing inputs with zero.

PC Agent API (experimental)

The PC-Agent is a separate Git repository (https://github.com/Solarminer-app/pc-agent) and is not part of the default Compose deployment. The Node talks to it only over its LAN HTTP API on :8084 (/api/agent/external/**; discovery via GET /api/agent/external/identity and UDP SOLARMINER_PROXY_DISCOVER_V1). Read-only identity, mining status, power status and hardware telemetry remain available when Agent-side Node control is disabled; all write commands remain gated. Mining status covers every local worker so PV-site power statistics include the PC's complete mining load. The full agent API contract moved with the component to pc-agent/docs/API.md.

Maintaining the documentation

When a REST controller or DTO changes:

  1. Keep the Spring mapping and parameter annotations explicit.
  2. Add a descriptive @Tag for a new controller.
  3. Update the endpoint inventory and compatibility notes in this file when behavior changes.
  4. Build the affected service and inspect /v3/api-docs.yaml before release.
  5. Treat removal/renaming of fields, enum values, paths, methods, or status codes as a breaking API change. Introduce a versioned path before making such a change for external consumers.

The React route forwarding controller is intentionally excluded because it serves HTML navigation and is not a REST interface. Likewise, internal Java classes whose names end in Controller but have no Spring HTTP mapping are not API controllers.

Node earnings forecast

GET /api/pv-site/{siteId}/dashboard/earnings returns per-coin daily forecasts and a site total with EUR/day, kWh/day, revenue in cents/kWh, the configured grid tariff in cents/kWh, and a completeness flag. Native Bitcoin remains a gross chain estimate. PC-Agent estimates use the additive netCoinsPerDay/netUsdPerDay fields only when knownFeesComplete=true; otherwise the coin is unavailable for profitability decisions instead of presenting gross revenue as net. grossCoinsPerDay, grossUsdPerDay, knownFeePercent, and estimateKind preserve the distinction in the response. actualPoolCredits separately reports seven completed UTC days from configured Kryptex XMR/PRL reward-chart routes, including completeness and route/data-point counts; these are credited historical amounts, not balances or payouts. Coin identities and algorithm mapping come from MiningCoin; each device/chain forecast is a MiningEarningsSource bean. The Node uses the currency service for all coin prices and USD/EUR conversion. Unavailable, stale, or missing values block the site profitability comparison.

The controller DSL variable MINING_MARGIN_CENTS_PER_KWH is estimated gross mining revenue per kWh minus the current grid tariff. It returns a failing value when data is incomplete. The optional "Profitable grid mining" mode can be added in cluster configuration; it is absent from the standard ruleset. The emergency battery mode retains first priority. Historical simulator runs reject this live-only variable because historical earnings inputs are not stored.