API-documentatie

Bouw je eigen client voor de pool. Elk endpoint, met requests, responses en fouten.

Overzicht

De API van btcpuzzle.info is waar de poolclient mee praat. Hij deelt sleutelranges uit om te scannen, neemt het resultaat van een scan in ontvangst en publiceert de openbare statistieken van de pool. btcpuzzle.info is opensource en iedereen kan een client schrijven: deze gids beschrijft elk openbaar endpoint, de gegevens die je stuurt, de gegevens die je terugkrijgt en de fouten die je kunt tegenkomen. Vragen: support@btcpuzzle.info.

Deze API is bewust bevroren: miners en tools van derden zijn ervan afhankelijk. Paden, headers, veldnamen (inclusief een paar oude spellingen zoals dateProcces en holded) en foutcodes veranderen niet. Aan responses kunnen nieuwe velden worden toegevoegd, dus negeer velden die je niet kent.

Basis-URL

Elk pad in deze gids is relatief ten opzichte van de basis-URL:

https://btcpuzzle.info/api

Clients die zijn geschreven voordat de website verhuisde, kunnen de oude host blijven gebruiken, met dezelfde paden en zonder het voorvoegsel /api:

https://api.btcpuzzle.info

Zo geven GET https://btcpuzzle.info/api/puzzle/codes en GET https://api.btcpuzzle.info/puzzle/codes hetzelfde antwoord. Nieuwe clients gebruiken de basis-URL met /api.

Snel aan de slag

Maak een gratis account aan op btcpuzzle.info, kopieer je minertoken vanaf het dashboard en vraag dan een range aan:

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Scan de teruggegeven range samen met de zes bewijsadressen, stuur het bewijs met PUT /puzzle/71/range en herhaal. Stuur tussen de twee calls af en toe een ping, zodat de pool weet dat de worker nog leeft.

Conventies

Versiebeheer

Er is één versie en er staat geen versie in de URL. Het contract van de oude API is exact behouden; zie Wijzigingen ten opzichte van de oude documentatie.

Authenticatie

De miner-endpoints worden geïdentificeerd met de header UserToken: de minertoken van 128 tekens van je account. Er is geen andere login en geen sessie voor deze endpoints. Je kunt op elk moment via je account een nieuwe token aanmaken; de oude werkt dan meteen niet meer. Houd de token geheim: wie hem heeft, scant op jouw naam.

Alle data-endpoints (puzzles, statistieken, pool, token) zijn openbaar en hebben geen token nodig.

Requests en responses

  • Bij de miner-endpoints gaan de requestgegevens in HTTP-headers, niet in de querystring of body. Headernamen zijn niet hoofdlettergevoelig (UserToken, usertoken en userToken zijn dezelfde header). Alleen POST /puzzle/{puzzleCode}/save-private-key heeft een JSON-body (Content-Type: application/json).
  • Responses zijn JSON in UTF-8 met propertynamen in camelCase. Properties zonder waarde worden weggelaten; de API schrijft nooit een JSON-null. Vertrouw niet op de inspringing.
  • Datums zijn ISO 8601 in UTC (2026-11-18T08:28:25.8176144Z). Geldbedragen en hoeveelheden zijn JSON-getallen.
  • Grote getallen zoals rangeContainsKeys zijn unsigned 64-bits integers en kunnen groter zijn dan 2^53: parse ze als 64-bits integers of als strings in talen die doubles gebruiken.
  • Walletadressen in openbare gegevens worden ingekort (eerste 8 tekens, ..., laatste 8) en het derde teken van een range-HEX wordt vervangen door X (3AB8443 wordt 3AX8443).

Rate limits

De limieten hieronder zijn de huidige standaardwaarden. Ze worden geteld in een vast tijdvenster; de beheerder kan ze aanpassen, dus lees het 429-antwoord in plaats van de getallen hard te coderen.

Geldt voorGeteld perLimiet
GET /puzzle/{puzzleCode}/rangeUserToken120 requests per 60 seconden
PUT /puzzle/{puzzleCode}/rangeUserToken360 requests per 60 seconden
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 requests per 60 seconden
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 requests per 180 seconden
Elk ander endpointIP-adres20 requests per seconde per endpoint, 200 per seconde in totaal

Een request boven de limiet krijgt als antwoord 429 Too Many Requests, een header Retry-After en deze body:

{
  "isSuccess": false,
  "details": "Quota exceeded."
}

Fouten

Bij fouten worden de statuscodes hieronder gebruikt. De body hangt af van het endpoint, dus controleer eerst de statuscode.

StatusBodyBetekenis
400{"error": "<code>"}Een miner-endpoint heeft het request geweigerd. De code zegt waarom: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (de spelling is historisch), invalid_request.
400{"isSuccess": false}Het markeringsverzoek van een range is geweigerd (verkeerd bewijs, onbekende of al gescande range, geblokkeerde gebruiker, inactieve puzzle).
400validatieprobleemEen verplichte header ontbreekt of is ongeldig, of het puzzlenummer ligt buiten 1 tot 160. Het is een application/problem+json-object waarvan errors de foute namen opsomt.
400problem detailsEen openbaar data-endpoint heeft voor deze puzzle niets te melden (onbekende of inactieve puzzle). application/problem+json met type, title, status en traceId.
401{"error": "invalid_user_token"}De minertoken is onbekend of het account is geblokkeerd (ping en save-private-key).
404{"error": "range_not_found"}De range voor de ping is niet in handen van deze worker.
429{"isSuccess": false, "details": "Quota exceeded."}Rate limit. Wacht Retry-After seconden.

