Documentazione API

Crea il tuo client per il pool. Tutti gli endpoint, con richieste, risposte ed errori.

Panoramica

L'API di btcpuzzle.info è ciò con cui comunica il client del pool. Assegna i range di chiavi da scansionare, riceve il risultato di una scansione e pubblica le statistiche pubbliche del pool. btcpuzzle.info è open source e chiunque può scrivere un client: questa guida descrive ogni endpoint pubblico, i dati da inviare, i dati che ricevi e gli errori che puoi incontrare. Domande: support@btcpuzzle.info.

Questa API è congelata di proposito: miner e strumenti di terze parti dipendono da essa. Percorsi, header, nomi dei campi (compresi alcuni vecchi errori di ortografia come dateProcces e holded) e codici di errore non cambiano. Alle risposte possono essere aggiunti nuovi campi, quindi ignora i campi che non conosci.

Base URL

Ogni percorso in questa guida è relativo al base URL:

https://btcpuzzle.info/api

I client scritti prima del trasferimento del sito possono continuare a usare il vecchio host, con gli stessi percorsi e senza il prefisso /api:

https://api.btcpuzzle.info

Ad esempio GET https://btcpuzzle.info/api/puzzle/codes e GET https://api.btcpuzzle.info/puzzle/codes rispondono allo stesso modo. I nuovi client dovrebbero usare il base URL con /api.

Avvio rapido

Crea un account gratuito su btcpuzzle.info, copia il tuo miner token dalla dashboard, poi richiedi un range:

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

Scansiona il range ricevuto insieme ai sei indirizzi di prova, invia la prova con PUT /puzzle/71/range e ripeti. Tra le due chiamate invia ogni tanto un ping, così il pool sa che il worker è attivo.

Convenzioni

Versioni

Esiste una sola versione e nessuna versione nell'URL. Il contratto della vecchia API è mantenuto esattamente; vedi Modifiche rispetto alla vecchia documentazione.

Autenticazione

Gli endpoint per i miner si identificano con l'header UserToken: il miner token di 128 caratteri del tuo account. Non c'è nessun altro login e nessuna sessione per questi endpoint. Puoi creare un nuovo token dal tuo account in qualsiasi momento; quello vecchio smette subito di funzionare. Mantieni il token privato: chi lo possiede scansiona a tuo nome.

Tutti gli endpoint di dati (puzzle, statistiche, pool, token) sono pubblici e non richiedono un token.

Richieste e risposte

  • Per gli endpoint dei miner, i dati della richiesta vanno negli header HTTP, non nella query string né nel body. I nomi degli header non distinguono maiuscole e minuscole (UserToken, usertoken e userToken sono lo stesso header). Solo POST /puzzle/{puzzleCode}/save-private-key ha un body JSON (Content-Type: application/json).
  • Le risposte sono JSON in UTF-8 con nomi delle proprietà in camelCase. Le proprietà senza valore vengono omesse; l'API non scrive mai un null JSON. Non fare affidamento sull'indentazione.
  • Le date sono in formato ISO 8601 in UTC (2026-11-18T08:28:25.8176144Z). Valori monetari e importi sono numeri JSON.
  • I numeri grandi come rangeContainsKeys sono interi senza segno a 64 bit e possono superare 2^53: nei linguaggi che usano i double, leggili come interi a 64 bit o come stringhe.
  • Gli indirizzi wallet nei dati pubblici sono abbreviati (primi 8 caratteri, ..., ultimi 8) e il terzo carattere dell'HEX di un range è sostituito da X (3AB8443 diventa 3AX8443).

Limiti di frequenza

I limiti qui sotto sono i valori predefiniti attuali. Sono conteggiati in una finestra temporale fissa; il gestore può modificarli, quindi leggi la risposta 429 invece di scrivere i numeri nel codice.

Si applica aConteggiato perLimite
GET /puzzle/{puzzleCode}/rangeUserToken120 richieste ogni 60 secondi
PUT /puzzle/{puzzleCode}/rangeUserToken360 richieste ogni 60 secondi
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 richieste ogni 60 secondi
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 richieste ogni 180 secondi
Tutti gli altri endpointIndirizzo IP20 richieste al secondo per ciascun endpoint, 200 al secondo in totale

Una richiesta oltre il limite riceve come risposta 429 Too Many Requests, un header Retry-After e questo body:

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

