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.
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.
- 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. localeaccepts a language tag such asdeoren.currencyuses an uppercase currency code such asEUR,USDorCHFwhere the endpoint supports it.timeZone/timezoneuses an IANA zone such asEurope/Berlin.- Successful delete and command endpoints commonly return
204 No Content; data queries normally return200 OKwith 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
8080for product integrations. Call Core directly only when low-level miner control is deliberately required. Do not couple external clients to MariaDB or InfluxDB schemas.
The Node API is the recommended surface for frontends and appliance integrations. Base URL in the default deployment: http://<node>:8080.
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. |
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. |
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. |
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.
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. |
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. |
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. |
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.
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.
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.
When a REST controller or DTO changes:
- Keep the Spring mapping and parameter annotations explicit.
- Add a descriptive
@Tagfor a new controller. - Update the endpoint inventory and compatibility notes in this file when behavior changes.
- Build the affected service and inspect
/v3/api-docs.yamlbefore release. - 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.
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.