Voorbeeld van een validatieprobleem (GET /puzzle/71/range zonder de header UserToken):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "UserToken": [
      "The UserToken field is required."
    ]
  },
  "traceId": "00-e3fc704f799663ec7f42c140ab4c996d-8592b3515c26a5c2-00"
}

Caching en CORS

Openbare data-endpoints sturen Cache-Control: public, max-age=N; de waarde staat bij elk endpoint, en een gecachte kopie wordt gedeeld door alle aanroepers, dus vaker pollen dan elke N seconden levert alleen dezelfde gegevens op. Miner-endpoints worden nooit gecachet. Browsers mogen de API aanroepen vanaf https://btcpuzzle.info, https://www.btcpuzzle.info en http://localhost:3000 (die laatste bestaat voor lokale ontwikkeling van de oude frontend); native clients hebben geen last van CORS.

Miner-endpoints

De drie calls van de scanlus: een range ophalen, pingen tijdens het scannen, de range als gescand markeren. Een vierde call slaat een gevonden sleutel op. Alle vier gebruiken de header UserToken.

GET/puzzle/{puzzleCode}/range

Geeft een willekeurige vrije range van de puzzle uit en houdt die voor je vast. Niemand anders krijgt een range die jij vasthoudt; als je hem niet markeert, gaat hij na een tijdje terug naar de pool (een ping verlengt het vasthouden).

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathinteger (1 tot 160)JaDe puzzle om te scannen, bijvoorbeeld 71. 38 is de testpool. GET /puzzle/codes geeft de codes. Voor een voltooide puzzle wordt stilzwijgend de standaardpuzzle gebruikt, en het antwoord zegt in puzzleCode welke puzzle je hebt gekregen.
UserTokenheaderstring (128 tekens)JaJe minertoken.
WorkerNameheaderstring (1 tot 16 tekens)NeeDe naam van deze worker. Alleen letters en cijfers. Opgeslagen als default als je er geen stuurt.
SecurityHashheaderstringNeeVrije tekst die bij de range wordt bewaard. Optioneel.
CustomRangeheaderstringNeeBeperkt de range die je krijgt: een prefix van de HEX (2D, 3BA) of start:end (3400000:38FFFFF). none of geen header betekent elke range. Een heel smal venster wordt door de pool verbreed, dus je kunt een andere range krijgen dan je noemde.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Voorbeeldresponse

200 OK

{
  "hex": "3AB8443",
  "puzzleCode": 71,
  "workloadStart": "00000000000",
  "workloadEnd": "fffffffffff",
  "targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
  "proofOfWorkAddresses": [
    "1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
    "15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
    "1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
    "14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
    "1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
    "14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
  ]
}

Responsevelden

VeldTypeBeschrijving
hexstringDe range om te scannen, in hoofdletters zonder opvulling. Het is het begin van de privésleutels van de range.
puzzleCodeintegerDe puzzle waartoe de range behoort (de standaardpuzzle wanneer de gevraagde puzzle voltooid is).
workloadStartstringAchter hex geplakt geeft dit de eerste privésleutel van de range.
workloadEndstringAchter hex geplakt geeft dit de laatste privésleutel van de range. Kan langer zijn dan workloadStart bij puzzles waarvan de ranges meerdere ID's beslaan.
targetAddressstringHet puzzleadres dat je zoekt. Scan het samen met de bewijsadressen.
proofOfWorkAddressesarray van 6 stringsAdressen van zes privésleutels die de pool in de range heeft geplaatst. Vind hun privésleutels om de scan te bewijzen: zie Proof of work.

In het voorbeeld hierboven loopt de range van 3AB8443 + 00000000000 = 3AB844300000000000 tot 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Privésleutels zijn 64 hexadecimale tekens; vul links aan met nullen.

Fouten

StatusBodyWanneer
400{"error": "invalid_puzzle"}De puzzle bestaat niet of is niet actief.
400{"error": "invalid_user_token"}De token is onbekend of geblokkeerd.
400{"error": "too_much_request"}Je houdt te veel ranges vast die je nog niet hebt gescand, of je vraagt sneller aan dan je afrondt. Scan wat je vasthoudt; vastgehouden ranges gaan na korte tijd terug naar de pool.
400{"error": "not_eligable"}De puzzle heeft deelnamekosten en je voldoet nog niet aan de voorwaarden.
400{"error": "reached_of_keyspace"}Er is geen vrije range meer (of geen die past bij je CustomRange).
400validation problemOntbrekende of misvormde header, of een puzzlenummer buiten 1 tot 160.
429{"isSuccess": false, ...}Rate limit: 120 per minuut per token.

