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/apiClients die zijn geschreven voordat de website verhuisde, kunnen de oude host blijven gebruiken, met dezelfde paden en zonder het voorvoegsel /api:
https://api.btcpuzzle.infoZo 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,usertokenenuserTokenzijn dezelfde header). AlleenPOST /puzzle/{puzzleCode}/save-private-keyheeft 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
rangeContainsKeyszijn 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 doorX(3AB8443wordt3AX8443).
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 voor | Geteld per | Limiet |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 requests per 60 seconden |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 requests per 60 seconden |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 requests per 60 seconden |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 requests per 180 seconden |
| Elk ander endpoint | IP-adres | 20 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.
| Status | Body | Betekenis |
|---|---|---|
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). |
400 | validatieprobleem | Een 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. |
400 | problem details | Een 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer (1 tot 160) | Ja | De 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. |
UserToken | header | string (128 tekens) | Ja | Je minertoken. |
WorkerName | header | string (1 tot 16 tekens) | Nee | De naam van deze worker. Alleen letters en cijfers. Opgeslagen als default als je er geen stuurt. |
SecurityHash | header | string | Nee | Vrije tekst die bij de range wordt bewaard. Optioneel. |
CustomRange | header | string | Nee | Beperkt 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
| Veld | Type | Beschrijving |
|---|---|---|
hex | string | De range om te scannen, in hoofdletters zonder opvulling. Het is het begin van de privésleutels van de range. |
puzzleCode | integer | De puzzle waartoe de range behoort (de standaardpuzzle wanneer de gevraagde puzzle voltooid is). |
workloadStart | string | Achter hex geplakt geeft dit de eerste privésleutel van de range. |
workloadEnd | string | Achter 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. |
targetAddress | string | Het puzzleadres dat je zoekt. Scan het samen met de bewijsadressen. |
proofOfWorkAddresses | array van 6 strings | Adressen 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
| Status | Body | Wanneer |
|---|---|---|
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). |
400 | validation problem | Ontbrekende 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:
- Schrijf elke privésleutel als 64 hexadecimale hoofdletters, links aangevuld met nullen.
- Plak de zes strings aan elkaar, in de volgorde van de adressen, zonder iets ertussen.
- Neem de SHA-256 van de UTF-8-tekst en schrijf die als 64 hexadecimale kleine letters. Dat is de
HashedProofKeyvan het markeringsverzoek.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87Het 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer (1 tot 160) | Ja | De puzzle van de range. |
UserToken | header | string (128 tekens) | Ja | Je minertoken. |
HEX | header | string | Ja | De hex van de range die je hebt gescand, zoals de pool hem teruggaf. Voorbeeld: 3AB8443. |
HashedProofKey | header | string | Ja | Het proof of work: zie Proof of work. |
WorkerName | header | string (1 tot 16 tekens) | Nee | De worker die de range heeft gescand. |
GPUName | header | string | Nee | Het model van de videokaart. Gebruikt voor de openbare statistieken. |
GPUCount | header | integer | Nee | Aantal kaarten van de worker. Standaard 1. |
IsForceContinue | header | boolean | Nee | Zet 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
| Status | Body | Wanneer |
|---|---|---|
400 | {"isSuccess": false} | Elke weigering: verkeerd bewijs, onbekende range, een range die al gemarkeerd is, geblokkeerd account, inactieve puzzle. |
400 | validation problem | Een 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | De puzzle van de range. |
Hex | header | string | Ja | De range die de worker nu scant. |
UserToken | header | string (128 tekens) | Ja | Je minertoken. |
WorkerName | header | string | Ja | De 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
| Status | Body | Wanneer |
|---|---|---|
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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | De puzzle waartoe de sleutel behoort. |
UserToken | header | string (128 tekens) | Ja | Je minertoken. |
Content-Type | header | string | Ja | application/json. |
name | body | string | Nee | Een label, bijvoorbeeld de workernaam. Opgeslagen als Puzzle71 - rig1. |
encryptedKey | body | string | Ja | De 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
| Status | Body | Wanneer |
|---|---|---|
401 | {"error": "invalid_user_token"} | Onbekende of geblokkeerde token. |
400 | problem details | Er 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
| Status | Body | Wanneer |
|---|---|---|
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
| Status | Body | Wanneer |
|---|---|---|
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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Het 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
| Status | Body | Wanneer |
|---|---|---|
204 | leeg | Die 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Een 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
| Status | Body | Wanneer |
|---|---|---|
400 | problem details | De 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Het 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Het 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Een 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
| Status | Body | Wanneer |
|---|---|---|
400 | problem details | De 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Een 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
| Status | Body | Wanneer |
|---|---|---|
400 | problem details | De puzzle is niet actief. |
GET/puzzle/{puzzleCode}/entrancefee
De deelnamekosten van een puzzle in USD, als die aan staan. 300 seconden gecachet.
Parameters
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Een actieve puzzle met deelnamekosten. |
Voorbeeldrequest
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Voorbeeldresponse
200 OK
{
"fee": 25.0,
"puzzle": 71
}Fouten
| Status | Body | Wanneer |
|---|---|---|
400 | problem details | De 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
| Naam | In | Type | Verplicht | Beschrijving |
|---|---|---|---|---|
puzzleCode | path | integer | Ja | Een 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
| Status | Body | Wanneer |
|---|---|---|
400 | problem details | De 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
| Veld | Type | Beschrijving |
|---|---|---|
brand | string | nvidia of amd. |
name | string | De kaart. |
keysPerSecond | number | Gemeten snelheid. |
dateUpdated | date | Laatste 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
| Veld | Type | Beschrijving |
|---|---|---|
id | integer | Nummer van de uitkering. |
dateProcces | date | Wanneer die is uitgevoerd. De naam is verkeerd gespeld en bevroren. |
totalUsers | integer | Gebruikers die tokens hebben ontvangen. |
totalAmount | number | Uitgekeerde BCPZ (1 per gescande range). |
description | string | Resultaattekst. |
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
| Veld | Type | Beschrijving |
|---|---|---|
walletAddress | string | Ingekort adres. |
balance | number | BCPZ die nu op het account staat. |
total | number | In totaal verdiende BCPZ. |
minted | number | BCPZ 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
| Veld | Type | Beschrijving |
|---|---|---|
walletAddress | string | Ingekort adres van het account. |
minted | number | Verstuurde BCPZ. |
date | date | Wanneer het is verstuurd. |
txId | string | Transactiehash 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-URL | https://btcpuzzle.info/api/hex_socket |
| Oude host | https://api.btcpuzzle.info/hex_socket |
| Protocol | SignalR met het standaard-JSON-protocol; WebSockets, Server-Sent Events en Long Polling worden aangeboden. |
| Event | PoolStatus |
| Limiet | Het 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"
}| Veld | Type | Beschrijving |
|---|---|---|
hex | string | De range-HEX met het derde teken vervangen door X. |
walletAddress | string | Ingekort adres van het account. |
workerName | string of null | De workernaam (default als er geen werd gestuurd). Bij scanned is het de naam die met het markeringsverzoek werd gestuurd, en die kan null zijn. |
puzzleCode | integer | De puzzle van de range. |
status | string | holded 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.
| Veld | Type | Beschrijving |
|---|---|---|
id | integer | Database-ID (gelijk aan code voor puzzles uit het oude systeem). |
name | string | Bijvoorbeeld Puzzle 71. |
code | integer | Het puzzlenummer. |
hexStart, hexEnd | string | Eerste en laatste privésleutel van de puzzle, hexadecimaal. |
targetWalletAddress | string | Het adres met de beloning. |
hexRangeLength | integer | Lengte van de range-HEX die de pool uitgeeft (het deel van de sleutel dat hij kiest). |
reward | number | De beloning in BTC. |
hexStartPool, hexEndPool | string | Eerste en laatste range-HEX. Leeg tenzij de puzzle in de pool staat. |
totalRanges | integer | Aantal ranges van de puzzle. 0 tenzij de puzzle in de pool staat. |
percentage | number | Percentage van de ranges dat is gescand. |
totalScanned, rangesScannedLastHour | integer | Gescande ranges in totaal en in het afgelopen uur (gevuld in de lijst-endpoints). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | diverse | Eindcijfers van een voltooide puzzle; statisticsFoundBy is alleen aanwezig als die bekend is. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | Aantal privésleutels (min één) in één range. De twee verschillen wanneer ranges meerdere ID's beslaan. |
rangesPerKey | integer | Hoeveel range-ID's één range beslaat (1 voor de meeste puzzles). |
workloadStart, workloadEnd | string | Het deel van de privésleutel dat een client na de range-HEX scant: zie GET range. |
customWorkloadStart, customWorkloadEnd | string | Aanwezig als de puzzle een aangepaste workload gebruikt. |
dateStart, dateEnd | date | Geplande datums van de puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | De toestand van de puzzle: voltooid, aangekondigd, nu scanbaar, de standaard, de testpool, in de pool. |
isEntranceFeeActive, entranceFee | boolean, number | Of de deelnamekosten aan staan en de prijs ervan in USD (0 als ze uit staan). |
nextScanAllowedInMinutes | integer | Hoe lang een uitgegeven range wordt vastgehouden voordat hij aan iemand anders kan worden gegeven. |
challenges | array | De laatste challenge, of een lege array. |
privateKey, publicKey | string | Alleen voor opgeloste puzzles. |
rewards, speed | array, object | Alleen aanwezig bij sommige endpoints. |
Statistics-object
| Veld | Type | Beschrijving |
|---|---|---|
puzzle | object | De hoofdcijfers van de puzzle (naam, code, aantallen ranges, workload, toestand, beloning). |
scannedLast24H | integer | Gescande ranges in de laatste 24 uur. |
entranceFeesPaidTotal | number | Betaalde deelnamekosten voor de puzzle, USD. |
topWorkersAlltime | array | Maximaal 50 keer {userId, walletAddress, totalScanned}; userId is hier 0. |
topWorkersLast24h | array | Hetzelfde voor de laatste 24 uur. |
activeWorkers | array | {walletAddress, workerName} van de workers die in de laatste 30 minuten hebben gepingd. |
challenges | array | Maximaal 32 challenges. |
kingdom | object | De koning van de puzzle: walletAddress, message, image en isPublished. |
topSpeed | object | Het beste uur ooit: date, scanned ranges en keysPerSecond. |
chartData | array | De laatste maand per uur, nieuwste eerst: date, dateOnly, hoursOnly en rangesScanned. |
lastRanges | array | De laatste 200 gescande ranges, nieuwste eerst: hex (gemaskeerd), walletAddress (gemaskeerd), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds en totalSeconds. |
rewards | array | Beloningen van de puzzle (zonder privésleutels). |
dateUpdated | date | Wanneer de cijfers zijn berekend. |
currentSpeed | object | CurrentSpeed. |
CurrentSpeed-object
| Veld | Type | Beschrijving |
|---|---|---|
activeWorkerCount | integer | Workers die in de laatste 6 uur hebben gescand en in het afgelopen uur hebben gepingd. |
keysPerSecondFormatted | string | De snelheid met een eenheid: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s enzovoort. |
keysPerSecondRaw | string | De snelheid in sleutels per seconde als integer-tekst. |
Challenge-object
| Veld | Type | Beschrijving |
|---|---|---|
hex | string | De begintekens die elke deelnemer aan de challenge scant. |
dateCreated | date | Wanneer de challenge begon. |
puzzleId | integer | De puzzle. |
Reward-object
| Veld | Type | Beschrijving |
|---|---|---|
id, puzzleCode, puzzleId | integer | Identificatie. |
targetAddress | string | Het adres van de beloningssleutel. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | Wat de prijs is en wie die geeft. Properties zonder waarde worden weggelaten. |
privateKey | string | Alleen aanwezig nadat de beloning is opgelost. |
dateCreated, dateSolved | date | Wanneer 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
UserTokenvan 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 is38. - De basis-URL is
https://btcpuzzle.info/api; de oude hostapi.btcpuzzle.infoblijft 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.