Documentation de l'API

Créez votre propre client pour le pool. Tous les endpoints, avec requêtes, réponses et erreurs.

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

Les 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.info

Par 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, usertoken et userToken sont le même en-tête). Seul POST /puzzle/{puzzleCode}/save-private-key a 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 null JSON. 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 rangeContainsKeys sont 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é par X (3AB8443 devient 3AX8443).

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é parLimite
GET /puzzle/{puzzleCode}/rangeUserToken120 requêtes par 60 secondes
PUT /puzzle/{puzzleCode}/rangeUserToken360 requêtes par 60 secondes
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 requêtes par 60 secondes
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 requêtes par 180 secondes
Tous les autres endpointsAdresse IP20 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.

StatutCorpsSignification
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).
400problème de validationUn 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.
400problem detailsUn 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentier (1 à 160)OuiLe 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.
UserTokenen-têtechaîne (128 caractères)OuiVotre token de mineur.
WorkerNameen-têtechaîne (1 à 16 caractères)NonLe nom de ce worker. Lettres et chiffres uniquement. Enregistré comme default si vous n'en envoyez pas.
SecurityHashen-têtechaîneNonTexte libre conservé avec la plage. Facultatif.
CustomRangeen-têtechaîneNonLimite 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

ChampTypeDescription
hexchaîneLa plage à scanner, en majuscules, sans remplissage. C'est le début des clés privées de la plage.
puzzleCodeentierLe puzzle auquel appartient la plage (le puzzle par défaut quand celui demandé est terminé).
workloadStartchaîneÀ ajouter à la suite de hex pour obtenir la première clé privée de la plage.
workloadEndchaî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.
targetAddresschaîneL'adresse du puzzle que vous cherchez. Scannez-la en même temps que les adresses de preuve.
proofOfWorkAddressestableau de 6 chaînesLes 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

StatutCorpsQuand
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).
400validation problemEn-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 :

  1. Écrivez chaque clé privée sous forme de 64 caractères hexadécimaux en majuscules, complétés à gauche par des zéros.
  2. Concaténez les six chaînes, dans l'ordre des adresses, sans rien entre elles.
  3. Calculez le SHA-256 du texte UTF-8 et écrivez-le sous forme de 64 caractères hexadécimaux en minuscules. C'est le HashedProofKey de 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 ) )
               = 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87

La 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentier (1 à 160)OuiLe puzzle de la plage.
UserTokenen-têtechaîne (128 caractères)OuiVotre token de mineur.
HEXen-têtechaîneOuiLe hex de la plage scannée, tel que le pool l'a renvoyé. Exemple : 3AB8443.
HashedProofKeyen-têtechaîneOuiLa preuve de travail : voir Preuve de travail.
WorkerNameen-têtechaîne (1 à 16 caractères)NonLe worker qui a scanné la plage.
GPUNameen-têtechaîneNonLe modèle de carte graphique. Utilisé pour les statistiques publiques.
GPUCounten-têteentierNonNombre de cartes du worker. Par défaut 1.
IsForceContinueen-têtebooléenNonÀ 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

StatutCorpsQuand
400{"isSuccess": false}Tout refus : preuve fausse, plage inconnue, plage déjà marquée, compte banni, puzzle inactif.
400validation problemUn 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiLe puzzle de la plage.
Hexen-têtechaîneOuiLa plage que le worker scanne en ce moment.
UserTokenen-têtechaîne (128 caractères)OuiVotre token de mineur.
WorkerNameen-têtechaîneOuiLe 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

StatutCorpsQuand
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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiLe puzzle auquel appartient la clé.
UserTokenen-têtechaîne (128 caractères)OuiVotre token de mineur.
Content-Typeen-têtechaîneOuiapplication/json.
namecorpschaîneNonUn libellé, par exemple le nom du worker. Enregistré comme Puzzle71 - rig1.
encryptedKeycorpschaîneOuiLa 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

StatutCorpsQuand
401{"error": "invalid_user_token"}Token inconnu ou banni.
400problem detailsRien 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

StatutCorpsQuand
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

StatutCorpsQuand
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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiLe 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

StatutCorpsQuand
204videCe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiUn 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

StatutCorpsQuand
400problem detailsLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiUn 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

StatutCorpsQuand
400problem detailsLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiUn 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

StatutCorpsQuand
400problem detailsLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiUn 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

StatutCorpsQuand
400problem detailsLe 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

NomEmplacementTypeObligatoireDescription
puzzleCodecheminentierOuiUn 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

StatutCorpsQuand
400problem detailsLe 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

ChampTypeDescription
brandchaînenvidia ou amd.
namechaîneLa carte.
keysPerSecondnombreVitesse mesurée.
dateUpdateddateDerniè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

ChampTypeDescription
identierNuméro de la distribution.
dateProccesdateDate d'exécution. Le nom est mal orthographié et figé.
totalUsersentierUtilisateurs ayant reçu des jetons.
totalAmountnombreBCPZ distribués (1 par plage scannée).
descriptionchaîneTexte 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

ChampTypeDescription
walletAddresschaîneAdresse raccourcie.
balancenombreBCPZ actuellement sur le compte.
totalnombreBCPZ gagnés au total.
mintednombreBCPZ 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