Proof of work

De pool wil zeker weten dat je de range echt hebt gescand. Bij elke range kiest hij zes privésleutels erbinnen en geeft hij alleen hun adressen terug (proofOfWorkAddresses). Scan terwijl je de range naar het doeladres scant ook naar deze zes adressen. Als je alle zes privésleutels hebt gevonden:

  1. Schrijf elke privésleutel als 64 hexadecimale hoofdletters, links aangevuld met nullen.
  2. Plak de zes strings aan elkaar, in de volgorde van de adressen, zonder iets ertussen.
  3. Neem de SHA-256 van de UTF-8-tekst en schrijf die als 64 hexadecimale kleine letters. Dat is de HashedProofKey van het markeringsverzoek.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
               = 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87

Het bewijs is voor elke range anders. Het aantal bewijsadressen is vandaag zes; lees de lengte van proofOfWorkAddresses in plaats van ervan uit te gaan.

PUT/puzzle/{puzzleCode}/range

Markeert een range als gescand. De pool controleert het bewijs en telt de range, als het klopt, als voltooid voor jou. Een range kan maar één keer worden gemarkeerd.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathinteger (1 tot 160)JaDe puzzle van de range.
UserTokenheaderstring (128 tekens)JaJe minertoken.
HEXheaderstringJaDe hex van de range die je hebt gescand, zoals de pool hem teruggaf. Voorbeeld: 3AB8443.
HashedProofKeyheaderstringJaHet proof of work: zie Proof of work.
WorkerNameheaderstring (1 tot 16 tekens)NeeDe worker die de range heeft gescand.
GPUNameheaderstringNeeHet model van de videokaart. Gebruikt voor de openbare statistieken.
GPUCountheaderintegerNeeAantal kaarten van de worker. Standaard 1.
IsForceContinueheaderbooleanNeeZet dit wanneer de worker doorging hoewel hij het einde van zijn keyspace had bereikt. Standaard false.

Voorbeeldrequest

curl -X PUT "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1" \
  -H "HEX: 3AB8443" \
  -H "HashedProofKey: 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87" \
  -H "GPUName: RTX 4090" \
  -H "GPUCount: 1"

Voorbeeldresponse

200 OK

{
  "isSuccess": true
}

Fouten

StatusBodyWanneer
400{"isSuccess": false}Elke weigering: verkeerd bewijs, onbekende range, een range die al gemarkeerd is, geblokkeerd account, inactieve puzzle.
400validation problemEen verplichte header ontbreekt of is misvormd.
429{"isSuccess": false, ...}Rate limit: 360 per minuut per token.

PATCH/puzzle/{puzzleCode}/range/ping

Laat de pool weten dat een worker zijn range nog aan het scannen is. Een ping houdt de range vast en toont de worker als actief op de website. Stuur er ongeveer elke 2 minuten een; het interval mag niet langer zijn dan 30 minuten, anders neemt de pool de range terug.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaDe puzzle van de range.
HexheaderstringJaDe range die de worker nu scant.
UserTokenheaderstring (128 tekens)JaJe minertoken.
WorkerNameheaderstringJaDe workernaam die werd gebruikt toen de range werd aangevraagd (default als er geen werd gestuurd).

Voorbeeldrequest

curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
  -H "Hex: 3AB8443" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Voorbeeldresponse

200 OK met een lege body.

Fouten

StatusBodyWanneer
400{"error": "invalid_request"}Een header is leeg.
401{"error": "invalid_user_token"}Onbekende of geblokkeerde token.
404{"error": "range_not_found"}Deze worker houdt in die puzzle geen ongescande range met die HEX vast.
429{"isSuccess": false, ...}Rate limit: 360 per minuut per token.

POST/puzzle/{puzzleCode}/save-private-key

Slaat een gevonden privésleutel versleuteld op in je account. De client versleutelt de sleutel met de RSA public key die je hem hebt gegeven; de site bewaart alleen de versleutelde tekst, die jij met je private key ontsleutelt. De sleutel verschijnt op de pagina met gevonden sleutels van je dashboard.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaDe puzzle waartoe de sleutel behoort.
UserTokenheaderstring (128 tekens)JaJe minertoken.
Content-TypeheaderstringJaapplication/json.
namebodystringNeeEen label, bijvoorbeeld de workernaam. Opgeslagen als Puzzle71 - rig1.
encryptedKeybodystringJaDe versleutelde privésleutel (de client stuurt die in base64).

Voorbeeldrequest

curl -X POST "https://btcpuzzle.info/api/puzzle/71/save-private-key" \
  -H "UserToken: <128-character miner token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "rig1","encryptedKey": "<encrypted key, base64>"}'

Voorbeeldresponse

200 OK Let op: de property heet success, niet isSuccess.

{
  "success": true,
  "message": "Key saved successfully."
}

Fouten

StatusBodyWanneer
401{"error": "invalid_user_token"}Onbekende of geblokkeerde token.
400problem detailsEr is niets opgeslagen: dezelfde sleutel is al voor dit account opgeslagen, of de body ontbreekt.
429{"isSuccess": false, ...}Rate limit: 10 per 180 seconden per token.

