PUZZLE POOL

OFFLINE
Pool Hashrate
—
—
Active Workers
—
—
Jobs Done
—
—
Keys Completed
—
—
Found
0
Active Puzzle
Loading...
Night Sky Heatmap
Done
In Progress
Reclaimed
Found
Blocked
Visible Workers
Worker Version Speed Job Start Chunk Chunks Progress Last Seen
Scores — All Time
WorkerKeys CompletedJobs
Keys Found
WorkerAddressVirtual Chunk StartVirtual Chunk EndJob IDDatetime
Allocator Diagnostics
Generation
Generation counts: —
Assignment Order → Virtual Chunk Start
Sorted Gap Histogram
Normalized Nearest-Neighbor Gap Histogram
Low Bits Residue Map
Hilbert Curve Mapping (Full Scale)
API Reference
POST /api/v1/work Request a chunk of keyspace to scan
Request 
{
  "name": "rig-01",                  // required: unique worker id
  "hashrate": 5000000,               // optional: keys/s, used to size the next job
  "version": "1.3.3",                // optional: shown on dashboard
  "min_chunk_keys": "30000000",      // optional: minimum desired job size in keys
  "chunk_quantum_keys": "1048576"    // optional: round job size up to this quantum
}
Response 
{
  "job_id": 42,                      // use in /submit and /heartbeat
  "start_key": "0000...0000",        // inclusive range start
  "end_key":   "0000...1c00"         // exclusive range end
}
// worker scans [start_key, end_key)
// if the worker already owns an active job for the selected puzzle,
// the same job can be returned again.

{
  "error": "No active puzzle configured"
}
{
  "error": "All keyspace has been assigned"
}
Example Usage 
curl -sS -X POST "$POOL_SERVER/api/v1/work" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"rig-01",
    "hashrate":5000000,
    "version":"1.3.3",
    "min_chunk_keys":"30000000",
    "chunk_quantum_keys":"1048576"
  }'
POST /api/v1/submit Report a completed, partial, or solved chunk
Request 
// completed normally
{
  "name": "rig-01",
  "job_id": 42,
  "status": "done",
  "keys_scanned": 300000000
}

// found one or more matching keys
{
  "name": "rig-01",
  "job_id": 42,
  "status": "FOUND",
  "findings": [
    {
      "found_key": "0000000000000000000000000000000000000000000000600000000000100000",
      "found_address": "16vXLNVjJwrfHirzHsZdzWNPrAXq7n9oRT"
    }
  ]
}
Response 
{
  "accepted": true
}

{
  "accepted": false
}

{
  "accepted": false,
  "error": "chunk #42 not accepted, reported size: 123, expected size: 456. Chunk reclaimed."
}

// notes:
// - for status="done", keys_scanned is required
// - if keys_scanned < expected job size, the chunk becomes reclaimed
// - for status="FOUND", findings must be a non-empty array
// - duplicate findings are deduplicated server-side
Example Usage 
curl -sS -X POST "$POOL_SERVER/api/v1/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"rig-01",
    "job_id":42,
    "status":"done",
    "keys_scanned":300000000
  }'

curl -sS -X POST "$POOL_SERVER/api/v1/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"rig-01",
    "job_id":42,
    "status":"FOUND",
    "findings":[
      {
        "found_key":"0000000000000000000000000000000000000000000000600000000000100000",
        "found_address":"16vXLNVjJwrfHirzHsZdzWNPrAXq7n9oRT"
      }
    ]
  }'
POST /api/v1/heartbeat Keep a worker and its current job alive
Request 
{
  "name": "rig-01",
  "job_id": 42
}
Response 
{
  "ok": true
}

{
  "error": "Missing name or job_id"
}
Example Usage 
curl -sS -X POST "$POOL_SERVER/api/v1/heartbeat" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"rig-01",
    "job_id":42
  }'
GET /api/v1/stats Dashboard and monitoring snapshot
Request 
// active puzzle
GET /api/v1/stats

