# Build your miner experience with the Go API

> Build BCH miner dashboards with CashStratum's read-only Go API: share quality, resumable polling, worker stats, coinbase inspection and block events.

Reviewed 2026-10-26.

[HTML guide](https://cashstratum.com/docs/operator-api) · [Authoritative source](https://github.com/cashstratum/cashstratum/blob/main/docs/operator-api.md)

## 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](https://github.com/cashstratum/cashstratum/blob/main/docs/operator-api.md) 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](https://github.com/cashstratum/cashstratum/blob/main/api/NOTIFIER.md) 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](https://github.com/cashstratum/cashstratum/blob/main/docs/security-hardening.md). Install the API separately using [the build and service instructions](https://github.com/cashstratum/cashstratum/blob/main/api/README.md).