Puzzlegegevens

Openbare lees-endpoints over de puzzles van de pool. Er is geen token nodig. Het Puzzle-object en de andere objecten worden aan het eind van deze gids beschreven.

GET/puzzle

De puzzles die in de pool staan: de actieve, de volgende en de testpool (en de voltooide die voor de geschiedenis worden bewaard). 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle"

Voorbeeldresponse

200 OK Een array van Puzzle-objecten, hier ingekort tot één.

[
  {
    "id": 71,
    "name": "Puzzle 71",
    "code": 71,
    "hexStart": "400000000000000000",
    "hexEnd": "7fffffffffffffffff",
    "targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
    "hexRangeLength": 7,
    "reward": 7.1,
    "hexStartPool": "4000000",
    "hexEndPool": "7ffffff",
    "totalRanges": 67108864,
    "percentage": 0.4172,
    "rangesScannedLastHour": 612,
    "totalScanned": 279997,
    "statisticsTotalScanned": 0,
    "statisticsFoundOnPool": false,
    "statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
    "rangeContainsKeyByDefault": 17592186044415,
    "rangeContainsKeys": 17592186044415,
    "rangesPerKey": 1,
    "workloadStart": "00000000000",
    "workloadEnd": "fffffffffff",
    "dateStart": "2026-01-01T00:00:00Z",
    "dateEnd": "2027-01-01T00:00:00Z",
    "isCompleted": false,
    "isNextPuzzle": false,
    "isActive": true,
    "isEntranceFeeActive": false,
    "entranceFee": 0,
    "isDefault": true,
    "isTestPool": false,
    "isOnPool": true,
    "nextScanAllowedInMinutes": 360,
    "challenges": []
  }
]

Fouten

StatusBodyWanneer
404[]De pool heeft helemaal geen puzzle.

GET/puzzle/all

Elke puzzle in de database, voltooide inbegrepen. 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/all"

Antwoordt 200 met een array van Puzzle-objecten.

GET/puzzle/available

De puzzles die in de pool kunnen worden gescand. 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/available"

Antwoordt 200 met een array van Puzzle-objecten.

GET/puzzle/default

De standaardpuzzle: de puzzle waarop een aanvraag voor een voltooide puzzle terugvalt. 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/default"

Voorbeeldresponse

200 OK Eén Puzzle-object.

{
  "id": 71,
  "name": "Puzzle 71",
  "code": 71,
  "hexStart": "400000000000000000",
  "hexEnd": "7fffffffffffffffff",
  "targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
  "hexRangeLength": 7,
  "reward": 7.1,
  "hexStartPool": "4000000",
  "hexEndPool": "7ffffff",
  "totalRanges": 67108864,
  "percentage": 0.4172,
  "rangesScannedLastHour": 612,
  "totalScanned": 279997,
  "statisticsTotalScanned": 0,
  "statisticsFoundOnPool": false,
  "statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
  "rangeContainsKeyByDefault": 17592186044415,
  "rangeContainsKeys": 17592186044415,
  "rangesPerKey": 1,
  "workloadStart": "00000000000",
  "workloadEnd": "fffffffffff",
  "dateStart": "2026-01-01T00:00:00Z",
  "dateEnd": "2027-01-01T00:00:00Z",
  "isCompleted": false,
  "isNextPuzzle": false,
  "isActive": true,
  "isEntranceFeeActive": false,
  "entranceFee": 0,
  "isDefault": true,
  "isTestPool": false,
  "isOnPool": true,
  "nextScanAllowedInMinutes": 360,
  "challenges": []
}

Fouten

StatusBodyWanneer
404{"error": "puzzle_not_found"}Er is geen standaardpuzzle ingesteld.

GET/puzzle/codes

De nummers van de puzzles die actief zijn of als volgende komen, gewone puzzles eerst en de testpool als laatste. 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/codes"

Voorbeeldresponse

200 OK

[71, 72, 73, 38]

GET/puzzle/{puzzleCode}/info

Eén puzzle, gelezen uit de database. 10 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaHet puzzlenummer.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/info"

Voorbeeldresponse

200 OK Een Puzzle-object. Runtimewaarden zoals rangesScannedLastHour worden alleen in de lijst-endpoints gevuld.

{
  "id": 71,
  "name": "Puzzle 71",
  "code": 71,
  "hexStart": "400000000000000000",
  "hexEnd": "7fffffffffffffffff",
  "targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
  "hexRangeLength": 7,
  "reward": 7.1,
  "hexStartPool": "4000000",
  "hexEndPool": "7ffffff",
  "totalRanges": 67108864,
  "percentage": 0.4172,
  "rangesScannedLastHour": 612,
  "totalScanned": 279997,
  "statisticsTotalScanned": 0,
  "statisticsFoundOnPool": false,
  "statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
  "rangeContainsKeyByDefault": 17592186044415,
  "rangeContainsKeys": 17592186044415,
  "rangesPerKey": 1,
  "workloadStart": "00000000000",
  "workloadEnd": "fffffffffff",
  "dateStart": "2026-01-01T00:00:00Z",
  "dateEnd": "2027-01-01T00:00:00Z",
  "isCompleted": false,
  "isNextPuzzle": false,
  "isActive": true,
  "isEntranceFeeActive": false,
  "entranceFee": 0,
  "isDefault": true,
  "isTestPool": false,
  "isOnPool": true,
  "nextScanAllowedInMinutes": 360,
  "challenges": []
}

