Skip to main content

Miner Agent Local API

This document describes the local FastAPI diagnostics API exposed by miner-agent.

Security Recommendation

These endpoints are for local diagnostics and operations. Do not expose them publicly without network controls.

Basic Information​

  • Default address: http://127.0.0.1:8080
  • Port control: Determined by miner_client config

Endpoint Overview​

MethodPathPurpose
GET/healthzProcess liveness
GET/readyzReadiness based on registration, heartbeat recency, and challenge state
GET/v1/miner/statusCurrent settings and in-memory agent state
GET/v1/miner/identityPublic view of the persisted identity
POST/v1/miner/registerTrigger one registration attempt
POST/v1/miner/heartbeatTrigger one heartbeat attempt
POST/v1/miner/challengeTrigger one challenge flow with default purpose reverify

Liveness Check​

Check if the process is running:

curl http://127.0.0.1:8080/healthz

Response:

{
  "status": "ok"
}

Readiness Check​

Check if the node is ready:

curl -i http://127.0.0.1:8080/readyz

Healthy response:

{
  "status": "ready",
  "registered": true,
  "verified": true,
  "last_error": null
}

Degraded response (HTTP 503):

{
  "status": "degraded",
  "registered": false,
  "verified": false,
  "last_error": "register failed: ..."
}

Status and Identity​

# View status
curl http://127.0.0.1:8080/v1/miner/status

# View identity
curl http://127.0.0.1:8080/v1/miner/identity
  • status returns masked settings, registration state, verification state, recent responses, latest probe snapshot, and latest error
  • identity hides private keys and returns only public identity fields

Manual Control​

Manually trigger registration, heartbeat, or challenge:

curl -X POST http://127.0.0.1:8080/v1/miner/register
curl -X POST http://127.0.0.1:8080/v1/miner/heartbeat
curl -X POST http://127.0.0.1:8080/v1/miner/challenge