Documentación de la API

Crea tu propio cliente para el pool. Todos los endpoints, con peticiones, respuestas y errores.

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

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

Por 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, usertoken y userToken son la misma cabecera). Solo POST /puzzle/{puzzleCode}/save-private-key tiene 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 rangeContainsKeys son 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 por X (3AB8443 pasa a ser 3AX8443).

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 aSe cuenta porLímite
GET /puzzle/{puzzleCode}/rangeUserToken120 peticiones cada 60 segundos
PUT /puzzle/{puzzleCode}/rangeUserToken360 peticiones cada 60 segundos
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 peticiones cada 60 segundos
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 peticiones cada 180 segundos
Cualquier otro endpointDirección IP20 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.

EstadoCuerpoSignificado
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).
400problema de validaciónFalta 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.
400detalles del problemaUn 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

NombreEnTipoObligatorioDescripción
puzzleCoderutainteger (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.
UserTokencabecerastring (128 caracteres)SíTu token de minero.
WorkerNamecabecerastring (de 1 a 16 caracteres)NoEl nombre de este worker. Solo letras y dígitos. Se guarda como default si no envías ninguno.
SecurityHashcabecerastringNoTexto libre que se guarda con el rango. Opcional.
CustomRangecabecerastringNoLimita 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

CampoTipoDescripción
hexstringEl rango que hay que escanear, en mayúsculas y sin relleno. Es el principio de las claves privadas del rango.
puzzleCodeintegerEl puzzle al que pertenece el rango (el puzzle predeterminado si el que pediste está completado).
workloadStartstringSe añade a hex para obtener la primera clave privada del rango.
workloadEndstringSe 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.
targetAddressstringLa dirección del puzzle que buscas. Escanéala junto con las direcciones de prueba.
proofOfWorkAddressesarray de 6 stringsDirecciones 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

EstadoCuerpoCuá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).
400validation problemCabecera 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:

  1. Escribe cada clave privada como 64 caracteres hexadecimales en mayúsculas, rellenados con ceros a la izquierda.
  2. Concatena las seis cadenas, en el orden de las direcciones, sin nada entre ellas.
  3. Calcula el SHA-256 del texto UTF-8 y escríbelo como 64 caracteres hexadecimales en minúsculas. Ese es el HashedProofKey de 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 ) )
               = 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87

La 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

NombreEnTipoObligatorioDescripción
puzzleCoderutainteger (1 a 160)SíEl puzzle del rango.
UserTokencabecerastring (128 caracteres)SíTu token de minero.
HEXcabecerastringSíEl hex del rango que escaneaste, tal como lo devolvió el pool. Ejemplo: 3AB8443.
HashedProofKeycabecerastringSíLa prueba de trabajo: consulta Prueba de trabajo.
WorkerNamecabecerastring (de 1 a 16 caracteres)NoEl worker que escaneó el rango.
GPUNamecabecerastringNoEl modelo de tarjeta gráfica. Se usa para las estadísticas públicas.
GPUCountcabeceraintegerNoNúmero de tarjetas del worker. Predeterminado 1.
IsForceContinuecabecerabooleanNoPonlo 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

EstadoCuerpoCuándo
400{"isSuccess": false}Cualquier rechazo: prueba incorrecta, rango desconocido, un rango ya marcado, cuenta bloqueada, puzzle inactivo.
400validation problemFalta 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSíEl puzzle del rango.
HexcabecerastringSíEl rango que el worker escanea ahora.
UserTokencabecerastring (128 caracteres)SíTu token de minero.
WorkerNamecabecerastringSí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

EstadoCuerpoCuá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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSíEl puzzle al que pertenece la clave.
UserTokencabecerastring (128 caracteres)SíTu token de minero.
Content-TypecabecerastringSíapplication/json.
namecuerpostringNoUna etiqueta, por ejemplo el nombre del worker. Se guarda como Puzzle71 - rig1.
encryptedKeycuerpostringSí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

EstadoCuerpoCuándo
401{"error": "invalid_user_token"}Token desconocido o bloqueado.
400problem detailsNo 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

EstadoCuerpoCuá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

EstadoCuerpoCuá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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
204vacíoNo 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
400problem detailsEl 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
400problem detailsEl 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
400problem detailsEl 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
400problem detailsEl 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

NombreEnTipoObligatorioDescripción
puzzleCoderutaintegerSí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

EstadoCuerpoCuándo
400problem detailsEl 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

CampoTipoDescripción
brandstringnvidia o amd.
namestringLa tarjeta.
keysPerSecondnumberVelocidad medida.
dateUpdateddateÚ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

CampoTipoDescripción
idintegerNúmero de distribución.
dateProccesdateCuándo se ejecutó. El nombre está mal escrito y congelado.
totalUsersintegerUsuarios que recibieron tokens.
totalAmountnumberBCPZ repartidos (1 por rango escaneado).
descriptionstringTexto 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

CampoTipoDescripción
walletAddressstringDirección abreviada.
balancenumberBCPZ actuales en la cuenta.
totalnumberBCPZ ganados en total.
mintednumberBCPZ 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