ChampTypeDescription
walletAddresschaîneAdresse raccourcie du compte.
mintednombreBCPZ envoyés.
datedateDate d'envoi.
txIdchaîneHash 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 hubhttps://btcpuzzle.info/api/hex_socket
Ancien hôtehttps://api.btcpuzzle.info/hex_socket
ProtocoleSignalR avec le protocole JSON par défaut ; WebSockets, Server-Sent Events et Long Polling sont proposés.
ÉvénementPoolStatus
LimiteLa 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"
}
ChampTypeDescription
hexchaîneLe HEX de la plage, avec son troisième caractère remplacé par X.
walletAddresschaîneAdresse raccourcie du compte.
workerNamechaîne ou nullLe 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.
puzzleCodeentierLe puzzle de la plage.
statuschaîneholded 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.

ChampTypeDescription
identierID en base de données (identique à code pour les puzzles de l'ancien système).
namechaînePar exemple Puzzle 71.
codeentierLe numéro du puzzle.
hexStart, hexEndchaînePremière et dernière clé privée du puzzle, en hexadécimal.
targetWalletAddresschaîneL'adresse qui détient la récompense.
hexRangeLengthentierLongueur du HEX de plage distribué par le pool (la partie de la clé qu'il choisit).
rewardnombreLa récompense en BTC.
hexStartPool, hexEndPoolchaînePremier et dernier HEX de plage. Vide sauf si le puzzle est sur le pool.
totalRangesentierNombre de plages du puzzle. 0 sauf si le puzzle est sur le pool.
percentagenombrePourcentage des plages scannées.
totalScanned, rangesScannedLastHourentierPlages scannées au total et au cours de la dernière heure (renseigné dans les endpoints de liste).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBydiversChiffres finaux d'un puzzle terminé ; statisticsFoundBy n'est présent que s'il est connu.
rangeContainsKeys, rangeContainsKeyByDefaultentierNombre de clés privées (moins une) dans une plage. Les deux diffèrent quand les plages couvrent plusieurs ID.
rangesPerKeyentierNombre d'ID de plage couverts par une plage (1 pour la plupart des puzzles).
workloadStart, workloadEndchaîneLa partie de la clé privée qu'un client scanne après le HEX de plage : voir GET range.
customWorkloadStart, customWorkloadEndchaînePrésent quand le puzzle utilise une charge de travail personnalisée.
dateStart, dateEnddateDates prévues du puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooléenL'état du puzzle : terminé, annoncé, scannable maintenant, par défaut, pool de test, sur le pool.
isEntranceFeeActive, entranceFeebooléen, nombreSi les frais d'entrée sont activés, et leur prix en USD (0 s'ils sont désactivés).
nextScanAllowedInMinutesentierDurée pendant laquelle une plage distribuée est réservée avant de pouvoir être confiée à quelqu'un d'autre.
challengestableauLe dernier challenge, ou un tableau vide.
privateKey, publicKeychaîneUniquement pour les puzzles résolus.
rewards, speedtableau, objetPrésent uniquement sur certains endpoints.

Objet Statistics

ChampTypeDescription
puzzleobjetLes principaux chiffres du puzzle (nom, code, nombre de plages, charge de travail, état, récompense).
scannedLast24HentierPlages scannées au cours des dernières 24 heures.
entranceFeesPaidTotalnombreFrais d'entrée payés pour le puzzle, en USD.
topWorkersAlltimetableauJusqu'à 50 éléments {userId, walletAddress, totalScanned} ; userId vaut ici 0.
topWorkersLast24htableauLa même chose pour les dernières 24 heures.
activeWorkerstableau{walletAddress, workerName} des workers ayant pingé au cours des 30 dernières minutes.
challengestableauJusqu'à 32 challenges.
kingdomobjetLe roi du puzzle : walletAddress, message, image et isPublished.
topSpeedobjetLa meilleure heure de tous les temps : date, plages scanned et keysPerSecond.
chartDatatableauLe dernier mois heure par heure, le plus récent d'abord : date, dateOnly, hoursOnly et rangesScanned.
lastRangestableauLes 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.
rewardstableauRécompenses du puzzle (sans les clés privées).
dateUpdateddateDate du calcul des chiffres.
currentSpeedobjetCurrentSpeed.

Objet CurrentSpeed

ChampTypeDescription
activeWorkerCountentierWorkers ayant scanné au cours des 6 dernières heures et pingé au cours de la dernière heure.
keysPerSecondFormattedchaîneLa vitesse avec une unité : keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s, etc.
keysPerSecondRawchaîneLa vitesse en clés par seconde, sous forme de texte d'entier.

Objet Challenge

ChampTypeDescription
hexchaîneLes caractères de départ que scanne chaque participant au challenge.
dateCreateddateDate de début du challenge.
puzzleIdentierLe puzzle.

Objet Reward

ChampTypeDescription
id, puzzleCode, puzzleIdentierIdentification.
targetAddresschaîneL'adresse de la clé de la récompense.
rewardContent, rewardDescription, provider, providerDesc, brandchaîneLa nature du prix et qui l'offre. Les propriétés sans valeur sont omises.
privateKeychaînePrésent uniquement une fois la récompense résolue.
dateCreated, dateSolveddateDates 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 UserToken de 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 le 38.
  • L'URL de base est https://btcpuzzle.info/api ; l'ancien hôte api.btcpuzzle.info continue 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 CustomRange trè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.

Offrez-moi un café

Puzzles du pool

Ce que le pool scanne maintenant, ce qui vient ensuite, et les puzzles sur lesquels il a déjà travaillé.

En cours de scan1

Suivant2

Scannés auparavant4

Les 160 puzzles