Errori

Gli errori usano i codici di stato qui sotto. Il body dipende dall'endpoint, quindi controlla prima il codice di stato.

StatoBodySignificato
400{"error": "<code>"}Un endpoint per i miner ha rifiutato la richiesta. Il codice spiega il motivo: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (l'ortografia è storica), invalid_request.
400{"isSuccess": false}La richiesta di marcatura di un range è stata rifiutata (prova errata, range sconosciuto o già scansionato, utente bannato, puzzle non attivo).
400problema di validazioneUn header obbligatorio manca o non è valido, oppure il numero del puzzle è fuori dall'intervallo da 1 a 160. È un oggetto application/problem+json il cui errors elenca i nomi errati.
400problem detailsUn endpoint di dati pubblici non ha nulla da rispondere per questo puzzle (puzzle sconosciuto o non attivo). application/problem+json con type, title, status e traceId.
401{"error": "invalid_user_token"}Il miner token è sconosciuto o l'account è bannato (ping e save-private-key).
404{"error": "range_not_found"}Il range da pingare non è assegnato a questo worker.
429{"isSuccess": false, "details": "Quota exceeded."}Limite di frequenza. Attendi Retry-After secondi.

Esempio di problema di validazione (GET /puzzle/71/range senza l'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"
}

Cache e CORS

Gli endpoint di dati pubblici inviano Cache-Control: public, max-age=N; il valore è indicato per ciascun endpoint, e una copia in cache è condivisa da tutti i chiamanti, quindi interrogare più spesso di N secondi restituisce solo gli stessi dati. Gli endpoint per i miner non vengono mai messi in cache. I browser possono chiamare l'API da https://btcpuzzle.info, https://www.btcpuzzle.info e http://localhost:3000 (l'ultimo esiste per lo sviluppo locale del vecchio frontend); i client nativi non sono soggetti a CORS.

Endpoint per i miner

Le tre chiamate del ciclo di scansione: ottieni un range, invia ping mentre lo scansioni, marcalo come scansionato. Una quarta chiamata salva una chiave trovata. Tutte e quattro usano l'header UserToken.

GET/puzzle/{puzzleCode}/range

Assegna un range libero casuale del puzzle e lo riserva per te. Un range riservato a te non viene dato a nessun altro; se non lo marchi, dopo un po' torna al pool (un ping prolunga la riserva).

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathinteger (da 1 a 160)SìIl puzzle da scansionare, ad esempio 71. 38 è il pool di test. GET /puzzle/codes elenca i codici. Per un puzzle completato viene servito senza avviso il puzzle predefinito, e la risposta indica in puzzleCode quale puzzle hai ricevuto.
UserTokenheaderstring (128 caratteri)SìIl tuo miner token.
WorkerNameheaderstring (da 1 a 16 caratteri)NoIl nome di questo worker. Solo lettere e cifre. Salvato come default se non ne invii uno.
SecurityHashheaderstringNoTesto libero conservato con il range. Facoltativo.
CustomRangeheaderstringNoLimita il range che ricevi: un prefisso dell'HEX (2D, 3BA) oppure start:end (3400000:38FFFFF). none o nessun header significa qualsiasi range. Una finestra molto stretta viene allargata dal pool, quindi potresti ricevere un range diverso da quello indicato.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Campi della risposta

CampoTipoDescrizione
hexstringIl range da scansionare, in maiuscolo e senza padding. È la parte iniziale delle chiavi private del range.
puzzleCodeintegerIl puzzle a cui appartiene il range (il puzzle predefinito se quello richiesto è completato).
workloadStartstringDa aggiungere dopo hex per ottenere la prima chiave privata del range.
workloadEndstringDa aggiungere dopo hex per ottenere l'ultima chiave privata del range. Può essere più lungo di workloadStart nei puzzle i cui range coprono più id.
targetAddressstringL'indirizzo del puzzle che stai cercando. Scansionalo insieme agli indirizzi di prova.
proofOfWorkAddressesarray di 6 stringheIndirizzi di sei chiavi private che il pool ha collocato all'interno del range. Trova le loro chiavi private per dimostrare la scansione: vedi Proof of work.

Con l'esempio qui sopra il range va da 3AB8443 + 00000000000 = 3AB844300000000000 a 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Le chiavi private sono di 64 caratteri esadecimali; completa a sinistra con degli zeri.

