Public API

Read-only HTTP endpoints surfacing exactly what the goldenpool dashboard renders. Same data, no extras: tuned for embeds, scripts, and explorers without exposing internal pool tuning knobs.

At a glance

Base URL: /api/v1 (same origin as this dashboard)
Auth: None. Endpoints are public read-only.
Rate limit: 60 requests per minute, per IP. Fixed window; resets on the minute boundary tracked per-IP. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix epoch seconds). When exceeded, the response is 429 with a Retry-After header.
Cache: no-store on every response — live data, no edge caching. Be a good neighbour and don't poll faster than 5 s.
Content-Type: Always application/json; charset=utf-8.
Amounts: All PRL amounts are grains (1 PRL = 10⁸ grains, same as satoshis). Integer encoded as JSON number.
Timestamps: Unix epoch milliseconds, JSON number. null means "not applicable / not yet" (e.g. a payout that has not yet confirmed).

Errors

Errors are JSON objects with at least an error discriminator string. Detail fields may be added without notice; don't pattern-match on free-text messages.

Status	error	When
400	bad_request	Address path segment missing or longer than 128 chars.
404	not_found	Address has never connected to this pool.
429	rate_limited	Per-IP rate limit exceeded. See `Retry-After`.
502	upstream_error / upstream_unreachable	The underlying pool process is down or returned 5xx. Retry with backoff.

Endpoints

#Pool status

GET/api/v1/status

Aggregate snapshot used by the dashboard's overview cards: fee, payout scheme, online miner/worker counts, recent share counts, and the underlying network's tip height.

Response shape

typescript

interface PoolStatus {
  pool: {
    fee_bps: number;
    payout_scheme: string;        // e.g. "PPLNS"
    min_payout_grains: number;
    stratum_endpoint: string;     // "host:port"
  };
  network: {
    name: string;                 // e.g. "mainnet"
    height: number;
  };
  miners_online: number;
  workers_online: number;
  /** Sum of all worker self-reports via mining.submit_hashrate (5m TTL). */
  pool_hashrate_hps: number;
  shares: {
    last_minute: number;
    last_hour: number;
  };
}

Example response

json

{
  "pool": {
    "fee_bps": 100,
    "payout_scheme": "PPLNS",
    "min_payout_grains": 100000000,
    "stratum_endpoint": "stratum.goldenpool.net:3333"
  },
  "network": { "name": "mainnet", "height": 32419 },
  "miners_online": 14,
  "workers_online": 31,
  "pool_hashrate_hps": 1234567890,
  "shares": {
    "last_minute": 42,
    "last_hour": 2530
  }
}

curl

bash

curl -sS https://goldenpool.net/api/v1/status | jq

#Recent blocks

GET/api/v1/blocks

Blocks this pool has submitted to the network, newest first. The `reward_grains` field is the miners' share after the pool fee — not the full block reward.

Parameters

Name	In	Required	Default	Description
limit	query	no	50	Maximum rows to return. Clamped to [1, 200].

Response shape

typescript

interface BlockSummary {
  height: number;
  hash_hex: string;       // lowercase hex, 64 chars
  state: string;          // "immature" | "matured" | "orphaned"
  found_at_ms: number;
  reward_grains: number;  // miners' cut, AFTER pool fee
}

Example response

json

[
  {
    "height": 32418,
    "hash_hex": "b57702ffb013178dece7f2cb165e11e1409d6583daa3a706227903157311ab38",
    "state": "matured",
    "found_at_ms": 1764025461522,
    "reward_grains": 4950000000
  }
]

curl

bash

curl -sS 'https://goldenpool.net/api/v1/blocks?limit=10' | jq

#Miner detail

GET/api/v1/miners/{address}

Balance breakdown, lifetime stats, and registered workers for a Pearl address.

Parameters

Name	In	Required	Default	Description
address	path	yes	—	Pearl bech32m address. Must start with prl1, tprl1, or rprl1. Max 128 chars.

Response shape

typescript

interface MinerDetail {
  address: string;
  mature_grains: number;
  immature_grains: number;
  total_paid_grains: number;
  total_blocks_credited: number;
  first_seen_ms: number;
  last_seen_ms: number;
  workers: WorkerSummary[];
}

interface WorkerSummary {
  worker_label: string;
  first_seen_ms: number;
  last_seen_ms: number;
  last_share_ms: number | null;
  shares_last_5m: number;
  shares_last_hour: number;
  /** Self-reported via mining.submit_hashrate. Null if stale (>5min) or never reported. */
  reported_hashrate_hps: number | null;
}