// specific puzzle
GET /api/v1/stats?puzzle_id=1
Response 
{
  "stage": "PROD",
  "puzzles": [
    { "id": 1, "name": "PUZZLE 71", "active": 1 }
  ],
  "puzzle": {
    "id": 1,
    "name": "PUZZLE 71",
    "start_hex": "0000...",
    "end_hex": "0000...",
    "total_keys": "1180591620717411303423",
    "test_chunk": null,
    "alloc_strategy": "virtual_random_chunks_v1",
    "alloc_cursor": "2220012",
    "virtual_chunk_size_keys": "33554432",
    "virtual_chunk_count": "35184372088832",
    "bootstrap_stage": 3,
    "status": {
      "state": "unsolved",
      "label": "unsolved",
      "target_type": "address",
      "target_value": "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU",
      "checked_at": "2026-05-23T10:00:00Z",
      "link": "https://mempool.space/address/1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU",
      "note": null
    }
  },
  "active_workers_count": 2,
  "inactive_workers_count": 1,
  "total_hashrate": 123456789,
  "completed_chunks": 2490237,
  "reclaimed_chunks": 0,
  "total_keys_completed": "83751426068480",
  "vis_revision": 42,
  "virtual_chunks": {
    "total": "35184372088832",
    "started_vchunks": "2495003",
    "completed_vchunks": "2490237",
    "virtual_chunk_size_keys": "33554432",
    "blocked_vchunk_count": "1024"
  },
  "shards": { // backward-compatible alias },
  "workers": [
    {
      "name": "rig-01",
      "hashrate": 5000000,
      "last_seen": "2026-04-28 09:45:12",
      "version": "1.3.3",
      "min_chunk_keys": "30000000",
      "chunk_quantum_keys": "1048576",
      "fresh": true,
      "assigned_here": true,
      "active": true,
      "current_chunk": 42,
      "current_vchunk_run": "4604757760040 + 1904"
    }
  ],
  "scores": [],
  "finders": []
}
Example Usage 
curl -sS "$POOL_SERVER/api/v1/stats"
curl -sS "$POOL_SERVER/api/v1/stats?puzzle_id=1"
GET /api/v1/visualization/heatmap Aggregated Night Sky Heatmap payload
Request 
GET /api/v1/visualization/heatmap
GET /api/v1/visualization/heatmap?puzzle_id=1
Response 
{
  "puzzle_id": 1,
  "loaded_at": "2026-05-24T08:11:29Z",
  "cells": [
    [1042, 83, 0, 1, 0, 0],
    [1043, 11, 0, 0, 0, 1]
  ]
}
Example Usage 
curl -sS "$POOL_SERVER/api/v1/visualization/heatmap"
curl -sS "$POOL_SERVER/api/v1/visualization/heatmap?puzzle_id=1"
GET /api/v1/visualization/hilbert Aggregated Hilbert Curve payload
Request 
GET /api/v1/visualization/hilbert
GET /api/v1/visualization/hilbert?puzzle_id=1
Response 
{
  "puzzle_id": 1,
  "loaded_at": "2026-05-24T08:11:29Z",
  "cells": [
    [17, 4, 0, 0, 0, 0],
    [18, 0, 0, 0, 1, 0]
  ]
}
Example Usage 
curl -sS "$POOL_SERVER/api/v1/visualization/hilbert"
curl -sS "$POOL_SERVER/api/v1/visualization/hilbert?puzzle_id=1"
GET /api/v1/visualization/allocator Aggregated Allocator Diagnostics payload
Request 
GET /api/v1/visualization/allocator
GET /api/v1/visualization/allocator?puzzle_id=1
Response 
{
  "puzzle_id": 1,
  "loaded_at": "2026-05-24T08:11:29Z",
  "generations": {
    "all": {
      "total_count": 2048,
      "scatter": [
        [0.0, 0.0008010864, 0],
        [0.5, 0.5000000000, 3]
      ],
      "gap_histogram": {
        "bins": [12, 9, 4, 1],
        "max_gap": 0.03125
      },
      "norm_gap_histogram": {
        "bins": [0, 3, 8, 19],
        "clip": 6.0
      },
      "metrics": {
        "n": 2047,
        "mean": 0.0004885,
        "median": 0.0002441,
        "p95": 0.0019531,
        "max": 0.03125,
        "cv": 1.87,
        "max_over_mean": 63.97
      }
    },
    "legacy": { "...": "same shape" },
    "affine": { "...": "same shape" },
    "feistel": { "...": "same shape" }
  }
}
Example Usage 
curl -sS "$POOL_SERVER/api/v1/visualization/allocator"
curl -sS "$POOL_SERVER/api/v1/visualization/allocator?puzzle_id=1"
POST /api/v1/admin/import-ranges Block externally-searched key ranges
Request 
{
  "puzzle_id": 1,
  "source":    "btcpuzzle.info",
  "base_hex":  "0000000000000000000000000000000000000000000000000000000000000001",
  "step":      "33554432",
  "range_ids": ["0", "1", "42", "99"]
}
Response 
{
  "ok": true,
  "inserted_ranges": 3,
  "already_blocked": 1,
  "invalid": 0,
  "errors": []
}

{ "error": "Puzzle does not use virtual_random_chunks_v1 strategy" }
{ "error": "Puzzle not found" }
Example Usage 
curl -sS -X POST "$POOL_SERVER/api/v1/admin/import-ranges" \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -d '{"puzzle_id":1,"source":"btcpuzzle.info","base_hex":"0000000000000000000000000000000000000000000000000000000000000001","step":"33554432","range_ids":["0","1","42"]}'
POST /api/v1/admin/activate-puzzle Switch active keyspace
Request 
{
  "id": 2
}
Response 
{
  "ok": true,
  "puzzle": {
    "id": 2,
    "name": "ALL BTC",
    "active": 1
  }
}

{
  "error": "unauthorized"
}
{
  "error": "Puzzle not found"
}
Example Usage 
curl -sS -X POST "$POOL_SERVER/api/v1/admin/activate-puzzle" \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -d '{"id":2}'