Documentație API

Construiește-ți propriul client pentru pool. Fiecare endpoint, cu cereri, răspunsuri și erori.

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/api

Clienț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.info

De 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 și userToken sunt același header). Doar POST /puzzle/{puzzleCode}/save-private-key are 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 cu X (3AB8443 devine 3AX8443).

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ă laNumărat perLimită
GET /puzzle/{puzzleCode}/rangeUserToken120 de cereri la 60 de secunde
PUT /puzzle/{puzzleCode}/rangeUserToken360 de cereri la 60 de secunde
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 de cereri la 60 de secunde
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 cereri la 180 de secunde
Orice alt endpointAdresă IP20 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.

StatusCorpSemnificaț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).
400problemă de validareUn 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.
400problem detailsUn 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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntreg (de la 1 la 160)DaPuzzle-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.
UserTokenheaderșir (128 de caractere)DaTokenul tău de miner.
WorkerNameheaderșir (de la 1 la 16 caractere)NuNumele acestui worker. Doar litere și cifre. Se salvează ca default dacă nu trimiți niciunul.
SecurityHashheaderșirNuText liber păstrat împreună cu intervalul. Opțional.
CustomRangeheaderșirNuRestrâ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âmpTipDescriere
hexșirIntervalul de scanat, cu majuscule și fără completare. Este începutul cheilor private din interval.
puzzleCodeîntregPuzzle-ul căruia îi aparține intervalul (puzzle-ul implicit dacă cel cerut de tine este finalizat).
workloadStartșirSe adaugă după hex pentru a obține prima cheie privată a intervalului.
workloadEndșirSe 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șirAdresa puzzle-ului pe care o cauți. Scanează-o împreună cu adresele de dovadă.
proofOfWorkAddressestablou de 6 șiruriAdresele 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

StatusCorpCâ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).
400validation problemHeader 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:

  1. Scrie fiecare cheie privată ca 64 de caractere hexazecimale majuscule, completate la stânga cu zerouri.
  2. Concatenează cele șase șiruri, în ordinea adreselor, fără nimic între ele.
  3. Calculează SHA-256 al textului UTF-8 și scrie-l ca 64 de caractere hexazecimale minuscule. Acesta este HashedProofKey din cererea de marcare.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

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

Dovada 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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntreg (de la 1 la 160)DaPuzzle-ul intervalului.
UserTokenheaderșir (128 de caractere)DaTokenul tău de miner.
HEXheaderșirDaValoarea hex a intervalului scanat, exact cum a întors-o pool-ul. Exemplu: 3AB8443.
HashedProofKeyheaderșirDaDovada muncii: vezi Dovada muncii.
WorkerNameheaderșir (de la 1 la 16 caractere)NuWorkerul care a scanat intervalul.
GPUNameheaderșirNuModelul plăcii video. Folosit pentru statisticile publice.
GPUCountheaderîntregNuNumărul de plăci ale workerului. Implicit 1.
IsForceContinueheaderbooleanNuSetează-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

StatusCorpCând
400{"isSuccess": false}Orice refuz: dovadă greșită, interval necunoscut, interval deja marcat, cont blocat, puzzle inactiv.
400validation problemUn 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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaPuzzle-ul intervalului.
HexheaderșirDaIntervalul pe care workerul îl scanează acum.
UserTokenheaderșir (128 de caractere)DaTokenul tău de miner.
WorkerNameheaderșirDaNumele 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

StatusCorpCâ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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaPuzzle-ul căruia îi aparține cheia.
UserTokenheaderșir (128 de caractere)DaTokenul tău de miner.
Content-TypeheaderșirDaapplication/json.
namecorpșirNuO etichetă, de exemplu numele workerului. Se salvează ca Puzzle71 - rig1.
encryptedKeycorpșirDaCheia 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

StatusCorpCând
401{"error": "invalid_user_token"}Token necunoscut sau blocat.
400problem detailsNu 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

StatusCorpCâ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

StatusCorpCâ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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaNumă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

StatusCorpCând
204golNu 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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaUn 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

StatusCorpCând
400problem detailsPuzzle-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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaNumă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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaNumă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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaUn 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

StatusCorpCând
400problem detailsPuzzle-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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaUn 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

StatusCorpCând
400problem detailsPuzzle-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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaUn 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

StatusCorpCând
400problem detailsPuzzle-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

NumeLocTipObligatoriuDescriere
puzzleCodecaleîntregDaUn 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