Fouten

StatusBodyWanneer
204leegDie puzzle bestaat niet.

GET/puzzle/{puzzleCode}/statistics

Alles wat de puzzlepagina toont: totalen, ranglijsten, actieve workers, de laatste 200 gescande ranges en een grafiek per uur. 60 seconden gecachet (en de server bewaart één kopie 5 minuten).

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaEen actieve puzzle (of de testpool).

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/statistics"

Voorbeeldresponse

200 OK Ingekort: de arrays bevatten hier één element, en lastRanges maximaal 200.

{
  "puzzle": {
    "name": "Puzzle 71",
    "code": 71,
    "hexStart": "400000000000000000",
    "hexEnd": "7fffffffffffffffff",
    "targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
    "hexStartPool": "4000000",
    "hexEndPool": "7ffffff",
    "totalRanges": 67108864,
    "totalScanned": 279997,
    "rangeContainsKeys": 17592186044415,
    "workloadStart": "00000000000",
    "workloadEnd": "fffffffffff",
    "rangesPerKey": 1,
    "isCompleted": false,
    "isActive": true,
    "isEntranceFeeActive": false,
    "entranceFee": 0,
    "isDefault": true,
    "isTestPool": false,
    "reward": 7.1
  },
  "scannedLast24H": 14702,
  "entranceFeesPaidTotal": 0,
  "topWorkersAlltime": [
    {
      "userId": 0,
      "walletAddress": "1BvBMSEY...7xJaNVN2",
      "totalScanned": 5120
    }
  ],
  "topWorkersLast24h": [
    {
      "userId": 2051875,
      "walletAddress": "1BvBMSEY...7xJaNVN2",
      "totalScanned": 412
    }
  ],
  "activeWorkers": [
    {
      "walletAddress": "1BvBMSEY...7xJaNVN2",
      "workerName": "rig1"
    }
  ],
  "challenges": [],
  "kingdom": {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "message": "Hello pool",
    "image": 3,
    "isPublished": true
  },
  "topSpeed": {
    "date": "2026-11-10T14:00:00Z",
    "scanned": 912,
    "keysPerSecond": 4456789012345
  },
  "chartData": [
    {
      "date": "2026-11-18T08:00:00Z",
      "dateOnly": "2026-11-18",
      "hoursOnly": 8,
      "rangesScanned": 640
    }
  ],
  "lastRanges": [
    {
      "hex": "10X0",
      "walletAddress": "1BvBMSEY...7xJaNVN2",
      "startTime": "2026-11-18T07:27:57.603786Z",
      "endTime": "2026-11-18T08:22:57.603786Z",
      "pingTime": "2026-11-18T08:20:57.603786Z",
      "gpuModel": "RTX 4090",
      "gpuCount": 1,
      "workerName": "rig1",
      "isPremiumUser": false,
      "isScanned": true,
      "isPinged": false,
      "keysInSeconds": 20824083.85909091,
      "totalSeconds": 3300
    }
  ],
  "rewards": [],
  "dateUpdated": "2026-11-18T08:28:25.8176144Z",
  "currentSpeed": {
    "activeWorkerCount": 38,
    "keysPerSecondFormatted": "162.3 Bkeys/s",
    "keysPerSecondRaw": "162300000000"
  }
}

Voor een puzzle die nog niet actief is (de volgende) worden alleen puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges en dateUpdated teruggegeven. Zie Statistics-object voor de velden.

Fouten

StatusBodyWanneer
400problem detailsDe puzzle bestaat niet of is niet actief en ook niet de volgende.

GET/puzzle/{puzzleCode}/speed

De huidige snelheid van de pool in een puzzle. 60 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaHet puzzlenummer.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/speed"

Voorbeeldresponse

200 OK Zie CurrentSpeed. Een onbekende puzzle antwoordt met nulwaarden, nooit met een fout.

{
  "puzzleCode": 71,
  "currentSpeed": {
    "activeWorkerCount": 38,
    "keysPerSecondFormatted": "162.3 Bkeys/s",
    "keysPerSecondRaw": "162300000000"
  }
}

GET/puzzle/{puzzleCode}/workers

De workers die nu scannen: die met een range die ze in de laatste 30 minuten hebben gepingd. Niet gecachet door de browser; de server bewaart het antwoord 60 seconden. puzzleCode 0 betekent de standaardpuzzle.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaHet puzzlenummer.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/workers"

Voorbeeldresponse

200 OK Een lege array als niemand scant of de puzzle onbekend is.

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "workerName": "rig1"
  }
]

GET/puzzle/{puzzleCode}/workers-pinging

Dezelfde lijst als /workers (als apart pad behouden omdat clients beide gebruiken).

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"

