Présentation
L'API de btcpuzzle.info est celle avec laquelle dialogue le client du pool. Elle distribue des plages de clés à scanner, reçoit le résultat d'un scan et publie les statistiques publiques du pool. btcpuzzle.info est open source et chacun peut écrire un client : ce guide décrit chaque endpoint public, les données à envoyer, les données renvoyées et les erreurs possibles. Questions : support@btcpuzzle.info.
Cette API est volontairement figée : les mineurs et des outils tiers en dépendent. Les chemins, en-têtes, noms de champs (y compris quelques anciennes orthographes comme dateProcces et holded) et codes d'erreur ne changent pas. De nouveaux champs peuvent être ajoutés aux réponses : ignorez donc les champs que vous ne connaissez pas.
URL de base
Tous les chemins de ce guide sont relatifs à l'URL de base :
https://btcpuzzle.info/apiLes clients écrits avant le déménagement du site peuvent continuer à utiliser l'ancien hôte, avec les mêmes chemins et sans préfixe /api :
https://api.btcpuzzle.infoPar exemple, GET https://btcpuzzle.info/api/puzzle/codes et GET https://api.btcpuzzle.info/puzzle/codes répondent la même chose. Les nouveaux clients doivent utiliser l'URL de base avec /api.
Démarrage rapide
Créez un compte gratuit sur btcpuzzle.info, copiez votre token de mineur depuis le tableau de bord, puis demandez une plage :
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Scannez la plage renvoyée en même temps que les six adresses de preuve, envoyez la preuve avec PUT /puzzle/71/range, et recommencez. Entre les deux appels, envoyez un ping de temps en temps pour que le pool sache que le worker est actif.
Conventions
Versions
Il n'existe qu'une seule version, et aucune version dans l'URL. Le contrat de l'ancienne API est conservé à l'identique ; voir Changements par rapport à l'ancienne documentation.
Authentification
Les endpoints des mineurs sont identifiés par l'en-tête UserToken : le token de mineur de 128 caractères de votre compte. Il n'y a pour eux ni autre connexion ni session. Vous pouvez créer un nouveau token depuis votre compte à tout moment ; l'ancien cesse aussitôt de fonctionner. Gardez le token privé : quiconque le possède scanne en votre nom.
Tous les endpoints de données (puzzles, statistiques, pool, jeton) sont publics et ne demandent aucun token.
Requêtes et réponses
- Pour les endpoints des mineurs, les données de la requête passent dans les en-têtes HTTP, pas dans la query string ni dans le corps. Les noms d'en-têtes ne sont pas sensibles à la casse (
UserToken,usertokenetuserTokensont le même en-tête). SeulPOST /puzzle/{puzzleCode}/save-private-keya un corps JSON (Content-Type: application/json). - Les réponses sont en JSON UTF-8 avec des noms de propriétés en camelCase. Les propriétés sans valeur sont omises ; l'API n'écrit jamais de
nullJSON. Ne vous fiez pas à l'indentation. - Les dates sont au format ISO 8601 en UTC (
2026-11-18T08:28:25.8176144Z). Les sommes et montants sont des nombres JSON. - Les grands nombres comme
rangeContainsKeyssont des entiers non signés 64 bits et peuvent dépasser 2^53 : dans les langages qui utilisent des doubles, lisez-les comme des entiers 64 bits ou des chaînes. - Dans les données publiques, les adresses de portefeuille sont raccourcies (8 premiers caractères,
..., 8 derniers) et le troisième caractère d'un HEX de plage est remplacé parX(3AB8443devient3AX8443).
Limites de débit
Les limites ci-dessous sont les valeurs par défaut actuelles. Elles sont comptées sur une fenêtre de temps fixe ; l'opérateur peut les ajuster : lisez donc la réponse 429 plutôt que de coder les nombres en dur.
| S'applique à | Compté par | Limite |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 requêtes par 60 secondes |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 requêtes par 60 secondes |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 requêtes par 60 secondes |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 requêtes par 180 secondes |
| Tous les autres endpoints | Adresse IP | 20 requêtes par seconde pour chaque endpoint, 200 par seconde au total |
Une requête au-delà de la limite reçoit la réponse 429 Too Many Requests, un en-tête Retry-After et ce corps :
{
"isSuccess": false,
"details": "Quota exceeded."
}Erreurs
Les échecs utilisent les codes de statut ci-dessous. Le corps dépend de l'endpoint : vérifiez donc d'abord le code de statut.
| Statut | Corps | Signification |
|---|---|---|
400 | {"error": "<code>"} | Un endpoint de mineur a refusé la requête. Le code indique pourquoi : invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (l'orthographe est historique), invalid_request. |
400 | {"isSuccess": false} | La requête de marquage d'une plage a été refusée (preuve fausse, plage inconnue ou déjà scannée, utilisateur banni, puzzle inactif). |
400 | problème de validation | Un en-tête obligatoire est manquant ou invalide, ou le numéro de puzzle est hors de l'intervalle 1 à 160. C'est un objet application/problem+json dont errors liste les noms fautifs. |
400 | problem details | Un endpoint de données publiques n'a rien à répondre pour ce puzzle (puzzle inconnu ou inactif). application/problem+json avec type, title, status et traceId. |
401 | {"error": "invalid_user_token"} | Le token de mineur est inconnu ou le compte est banni (ping et save-private-key). |
404 | {"error": "range_not_found"} | La plage à pinger n'est pas détenue par ce worker. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Limite de débit. Attendez Retry-After secondes. |
Exemple de problème de validation (GET /puzzle/71/range sans l'en-tête 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 et CORS
Les endpoints de données publiques envoient Cache-Control: public, max-age=N ; la valeur est indiquée pour chaque endpoint, et une copie en cache est partagée par tous les appelants : interroger plus souvent que toutes les N secondes renvoie donc les mêmes données. Les endpoints des mineurs ne sont jamais mis en cache. Les navigateurs peuvent appeler l'API depuis https://btcpuzzle.info, https://www.btcpuzzle.info et http://localhost:3000 (ce dernier existe pour le développement local de l'ancien frontend) ; les clients natifs ne sont pas concernés par CORS.
Endpoints des mineurs
Les trois appels de la boucle de scan : obtenir une plage, pinger pendant le scan, la marquer comme scannée. Un quatrième appel enregistre une clé trouvée. Les quatre utilisent l'en-tête UserToken.
GET/puzzle/{puzzleCode}/range
Distribue une plage libre aléatoire du puzzle et la réserve pour vous. Personne d'autre ne reçoit une plage que vous détenez ; si vous ne la marquez pas, elle retourne au pool au bout d'un moment (un ping prolonge la réservation).
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier (1 à 160) | Oui | Le puzzle à scanner, par exemple 71. 38 est le pool de test. GET /puzzle/codes liste les codes. Pour un puzzle terminé, la plage est servie silencieusement depuis le puzzle par défaut, et la réponse indique le puzzle obtenu dans puzzleCode. |
UserToken | en-tête | chaîne (128 caractères) | Oui | Votre token de mineur. |
WorkerName | en-tête | chaîne (1 à 16 caractères) | Non | Le nom de ce worker. Lettres et chiffres uniquement. Enregistré comme default si vous n'en envoyez pas. |
SecurityHash | en-tête | chaîne | Non | Texte libre conservé avec la plage. Facultatif. |
CustomRange | en-tête | chaîne | Non | Limite la plage obtenue : un préfixe du HEX (2D, 3BA) ou start:end (3400000:38FFFFF). none ou l'absence d'en-tête signifie n'importe quelle plage. Une fenêtre très étroite est élargie par le pool : vous pouvez donc recevoir une autre plage que celle indiquée. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemple de réponse
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}Champs de la réponse
| Champ | Type | Description |
|---|---|---|
hex | chaîne | La plage à scanner, en majuscules, sans remplissage. C'est le début des clés privées de la plage. |
puzzleCode | entier | Le puzzle auquel appartient la plage (le puzzle par défaut quand celui demandé est terminé). |
workloadStart | chaîne | À ajouter à la suite de hex pour obtenir la première clé privée de la plage. |
workloadEnd | chaîne | À ajouter à la suite de hex pour obtenir la dernière clé privée de la plage. Sa longueur peut dépasser celle de workloadStart sur les puzzles dont les plages couvrent plusieurs ID. |
targetAddress | chaîne | L'adresse du puzzle que vous cherchez. Scannez-la en même temps que les adresses de preuve. |
proofOfWorkAddresses | tableau de 6 chaînes | Les adresses de six clés privées placées par le pool dans la plage. Trouvez leurs clés privées pour prouver le scan : voir Preuve de travail. |
Avec l'exemple ci-dessus, la plage va de 3AB8443 + 00000000000 = 3AB844300000000000 à 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Les clés privées font 64 caractères hexadécimaux ; complétez à gauche avec des zéros.
Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | {"error": "invalid_puzzle"} | Le puzzle n'existe pas ou n'est pas actif. |
400 | {"error": "invalid_user_token"} | Le token est inconnu ou banni. |
400 | {"error": "too_much_request"} | Vous détenez trop de plages non scannées, ou vous demandez plus vite que vous ne terminez. Scannez ce que vous détenez ; les plages réservées retournent au pool après un court délai. |
400 | {"error": "not_eligable"} | Le puzzle a des frais d'entrée et vous n'en remplissez pas encore les conditions. |
400 | {"error": "reached_of_keyspace"} | Il ne reste aucune plage libre (ou aucune qui corresponde à votre CustomRange). |
400 | validation problem | En-tête manquant ou mal formé, ou numéro de puzzle hors de l'intervalle 1 à 160. |
429 | {"isSuccess": false, ...} | Limite de débit : 120 par minute et par token. |
Preuve de travail
Le pool veut être sûr que vous avez réellement scanné la plage. Pour chaque plage, il choisit six clés privées à l'intérieur et ne renvoie que leurs adresses (proofOfWorkAddresses). Pendant que vous scannez la plage à la recherche de l'adresse cible, cherchez aussi ces six adresses. Quand vous avez trouvé les six clés privées :
- Écrivez chaque clé privée sous forme de 64 caractères hexadécimaux en majuscules, complétés à gauche par des zéros.
- Concaténez les six chaînes, dans l'ordre des adresses, sans rien entre elles.
- Calculez le SHA-256 du texte UTF-8 et écrivez-le sous forme de 64 caractères hexadécimaux en minuscules. C'est le
HashedProofKeyde la requête de marquage.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87La preuve est différente pour chaque plage. Le nombre d'adresses de preuve est de six aujourd'hui ; lisez la longueur de proofOfWorkAddresses au lieu de la supposer.
PUT/puzzle/{puzzleCode}/range
Marque une plage comme scannée. Le pool vérifie la preuve et, si elle est correcte, compte la plage comme terminée pour vous. Une plage ne peut être marquée qu'une seule fois.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier (1 à 160) | Oui | Le puzzle de la plage. |
UserToken | en-tête | chaîne (128 caractères) | Oui | Votre token de mineur. |
HEX | en-tête | chaîne | Oui | Le hex de la plage scannée, tel que le pool l'a renvoyé. Exemple : 3AB8443. |
HashedProofKey | en-tête | chaîne | Oui | La preuve de travail : voir Preuve de travail. |
WorkerName | en-tête | chaîne (1 à 16 caractères) | Non | Le worker qui a scanné la plage. |
GPUName | en-tête | chaîne | Non | Le modèle de carte graphique. Utilisé pour les statistiques publiques. |
GPUCount | en-tête | entier | Non | Nombre de cartes du worker. Par défaut 1. |
IsForceContinue | en-tête | booléen | Non | À définir quand le worker a continué bien qu'il ait atteint la fin de son espace de clés. Par défaut false. |
Exemple de requête
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"Exemple de réponse
200 OK
{
"isSuccess": true
}Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | {"isSuccess": false} | Tout refus : preuve fausse, plage inconnue, plage déjà marquée, compte banni, puzzle inactif. |
400 | validation problem | Un en-tête obligatoire est manquant ou mal formé. |
429 | {"isSuccess": false, ...} | Limite de débit : 360 par minute et par token. |
PATCH/puzzle/{puzzleCode}/range/ping
Indique au pool qu'un worker scanne toujours sa plage. Un ping maintient la réservation de la plage et affiche le worker comme actif sur le site. Envoyez-en un environ toutes les 2 minutes ; l'intervalle ne doit pas dépasser 30 minutes, sinon le pool reprend la plage.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Le puzzle de la plage. |
Hex | en-tête | chaîne | Oui | La plage que le worker scanne en ce moment. |
UserToken | en-tête | chaîne (128 caractères) | Oui | Votre token de mineur. |
WorkerName | en-tête | chaîne | Oui | Le nom de worker utilisé lors de la demande de la plage (default si aucun n'a été envoyé). |
Exemple de requête
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemple de réponse
200 OK avec un corps vide.
Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | {"error": "invalid_request"} | Un en-tête est vide. |
401 | {"error": "invalid_user_token"} | Token inconnu ou banni. |
404 | {"error": "range_not_found"} | Ce worker ne détient pas de plage non scannée avec ce HEX sur ce puzzle. |
429 | {"isSuccess": false, ...} | Limite de débit : 360 par minute et par token. |
POST/puzzle/{puzzleCode}/save-private-key
Enregistre une clé privée trouvée sur votre compte, chiffrée. Le client chiffre la clé avec la clé publique RSA que vous lui avez fournie ; le site ne conserve que le texte chiffré, que vous déchiffrez avec votre clé privée. La clé apparaît sur la page des clés trouvées de votre tableau de bord.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Le puzzle auquel appartient la clé. |
UserToken | en-tête | chaîne (128 caractères) | Oui | Votre token de mineur. |
Content-Type | en-tête | chaîne | Oui | application/json. |
name | corps | chaîne | Non | Un libellé, par exemple le nom du worker. Enregistré comme Puzzle71 - rig1. |
encryptedKey | corps | chaîne | Oui | La clé privée chiffrée (le client l'envoie en base64). |
Exemple de requête
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>"}'Exemple de réponse
200 OK Notez que la propriété est success, et non isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Erreurs
| Statut | Corps | Quand |
|---|---|---|
401 | {"error": "invalid_user_token"} | Token inconnu ou banni. |
400 | problem details | Rien n'a été enregistré : la même clé est déjà stockée pour ce compte, ou le corps est manquant. |
429 | {"isSuccess": false, ...} | Limite de débit : 10 par 180 secondes et par token. |
Données des puzzles
Endpoints publics de lecture sur les puzzles du pool. Aucun token n'est nécessaire. L'objet Puzzle et les autres objets sont décrits à la fin de ce guide.
GET/puzzle
Les puzzles présents sur le pool : les actifs, les suivants et le pool de test (ainsi que les terminés conservés pour l'historique). Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle"Exemple de réponse
200 OK Un tableau d'objets Puzzle, réduit ici à un seul.
[
{
"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": []
}
]Erreurs
| Statut | Corps | Quand |
|---|---|---|
404 | [] | Le pool n'a aucun puzzle. |
GET/puzzle/all
Tous les puzzles de la base de données, terminés compris. Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/all"Répond 200 avec un tableau d'objets Puzzle.
GET/puzzle/available
Les puzzles qui peuvent être scannés sur le pool. Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/available"Répond 200 avec un tableau d'objets Puzzle.
GET/puzzle/default
Le puzzle par défaut : celui vers lequel se rabat une requête portant sur un puzzle terminé. Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/default"Exemple de réponse
200 OK Un seul objet 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": []
}Erreurs
| Statut | Corps | Quand |
|---|---|---|
404 | {"error": "puzzle_not_found"} | Aucun puzzle par défaut n'est défini. |
GET/puzzle/codes
Les numéros des puzzles actifs ou suivants, les puzzles normaux d'abord et le pool de test en dernier. Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/codes"Exemple de réponse
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
Un puzzle, lu depuis la base de données. Mis en cache 10 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Le numéro du puzzle. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/info"Exemple de réponse
200 OK Un objet Puzzle. Les valeurs calculées à l'exécution comme rangesScannedLastHour ne sont renseignées que dans les endpoints de liste.
{
"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": []
}Erreurs
| Statut | Corps | Quand |
|---|---|---|
204 | vide | Ce puzzle n'existe pas. |
GET/puzzle/{puzzleCode}/statistics
Tout ce qu'affiche la page du puzzle : totaux, classements, workers actifs, les 200 dernières plages scannées et un graphique horaire. Mis en cache 60 secondes (et le serveur conserve une copie pendant 5 minutes).
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Un puzzle actif (ou le pool de test). |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Exemple de réponse
200 OK Version abrégée : les tableaux contiennent ici un élément, et lastRanges jusqu'à 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"
}
}Pour un puzzle pas encore actif (les suivants), seuls puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges et dateUpdated sont renvoyés. Voir l'objet Statistics pour les champs.
Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | problem details | Le puzzle n'existe pas ou n'est ni actif ni suivant. |
GET/puzzle/{puzzleCode}/speed
La vitesse actuelle du pool sur un puzzle. Mis en cache 60 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Le numéro du puzzle. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/speed"Exemple de réponse
200 OK Voir CurrentSpeed. Un puzzle inconnu répond avec des valeurs à zéro, jamais avec une erreur.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
Les workers qui scannent en ce moment : ceux qui ont pingé une plage au cours des 30 dernières minutes. Non mis en cache par le navigateur ; le serveur conserve la réponse 60 secondes. puzzleCode 0 désigne le puzzle par défaut.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Le numéro du puzzle. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/workers"Exemple de réponse
200 OK Un tableau vide quand personne ne scanne ou que le puzzle est inconnu.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
La même liste que /workers (conservée comme chemin distinct car les clients utilisent les deux).
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"Mêmes paramètres et même réponse que GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
Les récompenses du pool d'un puzzle actif : des prix supplémentaires que des sponsors placent sur des clés privées à l'intérieur des plages (les plus récentes d'abord, jusqu'à 32). La clé privée d'une récompense n'est affichée qu'une fois celle-ci résolue. Mis en cache 600 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Un puzzle actif. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Exemple de réponse
200 OK Voir Reward. Un tableau vide quand le puzzle n'en a pas.
[
{
"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
}
]Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | problem details | Le puzzle n'est pas actif. |
GET/puzzle/{puzzleCode}/challenge
Les derniers points de départ de challenge d'un puzzle actif (les plus récents d'abord, jusqu'à 32). Mis en cache 600 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Un puzzle actif. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Exemple de réponse
200 OK Voir Challenge. Un tableau vide quand il n'y en a aucun.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | problem details | Le puzzle n'est pas actif. |
GET/puzzle/{puzzleCode}/entrancefee
Les frais d'entrée d'un puzzle en USD, quand ils sont activés. Mis en cache 300 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Un puzzle actif avec des frais d'entrée. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Exemple de réponse
200 OK
{
"fee": 25.0,
"puzzle": 71
}Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | problem details | Le puzzle n'est pas actif ou n'a pas de frais d'entrée. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
La part scannée du puzzle pour chaque préfixe de deux caractères du HEX de plage (la carte de chaleur de la page du puzzle). Mis en cache 3600 secondes.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
|---|---|---|---|---|
puzzleCode | chemin | entier | Oui | Un puzzle actif. |
Exemple de requête
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Exemple de réponse
200 OK Un élément par préfixe, trié par hexStarts. La propriété pertantageShow est volontairement mal orthographiée (figée). À partir de 70 %, les chiffres s'arrêtent à 70 % et isLimitExceeded vaut true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Erreurs
| Statut | Corps | Quand |
|---|---|---|
400 | problem details | Le puzzle n'est pas actif. |
Données du pool
Endpoints publics de lecture sur le pool dans son ensemble, la liste des GPU et le jeton BCPZ.
GET/pool/homepage
La liste des puzzles de la page d'accueil : le même tableau que GET /puzzle, et le puzzle par défaut porte sa speed. Mis en cache 60 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/homepage"Répond 200 avec un tableau d'objets Puzzle.
GET/pool/gpus
La liste du benchmark des GPU, les plus rapides d'abord (clés par seconde sur le pool). Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/gpus"Exemple de réponse
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Champs de la réponse
| Champ | Type | Description |
|---|---|---|
brand | chaîne | nvidia ou amd. |
name | chaîne | La carte. |
keysPerSecond | nombre | Vitesse mesurée. |
dateUpdated | date | Dernière mise à jour. |
GET/pool/token-distribute-history
Les distributions quotidiennes de BCPZ, les plus récentes d'abord (jusqu'à 180). Mis en cache 300 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/token-distribute-history"Exemple de réponse
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]Champs de la réponse
| Champ | Type | Description |
|---|---|---|
id | entier | Numéro de la distribution. |
dateProcces | date | Date d'exécution. Le nom est mal orthographié et figé. |
totalUsers | entier | Utilisateurs ayant reçu des jetons. |
totalAmount | nombre | BCPZ distribués (1 par plage scannée). |
description | chaîne | Texte du résultat. |
GET/pool/token-top-50-holders
Les 50 comptes ayant gagné le plus de BCPZ, adresses de portefeuille raccourcies. Mis en cache 600 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Exemple de réponse
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Champs de la réponse
| Champ | Type | Description |
|---|---|---|
walletAddress | chaîne | Adresse raccourcie. |
balance | nombre | BCPZ actuellement sur le compte. |
total | nombre | BCPZ gagnés au total. |
minted | nombre | BCPZ déjà retirés vers le réseau Polygon. |
GET/pool/token-mint-history
Les derniers retraits de BCPZ vers le réseau Polygon, les plus récents d'abord (jusqu'à 180). Mis en cache 600 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/token-mint-history"Exemple de réponse
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]Champs de la réponse
| Champ | Type | Description |
|---|---|---|
walletAddress | chaîne | Adresse raccourcie du compte. |
minted | nombre | BCPZ envoyés. |
date | date | Date d'envoi. |
txId | chaîne | Hash de la transaction Polygon. Omis tant que le transfert n'est pas effectué. |
GET/pool/btc-price
Le cours du Bitcoin en USD et en EUR, issu d'une plateforme d'échange. Mis en cache 600 secondes.
Exemple de requête
curl "https://btcpuzzle.info/api/pool/btc-price"Exemple de réponse
200 OK Les deux valeurs valent 0 quand la source du cours est injoignable.
{"usd":66739.06,"eur":60607.25}Flux en temps réel (SignalR)
Le pool publie chaque plage réservée et terminée sur un hub SignalR. Le site l'utilise pour la page d'état en direct. Le hub est public, ne demande aucun token et ne fait qu'émettre : aucun client ne peut appeler de méthode.
| URL du hub | https://btcpuzzle.info/api/hex_socket |
| Ancien hôte | https://api.btcpuzzle.info/hex_socket |
| Protocole | SignalR avec le protocole JSON par défaut ; WebSockets, Server-Sent Events et Long Polling sont proposés. |
| Événement | PoolStatus |
| Limite | La requête negotiate compte dans la limite de débit par IP. Le hub lui-même n'est pas limité une fois connecté. |
Connexion
Utilisez une bibliothèque cliente SignalR (JavaScript : @microsoft/signalr ; .NET : Microsoft.AspNetCore.SignalR.Client). En interne, elle commence par une négociation :
Exemple de requête
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"Exemple de réponse
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();Événement PoolStatus
Un argument, un objet JSON. L'événement est envoyé à tous les clients connectés quand une plage est distribuée et quand une plage est marquée comme scannée.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Champ | Type | Description |
|---|---|---|
hex | chaîne | Le HEX de la plage, avec son troisième caractère remplacé par X. |
walletAddress | chaîne | Adresse raccourcie du compte. |
workerName | chaîne ou null | Le nom du worker (default si aucun n'a été envoyé). Pour scanned, c'est le nom envoyé avec la requête de marquage, qui peut être null. |
puzzleCode | entier | Le puzzle de la plage. |
status | chaîne | holded après la distribution d'une plage, scanned après son marquage. L'orthographe est figée. |
Les événements sont livrés tant que la connexion est ouverte ; rien n'est rejoué après une reconnexion. Quand l'opérateur désactive le flux en direct, les connexions sont refusées.
Objets
Objet Puzzle
Renvoyé par les endpoints de liste des puzzles et par /puzzle/{puzzleCode}/info. Les propriétés sans valeur sont omises.
| Champ | Type | Description |
|---|---|---|
id | entier | ID en base de données (identique à code pour les puzzles de l'ancien système). |
name | chaîne | Par exemple Puzzle 71. |
code | entier | Le numéro du puzzle. |
hexStart, hexEnd | chaîne | Première et dernière clé privée du puzzle, en hexadécimal. |
targetWalletAddress | chaîne | L'adresse qui détient la récompense. |
hexRangeLength | entier | Longueur du HEX de plage distribué par le pool (la partie de la clé qu'il choisit). |
reward | nombre | La récompense en BTC. |
hexStartPool, hexEndPool | chaîne | Premier et dernier HEX de plage. Vide sauf si le puzzle est sur le pool. |
totalRanges | entier | Nombre de plages du puzzle. 0 sauf si le puzzle est sur le pool. |
percentage | nombre | Pourcentage des plages scannées. |
totalScanned, rangesScannedLastHour | entier | Plages scannées au total et au cours de la dernière heure (renseigné dans les endpoints de liste). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | divers | Chiffres finaux d'un puzzle terminé ; statisticsFoundBy n'est présent que s'il est connu. |
rangeContainsKeys, rangeContainsKeyByDefault | entier | Nombre de clés privées (moins une) dans une plage. Les deux diffèrent quand les plages couvrent plusieurs ID. |
rangesPerKey | entier | Nombre d'ID de plage couverts par une plage (1 pour la plupart des puzzles). |
workloadStart, workloadEnd | chaîne | La partie de la clé privée qu'un client scanne après le HEX de plage : voir GET range. |
customWorkloadStart, customWorkloadEnd | chaîne | Présent quand le puzzle utilise une charge de travail personnalisée. |
dateStart, dateEnd | date | Dates prévues du puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | booléen | L'état du puzzle : terminé, annoncé, scannable maintenant, par défaut, pool de test, sur le pool. |
isEntranceFeeActive, entranceFee | booléen, nombre | Si les frais d'entrée sont activés, et leur prix en USD (0 s'ils sont désactivés). |
nextScanAllowedInMinutes | entier | Durée pendant laquelle une plage distribuée est réservée avant de pouvoir être confiée à quelqu'un d'autre. |
challenges | tableau | Le dernier challenge, ou un tableau vide. |
privateKey, publicKey | chaîne | Uniquement pour les puzzles résolus. |
rewards, speed | tableau, objet | Présent uniquement sur certains endpoints. |
Objet Statistics
| Champ | Type | Description |
|---|---|---|
puzzle | objet | Les principaux chiffres du puzzle (nom, code, nombre de plages, charge de travail, état, récompense). |
scannedLast24H | entier | Plages scannées au cours des dernières 24 heures. |
entranceFeesPaidTotal | nombre | Frais d'entrée payés pour le puzzle, en USD. |
topWorkersAlltime | tableau | Jusqu'à 50 éléments {userId, walletAddress, totalScanned} ; userId vaut ici 0. |
topWorkersLast24h | tableau | La même chose pour les dernières 24 heures. |
activeWorkers | tableau | {walletAddress, workerName} des workers ayant pingé au cours des 30 dernières minutes. |
challenges | tableau | Jusqu'à 32 challenges. |
kingdom | objet | Le roi du puzzle : walletAddress, message, image et isPublished. |
topSpeed | objet | La meilleure heure de tous les temps : date, plages scanned et keysPerSecond. |
chartData | tableau | Le dernier mois heure par heure, le plus récent d'abord : date, dateOnly, hoursOnly et rangesScanned. |
lastRanges | tableau | Les 200 dernières plages scannées, les plus récentes d'abord : hex (masqué), walletAddress (masqué), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds et totalSeconds. |
rewards | tableau | Récompenses du puzzle (sans les clés privées). |
dateUpdated | date | Date du calcul des chiffres. |
currentSpeed | objet | CurrentSpeed. |
Objet CurrentSpeed
| Champ | Type | Description |
|---|---|---|
activeWorkerCount | entier | Workers ayant scanné au cours des 6 dernières heures et pingé au cours de la dernière heure. |
keysPerSecondFormatted | chaîne | La vitesse avec une unité : keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s, etc. |
keysPerSecondRaw | chaîne | La vitesse en clés par seconde, sous forme de texte d'entier. |
Objet Challenge
| Champ | Type | Description |
|---|---|---|
hex | chaîne | Les caractères de départ que scanne chaque participant au challenge. |
dateCreated | date | Date de début du challenge. |
puzzleId | entier | Le puzzle. |
Objet Reward
| Champ | Type | Description |
|---|---|---|
id, puzzleCode, puzzleId | entier | Identification. |
targetAddress | chaîne | L'adresse de la clé de la récompense. |
rewardContent, rewardDescription, provider, providerDesc, brand | chaîne | La nature du prix et qui l'offre. Les propriétés sans valeur sont omises. |
privateKey | chaîne | Présent uniquement une fois la récompense résolue. |
dateCreated, dateSolved | date | Dates de création et de résolution (0001-01-01T00:00:00 tant qu'elle n'est pas résolue). |
Changements par rapport à l'ancienne documentation
Rien n'a changé dans le contrat : chaque endpoint, en-tête, champ et code d'erreur de l'ancienne API fonctionne toujours et répond de la même façon. Ce guide remplace l'ancienne page, qui décrivait trois endpoints. Les nouveautés :
- Les endpoints de données publiques, le flux en temps réel, les codes d'erreur et les limites de débit sont documentés. L'ancienne page ne les mentionnait pas.
- Corrections de l'ancien texte : l'en-tête
UserTokende la requête de marquage est le token de mineur (l'ancienne page parlait d'une adresse de portefeuille) ; l'intervalle de ping est d'environ 2 minutes et de 30 minutes au plus, et la limite est de 360 pings par minute et par token, et non de 60 par heure ; le puzzle du pool de test est le38. - L'URL de base est
https://btcpuzzle.info/api; l'ancien hôteapi.btcpuzzle.infocontinue de fonctionner. - Le hub SignalR n'a plus de méthode client-vers-serveur : personne ne peut donc envoyer de faux événements. L'événement lui-même n'a pas changé.
- La dernière plage libre d'un puzzle est désormais distribuée elle aussi, et une fenêtre
CustomRangetrès étroite est élargie pour qu'on ne puisse pas choisir une plage en demandant exactement celle-ci. - Les statistiques publiques n'affichent plus l'adresse IP d'un mineur.