StatusCorpCând
400problem detailsPuzzle-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âmpTipDescriere
brandșirnvidia sau amd.
nameșirPlaca video.
keysPerSecondnumărViteza măsurată.
dateUpdateddată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âmpTipDescriere
idîntregNumărul distribuției.
dateProccesdatăCând a rulat. Numele este scris greșit și înghețat.
totalUsersîntregUtilizatorii care au primit tokenuri.
totalAmountnumărBCPZ distribuit (1 pentru fiecare interval scanat).
descriptionșirTextul 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âmpTipDescriere
walletAddressșirAdresa scurtată.
balancenumărBCPZ aflat acum în cont.
totalnumărBCPZ câștigat în total.
mintednumărBCPZ 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âmpTipDescriere
walletAddressșirAdresa scurtată a contului.
mintednumărBCPZ trimis.
datedatăCând a fost trimis.
txIdșirHash-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 hubhttps://btcpuzzle.info/api/hex_socket
Host vechihttps://api.btcpuzzle.info/hex_socket
ProtocolSignalR cu protocolul JSON implicit; sunt oferite WebSockets, Server-Sent Events și Long Polling.
EvenimentPoolStatus
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âmpTipDescriere
hexșirHEX-ul intervalului, cu al treilea caracter înlocuit cu X.
walletAddressșirAdresa scurtată a contului.
workerNameșir sau nullNumele workerului (default dacă nu s-a trimis niciunul). La scanned este numele trimis cu cererea de marcare, care poate fi null.
puzzleCodeîntregPuzzle-ul intervalului.
statusșirholded 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âmpTipDescriere
idîntregId-ul din baza de date (același cu code pentru puzzle-urile din sistemul vechi).
nameșirDe exemplu Puzzle 71.
codeîntregNumărul puzzle-ului.
hexStart, hexEndșirPrima și ultima cheie privată a puzzle-ului, în hexazecimal.
targetWalletAddressșirAdresa care deține recompensa.
hexRangeLengthîntregLungimea HEX-ului de interval pe care îl distribuie pool-ul (partea din cheie pe care o alege el).
rewardnumărRecompensa în BTC.
hexStartPool, hexEndPoolșirPrimul și ultimul HEX de interval. Goale dacă puzzle-ul nu este în pool.
totalRangesîntregNumărul de intervale ale puzzle-ului. 0 dacă puzzle-ul nu este în pool.
percentagenumărProcentul de intervale scanate.
totalScanned, rangesScannedLastHourîntregIntervale scanate în total și în ultima oră (completate în endpointurile de listă).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBydiverseCifrele finale ale unui puzzle finalizat; statisticsFoundBy apare doar când este cunoscut.
rangeContainsKeys, rangeContainsKeyByDefaultîntregNumărul de chei private (minus unu) dintr-un interval. Cele două diferă când intervalele acoperă mai multe id-uri.
rangesPerKeyîntregCâte id-uri de interval acoperă un interval (1 pentru majoritatea puzzle-urilor).
workloadStart, workloadEndșirPartea din cheia privată pe care un client o scanează după HEX-ul intervalului: vezi GET range.
customWorkloadStart, customWorkloadEndșirPrezente când puzzle-ul folosește un workload personalizat.
dateStart, dateEnddatăDatele planificate ale puzzle-ului.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanStarea puzzle-ului: finalizat, anunțat, scanabil acum, cel implicit, pool-ul de test, în pool.
isEntranceFeeActive, entranceFeeboolean, numărDacă taxa de intrare este activă și prețul ei în USD (0 când este dezactivată).
nextScanAllowedInMinutesîntregCât timp este blocat un interval distribuit înainte de a putea fi dat altcuiva.
challengestablouCea mai recentă provocare sau un tablou gol.
privateKey, publicKeyșirDoar pentru puzzle-urile rezolvate.
rewards, speedtablou, obiectPrezente doar la unele endpointuri.

Obiectul Statistics

CâmpTipDescriere
puzzleobiectCifrele principale ale puzzle-ului (nume, cod, numărul de intervale, workload, stare, recompensă).
scannedLast24HîntregIntervale scanate în ultimele 24 de ore.
entranceFeesPaidTotalnumărTaxele de intrare plătite pentru puzzle, în USD.
topWorkersAlltimetablouPână la 50 de elemente {userId, walletAddress, totalScanned}; userId este 0 aici.
topWorkersLast24htablouLa fel, pentru ultimele 24 de ore.
activeWorkerstablou{walletAddress, workerName} ale workerilor care au trimis ping în ultimele 30 de minute.
challengestablouPână la 32 de provocări.
kingdomobiectRegele puzzle-ului: walletAddress, message, image și isPublished.
topSpeedobiectCea mai bună oră din toate timpurile: date, intervalele scanned și keysPerSecond.
chartDatatablouUltima lună, pe ore, cele mai noi primele: date, dateOnly, hoursOnly și rangesScanned.
lastRangestablouUltimele 200 de intervale scanate, cele mai noi primele: hex (mascat), walletAddress (mascat), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds și totalSeconds.
rewardstablouRecompensele puzzle-ului (fără chei private).
dateUpdateddatăCând au fost calculate cifrele.
currentSpeedobiectCurrentSpeed.

Obiectul CurrentSpeed

CâmpTipDescriere
activeWorkerCountîntregWorkerii care au scanat în ultimele 6 ore și au trimis ping în ultima oră.
keysPerSecondFormattedșirViteza cu unitate de măsură: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s și așa mai departe.
keysPerSecondRawșirViteza în chei pe secundă, ca text cu un număr întreg.

Obiectul Challenge

CâmpTipDescriere
hexșirCaracterele de început pe care le scanează fiecare participant la provocare.
dateCreateddatăCând a început provocarea.
puzzleIdîntregPuzzle-ul.

Obiectul Reward

CâmpTipDescriere
id, puzzleCode, puzzleIdîntregIdentificare.
targetAddressșirAdresa cheii recompensei.
rewardContent, rewardDescription, provider, providerDesc, brandșirCe este premiul și cine îl oferă. Proprietățile fără valoare sunt omise.
privateKeyșirPrezentă doar după ce recompensa a fost rezolvată.
dateCreated, dateSolveddată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 UserToken din 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 este 38.
  • URL-ul de bază este https://btcpuzzle.info/api; hostul vechi api.btcpuzzle.info funcț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ă CustomRange foarte î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.

Cumpără-mi o cafea

Puzzle-urile pool-ului

Ce scanează pool-ul acum, ce urmează și puzzle-urile la care a lucrat deja.

Se scanează acum1

Următorul2

Scanate anterior4

Toate cele 160 puzzle-uri