Dezelfde parameters en hetzelfde antwoord als GET /puzzle/{puzzleCode}/workers.

GET/puzzle/{puzzleCode}/rewards

De poolbeloningen van een actieve puzzle: extra prijzen die sponsors op privésleutels binnen de ranges hebben gezet (nieuwste eerst, maximaal 32). De privésleutel van een beloning wordt pas getoond nadat die is opgelost. 600 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaEen actieve puzzle.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/rewards"

Voorbeeldresponse

200 OK Zie Reward. Een lege array als de puzzle er geen heeft.

[
  {
    "id": 12,
    "puzzleCode": 71,
    "targetAddress": "1ExampleRewardAddress0000000000000",
    "rewardDescription": "Hardware wallet",
    "provider": "Sponsor",
    "brand": "Example",
    "dateCreated": "2026-11-01T00:00:00Z",
    "dateSolved": "0001-01-01T00:00:00",
    "puzzleId": 71
  }
]

Fouten

StatusBodyWanneer
400problem detailsDe puzzle is niet actief.

GET/puzzle/{puzzleCode}/challenge

De laatste startpunten van challenges van een actieve puzzle (nieuwste eerst, maximaal 32). 600 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaEen actieve puzzle.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/challenge"

Voorbeeldresponse

200 OK Zie Challenge. Een lege array als er geen is.

[
  {
    "hex": "3A",
    "dateCreated": "2026-11-18T06:00:00Z",
    "puzzleId": 71
  }
]

Fouten

StatusBodyWanneer
400problem detailsDe puzzle is niet actief.

GET/puzzle/{puzzleCode}/entrancefee

De deelnamekosten van een puzzle in USD, als die aan staan. 300 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaEen actieve puzzle met deelnamekosten.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"

Voorbeeldresponse

200 OK

{
  "fee": 25.0,
  "puzzle": 71
}

Fouten

StatusBodyWanneer
400problem detailsDe puzzle is niet actief of heeft geen deelnamekosten.

GET/puzzle/{puzzleCode}/statistics-by-hex-prefix

Hoeveel van de puzzle is gescand per prefix van twee tekens van de range-HEX (de heatmap van de puzzlepagina). 3600 seconden gecachet.

Parameters

NaamInTypeVerplichtBeschrijving
puzzleCodepathintegerJaEen actieve puzzle.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"

Voorbeeldresponse

200 OK Eén element per prefix, gesorteerd op hexStarts. De property pertantageShow is bewust verkeerd gespeld (bevroren). Vanaf 70% stoppen de getallen bij 70% en is isLimitExceeded true.

[
  {
    "hexStarts": "40",
    "maxRanges": 1048576,
    "scannedShow": 4411,
    "pertantageShow": 0.37,
    "isLimitExceeded": false
  }
]

Fouten

StatusBodyWanneer
400problem detailsDe puzzle is niet actief.

Poolgegevens

Openbare lees-endpoints over de pool als geheel, de GPU-lijst en de BCPZ-token.

GET/pool/homepage

De puzzlelijst van de homepage: dezelfde array als GET /puzzle, en de standaardpuzzle heeft zijn speed. 60 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/homepage"

Antwoordt 200 met een array van Puzzle-objecten.

GET/pool/gpus

De GPU-benchmarklijst, snelste eerst (sleutels per seconde in de pool). 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/gpus"

Voorbeeldresponse

200 OK

[
  {
    "brand": "nvidia",
    "name": "RTX 4090",
    "keysPerSecond": 4491469067.71,
    "dateUpdated": "2026-11-18T08:27:53.190819Z"
  }
]

Responsevelden

VeldTypeBeschrijving
brandstringnvidia of amd.
namestringDe kaart.
keysPerSecondnumberGemeten snelheid.
dateUpdateddateLaatste update.

GET/pool/token-distribute-history

De dagelijkse BCPZ-uitkeringen, nieuwste eerst (maximaal 180). 300 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/token-distribute-history"

Voorbeeldresponse

200 OK

[
  {
    "id": 412,
    "dateProcces": "2026-11-17T03:00:19Z",
    "totalUsers": 85,
    "totalAmount": 516,
    "description": "Success: 85/85"
  }
]

Responsevelden

VeldTypeBeschrijving
idintegerNummer van de uitkering.
dateProccesdateWanneer die is uitgevoerd. De naam is verkeerd gespeld en bevroren.
totalUsersintegerGebruikers die tokens hebben ontvangen.
totalAmountnumberUitgekeerde BCPZ (1 per gescande range).
descriptionstringResultaattekst.

GET/pool/token-top-50-holders

De 50 accounts met de meeste verdiende BCPZ, met ingekorte walletadressen. 600 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/token-top-50-holders"

Voorbeeldresponse

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "balance": 2500.25,
    "total": 400,
    "minted": 200
  }
]

Responsevelden

VeldTypeBeschrijving
walletAddressstringIngekort adres.
balancenumberBCPZ die nu op het account staat.
totalnumberIn totaal verdiende BCPZ.
mintednumberBCPZ die al naar het Polygon-netwerk is opgenomen.

GET/pool/token-mint-history