Errori

StatoBodyQuando
400{"error": "invalid_puzzle"}Il puzzle non esiste o non è attivo.
400{"error": "invalid_user_token"}Il token è sconosciuto o bannato.
400{"error": "too_much_request"}Hai troppi range riservati non ancora scansionati, oppure chiedi range più in fretta di quanto li completi. Scansiona quelli che hai; i range riservati tornano al pool dopo poco tempo.
400{"error": "not_eligable"}Il puzzle ha una quota di ingresso e non ne soddisfi ancora le condizioni.
400{"error": "reached_of_keyspace"}Non ci sono più range liberi (o nessuno che rientri nel tuo CustomRange).
400validation problemHeader mancante o malformato, oppure numero del puzzle fuori dall'intervallo da 1 a 160.
429{"isSuccess": false, ...}Limite di frequenza: 120 al minuto per token.

Proof of work

Il pool vuole essere sicuro che tu abbia davvero scansionato il range. Per ogni range sceglie sei chiavi private al suo interno e restituisce solo i loro indirizzi (proofOfWorkAddresses). Mentre scansioni il range alla ricerca dell'indirizzo obiettivo, cerca anche questi sei indirizzi. Quando hai trovato tutte e sei le chiavi private:

  1. Scrivi ogni chiave privata come 64 caratteri esadecimali maiuscoli, completati a sinistra con degli zeri.
  2. Concatena le sei stringhe, nell'ordine degli indirizzi, senza nulla in mezzo.
  3. Calcola lo SHA-256 del testo UTF-8 e scrivilo come 64 caratteri esadecimali minuscoli. Questo è l'HashedProofKey della richiesta di marcatura.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

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

La prova è diversa per ogni range. Oggi gli indirizzi di prova sono sei; leggi la lunghezza di proofOfWorkAddresses invece di darla per scontata.

PUT/puzzle/{puzzleCode}/range

Marca un range come scansionato. Il pool controlla la prova e, se è corretta, conta il range come completato da te. Un range può essere marcato una sola volta.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathinteger (da 1 a 160)SìIl puzzle del range.
UserTokenheaderstring (128 caratteri)SìIl tuo miner token.
HEXheaderstringSìL'hex del range che hai scansionato, così come lo ha restituito il pool. Esempio: 3AB8443.
HashedProofKeyheaderstringSìLa proof of work: vedi Proof of work.
WorkerNameheaderstring (da 1 a 16 caratteri)NoIl worker che ha scansionato il range.
GPUNameheaderstringNoIl modello della scheda video. Usato per le statistiche pubbliche.
GPUCountheaderintegerNoNumero di schede del worker. Predefinito 1.
IsForceContinueheaderbooleanNoImpostalo quando il worker ha continuato pur avendo raggiunto la fine del suo spazio delle chiavi. Predefinito false.

Esempio di richiesta

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"

Esempio di risposta

200 OK

{
  "isSuccess": true
}

Errori

StatoBodyQuando
400{"isSuccess": false}Qualsiasi rifiuto: prova errata, range sconosciuto, range già marcato, account bannato, puzzle non attivo.
400validation problemUn header obbligatorio manca o è malformato.
429{"isSuccess": false, ...}Limite di frequenza: 360 al minuto per token.

PATCH/puzzle/{puzzleCode}/range/ping

Comunica al pool che un worker sta ancora scansionando il suo range. Un ping mantiene la riserva sul range e mostra il worker come attivo sul sito. Inviane uno circa ogni 2 minuti; l'intervallo non deve superare i 30 minuti, altrimenti il pool si riprende il range.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìIl puzzle del range.
HexheaderstringSìIl range che il worker sta scansionando ora.
UserTokenheaderstring (128 caratteri)SìIl tuo miner token.
WorkerNameheaderstringSìIl nome del worker usato quando è stato richiesto il range (default se non ne è stato inviato uno).

Esempio di richiesta

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

Esempio di risposta

200 OK con body vuoto.

Errori

StatoBodyQuando
400{"error": "invalid_request"}Un header è vuoto.
401{"error": "invalid_user_token"}Token sconosciuto o bannato.
404{"error": "range_not_found"}Questo worker non ha un range non scansionato con quell'HEX su quel puzzle.
429{"isSuccess": false, ...}Limite di frequenza: 360 al minuto per token.

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

