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/apiI 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.infoAd 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,usertokeneuserTokensono lo stesso header). SoloPOST /puzzle/{puzzleCode}/save-private-keyha 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
nullJSON. 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
rangeContainsKeyssono 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 daX(3AB8443diventa3AX8443).
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 a | Conteggiato per | Limite |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 richieste ogni 60 secondi |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 richieste ogni 60 secondi |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 richieste ogni 60 secondi |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 richieste ogni 180 secondi |
| Tutti gli altri endpoint | Indirizzo IP | 20 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.
| Stato | Body | Significato |
|---|---|---|
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). |
400 | problema di validazione | Un 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. |
400 | problem details | Un 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer (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. |
UserToken | header | string (128 caratteri) | Sì | Il tuo miner token. |
WorkerName | header | string (da 1 a 16 caratteri) | No | Il nome di questo worker. Solo lettere e cifre. Salvato come default se non ne invii uno. |
SecurityHash | header | string | No | Testo libero conservato con il range. Facoltativo. |
CustomRange | header | string | No | Limita 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
| Campo | Tipo | Descrizione |
|---|---|---|
hex | string | Il range da scansionare, in maiuscolo e senza padding. È la parte iniziale delle chiavi private del range. |
puzzleCode | integer | Il puzzle a cui appartiene il range (il puzzle predefinito se quello richiesto è completato). |
workloadStart | string | Da aggiungere dopo hex per ottenere la prima chiave privata del range. |
workloadEnd | string | Da 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. |
targetAddress | string | L'indirizzo del puzzle che stai cercando. Scansionalo insieme agli indirizzi di prova. |
proofOfWorkAddresses | array di 6 stringhe | Indirizzi 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
| Stato | Body | Quando |
|---|---|---|
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). |
400 | validation problem | Header 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:
- Scrivi ogni chiave privata come 64 caratteri esadecimali maiuscoli, completati a sinistra con degli zeri.
- Concatena le sei stringhe, nell'ordine degli indirizzi, senza nulla in mezzo.
- Calcola lo SHA-256 del testo UTF-8 e scrivilo come 64 caratteri esadecimali minuscoli. Questo è l'
HashedProofKeydella richiesta di marcatura.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87La 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer (da 1 a 160) | Sì | Il puzzle del range. |
UserToken | header | string (128 caratteri) | Sì | Il tuo miner token. |
HEX | header | string | Sì | L'hex del range che hai scansionato, così come lo ha restituito il pool. Esempio: 3AB8443. |
HashedProofKey | header | string | Sì | La proof of work: vedi Proof of work. |
WorkerName | header | string (da 1 a 16 caratteri) | No | Il worker che ha scansionato il range. |
GPUName | header | string | No | Il modello della scheda video. Usato per le statistiche pubbliche. |
GPUCount | header | integer | No | Numero di schede del worker. Predefinito 1. |
IsForceContinue | header | boolean | No | Impostalo 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
| Stato | Body | Quando |
|---|---|---|
400 | {"isSuccess": false} | Qualsiasi rifiuto: prova errata, range sconosciuto, range già marcato, account bannato, puzzle non attivo. |
400 | validation problem | Un 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | Il puzzle del range. |
Hex | header | string | Sì | Il range che il worker sta scansionando ora. |
UserToken | header | string (128 caratteri) | Sì | Il tuo miner token. |
WorkerName | header | string | Sì | 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
| Stato | Body | Quando |
|---|---|---|
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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | Il puzzle a cui appartiene la chiave. |
UserToken | header | string (128 caratteri) | Sì | Il tuo miner token. |
Content-Type | header | string | Sì | application/json. |
name | body | string | No | Un'etichetta, ad esempio il nome del worker. Salvata come Puzzle71 - rig1. |
encryptedKey | body | string | Sì | 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
| Stato | Body | Quando |
|---|---|---|
401 | {"error": "invalid_user_token"} | Token sconosciuto o bannato. |
400 | problem details | Non è 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
| Stato | Body | Quando |
|---|---|---|
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
| Stato | Body | Quando |
|---|---|---|
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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
204 | vuoto | Puzzle 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
400 | problem details | Il 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
400 | problem details | Il 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
400 | problem details | Il 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
400 | problem details | Il 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
| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
puzzleCode | path | integer | Sì | 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
| Stato | Body | Quando |
|---|---|---|
400 | problem details | Il 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
| Campo | Tipo | Descrizione |
|---|---|---|
brand | string | nvidia o amd. |
name | string | La scheda. |
keysPerSecond | number | Velocità misurata. |
dateUpdated | date | Ultimo 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
| Campo | Tipo | Descrizione |
|---|---|---|
id | integer | Numero della distribuzione. |
dateProcces | date | Quando è stata eseguita. Il nome contiene un errore di ortografia ed è congelato. |
totalUsers | integer | Utenti che hanno ricevuto token. |
totalAmount | number | BCPZ distribuiti (1 per range scansionato). |
description | string | Testo 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
| Campo | Tipo | Descrizione |
|---|---|---|
walletAddress | string | Indirizzo abbreviato. |
balance | number | BCPZ attualmente sull'account. |
total | number | BCPZ guadagnati in totale. |
minted | number | BCPZ 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
| Campo | Tipo | Descrizione |
|---|---|---|
walletAddress | string | Indirizzo abbreviato dell'account. |
minted | number | BCPZ inviati. |
date | date | Quando è stato inviato. |
txId | string | Hash 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'hub | https://btcpuzzle.info/api/hex_socket |
| Vecchio host | https://api.btcpuzzle.info/hex_socket |
| Protocollo | SignalR con il protocollo JSON predefinito; sono disponibili WebSockets, Server-Sent Events e Long Polling. |
| Evento | PoolStatus |
| Limite | La 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"
}| Campo | Tipo | Descrizione |
|---|---|---|
hex | string | L'HEX del range con il terzo carattere sostituito da X. |
walletAddress | string | Indirizzo abbreviato dell'account. |
workerName | string o null | Il nome del worker (default se non ne è stato inviato uno). Con scanned è il nome inviato con la richiesta di marcatura, che può essere null. |
puzzleCode | integer | Il puzzle del range. |
status | string | holded 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.
| Campo | Tipo | Descrizione |
|---|---|---|
id | integer | Id nel database (uguale a code per i puzzle del vecchio sistema). |
name | string | Ad esempio Puzzle 71. |
code | integer | Il numero del puzzle. |
hexStart, hexEnd | string | Prima e ultima chiave privata del puzzle, in esadecimale. |
targetWalletAddress | string | L'indirizzo che contiene il premio. |
hexRangeLength | integer | Lunghezza dell'HEX del range assegnato dal pool (la parte della chiave che sceglie il pool). |
reward | number | Il premio in BTC. |
hexStartPool, hexEndPool | string | Primo e ultimo HEX dei range. Vuoti se il puzzle non è nel pool. |
totalRanges | integer | Numero di range del puzzle. 0 se il puzzle non è nel pool. |
percentage | number | Percentuale dei range scansionati. |
totalScanned, rangesScannedLastHour | integer | Range scansionati in totale e nell'ultima ora (compilati negli endpoint di elenco). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | vari | Dati finali di un puzzle completato; statisticsFoundBy è presente solo se noto. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | Numero di chiavi private (meno una) in un range. I due valori differiscono quando i range coprono più id. |
rangesPerKey | integer | Quanti id di range copre un range (1 per la maggior parte dei puzzle). |
workloadStart, workloadEnd | string | La parte della chiave privata che un client scansiona dopo l'HEX del range: vedi GET range. |
customWorkloadStart, customWorkloadEnd | string | Presenti quando il puzzle usa un workload personalizzato. |
dateStart, dateEnd | date | Date previste del puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | Lo stato del puzzle: completato, annunciato, scansionabile ora, predefinito, pool di test, presente nel pool. |
isEntranceFeeActive, entranceFee | boolean, number | Se la quota di ingresso è attiva e il suo prezzo in USD (0 se disattivata). |
nextScanAllowedInMinutes | integer | Per quanto tempo un range assegnato resta riservato prima di poter essere dato a qualcun altro. |
challenges | array | L'ultima sfida, oppure un array vuoto. |
privateKey, publicKey | string | Solo per i puzzle risolti. |
rewards, speed | array, object | Presenti solo in alcuni endpoint. |
Oggetto Statistics
| Campo | Tipo | Descrizione |
|---|---|---|
puzzle | object | I dati principali del puzzle (nome, codice, numero di range, workload, stato, premio). |
scannedLast24H | integer | Range scansionati nelle ultime 24 ore. |
entranceFeesPaidTotal | number | Quote di ingresso pagate per il puzzle, in USD. |
topWorkersAlltime | array | Fino a 50 elementi {userId, walletAddress, totalScanned}; qui userId è 0. |
topWorkersLast24h | array | Lo stesso per le ultime 24 ore. |
activeWorkers | array | {walletAddress, workerName} dei worker che hanno inviato ping negli ultimi 30 minuti. |
challenges | array | Fino a 32 sfide. |
kingdom | object | Il re del puzzle: walletAddress, message, image e isPublished. |
topSpeed | object | L'ora migliore di sempre: date, range scanned e keysPerSecond. |
chartData | array | L'ultimo mese ora per ora, dal più recente: date, dateOnly, hoursOnly e rangesScanned. |
lastRanges | array | Gli ultimi 200 range scansionati, dal più recente: hex (mascherato), walletAddress (mascherato), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds e totalSeconds. |
rewards | array | Premi del puzzle (senza chiavi private). |
dateUpdated | date | Quando sono stati calcolati i dati. |
currentSpeed | object | CurrentSpeed. |
Oggetto CurrentSpeed
| Campo | Tipo | Descrizione |
|---|---|---|
activeWorkerCount | integer | Worker che hanno scansionato nelle ultime 6 ore e inviato un ping nell'ultima ora. |
keysPerSecondFormatted | string | La velocità con un'unità: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s e così via. |
keysPerSecondRaw | string | La velocità in chiavi al secondo, come testo di un intero. |
Oggetto Challenge
| Campo | Tipo | Descrizione |
|---|---|---|
hex | string | I caratteri iniziali che ogni partecipante alla sfida scansiona. |
dateCreated | date | Quando è iniziata la sfida. |
puzzleId | integer | Il puzzle. |
Oggetto Reward
| Campo | Tipo | Descrizione |
|---|---|---|
id, puzzleCode, puzzleId | integer | Identificazione. |
targetAddress | string | L'indirizzo della chiave del premio. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | In cosa consiste il premio e chi lo offre. Le proprietà senza valore vengono omesse. |
privateKey | string | Presente solo dopo che il premio è stato risolto. |
dateCreated, dateSolved | date | Quando è 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
UserTokendella 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 è il38. - Il base URL è
https://btcpuzzle.info/api; il vecchio hostapi.btcpuzzle.infocontinua 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
CustomRangemolto 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.