API Overview and Conventions

This category is derived from the requests made by the new RustMinerSystem frontend. It covers mining-proxy administration, Observer mode, fleet control, WebSocket traffic, and the embedded PoolNode administration endpoints. Response fields were also checked with safe read-only calls to a running instance. No backend source was read, and no restart, credential-change, route-change, or other write endpoint was called for verification.

Enablement and credential flow

The new frontend now provides a complete API credential-management screen. Before calling the API:

1. Set ENABLE_CONTROL_API=1 in rust-config, then restart RustMinerSystem. Script-install users can rerun the installer and select “Enable API.”
2. Open “Settings → API” in the management UI and read or create the API Key.
3. Use the API Key to generate an Access Token.
4. Send X-ACCESS-TOKEN with every open API request.

An Access Token is valid for approximately two hours. Generating a new Access Token immediately invalidates the previous token. Refreshing the API Key invalidates both the old Key and every Access Token created from it.

Fields and response formats remain dependent on the running RustMinerSystem version.

Base URL

The base URL is the RustMinerSystem backend address, including its safe route:

https://host:web-port/{safe-route}/api/...

For a backend at https://miner.example.com/rms-admin/, the port-list endpoint is:

https://miner.example.com/rms-admin/api/ports

Without a safe route, the API is under the website root. A reverse proxy must preserve the safe route and the X-ACCESS-TOKEN header.

API authentication header

API calls use the official header exposed by the frontend:

X-ACCESS-TOKEN: <Access Token>
Content-Type: application/json

Use the generated Access Token directly as the X-ACCESS-TOKEN value without an additional prefix.

Observer read-only requests use a separate credential:

X-OB-TOKEN: <Observer token>

The bundled frontend interceptor also writes a non-standard header named ContentType. That is an internal UI detail; third-party callers should send the standard Content-Type header.

Responses and errors

Mining-proxy endpoints commonly return an object, array, string, or number directly in the HTTP body. Some PoolNode administration endpoints use an envelope:

{
  "status": 0,
  "error": null,
  "data": {}
}

The frontend handles these states explicitly:

An error may be reported through message, error, or a business status. Do not treat every HTTP 200 response as business success.

Response notation:

null in a field table is a real missing-data state. Do not blindly coerce it to zero or an empty string, and allow additive response fields.

Covered modules

The documentation is organized into:

• API enablement, Key and Access Token management, and request headers.
• Dashboard, versions, and system configuration.
• Proxy ports and fee wallets.
• Workers, wallet statistics, charts, and logs.
• Web security, certificates, firewalls, and runtime logs.
• Observer read-only queries.
• Fleet-control forwarding.
• PoolNode project, website, revenue, and subaccount administration.
• Real-time WebSocket data and error handling.

Security guidance

• Expose the API only through HTTPS.
• Never place API, Observer, or fleet-control credentials in URLs, logs, or screenshots.
• The current frontend exposes no per-credential scope or multi-credential configuration, so treat the Access Token as a high-privilege secret.
• Back up configuration before changing ports, wallets, allowlists, certificates, or safe routes.
• Automation should enforce connect, read, and total timeouts and use bounded retry backoff.
• Set ENABLE_CONTROL_API=0 and restart the program when the API is not in use.