De laatste BCPZ-opnames naar het Polygon-netwerk, nieuwste eerst (maximaal 180). 600 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/token-mint-history"

Voorbeeldresponse

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "minted": 100,
    "date": "2026-11-15T08:27:58.123754Z",
    "txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
  }
]

Responsevelden

VeldTypeBeschrijving
walletAddressstringIngekort adres van het account.
mintednumberVerstuurde BCPZ.
datedateWanneer het is verstuurd.
txIdstringTransactiehash op Polygon. Weggelaten zolang de overboeking niet klaar is.

GET/pool/btc-price

De Bitcoinkoers in USD en EUR, van een exchange. 600 seconden gecachet.

Voorbeeldrequest

curl "https://btcpuzzle.info/api/pool/btc-price"

Voorbeeldresponse

200 OK Beide waarden zijn 0 als de prijsbron niet bereikbaar is.

{"usd":66739.06,"eur":60607.25}

Realtime feed (SignalR)

De pool publiceert elke geclaimde en voltooide range op een SignalR-hub. De website gebruikt die voor de live statuspagina. De hub is openbaar, heeft geen token nodig en verstuurt alleen: er zijn geen methoden die een client kan aanroepen.

Hub-URLhttps://btcpuzzle.info/api/hex_socket
Oude hosthttps://api.btcpuzzle.info/hex_socket
ProtocolSignalR met het standaard-JSON-protocol; WebSockets, Server-Sent Events en Long Polling worden aangeboden.
EventPoolStatus
LimietHet negotiate-request telt mee voor de IP-rate-limit. De hub zelf is na het verbinden niet beperkt.

Verbinden