Salva sul tuo account una chiave privata trovata, in forma cifrata. Il client cifra la chiave con la chiave pubblica RSA che gli hai fornito; il sito conserva solo il testo cifrato, che decifri con la tua chiave privata. La chiave compare nella pagina delle chiavi trovate della tua dashboard.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìIl puzzle a cui appartiene la chiave.
UserTokenheaderstring (128 caratteri)SìIl tuo miner token.
Content-TypeheaderstringSìapplication/json.
namebodystringNoUn'etichetta, ad esempio il nome del worker. Salvata come Puzzle71 - rig1.
encryptedKeybodystringSìLa chiave privata cifrata (il client la invia in base64).

Esempio di richiesta

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>"}'

Esempio di risposta

200 OK Nota che la proprietà è success, non isSuccess.

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

Errori

StatoBodyQuando
401{"error": "invalid_user_token"}Token sconosciuto o bannato.
400problem detailsNon è stato salvato nulla: la stessa chiave è già salvata per questo account, oppure manca il body.
429{"isSuccess": false, ...}Limite di frequenza: 10 ogni 180 secondi per token.

Dati dei puzzle

Endpoint pubblici di sola lettura sui puzzle del pool. Non serve alcun token. L'oggetto Puzzle e gli altri oggetti sono descritti alla fine di questa guida.

GET/puzzle

I puzzle presenti nel pool: quelli attivi, i prossimi e il pool di test (e quelli completati conservati per lo storico). In cache per 300 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK Un array di oggetti Puzzle, qui ridotto a uno.

[
  {
    "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": []
  }
]

Errori

StatoBodyQuando
404[]Il pool non ha alcun puzzle.

GET/puzzle/all

Tutti i puzzle del database, compresi quelli completati. In cache per 300 secondi.

Esempio di richiesta

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

Risponde 200 con un array di oggetti Puzzle.

GET/puzzle/available

I puzzle che si possono scansionare nel pool. In cache per 300 secondi.

Esempio di richiesta

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

Risponde 200 con un array di oggetti Puzzle.

GET/puzzle/default

Il puzzle predefinito: quello su cui ripiega una richiesta per un puzzle completato. In cache per 300 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK Un singolo oggetto 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": []
}

Errori

StatoBodyQuando
404{"error": "puzzle_not_found"}Nessun puzzle predefinito impostato.

GET/puzzle/codes

I numeri dei puzzle attivi o prossimi, prima i puzzle normali e per ultimo il pool di test. In cache per 300 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK

[71, 72, 73, 38]

GET/puzzle/{puzzleCode}/info

Un singolo puzzle, letto dal database. In cache per 10 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìIl numero del puzzle.

Esempio di richiesta

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

Esempio di risposta

200 OK Un oggetto Puzzle. I valori di runtime come rangesScannedLastHour sono compilati solo negli endpoint di elenco.

{
  "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": []
}

Errori

StatoBodyQuando
204vuotoPuzzle inesistente.

GET/puzzle/{puzzleCode}/statistics

Tutto ciò che mostra la pagina del puzzle: totali, classifiche, worker attivi, gli ultimi 200 range scansionati e un grafico orario. In cache per 60 secondi (e il server conserva una copia per 5 minuti).

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìUn puzzle attivo (o il pool di test).

Esempio di richiesta

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

Esempio di risposta

200 OK Abbreviato: qui gli array contengono un elemento, e lastRanges fino a 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"
  }
}

Per un puzzle non ancora attivo (i prossimi) vengono restituiti solo puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges e dateUpdated. Per i campi vedi l'oggetto Statistics.

Errori

StatoBodyQuando
400problem detailsIl puzzle non esiste oppure non è né attivo né prossimo.

GET/puzzle/{puzzleCode}/speed

La velocità attuale del pool su un puzzle. In cache per 60 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìIl numero del puzzle.

Esempio di richiesta

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

Esempio di risposta

200 OK Vedi CurrentSpeed. Un puzzle sconosciuto risponde con valori a zero, mai con un errore.

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

GET/puzzle/{puzzleCode}/workers

I worker che stanno scansionando ora: quelli con un range per cui hanno inviato un ping negli ultimi 30 minuti. Non messo in cache dal browser; il server conserva la risposta per 60 secondi. puzzleCode 0 indica il puzzle predefinito.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìIl numero del puzzle.

