Resumen
La API de btcpuzzle.info es con la que habla el cliente del pool. Reparte rangos de claves para escanear, recibe el resultado de un escaneo y publica las estadísticas públicas del pool. btcpuzzle.info es de código abierto y cualquiera puede escribir un cliente: esta guía describe todos los endpoints públicos, los datos que hay que enviar, los datos que recibes y los errores que te puedes encontrar. Preguntas: support@btcpuzzle.info.
Esta API está congelada a propósito: los mineros y las herramientas de terceros dependen de ella. Las rutas, las cabeceras, los nombres de campo (incluidas algunas grafías antiguas como dateProcces y holded) y los códigos de error no cambian. Pueden añadirse campos nuevos a las respuestas, así que ignora los campos que no conozcas.
URL base
Todas las rutas de esta guía son relativas a la URL base:
https://btcpuzzle.info/apiLos clientes escritos antes de que la web se mudara pueden seguir usando el host antiguo, con las mismas rutas y sin el prefijo /api:
https://api.btcpuzzle.infoPor ejemplo, GET https://btcpuzzle.info/api/puzzle/codes y GET https://api.btcpuzzle.info/puzzle/codes responden lo mismo. Los clientes nuevos deben usar la URL base con /api.
Inicio rápido
Crea una cuenta gratuita en btcpuzzle.info, copia tu token de minero desde el panel y pide un rango:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Escanea el rango devuelto junto con las seis direcciones de prueba, envía la prueba con PUT /puzzle/71/range y repite. Entre las dos llamadas, envía un ping de vez en cuando para que el pool sepa que el worker sigue vivo.
Convenciones
Versiones
Hay una sola versión y no hay versión en la URL. El contrato de la API antigua se mantiene exactamente; consulta Cambios respecto a la documentación antigua.
Autenticación
Los endpoints de minero se identifican por la cabecera UserToken: el token de minero de 128 caracteres de tu cuenta. No hay otro inicio de sesión ni sesión para ellos. Puedes crear un token nuevo desde tu cuenta en cualquier momento; el antiguo deja de funcionar al instante. Mantén el token en privado: quien lo tenga escanea en tu nombre.
Todos los endpoints de datos (puzzles, estadísticas, pool, token) son públicos y no necesitan token.
Peticiones y respuestas
- En los endpoints de minero, los datos de la petición van en cabeceras HTTP, no en la query string ni en el cuerpo. Los nombres de las cabeceras no distinguen mayúsculas (
UserToken,usertokenyuserTokenson la misma cabecera). SoloPOST /puzzle/{puzzleCode}/save-private-keytiene cuerpo JSON (Content-Type: application/json). - Las respuestas son JSON en UTF-8 con nombres de propiedad en camelCase. Las propiedades sin valor se omiten; la API nunca escribe un JSON
null. No dependas de la indentación. - Las fechas son ISO 8601 en UTC (
2026-11-18T08:28:25.8176144Z). El dinero y las cantidades son números JSON. - Los números grandes como
rangeContainsKeysson enteros de 64 bits sin signo y pueden ser mayores que 2^53: analízalos como enteros de 64 bits o como cadenas en los lenguajes que usan doubles. - Las direcciones de billetera de los datos públicos se abrevian (primeros 8 caracteres,
..., últimos 8) y el tercer carácter del HEX de un rango se sustituye porX(3AB8443pasa a ser3AX8443).
Límites de frecuencia
Los límites de abajo son los valores predeterminados actuales. Se cuentan en una ventana de tiempo fija; el operador puede ajustarlos, así que lee la respuesta 429 en lugar de fijar los números en el código.
| Se aplica a | Se cuenta por | Límite |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 peticiones cada 60 segundos |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 peticiones cada 60 segundos |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 peticiones cada 60 segundos |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 peticiones cada 180 segundos |
| Cualquier otro endpoint | Dirección IP | 20 peticiones por segundo por endpoint, 200 por segundo en total |
Una petición que supera el límite recibe 429 Too Many Requests, una cabecera Retry-After y este cuerpo:
{
"isSuccess": false,
"details": "Quota exceeded."
}Errores
Los fallos usan los códigos de estado de abajo. El cuerpo depende del endpoint, así que comprueba primero el código de estado.
| Estado | Cuerpo | Significado |
|---|---|---|
400 | {"error": "<code>"} | Un endpoint de minero rechazó la petición. El código indica el motivo: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (la grafía es histórica), invalid_request. |
400 | {"isSuccess": false} | Se rechazó la petición de marcado de un rango (prueba incorrecta, rango desconocido o ya escaneado, usuario bloqueado, puzzle inactivo). |
400 | problema de validación | Falta una cabecera obligatoria o no es válida, o el número de puzzle está fuera del rango 1 a 160. Es un objeto application/problem+json cuyo campo errors enumera los nombres erróneos. |
400 | detalles del problema | Un endpoint de datos públicos no tiene nada que responder para este puzzle (puzzle desconocido o inactivo). application/problem+json con type, title, status y traceId. |
401 | {"error": "invalid_user_token"} | El token de minero es desconocido o la cuenta está bloqueada (ping y save-private-key). |
404 | {"error": "range_not_found"} | Este worker no tiene el rango al que se hace ping. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Límite de frecuencia. Espera los Retry-After segundos. |
Ejemplo de problema de validación (GET /puzzle/71/range sin la cabecera 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"
}Caché y CORS
Los endpoints de datos públicos envían Cache-Control: public, max-age=N; el valor se indica en cada endpoint, y todos los llamantes comparten la copia en caché, así que consultar más a menudo que cada N segundos solo devuelve los mismos datos. Los endpoints de minero nunca se almacenan en caché. Los navegadores pueden llamar a la API desde https://btcpuzzle.info, https://www.btcpuzzle.info y http://localhost:3000 (el último existe para el desarrollo local del frontend antiguo); a los clientes nativos no les afecta CORS.
Endpoints de minero
Las tres llamadas del bucle de escaneo: pedir un rango, hacer ping mientras lo escaneas y marcarlo como escaneado. Una cuarta llamada guarda una clave hallada. Las cuatro usan la cabecera UserToken.
GET/puzzle/{puzzleCode}/range
Reparte un rango libre aleatorio del puzzle y te lo reserva. A nadie más se le da un rango que tú tienes reservado; si no lo marcas, vuelve al pool al cabo de un tiempo (un ping amplía la reserva).
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer (1 a 160) | Sí | El puzzle que se va a escanear, por ejemplo 71. 38 es el pool de prueba. GET /puzzle/codes lista los códigos. Un puzzle completado se sirve en silencio desde el puzzle predeterminado, y la respuesta indica qué puzzle te tocó en puzzleCode. |
UserToken | cabecera | string (128 caracteres) | Sí | Tu token de minero. |
WorkerName | cabecera | string (de 1 a 16 caracteres) | No | El nombre de este worker. Solo letras y dígitos. Se guarda como default si no envías ninguno. |
SecurityHash | cabecera | string | No | Texto libre que se guarda con el rango. Opcional. |
CustomRange | cabecera | string | No | Limita el rango que recibes: un prefijo del HEX (2D, 3BA) o start:end (3400000:38FFFFF). none o sin cabecera significa cualquier rango. El pool amplía una ventana muy estrecha, así que puedes recibir un rango distinto del que indicaste. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Ejemplo de respuesta
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
hex | string | El rango que hay que escanear, en mayúsculas y sin relleno. Es el principio de las claves privadas del rango. |
puzzleCode | integer | El puzzle al que pertenece el rango (el puzzle predeterminado si el que pediste está completado). |
workloadStart | string | Se añade a hex para obtener la primera clave privada del rango. |
workloadEnd | string | Se añade a hex para obtener la última clave privada del rango. Su longitud puede ser mayor que workloadStart en los puzzles cuyos rangos abarcan varios ids. |
targetAddress | string | La dirección del puzzle que buscas. Escanéala junto con las direcciones de prueba. |
proofOfWorkAddresses | array de 6 strings | Direcciones de seis claves privadas que el pool colocó dentro del rango. Encuentra sus claves privadas para demostrar el escaneo: consulta Prueba de trabajo. |
Con el ejemplo de arriba, el rango va de 3AB8443 + 00000000000 = 3AB844300000000000 a 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Las claves privadas tienen 64 caracteres hexadecimales; rellena con ceros a la izquierda.
Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | {"error": "invalid_puzzle"} | El puzzle no existe o no está activo. |
400 | {"error": "invalid_user_token"} | El token es desconocido o está bloqueado. |
400 | {"error": "too_much_request"} | Tienes demasiados rangos reservados sin escanear, o pides más rápido de lo que terminas. Escanea lo que tienes; los rangos reservados vuelven al pool al poco tiempo. |
400 | {"error": "not_eligable"} | El puzzle tiene cuota de entrada y aún no cumples sus condiciones. |
400 | {"error": "reached_of_keyspace"} | No queda ningún rango libre (o ninguno que encaje con tu CustomRange). |
400 | validation problem | Cabecera ausente o mal formada, o un número de puzzle fuera del rango 1 a 160. |
429 | {"isSuccess": false, ...} | Límite de frecuencia: 120 por minuto por token. |
Prueba de trabajo
El pool quiere estar seguro de que de verdad escaneaste el rango. Con cada rango elige seis claves privadas dentro de él y solo devuelve sus direcciones (proofOfWorkAddresses). Mientras escaneas el rango buscando la dirección objetivo, busca también estas seis direcciones. Cuando hayas encontrado las seis claves privadas:
- Escribe cada clave privada como 64 caracteres hexadecimales en mayúsculas, rellenados con ceros a la izquierda.
- Concatena las seis cadenas, en el orden de las direcciones, sin nada entre ellas.
- Calcula el SHA-256 del texto UTF-8 y escríbelo como 64 caracteres hexadecimales en minúsculas. Ese es el
HashedProofKeyde la petición de marcado.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87La prueba es distinta para cada rango. Hoy el número de direcciones de prueba es seis; lee la longitud de proofOfWorkAddresses en lugar de suponerla.
PUT/puzzle/{puzzleCode}/range
Marca un rango como escaneado. El pool comprueba la prueba y, si es correcta, cuenta el rango como hecho por ti. Un rango solo puede marcarse una vez.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer (1 a 160) | Sí | El puzzle del rango. |
UserToken | cabecera | string (128 caracteres) | Sí | Tu token de minero. |
HEX | cabecera | string | Sí | El hex del rango que escaneaste, tal como lo devolvió el pool. Ejemplo: 3AB8443. |
HashedProofKey | cabecera | string | Sí | La prueba de trabajo: consulta Prueba de trabajo. |
WorkerName | cabecera | string (de 1 a 16 caracteres) | No | El worker que escaneó el rango. |
GPUName | cabecera | string | No | El modelo de tarjeta gráfica. Se usa para las estadísticas públicas. |
GPUCount | cabecera | integer | No | Número de tarjetas del worker. Predeterminado 1. |
IsForceContinue | cabecera | boolean | No | Ponlo cuando el worker siguió aunque había llegado al final de su espacio de claves. Predeterminado false. |
Ejemplo de petición
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"Ejemplo de respuesta
200 OK
{
"isSuccess": true
}Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | {"isSuccess": false} | Cualquier rechazo: prueba incorrecta, rango desconocido, un rango ya marcado, cuenta bloqueada, puzzle inactivo. |
400 | validation problem | Falta una cabecera obligatoria o está mal formada. |
429 | {"isSuccess": false, ...} | Límite de frecuencia: 360 por minuto por token. |
PATCH/puzzle/{puzzleCode}/range/ping
Indica al pool que un worker sigue escaneando su rango. Un ping mantiene la reserva del rango y muestra el worker como activo en la web. Envía uno cada 2 minutos aproximadamente; el intervalo no debe superar los 30 minutos, o el pool recupera el rango.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | El puzzle del rango. |
Hex | cabecera | string | Sí | El rango que el worker escanea ahora. |
UserToken | cabecera | string (128 caracteres) | Sí | Tu token de minero. |
WorkerName | cabecera | string | Sí | El nombre de worker usado al pedir el rango (default si no se envió ninguno). |
Ejemplo de petición
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Ejemplo de respuesta
200 OK con el cuerpo vacío.
Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | {"error": "invalid_request"} | Una cabecera está vacía. |
401 | {"error": "invalid_user_token"} | Token desconocido o bloqueado. |
404 | {"error": "range_not_found"} | Este worker no tiene reservado un rango sin escanear con ese HEX en ese puzzle. |
429 | {"isSuccess": false, ...} | Límite de frecuencia: 360 por minuto por token. |
POST/puzzle/{puzzleCode}/save-private-key
Guarda en tu cuenta una clave privada hallada, cifrada. El cliente cifra la clave con la clave pública RSA que le diste; el sitio solo guarda el texto cifrado, que descifras con tu clave privada. La clave aparece en la página de claves halladas de tu panel.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | El puzzle al que pertenece la clave. |
UserToken | cabecera | string (128 caracteres) | Sí | Tu token de minero. |
Content-Type | cabecera | string | Sí | application/json. |
name | cuerpo | string | No | Una etiqueta, por ejemplo el nombre del worker. Se guarda como Puzzle71 - rig1. |
encryptedKey | cuerpo | string | Sí | La clave privada cifrada (el cliente la envía en base64). |
Ejemplo de petición
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>"}'Ejemplo de respuesta
200 OK Ten en cuenta que la propiedad es success, no isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
401 | {"error": "invalid_user_token"} | Token desconocido o bloqueado. |
400 | problem details | No se guardó nada: la misma clave ya está guardada en esta cuenta, o falta el cuerpo. |
429 | {"isSuccess": false, ...} | Límite de frecuencia: 10 cada 180 segundos por token. |
Datos de puzzles
Endpoints públicos de lectura sobre los puzzles del pool. No se necesita token. El objeto Puzzle y los demás objetos se describen al final de esta guía.
GET/puzzle
Los puzzles que están en el pool: los activos, los siguientes y el pool de prueba (y los completados que se conservan para el historial). En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle"Ejemplo de respuesta
200 OK Un array de objetos Puzzle, abreviado aquí 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": []
}
]Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
404 | [] | El pool no tiene ningún puzzle. |
GET/puzzle/all
Todos los puzzles de la base de datos, incluidos los completados. En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/all"Responde 200 con un array de objetos Puzzle.
GET/puzzle/available
Los puzzles que se pueden escanear en el pool. En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/available"Responde 200 con un array de objetos Puzzle.
GET/puzzle/default
El puzzle predeterminado: aquel al que recurre una petición de un puzzle completado. En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/default"Ejemplo de respuesta
200 OK Un único objeto 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": []
}Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
404 | {"error": "puzzle_not_found"} | No hay ningún puzzle predeterminado configurado. |
GET/puzzle/codes
Los números de los puzzles activos o siguientes, primero los puzzles normales y al final el pool de prueba. En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/codes"Ejemplo de respuesta
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
Un puzzle, leído de la base de datos. En caché durante 10 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | El número del puzzle. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/info"Ejemplo de respuesta
200 OK Un objeto Puzzle. Los valores de ejecución como rangesScannedLastHour solo se rellenan en los endpoints de listas.
{
"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": []
}Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
204 | vacío | No existe ese puzzle. |
GET/puzzle/{puzzleCode}/statistics
Todo lo que muestra la página del puzzle: totales, clasificaciones, workers activos, los últimos 200 rangos escaneados y un gráfico por horas. En caché durante 60 segundos (y el servidor guarda una copia durante 5 minutos).
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | Un puzzle activo (o el pool de prueba). |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Ejemplo de respuesta
200 OK Abreviado: aquí los arrays tienen un elemento, y lastRanges hasta 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"
}
}Para un puzzle que aún no está activo (los siguientes) solo se devuelven puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges y dateUpdated. Consulta Objeto Statistics para ver los campos.
Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | problem details | El puzzle no existe o no está activo ni es de los siguientes. |
GET/puzzle/{puzzleCode}/speed
La velocidad actual del pool en un puzzle. En caché durante 60 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | El número del puzzle. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/speed"Ejemplo de respuesta
200 OK Consulta CurrentSpeed. Un puzzle desconocido responde con los valores a cero, nunca con un error.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
Los workers que están escaneando ahora: los que tienen un rango al que hicieron ping en los últimos 30 minutos. El navegador no lo guarda en caché; el servidor guarda la respuesta durante 60 segundos. puzzleCode 0 significa el puzzle predeterminado.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | El número del puzzle. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/workers"Ejemplo de respuesta
200 OK Un array vacío cuando nadie está escaneando o el puzzle es desconocido.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
La misma lista que /workers (se mantiene como ruta aparte porque los clientes usan ambas).
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"Mismos parámetros y respuesta que GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
Las recompensas del pool de un puzzle activo: premios extra que los patrocinadores ponen en claves privadas dentro de los rangos (las más recientes primero, hasta 32). La clave privada de una recompensa solo se muestra después de resolverse. En caché durante 600 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | Un puzzle activo. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Ejemplo de respuesta
200 OK Consulta Reward. Un array vacío cuando el puzzle no tiene ninguna.
[
{
"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
}
]Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | problem details | El puzzle no está activo. |
GET/puzzle/{puzzleCode}/challenge
Los últimos puntos de inicio de desafío de un puzzle activo (los más recientes primero, hasta 32). En caché durante 600 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | Un puzzle activo. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Ejemplo de respuesta
200 OK Consulta Challenge. Un array vacío cuando no hay ninguno.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | problem details | El puzzle no está activo. |
GET/puzzle/{puzzleCode}/entrancefee
La cuota de entrada de un puzzle en USD, cuando está activada. En caché durante 300 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | Un puzzle activo con cuota de entrada. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Ejemplo de respuesta
200 OK
{
"fee": 25.0,
"puzzle": 71
}Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | problem details | El puzzle no está activo o no tiene cuota de entrada. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
Cuánto del puzzle está escaneado para cada prefijo de dos caracteres del HEX del rango (el mapa de calor de la página del puzzle). En caché durante 3600 segundos.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
puzzleCode | ruta | integer | Sí | Un puzzle activo. |
Ejemplo de petición
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Ejemplo de respuesta
200 OK Un elemento por prefijo, ordenado por hexStarts. La propiedad pertantageShow está mal escrita a propósito (congelada). A partir del 70 %, las cifras se quedan en el 70 % y isLimitExceeded es true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Errores
| Estado | Cuerpo | Cuándo |
|---|---|---|
400 | problem details | El puzzle no está activo. |
Datos del pool
Endpoints públicos de lectura sobre el pool en conjunto, la lista de GPU y el token BCPZ.
GET/pool/homepage
La lista de puzzles de la página de inicio: el mismo array que GET /puzzle, y el puzzle predeterminado lleva su speed. En caché durante 60 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/homepage"Responde 200 con un array de objetos Puzzle.
GET/pool/gpus
La lista de benchmarks de GPU, las más rápidas primero (claves por segundo en el pool). En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/gpus"Ejemplo de respuesta
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
brand | string | nvidia o amd. |
name | string | La tarjeta. |
keysPerSecond | number | Velocidad medida. |
dateUpdated | date | Última actualización. |
GET/pool/token-distribute-history
Las distribuciones diarias de BCPZ, las más recientes primero (hasta 180). En caché durante 300 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/token-distribute-history"Ejemplo de respuesta
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
id | integer | Número de distribución. |
dateProcces | date | Cuándo se ejecutó. El nombre está mal escrito y congelado. |
totalUsers | integer | Usuarios que recibieron tokens. |
totalAmount | number | BCPZ repartidos (1 por rango escaneado). |
description | string | Texto del resultado. |
GET/pool/token-top-50-holders
Las 50 cuentas que más BCPZ han ganado, con las direcciones de billetera abreviadas. En caché durante 600 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Ejemplo de respuesta
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
walletAddress | string | Dirección abreviada. |
balance | number | BCPZ actuales en la cuenta. |
total | number | BCPZ ganados en total. |
minted | number | BCPZ ya retirados a la red Polygon. |
GET/pool/token-mint-history
Los últimos retiros de BCPZ a la red Polygon, los más recientes primero (hasta 180). En caché durante 600 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/token-mint-history"Ejemplo de respuesta
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
walletAddress | string | Dirección abreviada de la cuenta. |
minted | number | BCPZ enviados. |
date | date | Cuándo se enviaron. |
txId | string | Hash de la transacción en Polygon. Se omite mientras la transferencia no se ha hecho. |
GET/pool/btc-price
El precio de Bitcoin en USD y EUR, de un exchange. En caché durante 600 segundos.
Ejemplo de petición
curl "https://btcpuzzle.info/api/pool/btc-price"Ejemplo de respuesta
200 OK Ambos valores son 0 cuando no se puede acceder a la fuente del precio.
{"usd":66739.06,"eur":60607.25}Feed en tiempo real (SignalR)
El pool publica cada rango reservado y terminado en un hub de SignalR. La web lo usa para la página de estado en vivo. El hub es público, no necesita token y solo envía: no hay métodos que un cliente pueda llamar.
| URL del hub | https://btcpuzzle.info/api/hex_socket |
| Host antiguo | https://api.btcpuzzle.info/hex_socket |
| Protocolo | SignalR con el protocolo JSON predeterminado; se ofrecen WebSockets, Server-Sent Events y Long Polling. |
| Evento | PoolStatus |
| Límite | La petición de negociación cuenta para el límite por IP. El hub en sí no tiene límite una vez conectado. |
Conexión
Usa una biblioteca cliente de SignalR (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Por debajo, primero negocia:
Ejemplo de petición
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"Ejemplo de respuesta
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 argumento, un objeto JSON. El evento se envía a todos los clientes conectados cuando se reparte un rango y cuando un rango se marca como escaneado.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Campo | Tipo | Descripción |
|---|---|---|
hex | string | El HEX del rango con su tercer carácter sustituido por X. |
walletAddress | string | Dirección abreviada de la cuenta. |
workerName | string o null | El nombre del worker (default si no se envió ninguno). En scanned es el nombre enviado con la petición de marcado, que puede ser null. |
puzzleCode | integer | El puzzle del rango. |
status | string | holded después de repartir un rango, scanned después de marcar un rango. La grafía está congelada. |
Los eventos se entregan mientras la conexión está abierta; no se reenvía nada tras una reconexión. Cuando el operador desactiva el feed en vivo, se rechazan las conexiones.
Objetos
Objeto Puzzle
Lo devuelven los endpoints de listas de puzzles y /puzzle/{puzzleCode}/info. Las propiedades sin valor se omiten.
| Campo | Tipo | Descripción |
|---|---|---|
id | integer | Id de la base de datos (el mismo que code en los puzzles del sistema antiguo). |
name | string | Por ejemplo, Puzzle 71. |
code | integer | El número del puzzle. |
hexStart, hexEnd | string | Primera y última clave privada del puzzle, en hexadecimal. |
targetWalletAddress | string | La dirección que guarda la recompensa. |
hexRangeLength | integer | Longitud del HEX de rango que reparte el pool (la parte de la clave que elige). |
reward | number | La recompensa en BTC. |
hexStartPool, hexEndPool | string | Primer y último HEX de rango. Vacío salvo que el puzzle esté en el pool. |
totalRanges | integer | Número de rangos del puzzle. 0 salvo que el puzzle esté en el pool. |
percentage | number | Porcentaje de los rangos que están escaneados. |
totalScanned, rangesScannedLastHour | integer | Rangos escaneados en total y en la última hora (se rellenan en los endpoints de listas). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | varios | Cifras finales de un puzzle completado; statisticsFoundBy solo aparece cuando se conoce. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | Número de claves privadas (menos una) de un rango. Los dos difieren cuando los rangos abarcan varios ids. |
rangesPerKey | integer | Cuántos ids de rango abarca un rango (1 en la mayoría de los puzzles). |
workloadStart, workloadEnd | string | La parte de la clave privada que un cliente escanea tras el HEX del rango: consulta GET range. |
customWorkloadStart, customWorkloadEnd | string | Aparece cuando el puzzle usa una carga de trabajo personalizada. |
dateStart, dateEnd | date | Fechas previstas del puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | El estado del puzzle: terminado, anunciado, escaneable ahora, predeterminado, pool de prueba, en el pool. |
isEntranceFeeActive, entranceFee | boolean, number | Si la cuota de entrada está activada y su precio en USD (0 si está desactivada). |
nextScanAllowedInMinutes | integer | Cuánto tiempo se reserva un rango repartido antes de poder dárselo a otra persona. |
challenges | array | El último desafío, o un array vacío. |
privateKey, publicKey | string | Solo en puzzles resueltos. |
rewards, speed | array, object | Solo aparece en algunos endpoints. |
Objeto Statistics
| Campo | Tipo | Descripción |
|---|---|---|
puzzle | object | Las cifras principales del puzzle (nombre, código, número de rangos, carga de trabajo, estado, recompensa). |
scannedLast24H | integer | Rangos escaneados en las últimas 24 horas. |
entranceFeesPaidTotal | number | Cuotas de entrada pagadas por el puzzle, en USD. |
topWorkersAlltime | array | Hasta 50 de {userId, walletAddress, totalScanned}; userId es 0 aquí. |
topWorkersLast24h | array | Lo mismo para las últimas 24 horas. |
activeWorkers | array | {walletAddress, workerName} de los workers que hicieron ping en los últimos 30 minutos. |
challenges | array | Hasta 32 desafíos. |
kingdom | object | El rey del puzzle: walletAddress, message, image y isPublished. |
topSpeed | object | La mejor hora de la historia: date, scanned rangos y keysPerSecond. |
chartData | array | El último mes por horas, lo más reciente primero: date, dateOnly, hoursOnly y rangesScanned. |
lastRanges | array | Los últimos 200 rangos escaneados, los más recientes primero: hex (enmascarado), walletAddress (enmascarado), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds y totalSeconds. |
rewards | array | Recompensas del puzzle (sin claves privadas). |
dateUpdated | date | Cuándo se calcularon las cifras. |
currentSpeed | object | CurrentSpeed. |
Objeto CurrentSpeed
| Campo | Tipo | Descripción |
|---|---|---|
activeWorkerCount | integer | Workers que escanearon en las últimas 6 horas e hicieron ping en la última hora. |
keysPerSecondFormatted | string | La velocidad con una unidad: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s y así sucesivamente. |
keysPerSecondRaw | string | La velocidad en claves por segundo como texto entero. |
Objeto Challenge
| Campo | Tipo | Descripción |
|---|---|---|
hex | string | Los caracteres iniciales que escanea cada participante del desafío. |
dateCreated | date | Cuándo empezó el desafío. |
puzzleId | integer | El puzzle. |
Objeto Reward
| Campo | Tipo | Descripción |
|---|---|---|
id, puzzleCode, puzzleId | integer | Identificación. |
targetAddress | string | La dirección de la clave de la recompensa. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | Qué es el premio y quién lo da. Las propiedades sin valor se omiten. |
privateKey | string | Solo aparece después de resolverse la recompensa. |
dateCreated, dateSolved | date | Cuándo se creó y se resolvió (0001-01-01T00:00:00 mientras no se resuelve). |
Cambios respecto a la documentación antigua
No ha cambiado nada del contrato: todos los endpoints, cabeceras, campos y códigos de error de la API antigua siguen funcionando y respondiendo igual. Esta guía sustituye a la página antigua, que describía tres endpoints. Lo nuevo:
- Se documentan los endpoints de datos públicos, el feed en tiempo real, los códigos de error y los límites de frecuencia. La página antigua no los mencionaba.
- Correcciones del texto antiguo: la cabecera
UserTokende la petición de marcado es el token de minero (la página antigua la llamaba dirección de billetera); el intervalo de ping es de unos 2 minutos y como máximo 30 minutos, y el límite es de 360 pings por minuto por token, no 60 por hora; el puzzle del pool de prueba es el38. - La URL base es
https://btcpuzzle.info/api; el host antiguoapi.btcpuzzle.infosigue funcionando. - El hub de SignalR ya no tiene ningún método de cliente a servidor, así que nadie puede enviar eventos falsos. El evento en sí no ha cambiado.
- Ahora también se reparte el último rango libre de un puzzle, y una ventana
CustomRangemuy estrecha se amplía para que no se pueda elegir un rango pidiendo exactamente uno. - Las estadísticas públicas ya no muestran la dirección IP de un minero.