Gebruik een SignalR-clientbibliotheek (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Onder de motorkap doet die eerst een negotiate:

Voorbeeldrequest

curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"

Voorbeeldresponse

200 OK

{
  "negotiateVersion": 1,
  "connectionId": "s7dzEsrMHQKQsCHjvm2faQ",
  "connectionToken": "A9SBLfct2OZrZZkvaQMLZw",
  "availableTransports": [
    {
      "transport": "WebSockets",
      "transferFormats": [
        "Text",
        "Binary"
      ]
    },
    {
      "transport": "ServerSentEvents",
      "transferFormats": [
        "Text"
      ]
    },
    {
      "transport": "LongPolling",
      "transferFormats": [
        "Text",
        "Binary"
      ]
    }
  ]
}
import { HubConnectionBuilder } from '@microsoft/signalr';

const hub = new HubConnectionBuilder()
  .withUrl('https://btcpuzzle.info/api/hex_socket')
  .withAutomaticReconnect()
  .build();
hub.on('PoolStatus', (event) => console.log(event));
await hub.start();

Event PoolStatus

Eén argument, een JSON-object. Het event wordt naar alle verbonden clients gestuurd wanneer een range wordt uitgegeven en wanneer een range als gescand wordt gemarkeerd.

{
  "hex": "3AX8443",
  "walletAddress": "1BvBMSEY...7xJaNVN2",
  "workerName": "rig1",
  "puzzleCode": 71,
  "status": "holded"
}
VeldTypeBeschrijving
hexstringDe range-HEX met het derde teken vervangen door X.
walletAddressstringIngekort adres van het account.
workerNamestring of nullDe workernaam (default als er geen werd gestuurd). Bij scanned is het de naam die met het markeringsverzoek werd gestuurd, en die kan null zijn.
puzzleCodeintegerDe puzzle van de range.
statusstringholded nadat een range is uitgegeven, scanned nadat een range is gemarkeerd. De spelling is bevroren.

Events worden afgeleverd zolang de verbinding open is; na een reconnect wordt niets opnieuw afgespeeld. Als de beheerder de live feed uitschakelt, worden verbindingen geweigerd.

Objecten

Puzzle-object

Teruggegeven door de puzzlelijst-endpoints en /puzzle/{puzzleCode}/info. Properties zonder waarde worden weggelaten.

VeldTypeBeschrijving
idintegerDatabase-ID (gelijk aan code voor puzzles uit het oude systeem).
namestringBijvoorbeeld Puzzle 71.
codeintegerHet puzzlenummer.
hexStart, hexEndstringEerste en laatste privésleutel van de puzzle, hexadecimaal.
targetWalletAddressstringHet adres met de beloning.
hexRangeLengthintegerLengte van de range-HEX die de pool uitgeeft (het deel van de sleutel dat hij kiest).
rewardnumberDe beloning in BTC.
hexStartPool, hexEndPoolstringEerste en laatste range-HEX. Leeg tenzij de puzzle in de pool staat.
totalRangesintegerAantal ranges van de puzzle. 0 tenzij de puzzle in de pool staat.
percentagenumberPercentage van de ranges dat is gescand.
totalScanned, rangesScannedLastHourintegerGescande ranges in totaal en in het afgelopen uur (gevuld in de lijst-endpoints).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBydiverseEindcijfers van een voltooide puzzle; statisticsFoundBy is alleen aanwezig als die bekend is.
rangeContainsKeys, rangeContainsKeyByDefaultintegerAantal privésleutels (min één) in één range. De twee verschillen wanneer ranges meerdere ID's beslaan.
rangesPerKeyintegerHoeveel range-ID's één range beslaat (1 voor de meeste puzzles).
workloadStart, workloadEndstringHet deel van de privésleutel dat een client na de range-HEX scant: zie GET range.
customWorkloadStart, customWorkloadEndstringAanwezig als de puzzle een aangepaste workload gebruikt.
dateStart, dateEnddateGeplande datums van de puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanDe toestand van de puzzle: voltooid, aangekondigd, nu scanbaar, de standaard, de testpool, in de pool.
isEntranceFeeActive, entranceFeeboolean, numberOf de deelnamekosten aan staan en de prijs ervan in USD (0 als ze uit staan).
nextScanAllowedInMinutesintegerHoe lang een uitgegeven range wordt vastgehouden voordat hij aan iemand anders kan worden gegeven.
challengesarrayDe laatste challenge, of een lege array.
privateKey, publicKeystringAlleen voor opgeloste puzzles.
rewards, speedarray, objectAlleen aanwezig bij sommige endpoints.

Statistics-object

VeldTypeBeschrijving
puzzleobjectDe hoofdcijfers van de puzzle (naam, code, aantallen ranges, workload, toestand, beloning).
scannedLast24HintegerGescande ranges in de laatste 24 uur.
entranceFeesPaidTotalnumberBetaalde deelnamekosten voor de puzzle, USD.
topWorkersAlltimearrayMaximaal 50 keer {userId, walletAddress, totalScanned}; userId is hier 0.
topWorkersLast24harrayHetzelfde voor de laatste 24 uur.
activeWorkersarray{walletAddress, workerName} van de workers die in de laatste 30 minuten hebben gepingd.
challengesarrayMaximaal 32 challenges.
kingdomobjectDe koning van de puzzle: walletAddress, message, image en isPublished.
topSpeedobjectHet beste uur ooit: date, scanned ranges en keysPerSecond.
chartDataarrayDe laatste maand per uur, nieuwste eerst: date, dateOnly, hoursOnly en rangesScanned.
lastRangesarrayDe laatste 200 gescande ranges, nieuwste eerst: hex (gemaskeerd), walletAddress (gemaskeerd), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds en totalSeconds.
rewardsarrayBeloningen van de puzzle (zonder privésleutels).
dateUpdateddateWanneer de cijfers zijn berekend.
currentSpeedobjectCurrentSpeed.

CurrentSpeed-object

VeldTypeBeschrijving
activeWorkerCountintegerWorkers die in de laatste 6 uur hebben gescand en in het afgelopen uur hebben gepingd.
keysPerSecondFormattedstringDe snelheid met een eenheid: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s enzovoort.
keysPerSecondRawstringDe snelheid in sleutels per seconde als integer-tekst.

Challenge-object

VeldTypeBeschrijving
hexstringDe begintekens die elke deelnemer aan de challenge scant.
dateCreateddateWanneer de challenge begon.
puzzleIdintegerDe puzzle.

Reward-object

VeldTypeBeschrijving
id, puzzleCode, puzzleIdintegerIdentificatie.
targetAddressstringHet adres van de beloningssleutel.
rewardContent, rewardDescription, provider, providerDesc, brandstringWat de prijs is en wie die geeft. Properties zonder waarde worden weggelaten.
privateKeystringAlleen aanwezig nadat de beloning is opgelost.
dateCreated, dateSolveddateWanneer die is gemaakt en opgelost (0001-01-01T00:00:00 zolang niet opgelost).

Wijzigingen ten opzichte van de oude documentatie

Aan het contract is niets veranderd: elk endpoint, elke header, elk veld en elke foutcode van de oude API werkt nog en antwoordt hetzelfde. Deze gids vervangt de oude pagina, die drie endpoints beschreef. Wat hier nieuw is:

  • De openbare data-endpoints, de realtime feed, de foutcodes en de rate limits zijn gedocumenteerd. De oude pagina noemde ze niet.
  • Correcties van de oude tekst: de header UserToken van het markeringsverzoek is de minertoken (de oude pagina noemde het een walletadres); het ping-interval is ongeveer 2 minuten en maximaal 30 minuten, en de limiet is 360 pings per minuut per token, niet 60 per uur; de puzzle van de testpool is 38.
  • De basis-URL is https://btcpuzzle.info/api; de oude host api.btcpuzzle.info blijft werken.
  • De SignalR-hub heeft geen client-naar-servermethode meer, zodat niemand nepevents kan sturen. Het event zelf is niet veranderd.
  • De laatste vrije range van een puzzle wordt nu ook uitgegeven, en een heel smal CustomRange-venster wordt verbreed, zodat een range niet kan worden uitgekozen door om precies één te vragen.
  • De openbare statistieken tonen het IP-adres van een miner niet meer.

Trakteer me op een koffie

Poolpuzzles

Wat de pool nu scant, wat er hierna komt en de puzzles waaraan hij al heeft gewerkt.

Nu aan het scannen1

Volgende2

Eerder gescand4

Alle 160 puzzles