Example response

json

{
  "address": "prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8",
  "mature_grains": 21750409000,
  "immature_grains": 0,
  "total_paid_grains": 1500000000,
  "total_blocks_credited": 12,
  "first_seen_ms": 1763400000000,
  "last_seen_ms": 1764030000000,
  "workers": [
    {
      "worker_label": "rig01",
      "first_seen_ms": 1763400000000,
      "last_seen_ms": 1764030000000,
      "last_share_ms": 1764030000000,
      "shares_last_5m": 12,
      "shares_last_hour": 145,
      "reported_hashrate_hps": 1500000000
    }
  ]
}

curl

bash

curl -sS https://goldenpool.net/api/v1/miners/prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8 | jq

#Blocks contributed by miner

GET/api/v1/miners/{address}/blocks

Blocks that included shares from this address, newest first. `grains_credited` is the share of the miners' reward this address earned on that block.

Parameters

Name	In	Required	Default	Description
address	path	yes	—	Pearl address (max 128 chars).
limit	query	no	50	Maximum rows. Clamped to [1, 200].

Response shape

typescript

interface ParticipationRow {
  block_height: number;
  block_hash_hex: string;
  difficulty_sum: number;   // sum of share difficulties this miner contributed
  share_count: number;
  grains_credited: number;
}

Example response

json

[
  {
    "block_height": 32418,
    "block_hash_hex": "b57702ffb013178dece7f2cb165e11e1409d6583daa3a706227903157311ab38",
    "difficulty_sum": 1850000,
    "share_count": 95,
    "grains_credited": 1450000000
  }
]

curl

bash

curl -sS 'https://goldenpool.net/api/v1/miners/prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8/blocks?limit=50' | jq

#Hashrate history

GET/api/v1/miners/{address}/hashrate

Hourly hashrate buckets used by the per-miner chart. Values are H/s directly — the average of every `mining.submit_hashrate` report the worker sent during that hour. No client-side derivation needed.

Parameters

Name	In	Required	Default	Description
address	path	yes	—	Pearl address (max 128 chars).
hours	query	no	24	Window size, in hours. Clamped to [1, 720] (30 days).

Response shape

typescript

interface HashrateSeries {
  address: string;
  hours: number;
  bucket_ms: number;        // typically 3600000 (1 hour)
  buckets: HashrateBucket[];
}

interface HashrateBucket {
  hour_bucket_ms: number;   // bucket start, epoch ms
  /** Average self-reported H/s (via mining.submit_hashrate) within this hour. */
  hashrate_hps: number;
}

Example response

json

{
  "address": "prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8",
  "hours": 24,
  "bucket_ms": 3600000,
  "buckets": [
    { "hour_bucket_ms": 1764025200000, "hashrate_hps": 1450000000 },
    { "hour_bucket_ms": 1764021600000, "hashrate_hps": 1380000000 }
  ]
}

curl

bash

curl -sS 'https://goldenpool.net/api/v1/miners/prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8/hashrate?hours=24' | jq

#Payout history

GET/api/v1/miners/{address}/payouts

On-chain payouts that included this address, newest first. A single payout TX may pay many miners; this endpoint shows only this miner's slice of each.

Parameters

Name	In	Required	Default	Description
address	path	yes	—	Pearl address (max 128 chars).
limit	query	no	50	Maximum rows. Clamped to [1, 200].

Response shape

typescript

interface MinerPayout {
  payout_id: number;
  txid_hex: string | null;          // null while pending
  state: string;                    // "pending" | "broadcast" | "confirmed" | "failed"
  grains: number;
  created_at_ms: number;
  broadcast_at_ms: number | null;
  confirmed_at_ms: number | null;
}

Example response

json

[
  {
    "payout_id": 17,
    "txid_hex": "efb5c3adf58eb7f481400fa72e3c34935bcda3ba26349fbf3b879d4b7c93640e",
    "state": "confirmed",
    "grains": 21500000000,
    "created_at_ms": 1764025000000,
    "broadcast_at_ms": 1764025002000,
    "confirmed_at_ms": 1764025130000
  }
]

curl

bash

curl -sS 'https://goldenpool.net/api/v1/miners/prl1pq5xcuhu3f9325cy9m69g9njfksw90cglq00ks3lylaf22krnc94qpargp8/payouts?limit=50' | jq