Esempio di richiesta

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

Esempio di risposta

200 OK Un array vuoto se nessuno sta scansionando o il puzzle è sconosciuto.

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

GET/puzzle/{puzzleCode}/workers-pinging

Lo stesso elenco di /workers (mantenuto come percorso separato perché i client li usano entrambi).

Esempio di richiesta

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

Stessi parametri e stessa risposta di GET /puzzle/{puzzleCode}/workers.

GET/puzzle/{puzzleCode}/rewards

I premi del pool di un puzzle attivo: premi extra che gli sponsor associano a chiavi private all'interno dei range (dal più recente, fino a 32). La chiave privata di un premio viene mostrata solo dopo che è stato risolto. In cache per 600 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìUn puzzle attivo.

Esempio di richiesta

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

Esempio di risposta

200 OK Vedi Reward. Un array vuoto se il puzzle non ne ha.

[
  {
    "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
  }
]

Errori

StatoBodyQuando
400problem detailsIl puzzle non è attivo.

GET/puzzle/{puzzleCode}/challenge

Gli ultimi punti di partenza delle sfide di un puzzle attivo (dal più recente, fino a 32). In cache per 600 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìUn puzzle attivo.

Esempio di richiesta

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

Esempio di risposta

200 OK Vedi Challenge. Un array vuoto se non ce ne sono.

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

Errori

StatoBodyQuando
400problem detailsIl puzzle non è attivo.

GET/puzzle/{puzzleCode}/entrancefee

La quota di ingresso di un puzzle in USD, quando la quota è attiva. In cache per 300 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìUn puzzle attivo con quota di ingresso.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Errori

StatoBodyQuando
400problem detailsIl puzzle non è attivo o non ha una quota di ingresso.

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

Quanta parte del puzzle è scansionata per ciascun prefisso di due caratteri dell'HEX del range (la heat map della pagina del puzzle). In cache per 3600 secondi.

Parametri

NomePosizioneTipoObbligatorioDescrizione
puzzleCodepathintegerSìUn puzzle attivo.

Esempio di richiesta

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

Esempio di risposta

200 OK Un elemento per prefisso, ordinati per hexStarts. La proprietà pertantageShow ha un errore di ortografia voluto (congelato). Dal 70% in su i numeri si fermano al 70% e isLimitExceeded è true.

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

Errori

StatoBodyQuando
400problem detailsIl puzzle non è attivo.

Dati del pool

Endpoint pubblici di sola lettura sul pool nel suo insieme, sull'elenco delle GPU e sul token BCPZ.

GET/pool/homepage

L'elenco dei puzzle della home page: lo stesso array di GET /puzzle, e il puzzle predefinito include la sua speed. In cache per 60 secondi.

Esempio di richiesta

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

Risponde 200 con un array di oggetti Puzzle.

GET/pool/gpus

L'elenco del benchmark delle GPU, dalla più veloce (chiavi al secondo nel pool). In cache per 300 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Campi della risposta

CampoTipoDescrizione
brandstringnvidia o amd.
namestringLa scheda.
keysPerSecondnumberVelocità misurata.
dateUpdateddateUltimo aggiornamento.

GET/pool/token-distribute-history

Le distribuzioni giornaliere di BCPZ, dalla più recente (fino a 180). In cache per 300 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Campi della risposta

CampoTipoDescrizione
idintegerNumero della distribuzione.
dateProccesdateQuando è stata eseguita. Il nome contiene un errore di ortografia ed è congelato.
totalUsersintegerUtenti che hanno ricevuto token.
totalAmountnumberBCPZ distribuiti (1 per range scansionato).
descriptionstringTesto del risultato.

GET/pool/token-top-50-holders

I 50 account che hanno guadagnato più BCPZ, con indirizzi wallet abbreviati. In cache per 600 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Campi della risposta

CampoTipoDescrizione
walletAddressstringIndirizzo abbreviato.
balancenumberBCPZ attualmente sull'account.
totalnumberBCPZ guadagnati in totale.
mintednumberBCPZ già prelevati sulla rete Polygon.

GET/pool/token-mint-history

Gli ultimi prelievi di BCPZ sulla rete Polygon, dal più recente (fino a 180). In cache per 600 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK

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

Campi della risposta