CampoTipoDescripción
walletAddressstringDirección abreviada de la cuenta.
mintednumberBCPZ enviados.
datedateCuándo se enviaron.
txIdstringHash 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 hubhttps://btcpuzzle.info/api/hex_socket
Host antiguohttps://api.btcpuzzle.info/hex_socket
ProtocoloSignalR con el protocolo JSON predeterminado; se ofrecen WebSockets, Server-Sent Events y Long Polling.
EventoPoolStatus
LímiteLa 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"
}
CampoTipoDescripción
hexstringEl HEX del rango con su tercer carácter sustituido por X.
walletAddressstringDirección abreviada de la cuenta.
workerNamestring o nullEl 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.
puzzleCodeintegerEl puzzle del rango.
statusstringholded 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.

CampoTipoDescripción
idintegerId de la base de datos (el mismo que code en los puzzles del sistema antiguo).
namestringPor ejemplo, Puzzle 71.
codeintegerEl número del puzzle.
hexStart, hexEndstringPrimera y última clave privada del puzzle, en hexadecimal.
targetWalletAddressstringLa dirección que guarda la recompensa.
hexRangeLengthintegerLongitud del HEX de rango que reparte el pool (la parte de la clave que elige).
rewardnumberLa recompensa en BTC.
hexStartPool, hexEndPoolstringPrimer y último HEX de rango. Vacío salvo que el puzzle esté en el pool.
totalRangesintegerNúmero de rangos del puzzle. 0 salvo que el puzzle esté en el pool.
percentagenumberPorcentaje de los rangos que están escaneados.
totalScanned, rangesScannedLastHourintegerRangos escaneados en total y en la última hora (se rellenan en los endpoints de listas).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByvariosCifras finales de un puzzle completado; statisticsFoundBy solo aparece cuando se conoce.
rangeContainsKeys, rangeContainsKeyByDefaultintegerNúmero de claves privadas (menos una) de un rango. Los dos difieren cuando los rangos abarcan varios ids.
rangesPerKeyintegerCuántos ids de rango abarca un rango (1 en la mayoría de los puzzles).
workloadStart, workloadEndstringLa parte de la clave privada que un cliente escanea tras el HEX del rango: consulta GET range.
customWorkloadStart, customWorkloadEndstringAparece cuando el puzzle usa una carga de trabajo personalizada.
dateStart, dateEnddateFechas previstas del puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanEl estado del puzzle: terminado, anunciado, escaneable ahora, predeterminado, pool de prueba, en el pool.
isEntranceFeeActive, entranceFeeboolean, numberSi la cuota de entrada está activada y su precio en USD (0 si está desactivada).
nextScanAllowedInMinutesintegerCuánto tiempo se reserva un rango repartido antes de poder dárselo a otra persona.
challengesarrayEl último desafío, o un array vacío.
privateKey, publicKeystringSolo en puzzles resueltos.
rewards, speedarray, objectSolo aparece en algunos endpoints.

Objeto Statistics

CampoTipoDescripción
puzzleobjectLas cifras principales del puzzle (nombre, código, número de rangos, carga de trabajo, estado, recompensa).
scannedLast24HintegerRangos escaneados en las últimas 24 horas.
entranceFeesPaidTotalnumberCuotas de entrada pagadas por el puzzle, en USD.
topWorkersAlltimearrayHasta 50 de {userId, walletAddress, totalScanned}; userId es 0 aquí.
topWorkersLast24harrayLo mismo para las últimas 24 horas.
activeWorkersarray{walletAddress, workerName} de los workers que hicieron ping en los últimos 30 minutos.
challengesarrayHasta 32 desafíos.
kingdomobjectEl rey del puzzle: walletAddress, message, image y isPublished.
topSpeedobjectLa mejor hora de la historia: date, scanned rangos y keysPerSecond.
chartDataarrayEl último mes por horas, lo más reciente primero: date, dateOnly, hoursOnly y rangesScanned.
lastRangesarrayLos ú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.
rewardsarrayRecompensas del puzzle (sin claves privadas).
dateUpdateddateCuándo se calcularon las cifras.
currentSpeedobjectCurrentSpeed.

Objeto CurrentSpeed

CampoTipoDescripción
activeWorkerCountintegerWorkers que escanearon en las últimas 6 horas e hicieron ping en la última hora.
keysPerSecondFormattedstringLa velocidad con una unidad: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s y así sucesivamente.
keysPerSecondRawstringLa velocidad en claves por segundo como texto entero.

Objeto Challenge

CampoTipoDescripción
hexstringLos caracteres iniciales que escanea cada participante del desafío.
dateCreateddateCuándo empezó el desafío.
puzzleIdintegerEl puzzle.

Objeto Reward

CampoTipoDescripción
id, puzzleCode, puzzleIdintegerIdentificación.
targetAddressstringLa dirección de la clave de la recompensa.
rewardContent, rewardDescription, provider, providerDesc, brandstringQué es el premio y quién lo da. Las propiedades sin valor se omiten.
privateKeystringSolo aparece después de resolverse la recompensa.
dateCreated, dateSolveddateCuá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 UserToken de 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 el 38.
  • La URL base es https://btcpuzzle.info/api; el host antiguo api.btcpuzzle.info sigue 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 CustomRange muy 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.

Invítame a un café

Puzzles del pool

Lo que escanea ahora el pool, lo que viene después y los puzzles en los que ya ha trabajado.

Escaneando1

Siguiente2

Escaneados antes4

Los 160 puzzles