Prezentare generală
API-ul btcpuzzle.info este cel cu care comunică clientul pool-ului. Distribuie intervale de chei de scanat, primește rezultatul unei scanări și publică statisticile publice ale pool-ului. btcpuzzle.info este open source și oricine poate scrie un client: acest ghid descrie fiecare endpoint public, datele pe care le trimiți, datele pe care le primești înapoi și erorile pe care le poți întâlni. Întrebări: support@btcpuzzle.info.
Acest API este înghețat intenționat: minerii și instrumentele terțe depind de el. Căile, headerele, numele câmpurilor (inclusiv câteva grafii vechi precum dateProcces și holded) și codurile de eroare nu se schimbă. În răspunsuri pot apărea câmpuri noi, așa că ignoră câmpurile pe care nu le cunoști.
URL de bază
Fiecare cale din acest ghid este relativă la URL-ul de bază:
https://btcpuzzle.info/apiClienții scriși înainte de mutarea site-ului pot folosi în continuare hostul vechi, cu aceleași căi și fără prefixul /api:
https://api.btcpuzzle.infoDe exemplu, GET https://btcpuzzle.info/api/puzzle/codes și GET https://api.btcpuzzle.info/puzzle/codes răspund la fel. Clienții noi ar trebui să folosească URL-ul de bază cu /api.
Start rapid
Creează un cont gratuit pe btcpuzzle.info, copiază tokenul de miner din panoul tău, apoi cere un interval:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Scanează intervalul primit împreună cu cele șase adrese de dovadă, trimite dovada cu PUT /puzzle/71/range și repetă. Între cele două apeluri trimite din când în când un ping, ca pool-ul să știe că workerul este activ.
Convenții
Versionare
Există o singură versiune și nicio versiune în URL. Contractul API-ului vechi este păstrat întocmai; vezi Modificări față de documentația veche.
Autentificare
Endpointurile pentru mineri sunt identificate prin headerul UserToken: tokenul de miner de 128 de caractere al contului tău. Nu există altă autentificare și nicio sesiune pentru ele. Poți crea oricând un token nou din contul tău; cel vechi nu mai funcționează imediat. Păstrează tokenul privat: oricine îl are scanează în numele tău.
Toate endpointurile de date (puzzle-uri, statistici, pool, token) sunt publice și nu au nevoie de token.
Cereri și răspunsuri
- Pentru endpointurile de mineri, datele cererii se trimit în headere HTTP, nu în query string sau în corp. Numele headerelor nu țin cont de majuscule (
UserToken,usertokenșiuserTokensunt același header). DoarPOST /puzzle/{puzzleCode}/save-private-keyare corp JSON (Content-Type: application/json). - Răspunsurile sunt JSON în UTF-8, cu nume de proprietăți în camelCase. Proprietățile fără valoare sunt omise; API-ul nu scrie niciodată un JSON
null. Nu te baza pe indentare. - Datele calendaristice sunt în format ISO 8601, în UTC (
2026-11-18T08:28:25.8176144Z). Sumele și cantitățile sunt numere JSON. - Numerele mari, precum
rangeContainsKeys, sunt întregi fără semn pe 64 de biți și pot fi mai mari decât 2^53: în limbajele care folosesc double, parsează-le ca întregi pe 64 de biți sau ca șiruri. - Adresele de portofel din datele publice sunt scurtate (primele 8 caractere,
..., ultimele 8), iar al treilea caracter al HEX-ului unui interval este înlocuit cuX(3AB8443devine3AX8443).
Limite de rată
Limitele de mai jos sunt valorile implicite actuale. Sunt numărate într-o fereastră de timp fixă; operatorul le poate ajusta, așa că citește răspunsul 429 în loc să scrii numerele direct în cod.
| Se aplică la | Numărat per | Limită |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 de cereri la 60 de secunde |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 de cereri la 60 de secunde |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 de cereri la 60 de secunde |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 cereri la 180 de secunde |
| Orice alt endpoint | Adresă IP | 20 de cereri pe secundă pentru fiecare endpoint, 200 pe secundă în total |
O cerere peste limită primește răspunsul 429 Too Many Requests, un header Retry-After și acest corp:
{
"isSuccess": false,
"details": "Quota exceeded."
}Erori
Eșecurile folosesc codurile de status de mai jos. Corpul depinde de endpoint, așa că verifică mai întâi codul de status.
| Status | Corp | Semnificație |
|---|---|---|
400 | {"error": "<code>"} | Un endpoint pentru mineri a refuzat cererea. Codul spune de ce: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (grafia este istorică), invalid_request. |
400 | {"isSuccess": false} | Cererea de marcare a unui interval a fost refuzată (dovadă greșită, interval necunoscut sau deja scanat, utilizator blocat, puzzle inactiv). |
400 | problemă de validare | Un header obligatoriu lipsește sau este invalid, ori numărul puzzle-ului este în afara intervalului 1–160. Este un obiect application/problem+json al cărui errors listează numele greșite. |
400 | problem details | Un endpoint public de date nu are ce răspunde pentru acest puzzle (puzzle necunoscut sau inactiv). application/problem+json cu type, title, status și traceId. |
401 | {"error": "invalid_user_token"} | Tokenul de miner este necunoscut sau contul este blocat (ping și save-private-key). |
404 | {"error": "range_not_found"} | Intervalul pentru ping nu este blocat de acest worker. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Limită de rată. Așteaptă Retry-After secunde. |
Exemplu de problemă de validare (GET /puzzle/71/range fără headerul 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"
}Cache și CORS
Endpointurile publice de date trimit Cache-Control: public, max-age=N; valoarea este indicată la fiecare endpoint, iar o copie din cache este partajată de toți apelanții, așa că o interogare mai deasă de N secunde întoarce doar aceleași date. Endpointurile pentru mineri nu sunt puse niciodată în cache. Browserele pot apela API-ul de pe https://btcpuzzle.info, https://www.btcpuzzle.info și http://localhost:3000 (ultimul există pentru dezvoltarea locală a frontendului vechi); clienții nativi nu sunt afectați de CORS.
Endpointuri pentru mineri
Cele trei apeluri ale buclei de scanare: obții un interval, trimiți ping cât timp îl scanezi, îl marchezi ca scanat. Un al patrulea apel salvează o cheie găsită. Toate patru folosesc headerul UserToken.
GET/puzzle/{puzzleCode}/range
Îți dă un interval liber aleatoriu al puzzle-ului și îl blochează pentru tine. Nimeni altcineva nu primește un interval blocat de tine; dacă nu îl marchezi, revine în pool după un timp (un ping prelungește blocarea).
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg (de la 1 la 160) | Da | Puzzle-ul de scanat, de exemplu 71. 38 este pool-ul de test. GET /puzzle/codes listează codurile. Pentru un puzzle finalizat se servește în tăcere puzzle-ul implicit, iar răspunsul îți spune în puzzleCode ce puzzle ai primit. |
UserToken | header | șir (128 de caractere) | Da | Tokenul tău de miner. |
WorkerName | header | șir (de la 1 la 16 caractere) | Nu | Numele acestui worker. Doar litere și cifre. Se salvează ca default dacă nu trimiți niciunul. |
SecurityHash | header | șir | Nu | Text liber păstrat împreună cu intervalul. Opțional. |
CustomRange | header | șir | Nu | Restrânge intervalul pe care îl primești: un prefix al HEX-ului (2D, 3BA) sau start:end (3400000:38FFFFF). none sau lipsa headerului înseamnă orice interval. O fereastră foarte îngustă este lărgită de pool, așa că poți primi alt interval decât cel indicat. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemplu de răspuns
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}Câmpurile răspunsului
| Câmp | Tip | Descriere |
|---|---|---|
hex | șir | Intervalul de scanat, cu majuscule și fără completare. Este începutul cheilor private din interval. |
puzzleCode | întreg | Puzzle-ul căruia îi aparține intervalul (puzzle-ul implicit dacă cel cerut de tine este finalizat). |
workloadStart | șir | Se adaugă după hex pentru a obține prima cheie privată a intervalului. |
workloadEnd | șir | Se adaugă după hex pentru a obține ultima cheie privată a intervalului. Poate fi mai lung decât workloadStart la puzzle-urile ale căror intervale acoperă mai multe id-uri. |
targetAddress | șir | Adresa puzzle-ului pe care o cauți. Scanează-o împreună cu adresele de dovadă. |
proofOfWorkAddresses | tablou de 6 șiruri | Adresele a șase chei private plasate de pool în interiorul intervalului. Găsește-le cheile private pentru a dovedi scanarea: vezi Dovada muncii. |
În exemplul de mai sus, intervalul merge de la 3AB8443 + 00000000000 = 3AB844300000000000 până la 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Cheile private au 64 de caractere hexazecimale; completează la stânga cu zerouri.
Erori
| Status | Corp | Când |
|---|---|---|
400 | {"error": "invalid_puzzle"} | Puzzle-ul nu există sau nu este activ. |
400 | {"error": "invalid_user_token"} | Tokenul este necunoscut sau blocat. |
400 | {"error": "too_much_request"} | Ai prea multe intervale blocate pe care nu le-ai scanat sau ceri mai repede decât termini. Scanează ce ai blocat; intervalele blocate revin în pool după scurt timp. |
400 | {"error": "not_eligable"} | Puzzle-ul are taxă de intrare și încă nu îndeplinești condițiile ei. |
400 | {"error": "reached_of_keyspace"} | Nu a mai rămas niciun interval liber (sau niciunul care să se potrivească cu CustomRange). |
400 | validation problem | Header lipsă sau malformat, ori un număr de puzzle în afara intervalului 1–160. |
429 | {"isSuccess": false, ...} | Limită de rată: 120 pe minut pentru fiecare token. |
Dovada muncii
Pool-ul vrea să fie sigur că ai scanat cu adevărat intervalul. La fiecare interval alege șase chei private din interiorul lui și îți întoarce doar adresele lor (proofOfWorkAddresses). În timp ce scanezi intervalul după adresa țintă, caută și aceste șase adrese. Când ai găsit toate cele șase chei private:
- Scrie fiecare cheie privată ca 64 de caractere hexazecimale majuscule, completate la stânga cu zerouri.
- Concatenează cele șase șiruri, în ordinea adreselor, fără nimic între ele.
- Calculează SHA-256 al textului UTF-8 și scrie-l ca 64 de caractere hexazecimale minuscule. Acesta este
HashedProofKeydin cererea de marcare.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87Dovada este diferită pentru fiecare interval. Numărul de adrese de dovadă este astăzi șase; citește lungimea lui proofOfWorkAddresses în loc să presupui această valoare.
PUT/puzzle/{puzzleCode}/range
Marchează un interval ca scanat. Pool-ul verifică dovada și, dacă este corectă, îți contabilizează intervalul ca terminat. Un interval poate fi marcat o singură dată.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg (de la 1 la 160) | Da | Puzzle-ul intervalului. |
UserToken | header | șir (128 de caractere) | Da | Tokenul tău de miner. |
HEX | header | șir | Da | Valoarea hex a intervalului scanat, exact cum a întors-o pool-ul. Exemplu: 3AB8443. |
HashedProofKey | header | șir | Da | Dovada muncii: vezi Dovada muncii. |
WorkerName | header | șir (de la 1 la 16 caractere) | Nu | Workerul care a scanat intervalul. |
GPUName | header | șir | Nu | Modelul plăcii video. Folosit pentru statisticile publice. |
GPUCount | header | întreg | Nu | Numărul de plăci ale workerului. Implicit 1. |
IsForceContinue | header | boolean | Nu | Setează-l când workerul a continuat deși ajunsese la capătul spațiului său de chei. Implicit false. |
Exemplu de cerere
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"Exemplu de răspuns
200 OK
{
"isSuccess": true
}Erori
| Status | Corp | Când |
|---|---|---|
400 | {"isSuccess": false} | Orice refuz: dovadă greșită, interval necunoscut, interval deja marcat, cont blocat, puzzle inactiv. |
400 | validation problem | Un header obligatoriu lipsește sau este malformat. |
429 | {"isSuccess": false, ...} | Limită de rată: 360 pe minut pentru fiecare token. |
PATCH/puzzle/{puzzleCode}/range/ping
Îi spune pool-ului că un worker încă își scanează intervalul. Un ping menține blocarea intervalului și arată workerul ca activ pe site. Trimite unul aproximativ la fiecare 2 minute; intervalul de timp nu trebuie să depășească 30 de minute, altfel pool-ul îți ia intervalul înapoi.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Puzzle-ul intervalului. |
Hex | header | șir | Da | Intervalul pe care workerul îl scanează acum. |
UserToken | header | șir (128 de caractere) | Da | Tokenul tău de miner. |
WorkerName | header | șir | Da | Numele workerului folosit la cererea intervalului (default dacă nu s-a trimis niciunul). |
Exemplu de cerere
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemplu de răspuns
200 OK cu corp gol.
Erori
| Status | Corp | Când |
|---|---|---|
400 | {"error": "invalid_request"} | Un header este gol. |
401 | {"error": "invalid_user_token"} | Token necunoscut sau blocat. |
404 | {"error": "range_not_found"} | Acest worker nu are blocat un interval nescanat cu acel HEX pe acel puzzle. |
429 | {"isSuccess": false, ...} | Limită de rată: 360 pe minut pentru fiecare token. |
POST/puzzle/{puzzleCode}/save-private-key
Salvează în contul tău o cheie privată găsită, criptată. Clientul criptează cheia cu cheia publică RSA pe care i-ai dat-o; site-ul păstrează doar textul criptat, pe care îl decriptezi cu cheia ta privată. Cheia apare pe pagina de chei găsite din panoul tău.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Puzzle-ul căruia îi aparține cheia. |
UserToken | header | șir (128 de caractere) | Da | Tokenul tău de miner. |
Content-Type | header | șir | Da | application/json. |
name | corp | șir | Nu | O etichetă, de exemplu numele workerului. Se salvează ca Puzzle71 - rig1. |
encryptedKey | corp | șir | Da | Cheia privată criptată (clientul o trimite în base64). |
Exemplu de cerere
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>"}'Exemplu de răspuns
200 OK Atenție: proprietatea este success, nu isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Erori
| Status | Corp | Când |
|---|---|---|
401 | {"error": "invalid_user_token"} | Token necunoscut sau blocat. |
400 | problem details | Nu s-a salvat nimic: aceeași cheie este deja salvată pentru acest cont sau corpul lipsește. |
429 | {"isSuccess": false, ...} | Limită de rată: 10 la 180 de secunde pentru fiecare token. |
Date despre puzzle-uri
Endpointuri publice de citire despre puzzle-urile pool-ului. Nu este nevoie de token. Obiectul Puzzle și celelalte obiecte sunt descrise la finalul acestui ghid.
GET/puzzle
Puzzle-urile care sunt în pool: cele active, cele următoare și pool-ul de test (plus cele finalizate, păstrate pentru istoric). Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle"Exemplu de răspuns
200 OK Un tablou de obiecte Puzzle, scurtat aici la unul singur.
[
{
"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": []
}
]Erori
| Status | Corp | Când |
|---|---|---|
404 | [] | Pool-ul nu are niciun puzzle. |
GET/puzzle/all
Toate puzzle-urile din baza de date, inclusiv cele finalizate. Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/all"Răspunde cu 200 și un tablou de obiecte Puzzle.
GET/puzzle/available
Puzzle-urile care pot fi scanate în pool. Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/available"Răspunde cu 200 și un tablou de obiecte Puzzle.
GET/puzzle/default
Puzzle-ul implicit: cel la care revine o cerere pentru un puzzle finalizat. Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/default"Exemplu de răspuns
200 OK Un singur obiect Puzzle.
{
"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": []
}Erori
| Status | Corp | Când |
|---|---|---|
404 | {"error": "puzzle_not_found"} | Nu este setat niciun puzzle implicit. |
GET/puzzle/codes
Numerele puzzle-urilor active sau următoare, întâi puzzle-urile normale și la final pool-ul de test. Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/codes"Exemplu de răspuns
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
Un singur puzzle, citit din baza de date. Păstrat în cache 10 secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Numărul puzzle-ului. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/info"Exemplu de răspuns
200 OK Un obiect Puzzle. Valorile calculate la rulare, precum rangesScannedLastHour, sunt completate doar în endpointurile de listă.
{
"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": []
}Erori
| Status | Corp | Când |
|---|---|---|
204 | gol | Nu există un astfel de puzzle. |
GET/puzzle/{puzzleCode}/statistics
Tot ce afișează pagina puzzle-ului: totaluri, clasamente, workeri activi, ultimele 200 de intervale scanate și un grafic pe ore. Păstrat în cache 60 de secunde (iar serverul păstrează o copie timp de 5 minute).
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Un puzzle activ (sau pool-ul de test). |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Exemplu de răspuns
200 OK Scurtat: tablourile au aici câte un element, iar lastRanges are până la 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"
}
}Pentru un puzzle care nu este încă activ (cele următoare) se întorc doar puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges și dateUpdated. Vezi Obiectul Statistics pentru câmpuri.
Erori
| Status | Corp | Când |
|---|---|---|
400 | problem details | Puzzle-ul nu există sau nu este nici activ, nici următor. |
GET/puzzle/{puzzleCode}/speed
Viteza actuală a pool-ului pe un puzzle. Păstrat în cache 60 de secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Numărul puzzle-ului. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/speed"Exemplu de răspuns
200 OK Vezi CurrentSpeed. Un puzzle necunoscut răspunde cu valori zero, niciodată cu o eroare.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
Workerii care scanează acum: cei cu un interval pentru care au trimis ping în ultimele 30 de minute. Nu este pus în cache de browser; serverul păstrează răspunsul 60 de secunde. puzzleCode 0 înseamnă puzzle-ul implicit.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Numărul puzzle-ului. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/workers"Exemplu de răspuns
200 OK Un tablou gol când nu scanează nimeni sau puzzle-ul este necunoscut.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
Aceeași listă ca /workers (păstrată ca o cale separată pentru că clienții le folosesc pe amândouă).
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"Aceiași parametri și același răspuns ca GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
Recompensele de pool ale unui puzzle activ: premii suplimentare puse de sponsori pe chei private din interiorul intervalelor (cele mai noi primele, până la 32). Cheia privată a unei recompense este afișată doar după ce a fost rezolvată. Păstrat în cache 600 de secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Un puzzle activ. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Exemplu de răspuns
200 OK Vezi Reward. Un tablou gol când puzzle-ul nu are niciuna.
[
{
"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
}
]Erori
| Status | Corp | Când |
|---|---|---|
400 | problem details | Puzzle-ul nu este activ. |
GET/puzzle/{puzzleCode}/challenge
Cele mai recente puncte de pornire ale provocărilor unui puzzle activ (cele mai noi primele, până la 32). Păstrat în cache 600 de secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Un puzzle activ. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Exemplu de răspuns
200 OK Vezi Challenge. Un tablou gol când nu există niciuna.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Erori
| Status | Corp | Când |
|---|---|---|
400 | problem details | Puzzle-ul nu este activ. |
GET/puzzle/{puzzleCode}/entrancefee
Taxa de intrare a unui puzzle în USD, când taxa este activă. Păstrat în cache 300 de secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Un puzzle activ cu taxă de intrare. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Exemplu de răspuns
200 OK
{
"fee": 25.0,
"puzzle": 71
}Erori
| Status | Corp | Când |
|---|---|---|
400 | problem details | Puzzle-ul nu este activ sau nu are taxă de intrare. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
Cât din puzzle este scanat pentru fiecare prefix de două caractere al HEX-ului intervalului (harta termică de pe pagina puzzle-ului). Păstrat în cache 3.600 de secunde.
Parametri
| Nume | Loc | Tip | Obligatoriu | Descriere |
|---|---|---|---|---|
puzzleCode | cale | întreg | Da | Un puzzle activ. |
Exemplu de cerere
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Exemplu de răspuns
200 OK Un element pentru fiecare prefix, ordonat după hexStarts. Proprietatea pertantageShow este scrisă greșit intenționat (înghețată). De la 70% în sus, numerele se opresc la 70%, iar isLimitExceeded este true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Erori
| Status | Corp | Când |
|---|---|---|
400 | problem details | Puzzle-ul nu este activ. |
Date despre pool
Endpointuri publice de citire despre pool în ansamblu, lista de GPU-uri și tokenul BCPZ.
GET/pool/homepage
Lista de puzzle-uri de pe pagina principală: același tablou ca GET /puzzle, iar puzzle-ul implicit are și speed. Păstrat în cache 60 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/homepage"Răspunde cu 200 și un tablou de obiecte Puzzle.
GET/pool/gpus
Lista de benchmark a GPU-urilor, cele mai rapide primele (chei pe secundă în pool). Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/gpus"Exemplu de răspuns
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Câmpurile răspunsului
| Câmp | Tip | Descriere |
|---|---|---|
brand | șir | nvidia sau amd. |
name | șir | Placa video. |
keysPerSecond | număr | Viteza măsurată. |
dateUpdated | dată | Ultima actualizare. |
GET/pool/token-distribute-history
Distribuțiile zilnice de BCPZ, cele mai noi primele (până la 180). Păstrat în cache 300 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/token-distribute-history"Exemplu de răspuns
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]Câmpurile răspunsului
| Câmp | Tip | Descriere |
|---|---|---|
id | întreg | Numărul distribuției. |
dateProcces | dată | Când a rulat. Numele este scris greșit și înghețat. |
totalUsers | întreg | Utilizatorii care au primit tokenuri. |
totalAmount | număr | BCPZ distribuit (1 pentru fiecare interval scanat). |
description | șir | Textul rezultatului. |
GET/pool/token-top-50-holders
Cele 50 de conturi care au câștigat cei mai mulți BCPZ, cu adresele de portofel scurtate. Păstrat în cache 600 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Exemplu de răspuns
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Câmpurile răspunsului
| Câmp | Tip | Descriere |
|---|---|---|
walletAddress | șir | Adresa scurtată. |
balance | număr | BCPZ aflat acum în cont. |
total | număr | BCPZ câștigat în total. |
minted | număr | BCPZ deja retras în rețeaua Polygon. |
GET/pool/token-mint-history
Cele mai recente retrageri de BCPZ în rețeaua Polygon, cele mai noi primele (până la 180). Păstrat în cache 600 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/token-mint-history"Exemplu de răspuns
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]Câmpurile răspunsului
| Câmp | Tip | Descriere |
|---|---|---|
walletAddress | șir | Adresa scurtată a contului. |
minted | număr | BCPZ trimis. |
date | dată | Când a fost trimis. |
txId | șir | Hash-ul tranzacției Polygon. Omis cât timp transferul nu este finalizat. |
GET/pool/btc-price
Prețul Bitcoin în USD și EUR, de la un exchange. Păstrat în cache 600 de secunde.
Exemplu de cerere
curl "https://btcpuzzle.info/api/pool/btc-price"Exemplu de răspuns
200 OK Ambele valori sunt 0 când sursa de preț nu poate fi accesată.
{"usd":66739.06,"eur":60607.25}Flux în timp real (SignalR)
Pool-ul publică fiecare interval revendicat și terminat într-un hub SignalR. Site-ul îl folosește pentru pagina de status live. Hubul este public, nu are nevoie de token și doar trimite: nu există metode pe care un client să le poată apela.
| URL hub | https://btcpuzzle.info/api/hex_socket |
| Host vechi | https://api.btcpuzzle.info/hex_socket |
| Protocol | SignalR cu protocolul JSON implicit; sunt oferite WebSockets, Server-Sent Events și Long Polling. |
| Eveniment | PoolStatus |
| Limită | Cererea de negociere contează pentru limita de rată pe IP. Hubul în sine nu este limitat după conectare. |
Conectare
Folosește o bibliotecă client SignalR (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). În spate, aceasta negociază mai întâi:
Exemplu de cerere
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"Exemplu de răspuns
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();Evenimentul PoolStatus
Un singur argument, un obiect JSON. Evenimentul este trimis tuturor clienților conectați când un interval este distribuit și când un interval este marcat ca scanat.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Câmp | Tip | Descriere |
|---|---|---|
hex | șir | HEX-ul intervalului, cu al treilea caracter înlocuit cu X. |
walletAddress | șir | Adresa scurtată a contului. |
workerName | șir sau null | Numele workerului (default dacă nu s-a trimis niciunul). La scanned este numele trimis cu cererea de marcare, care poate fi null. |
puzzleCode | întreg | Puzzle-ul intervalului. |
status | șir | holded după ce un interval a fost distribuit, scanned după ce un interval a fost marcat. Grafia este înghețată. |
Evenimentele sunt livrate cât timp conexiunea este deschisă; nimic nu este retransmis după o reconectare. Când operatorul oprește fluxul live, conexiunile sunt refuzate.
Obiecte
Obiectul Puzzle
Întors de endpointurile de listă a puzzle-urilor și de /puzzle/{puzzleCode}/info. Proprietățile fără valoare sunt omise.
| Câmp | Tip | Descriere |
|---|---|---|
id | întreg | Id-ul din baza de date (același cu code pentru puzzle-urile din sistemul vechi). |
name | șir | De exemplu Puzzle 71. |
code | întreg | Numărul puzzle-ului. |
hexStart, hexEnd | șir | Prima și ultima cheie privată a puzzle-ului, în hexazecimal. |
targetWalletAddress | șir | Adresa care deține recompensa. |
hexRangeLength | întreg | Lungimea HEX-ului de interval pe care îl distribuie pool-ul (partea din cheie pe care o alege el). |
reward | număr | Recompensa în BTC. |
hexStartPool, hexEndPool | șir | Primul și ultimul HEX de interval. Goale dacă puzzle-ul nu este în pool. |
totalRanges | întreg | Numărul de intervale ale puzzle-ului. 0 dacă puzzle-ul nu este în pool. |
percentage | număr | Procentul de intervale scanate. |
totalScanned, rangesScannedLastHour | întreg | Intervale scanate în total și în ultima oră (completate în endpointurile de listă). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | diverse | Cifrele finale ale unui puzzle finalizat; statisticsFoundBy apare doar când este cunoscut. |
rangeContainsKeys, rangeContainsKeyByDefault | întreg | Numărul de chei private (minus unu) dintr-un interval. Cele două diferă când intervalele acoperă mai multe id-uri. |
rangesPerKey | întreg | Câte id-uri de interval acoperă un interval (1 pentru majoritatea puzzle-urilor). |
workloadStart, workloadEnd | șir | Partea din cheia privată pe care un client o scanează după HEX-ul intervalului: vezi GET range. |
customWorkloadStart, customWorkloadEnd | șir | Prezente când puzzle-ul folosește un workload personalizat. |
dateStart, dateEnd | dată | Datele planificate ale puzzle-ului. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | Starea puzzle-ului: finalizat, anunțat, scanabil acum, cel implicit, pool-ul de test, în pool. |
isEntranceFeeActive, entranceFee | boolean, număr | Dacă taxa de intrare este activă și prețul ei în USD (0 când este dezactivată). |
nextScanAllowedInMinutes | întreg | Cât timp este blocat un interval distribuit înainte de a putea fi dat altcuiva. |
challenges | tablou | Cea mai recentă provocare sau un tablou gol. |
privateKey, publicKey | șir | Doar pentru puzzle-urile rezolvate. |
rewards, speed | tablou, obiect | Prezente doar la unele endpointuri. |
Obiectul Statistics
| Câmp | Tip | Descriere |
|---|---|---|
puzzle | obiect | Cifrele principale ale puzzle-ului (nume, cod, numărul de intervale, workload, stare, recompensă). |
scannedLast24H | întreg | Intervale scanate în ultimele 24 de ore. |
entranceFeesPaidTotal | număr | Taxele de intrare plătite pentru puzzle, în USD. |
topWorkersAlltime | tablou | Până la 50 de elemente {userId, walletAddress, totalScanned}; userId este 0 aici. |
topWorkersLast24h | tablou | La fel, pentru ultimele 24 de ore. |
activeWorkers | tablou | {walletAddress, workerName} ale workerilor care au trimis ping în ultimele 30 de minute. |
challenges | tablou | Până la 32 de provocări. |
kingdom | obiect | Regele puzzle-ului: walletAddress, message, image și isPublished. |
topSpeed | obiect | Cea mai bună oră din toate timpurile: date, intervalele scanned și keysPerSecond. |
chartData | tablou | Ultima lună, pe ore, cele mai noi primele: date, dateOnly, hoursOnly și rangesScanned. |
lastRanges | tablou | Ultimele 200 de intervale scanate, cele mai noi primele: hex (mascat), walletAddress (mascat), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds și totalSeconds. |
rewards | tablou | Recompensele puzzle-ului (fără chei private). |
dateUpdated | dată | Când au fost calculate cifrele. |
currentSpeed | obiect | CurrentSpeed. |
Obiectul CurrentSpeed
| Câmp | Tip | Descriere |
|---|---|---|
activeWorkerCount | întreg | Workerii care au scanat în ultimele 6 ore și au trimis ping în ultima oră. |
keysPerSecondFormatted | șir | Viteza cu unitate de măsură: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s și așa mai departe. |
keysPerSecondRaw | șir | Viteza în chei pe secundă, ca text cu un număr întreg. |
Obiectul Challenge
| Câmp | Tip | Descriere |
|---|---|---|
hex | șir | Caracterele de început pe care le scanează fiecare participant la provocare. |
dateCreated | dată | Când a început provocarea. |
puzzleId | întreg | Puzzle-ul. |
Obiectul Reward
| Câmp | Tip | Descriere |
|---|---|---|
id, puzzleCode, puzzleId | întreg | Identificare. |
targetAddress | șir | Adresa cheii recompensei. |
rewardContent, rewardDescription, provider, providerDesc, brand | șir | Ce este premiul și cine îl oferă. Proprietățile fără valoare sunt omise. |
privateKey | șir | Prezentă doar după ce recompensa a fost rezolvată. |
dateCreated, dateSolved | dată | Când a fost creată și când a fost rezolvată (0001-01-01T00:00:00 cât timp nu este rezolvată). |
Modificări față de documentația veche
Nimic din contract nu s-a schimbat: fiecare endpoint, header, câmp și cod de eroare al API-ului vechi funcționează în continuare și răspunde la fel. Acest ghid înlocuiește pagina veche, care descria trei endpointuri. Ce este nou aici:
- Endpointurile publice de date, fluxul în timp real, codurile de eroare și limitele de rată sunt documentate. Pagina veche nu le menționa.
- Corecturi ale textului vechi: headerul
UserTokendin cererea de marcare este tokenul de miner (pagina veche îl numea adresă de portofel); intervalul de ping este de aproximativ 2 minute și cel mult 30 de minute, iar limita este de 360 de ping-uri pe minut pentru fiecare token, nu 60 pe oră; puzzle-ul pool-ului de test este38. - URL-ul de bază este
https://btcpuzzle.info/api; hostul vechiapi.btcpuzzle.infofuncționează în continuare. - Hubul SignalR nu mai are nicio metodă client-server, așa că nimeni nu poate trimite evenimente false. Evenimentul în sine nu s-a schimbat.
- Ultimul interval liber al unui puzzle este acum distribuit și el, iar o fereastră
CustomRangefoarte îngustă este lărgită, astfel încât un interval să nu poată fi ales cerându-l exact pe acela. - Statisticile publice nu mai afișează adresa IP a unui miner.