CampoTipoDescrizione
walletAddressstringIndirizzo abbreviato dell'account.
mintednumberBCPZ inviati.
datedateQuando è stato inviato.
txIdstringHash della transazione Polygon. Omesso finché il trasferimento non è completato.

GET/pool/btc-price

Il prezzo di Bitcoin in USD e EUR, preso da un exchange. In cache per 600 secondi.

Esempio di richiesta

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

Esempio di risposta

200 OK Entrambi i valori sono 0 quando la fonte del prezzo non è raggiungibile.

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

Feed in tempo reale (SignalR)

Il pool pubblica su un hub SignalR ogni range prenotato e completato. Il sito lo usa per la pagina dello stato dal vivo. L'hub è pubblico, non richiede token e si limita a inviare: non ci sono metodi che un client possa chiamare.

URL dell'hubhttps://btcpuzzle.info/api/hex_socket
Vecchio hosthttps://api.btcpuzzle.info/hex_socket
ProtocolloSignalR con il protocollo JSON predefinito; sono disponibili WebSockets, Server-Sent Events e Long Polling.
EventoPoolStatus
LimiteLa richiesta di negotiate conta per il limite di frequenza per IP. L'hub in sé non ha limiti una volta connessi.

Connessione

Usa una libreria client SignalR (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Dietro le quinte esegue prima la negoziazione:

Esempio di richiesta

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

Esempio di risposta

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();

Evento PoolStatus

Un argomento, un oggetto JSON. L'evento viene inviato a tutti i client connessi quando un range viene assegnato e quando un range viene marcato come scansionato.

{
  "hex": "3AX8443",
  "walletAddress": "1BvBMSEY...7xJaNVN2",
  "workerName": "rig1",
  "puzzleCode": 71,
  "status": "holded"
}
CampoTipoDescrizione
hexstringL'HEX del range con il terzo carattere sostituito da X.
walletAddressstringIndirizzo abbreviato dell'account.
workerNamestring o nullIl nome del worker (default se non ne è stato inviato uno). Con scanned è il nome inviato con la richiesta di marcatura, che può essere null.
puzzleCodeintegerIl puzzle del range.
statusstringholded dopo l'assegnazione di un range, scanned dopo la marcatura di un range. L'ortografia è congelata.

Gli eventi vengono consegnati finché la connessione è aperta; dopo una riconnessione non viene riprodotto nulla. Quando il gestore disattiva il feed live, le connessioni vengono rifiutate.

Oggetti

Oggetto Puzzle

Restituito dagli endpoint di elenco dei puzzle e da /puzzle/{puzzleCode}/info. Le proprietà senza valore vengono omesse.

CampoTipoDescrizione
idintegerId nel database (uguale a code per i puzzle del vecchio sistema).
namestringAd esempio Puzzle 71.
codeintegerIl numero del puzzle.
hexStart, hexEndstringPrima e ultima chiave privata del puzzle, in esadecimale.
targetWalletAddressstringL'indirizzo che contiene il premio.
hexRangeLengthintegerLunghezza dell'HEX del range assegnato dal pool (la parte della chiave che sceglie il pool).
rewardnumberIl premio in BTC.
hexStartPool, hexEndPoolstringPrimo e ultimo HEX dei range. Vuoti se il puzzle non è nel pool.
totalRangesintegerNumero di range del puzzle. 0 se il puzzle non è nel pool.
percentagenumberPercentuale dei range scansionati.
totalScanned, rangesScannedLastHourintegerRange scansionati in totale e nell'ultima ora (compilati negli endpoint di elenco).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByvariDati finali di un puzzle completato; statisticsFoundBy è presente solo se noto.
rangeContainsKeys, rangeContainsKeyByDefaultintegerNumero di chiavi private (meno una) in un range. I due valori differiscono quando i range coprono più id.
rangesPerKeyintegerQuanti id di range copre un range (1 per la maggior parte dei puzzle).
workloadStart, workloadEndstringLa parte della chiave privata che un client scansiona dopo l'HEX del range: vedi GET range.
customWorkloadStart, customWorkloadEndstringPresenti quando il puzzle usa un workload personalizzato.
dateStart, dateEnddateDate previste del puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanLo stato del puzzle: completato, annunciato, scansionabile ora, predefinito, pool di test, presente nel pool.
isEntranceFeeActive, entranceFeeboolean, numberSe la quota di ingresso è attiva e il suo prezzo in USD (0 se disattivata).
nextScanAllowedInMinutesintegerPer quanto tempo un range assegnato resta riservato prima di poter essere dato a qualcun altro.
challengesarrayL'ultima sfida, oppure un array vuoto.
privateKey, publicKeystringSolo per i puzzle risolti.
rewards, speedarray, objectPresenti solo in alcuni endpoint.

Oggetto Statistics

CampoTipoDescrizione
puzzleobjectI dati principali del puzzle (nome, codice, numero di range, workload, stato, premio).
scannedLast24HintegerRange scansionati nelle ultime 24 ore.
entranceFeesPaidTotalnumberQuote di ingresso pagate per il puzzle, in USD.
topWorkersAlltimearrayFino a 50 elementi {userId, walletAddress, totalScanned}; qui userId è 0.
topWorkersLast24harrayLo stesso per le ultime 24 ore.
activeWorkersarray{walletAddress, workerName} dei worker che hanno inviato ping negli ultimi 30 minuti.
challengesarrayFino a 32 sfide.
kingdomobjectIl re del puzzle: walletAddress, message, image e isPublished.
topSpeedobjectL'ora migliore di sempre: date, range scanned e keysPerSecond.
chartDataarrayL'ultimo mese ora per ora, dal più recente: date, dateOnly, hoursOnly e rangesScanned.
lastRangesarrayGli ultimi 200 range scansionati, dal più recente: hex (mascherato), walletAddress (mascherato), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds e totalSeconds.
rewardsarrayPremi del puzzle (senza chiavi private).
dateUpdateddateQuando sono stati calcolati i dati.
currentSpeedobjectCurrentSpeed.

Oggetto CurrentSpeed

CampoTipoDescrizione
activeWorkerCountintegerWorker che hanno scansionato nelle ultime 6 ore e inviato un ping nell'ultima ora.
keysPerSecondFormattedstringLa velocità con un'unità: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s e così via.
keysPerSecondRawstringLa velocità in chiavi al secondo, come testo di un intero.

Oggetto Challenge

CampoTipoDescrizione
hexstringI caratteri iniziali che ogni partecipante alla sfida scansiona.
dateCreateddateQuando è iniziata la sfida.
puzzleIdintegerIl puzzle.

Oggetto Reward

CampoTipoDescrizione
id, puzzleCode, puzzleIdintegerIdentificazione.
targetAddressstringL'indirizzo della chiave del premio.
rewardContent, rewardDescription, provider, providerDesc, brandstringIn cosa consiste il premio e chi lo offre. Le proprietà senza valore vengono omesse.
privateKeystringPresente solo dopo che il premio è stato risolto.
dateCreated, dateSolveddateQuando è stato creato e risolto (0001-01-01T00:00:00 finché non è risolto).

Modifiche rispetto alla vecchia documentazione

Il contratto non è cambiato in nulla: ogni endpoint, header, campo e codice di errore della vecchia API funziona ancora e risponde allo stesso modo. Questa guida sostituisce la vecchia pagina, che descriveva tre endpoint. Le novità:

  • Sono documentati gli endpoint di dati pubblici, il feed in tempo reale, i codici di errore e i limiti di frequenza. La vecchia pagina non li menzionava.
  • Correzioni del vecchio testo: l'header UserToken della richiesta di marcatura è il miner token (la vecchia pagina lo chiamava indirizzo wallet); l'intervallo dei ping è di circa 2 minuti e al massimo di 30 minuti, e il limite è di 360 ping al minuto per token, non 60 all'ora; il puzzle del pool di test è il 38.
  • Il base URL è https://btcpuzzle.info/api; il vecchio host api.btcpuzzle.info continua a funzionare.
  • L'hub SignalR non ha più metodi dal client al server, quindi nessuno può inviare eventi falsi. L'evento in sé non è cambiato.
  • Ora viene assegnato anche l'ultimo range libero di un puzzle, e una finestra CustomRange molto stretta viene allargata, così non si può scegliere un range chiedendone esattamente uno.
  • Le statistiche pubbliche non mostrano più l'indirizzo IP di un miner.

Offrimi un caffè

Puzzle del pool

Cosa scansiona ora il pool, cosa viene dopo e i puzzle su cui ha già lavorato.

In scansione ora1

Prossimo2

Scansionati in passato4

Tutti i 160 puzzle