Build your miner experience with the Go API

From mining engine to miner interface

CashStratum ships a separate, static Go binary that reads the engine's logs and status files over HTTP. Your application can show pool activity without shell access to the mining host. The service is read-only: it cannot disconnect workers, alter payouts or control the engine.

The architecture is Go API → your backend → your miner interface. BlockSniper is a reference deployment of this approach, with miner pages that turn mining data into share displays, sounds and block celebrations. These effects are application features you build around the data; they are not UI components bundled into the API.

Pick the data your interface needs

Endpoint	What it enables
GET /stats	Pool hashrate, workers, users and the node's chain view.
GET /user-file?user=	A miner's parsed status, workers and best-share data.
GET /shares?since=&user=&limit=	Incremental share activity using a resumable cursor.
GET /find-block?height=	Solve context for a selected height, when retained in the logs.
GET /coinbase?user=	Decode the coinbase the miner is currently working on.
GET /ping	An unauthenticated, rate-limited latency probe.

The complete API reference also documents health, metrics, log reads, configuration and response examples.

Show how strong a share is

Share records distinguish credited difficulty (diff) from actual hash quality (sdiff). Use credited difficulty for contributed-work accounting and actual quality for a best-share display. A comparison of sdiff with network difficulty describes that individual hash; it is not a progress bar that guarantees a future solve.

Rejected shares carry result: false and a rejection reason. Display them separately from accepted work. Public interfaces should expose only the fields they need: raw records can contain miner IP addresses and user agents, which should stay behind your application boundary.

Poll without replaying the same shares

Call /shares without a cursor for an initial read. Preserve the returned next_cursor exactly and pass it as since on the next poll. The cursor is opaque and handles height rollover. An empty array with the same cursor means no new records have arrived; it is not an outage. Retention still matters: pruned history cannot be recovered through the API.

The default shares budget is 60 requests per client IP per minute; most other routes default to 20. These limits are configurable and use fixed windows. Read the response rate-limit headers, honor Retry-After on HTTP 429, and cache results in your backend where appropriate. Responses can be cached; design update timing around the documented contract rather than assuming a WebSocket feed.

Celebrate a confirmed event

Use solve context or the optional block notifier to drive your application's block state. Deduplicate events before playing sounds or confetti, and distinguish a candidate from an accepted block. Check confirmation status against chain data when your interface displays confirmations. Keep sounds opt-in so a background tab does not surprise the miner.

Keep credentials on the server

Every API endpoint except /ping requires a bearer token. Do not embed that token in a public page or connect a browser directly to authenticated routes. The service uses HTTP; restrict it to your consuming backend and follow the hardening guide. Install the API separately using the build and service instructions.