Visão geral
A API do btcpuzzle.info é com quem o cliente do pool conversa. Ela distribui intervalos de chaves para escanear, recebe o resultado de uma varredura e publica as estatísticas públicas do pool. O btcpuzzle.info é de código aberto e qualquer pessoa pode escrever um cliente: este guia descreve cada endpoint público, os dados a enviar, os dados que você recebe e os erros que pode encontrar. Dúvidas: support@btcpuzzle.info.
Esta API está congelada de propósito: mineradores e ferramentas de terceiros dependem dela. Caminhos, cabeçalhos, nomes de campos (incluindo algumas grafias antigas, como dateProcces e holded) e códigos de erro não mudam. Novos campos podem ser adicionados às respostas, então ignore os campos que você não conhece.
URL base
Todos os caminhos deste guia são relativos à URL base:
https://btcpuzzle.info/apiClientes escritos antes da mudança do site podem continuar usando o host antigo, com os mesmos caminhos e sem o prefixo /api:
https://api.btcpuzzle.infoPor exemplo, GET https://btcpuzzle.info/api/puzzle/codes e GET https://api.btcpuzzle.info/puzzle/codes respondem da mesma forma. Novos clientes devem usar a URL base com /api.
Início rápido
Crie uma conta gratuita no btcpuzzle.info, copie seu token de minerador no painel e peça um intervalo:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Escaneie o intervalo retornado junto com os seis endereços de prova, envie a prova com PUT /puzzle/71/range e repita. Entre as duas chamadas, envie um ping de tempos em tempos para que o pool saiba que o worker está ativo.
Convenções
Versionamento
Há uma única versão e nenhuma versão na URL. O contrato da API antiga é mantido exatamente; veja Mudanças em relação à documentação antiga.
Autenticação
Os endpoints do minerador são identificados pelo cabeçalho UserToken: o token de minerador de 128 caracteres da sua conta. Não há outro login nem sessão para eles. Você pode criar um novo token na sua conta a qualquer momento; o antigo para de funcionar na hora. Mantenha o token em sigilo: quem o tiver escaneia em seu nome.
Todos os endpoints de dados (puzzles, estatísticas, pool, token) são públicos e não precisam de token.
Requisições e respostas
- Nos endpoints do minerador, os dados da requisição vão em cabeçalhos HTTP, não na query string nem no corpo. Os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas (
UserToken,usertokeneuserTokensão o mesmo cabeçalho). ApenasPOST /puzzle/{puzzleCode}/save-private-keytem um corpo JSON (Content-Type: application/json). - As respostas são JSON em UTF-8 com nomes de propriedades em camelCase. Propriedades sem valor são omitidas; a API nunca escreve um
nullem JSON. Não dependa da indentação. - As datas estão em ISO 8601, em UTC (
2026-11-18T08:28:25.8176144Z). Valores monetários e quantidades são números JSON. - Números grandes como
rangeContainsKeyssão inteiros de 64 bits sem sinal e podem ser maiores que 2^53: em linguagens que usam doubles, leia-os como inteiros de 64 bits ou como strings. - Os endereços de carteira nos dados públicos são abreviados (primeiros 8 caracteres,
..., últimos 8) e o terceiro caractere do HEX de um intervalo é substituído porX(3AB8443vira3AX8443).
Limites de taxa
Os limites abaixo são os padrões atuais. Eles são contados em uma janela de tempo fixa; o operador pode ajustá-los, então leia a resposta 429 em vez de fixar os números no código.
| Aplica-se a | Contado por | Limite |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 requisições a cada 60 segundos |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 requisições a cada 60 segundos |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 requisições a cada 60 segundos |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 requisições a cada 180 segundos |
| Todos os outros endpoints | Endereço IP | 20 requisições por segundo para cada endpoint, 200 por segundo no total |
Uma requisição acima do limite recebe como resposta 429 Too Many Requests, um cabeçalho Retry-After e este corpo:
{
"isSuccess": false,
"details": "Quota exceeded."
}Erros
As falhas usam os códigos de status abaixo. O corpo depende do endpoint, então verifique primeiro o código de status.
| Status | Corpo | Significado |
|---|---|---|
400 | {"error": "<code>"} | Um endpoint do minerador recusou a requisição. O código diz o motivo: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (a grafia é histórica), invalid_request. |
400 | {"isSuccess": false} | A requisição de marcação de um intervalo foi recusada (prova errada, intervalo desconhecido ou já escaneado, usuário banido, puzzle inativo). |
400 | problema de validação | Um cabeçalho obrigatório está ausente ou é inválido, ou o número do puzzle está fora de 1 a 160. É um objeto application/problem+json cujo errors lista os nomes com problema. |
400 | detalhes do problema | Um endpoint de dados públicos não tem o que responder para este puzzle (puzzle desconhecido ou inativo). application/problem+json com type, title, status e traceId. |
401 | {"error": "invalid_user_token"} | O token de minerador é desconhecido ou a conta está banida (ping e save-private-key). |
404 | {"error": "range_not_found"} | O intervalo do ping não está reservado para este worker. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Limite de taxa. Aguarde Retry-After segundos. |
Exemplo de problema de validação (GET /puzzle/71/range sem o cabeçalho UserToken):
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"UserToken": [
"The UserToken field is required."
]
},
"traceId": "00-e3fc704f799663ec7f42c140ab4c996d-8592b3515c26a5c2-00"
}Cache e CORS
Os endpoints de dados públicos enviam Cache-Control: public, max-age=N; o valor aparece junto de cada endpoint, e uma cópia em cache é compartilhada por todos os chamadores, então consultar com frequência maior que N segundos só retorna os mesmos dados. Os endpoints do minerador nunca vão para cache. Navegadores podem chamar a API a partir de https://btcpuzzle.info, https://www.btcpuzzle.info e http://localhost:3000 (este último existe para o desenvolvimento local do frontend antigo); clientes nativos não são afetados pelo CORS.
Endpoints do minerador
As três chamadas do ciclo de varredura: pegar um intervalo, enviar pings enquanto o escaneia e marcá-lo como escaneado. Uma quarta chamada armazena uma chave encontrada. As quatro usam o cabeçalho UserToken.
GET/puzzle/{puzzleCode}/range
Entrega um intervalo livre aleatório do puzzle e o reserva para você. Ninguém mais recebe um intervalo reservado para você; se você não o marcar, ele volta ao pool depois de um tempo (um ping prolonga a reserva).
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro (1 a 160) | Sim | O puzzle a escanear, por exemplo 71. 38 é o pool de teste. GET /puzzle/codes lista os códigos. Um puzzle concluído é atendido silenciosamente pelo puzzle padrão, e a resposta informa em puzzleCode qual puzzle você recebeu. |
UserToken | header | string (128 caracteres) | Sim | Seu token de minerador. |
WorkerName | header | string (1 a 16 caracteres) | Não | O nome deste worker. Apenas letras e números. Armazenado como default quando você não envia nenhum. |
SecurityHash | header | string | Não | Texto livre guardado com o intervalo. Opcional. |
CustomRange | header | string | Não | Limita o intervalo que você recebe: um prefixo do HEX (2D, 3BA) ou start:end (3400000:38FFFFF). none ou nenhum cabeçalho significa qualquer intervalo. Uma janela muito estreita é ampliada pelo pool, então você pode receber um intervalo diferente do que indicou. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemplo de resposta
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
hex | string | O intervalo a escanear, em maiúsculas e sem preenchimento. É o início das chaves privadas do intervalo. |
puzzleCode | inteiro | O puzzle ao qual o intervalo pertence (o puzzle padrão quando o que você pediu está concluído). |
workloadStart | string | Anexado a hex para obter a primeira chave privada do intervalo. |
workloadEnd | string | Anexado a hex para obter a última chave privada do intervalo. Seu comprimento pode ser maior que o de workloadStart em puzzles cujos intervalos abrangem vários ids. |
targetAddress | string | O endereço do puzzle que você procura. Escaneie-o junto com os endereços de prova. |
proofOfWorkAddresses | array de 6 strings | Endereços de seis chaves privadas que o pool colocou dentro do intervalo. Encontre as chaves privadas deles para provar a varredura: veja Prova de trabalho. |
No exemplo acima, o intervalo vai de 3AB8443 + 00000000000 = 3AB844300000000000 a 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Chaves privadas têm 64 caracteres hexadecimais; complete com zeros à esquerda.
Erros
| Status | Corpo | Quando |
|---|---|---|
400 | {"error": "invalid_puzzle"} | O puzzle não existe ou não está ativo. |
400 | {"error": "invalid_user_token"} | O token é desconhecido ou está banido. |
400 | {"error": "too_much_request"} | Você tem intervalos reservados demais que ainda não escaneou, ou pede mais rápido do que conclui. Escaneie o que tem reservado; intervalos reservados voltam ao pool depois de pouco tempo. |
400 | {"error": "not_eligable"} | O puzzle tem taxa de entrada e você ainda não cumpre as condições dela. |
400 | {"error": "reached_of_keyspace"} | Não resta nenhum intervalo livre (ou nenhum que se encaixe no seu CustomRange). |
400 | validation problem | Cabeçalho ausente ou malformado, ou número de puzzle fora de 1 a 160. |
429 | {"isSuccess": false, ...} | Limite de taxa: 120 por minuto por token. |
Prova de trabalho
O pool quer ter certeza de que você realmente escaneou o intervalo. Para cada intervalo, ele escolhe seis chaves privadas dentro dele e retorna apenas os endereços delas (proofOfWorkAddresses). Enquanto escaneia o intervalo em busca do endereço alvo, procure também esses seis endereços. Quando tiver encontrado as seis chaves privadas:
- Escreva cada chave privada com 64 caracteres hexadecimais maiúsculos, completando com zeros à esquerda.
- Concatene as seis strings, na ordem dos endereços, sem nada entre elas.
- Calcule o SHA-256 do texto UTF-8 e escreva-o com 64 caracteres hexadecimais minúsculos. Esse é o
HashedProofKeyda requisição de marcação.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87A prova é diferente para cada intervalo. Hoje são seis endereços de prova; leia o tamanho de proofOfWorkAddresses em vez de presumir.
PUT/puzzle/{puzzleCode}/range
Marca um intervalo como escaneado. O pool verifica a prova e, se estiver correta, conta o intervalo como concluído para você. Um intervalo só pode ser marcado uma vez.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro (1 a 160) | Sim | O puzzle do intervalo. |
UserToken | header | string (128 caracteres) | Sim | Seu token de minerador. |
HEX | header | string | Sim | O hex do intervalo que você escaneou, como o pool o retornou. Exemplo: 3AB8443. |
HashedProofKey | header | string | Sim | A prova de trabalho: veja Prova de trabalho. |
WorkerName | header | string (1 a 16 caracteres) | Não | O worker que escaneou o intervalo. |
GPUName | header | string | Não | O modelo da placa de vídeo. Usado nas estatísticas públicas. |
GPUCount | header | inteiro | Não | Número de placas do worker. Padrão 1. |
IsForceContinue | header | booleano | Não | Defina quando o worker continuou mesmo tendo chegado ao fim do seu espaço de chaves. Padrão false. |
Exemplo de requisição
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"Exemplo de resposta
200 OK
{
"isSuccess": true
}Erros
| Status | Corpo | Quando |
|---|---|---|
400 | {"isSuccess": false} | Qualquer recusa: prova errada, intervalo desconhecido, intervalo já marcado, conta banida, puzzle inativo. |
400 | validation problem | Um cabeçalho obrigatório está ausente ou malformado. |
429 | {"isSuccess": false, ...} | Limite de taxa: 360 por minuto por token. |
PATCH/puzzle/{puzzleCode}/range/ping
Informa ao pool que um worker ainda está escaneando seu intervalo. Um ping mantém a reserva do intervalo e mostra o worker como ativo no site. Envie um a cada 2 minutos, aproximadamente; o intervalo entre pings não pode passar de 30 minutos, ou o pool retoma o intervalo.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | O puzzle do intervalo. |
Hex | header | string | Sim | O intervalo que o worker está escaneando agora. |
UserToken | header | string (128 caracteres) | Sim | Seu token de minerador. |
WorkerName | header | string | Sim | O nome do worker usado quando o intervalo foi solicitado (default se nenhum foi enviado). |
Exemplo de requisição
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Exemplo de resposta
200 OK com corpo vazio.
Erros
| Status | Corpo | Quando |
|---|---|---|
400 | {"error": "invalid_request"} | Um cabeçalho está vazio. |
401 | {"error": "invalid_user_token"} | Token desconhecido ou banido. |
404 | {"error": "range_not_found"} | Este worker não tem reservado nenhum intervalo não escaneado com esse HEX nesse puzzle. |
429 | {"isSuccess": false, ...} | Limite de taxa: 360 por minuto por token. |
POST/puzzle/{puzzleCode}/save-private-key
Armazena na sua conta, criptografada, uma chave privada encontrada. O cliente criptografa a chave com a chave pública RSA que você forneceu; o site guarda apenas o texto criptografado, que você descriptografa com sua chave privada. A chave aparece na página de chaves encontradas do seu painel.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | O puzzle ao qual a chave pertence. |
UserToken | header | string (128 caracteres) | Sim | Seu token de minerador. |
Content-Type | header | string | Sim | application/json. |
name | body | string | Não | Um rótulo, por exemplo o nome do worker. Armazenado como Puzzle71 - rig1. |
encryptedKey | body | string | Sim | A chave privada criptografada (o cliente a envia em base64). |
Exemplo de requisição
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>"}'Exemplo de resposta
200 OK Observe que a propriedade é success, não isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Erros
| Status | Corpo | Quando |
|---|---|---|
401 | {"error": "invalid_user_token"} | Token desconhecido ou banido. |
400 | problem details | Nada foi salvo: a mesma chave já está armazenada para esta conta, ou o corpo está ausente. |
429 | {"isSuccess": false, ...} | Limite de taxa: 10 a cada 180 segundos por token. |
Dados dos puzzles
Endpoints públicos de leitura sobre os puzzles do pool. Nenhum token é necessário. O objeto Puzzle e os outros objetos são descritos no fim deste guia.
GET/puzzle
Os puzzles que estão no pool: os ativos, os próximos e o pool de teste (e os concluídos mantidos para o histórico). Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle"Exemplo de resposta
200 OK Um array de objetos Puzzle, reduzido aqui a um.
[
{
"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": []
}
]Erros
| Status | Corpo | Quando |
|---|---|---|
404 | [] | O pool não tem nenhum puzzle. |
GET/puzzle/all
Todos os puzzles do banco de dados, incluindo os concluídos. Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/all"Responde 200 com um array de objetos Puzzle.
GET/puzzle/available
Os puzzles que podem ser escaneados no pool. Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/available"Responde 200 com um array de objetos Puzzle.
GET/puzzle/default
O puzzle padrão: aquele para o qual uma requisição de um puzzle concluído é redirecionada. Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/default"Exemplo de resposta
200 OK Um ú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": []
}Erros
| Status | Corpo | Quando |
|---|---|---|
404 | {"error": "puzzle_not_found"} | Nenhum puzzle padrão está definido. |
GET/puzzle/codes
Os números dos puzzles ativos ou próximos, primeiro os puzzles normais e por último o pool de teste. Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/codes"Exemplo de resposta
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
Um puzzle, lido do banco de dados. Em cache por 10 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | O número do puzzle. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/info"Exemplo de resposta
200 OK Um objeto Puzzle. Valores de tempo de execução como rangesScannedLastHour só são preenchidos nos endpoints de lista.
{
"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": []
}Erros
| Status | Corpo | Quando |
|---|---|---|
204 | vazio | Esse puzzle não existe. |
GET/puzzle/{puzzleCode}/statistics
Tudo o que a página do puzzle mostra: totais, rankings, workers ativos, os últimos 200 intervalos escaneados e um gráfico por hora. Em cache por 60 segundos (e o servidor guarda uma cópia por 5 minutos).
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | Um puzzle ativo (ou o pool de teste). |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Exemplo de resposta
200 OK Abreviado: aqui os arrays têm um elemento, e lastRanges até 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 um puzzle que ainda não está ativo (os próximos), apenas puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges e dateUpdated são retornados. Veja o objeto Statistics para os campos.
Erros
| Status | Corpo | Quando |
|---|---|---|
400 | problem details | O puzzle não existe ou não está ativo nem é o próximo. |
GET/puzzle/{puzzleCode}/speed
A velocidade atual do pool em um puzzle. Em cache por 60 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | O número do puzzle. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/speed"Exemplo de resposta
200 OK Veja CurrentSpeed. Um puzzle desconhecido responde com valores zero, nunca com erro.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
Os workers que estão escaneando agora: os que têm um intervalo com ping nos últimos 30 minutos. Não vai para o cache do navegador; o servidor guarda a resposta por 60 segundos. puzzleCode 0 significa o puzzle padrão.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | O número do puzzle. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/workers"Exemplo de resposta
200 OK Um array vazio quando ninguém está escaneando ou o puzzle é desconhecido.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
A mesma lista de /workers (mantida como caminho separado porque os clientes usam os dois).
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"Mesmos parâmetros e resposta de GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
As recompensas do pool de um puzzle ativo: prêmios extras que patrocinadores colocam em chaves privadas dentro dos intervalos (das mais recentes para as mais antigas, até 32). A chave privada de uma recompensa só é mostrada depois de resolvida. Em cache por 600 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | Um puzzle ativo. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Exemplo de resposta
200 OK Veja Reward. Um array vazio quando o puzzle não tem nenhuma.
[
{
"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
}
]Erros
| Status | Corpo | Quando |
|---|---|---|
400 | problem details | O puzzle não está ativo. |
GET/puzzle/{puzzleCode}/challenge
Os pontos de partida mais recentes dos desafios de um puzzle ativo (dos mais recentes para os mais antigos, até 32). Em cache por 600 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | Um puzzle ativo. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Exemplo de resposta
200 OK Veja Challenge. Um array vazio quando não há nenhum.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Erros
| Status | Corpo | Quando |
|---|---|---|
400 | problem details | O puzzle não está ativo. |
GET/puzzle/{puzzleCode}/entrancefee
A taxa de entrada de um puzzle em USD, quando a taxa está ativa. Em cache por 300 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | Um puzzle ativo com taxa de entrada. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Exemplo de resposta
200 OK
{
"fee": 25.0,
"puzzle": 71
}Erros
| Status | Corpo | Quando |
|---|---|---|
400 | problem details | O puzzle não está ativo ou não tem taxa de entrada. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
Quanto do puzzle está escaneado para cada prefixo de dois caracteres do HEX do intervalo (o mapa de calor da página do puzzle). Em cache por 3.600 segundos.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
puzzleCode | path | inteiro | Sim | Um puzzle ativo. |
Exemplo de requisição
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Exemplo de resposta
200 OK Um elemento por prefixo, ordenado por hexStarts. A propriedade pertantageShow tem a grafia errada de propósito (congelada). A partir de 70%, os números param em 70% e isLimitExceeded é true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Erros
| Status | Corpo | Quando |
|---|---|---|
400 | problem details | O puzzle não está ativo. |
Dados do pool
Endpoints públicos de leitura sobre o pool como um todo, a lista de GPUs e o token BCPZ.
GET/pool/homepage
A lista de puzzles da página inicial: o mesmo array de GET /puzzle, e o puzzle padrão traz sua speed. Em cache por 60 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/homepage"Responde 200 com um array de objetos Puzzle.
GET/pool/gpus
A lista de benchmark de GPUs, das mais rápidas para as mais lentas (chaves por segundo no pool). Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/gpus"Exemplo de resposta
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
brand | string | nvidia ou amd. |
name | string | A placa. |
keysPerSecond | número | Velocidade medida. |
dateUpdated | data | Última atualização. |
GET/pool/token-distribute-history
As distribuições diárias de BCPZ, das mais recentes para as mais antigas (até 180). Em cache por 300 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/token-distribute-history"Exemplo de resposta
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | inteiro | Número da distribuição. |
dateProcces | data | Quando foi executada. O nome tem a grafia errada e está congelado. |
totalUsers | inteiro | Usuários que receberam tokens. |
totalAmount | número | BCPZ distribuídos (1 por intervalo escaneado). |
description | string | Texto do resultado. |
GET/pool/token-top-50-holders
As 50 contas que mais ganharam BCPZ, com endereços de carteira abreviados. Em cache por 600 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Exemplo de resposta
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
walletAddress | string | Endereço abreviado. |
balance | número | BCPZ na conta agora. |
total | número | Total de BCPZ ganhos. |
minted | número | BCPZ já sacados para a rede Polygon. |
GET/pool/token-mint-history
Os saques de BCPZ mais recentes para a rede Polygon, dos mais recentes para os mais antigos (até 180). Em cache por 600 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/token-mint-history"Exemplo de resposta
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
walletAddress | string | Endereço abreviado da conta. |
minted | número | BCPZ enviados. |
date | data | Quando foi enviado. |
txId | string | Hash da transação na Polygon. Omitido enquanto a transferência não termina. |
GET/pool/btc-price
O preço do Bitcoin em USD e EUR, obtido de uma exchange. Em cache por 600 segundos.
Exemplo de requisição
curl "https://btcpuzzle.info/api/pool/btc-price"Exemplo de resposta
200 OK Os dois valores são 0 quando a fonte de preço não está acessível.
{"usd":66739.06,"eur":60607.25}Feed em tempo real (SignalR)
O pool publica cada intervalo pego e concluído em um hub SignalR. O site o usa na página de status ao vivo. O hub é público, não precisa de token e só envia: não há métodos que um cliente possa chamar.
| URL do hub | https://btcpuzzle.info/api/hex_socket |
| Host antigo | https://api.btcpuzzle.info/hex_socket |
| Protocolo | SignalR com o protocolo JSON padrão; são oferecidos WebSockets, Server-Sent Events e Long Polling. |
| Evento | PoolStatus |
| Limite | A requisição de negociação conta para o limite de taxa por IP. O hub em si não tem limite depois de conectado. |
Conexão
Use uma biblioteca cliente de SignalR (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Internamente, ela negocia primeiro:
Exemplo de requisição
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"Exemplo de resposta
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
Um argumento, um objeto JSON. O evento é enviado a todos os clientes conectados quando um intervalo é distribuído e quando um intervalo é marcado como escaneado.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Campo | Tipo | Descrição |
|---|---|---|
hex | string | O HEX do intervalo com o terceiro caractere substituído por X. |
walletAddress | string | Endereço abreviado da conta. |
workerName | string ou null | O nome do worker (default quando nenhum foi enviado). Em scanned, é o nome enviado com a requisição de marcação, que pode ser null. |
puzzleCode | inteiro | O puzzle do intervalo. |
status | string | holded depois que um intervalo foi distribuído, scanned depois que um intervalo foi marcado. A grafia está congelada. |
Os eventos são entregues enquanto a conexão está aberta; nada é reenviado após uma reconexão. Quando o operador desativa o feed ao vivo, as conexões são recusadas.
Objetos
Objeto Puzzle
Retornado pelos endpoints de lista de puzzles e por /puzzle/{puzzleCode}/info. Propriedades sem valor são omitidas.
| Campo | Tipo | Descrição |
|---|---|---|
id | inteiro | Id no banco de dados (igual a code para puzzles do sistema antigo). |
name | string | Por exemplo Puzzle 71. |
code | inteiro | O número do puzzle. |
hexStart, hexEnd | string | Primeira e última chave privada do puzzle, em hexadecimal. |
targetWalletAddress | string | O endereço que guarda a recompensa. |
hexRangeLength | inteiro | Comprimento do HEX do intervalo que o pool distribui (a parte da chave que ele escolhe). |
reward | número | A recompensa em BTC. |
hexStartPool, hexEndPool | string | Primeiro e último HEX de intervalo. Vazio, a menos que o puzzle esteja no pool. |
totalRanges | inteiro | Número de intervalos do puzzle. 0, a menos que o puzzle esteja no pool. |
percentage | número | Porcentagem dos intervalos que estão escaneados. |
totalScanned, rangesScannedLastHour | inteiro | Intervalos escaneados no total e na última hora (preenchidos nos endpoints de lista). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | vários | Números finais de um puzzle concluído; statisticsFoundBy só está presente quando é conhecido. |
rangeContainsKeys, rangeContainsKeyByDefault | inteiro | Número de chaves privadas (menos uma) em um intervalo. Os dois diferem quando os intervalos abrangem vários ids. |
rangesPerKey | inteiro | Quantos ids de intervalo um intervalo abrange (1 na maioria dos puzzles). |
workloadStart, workloadEnd | string | A parte da chave privada que um cliente escaneia depois do HEX do intervalo: veja GET range. |
customWorkloadStart, customWorkloadEnd | string | Presente quando o puzzle usa uma carga de trabalho personalizada. |
dateStart, dateEnd | data | Datas planejadas do puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | booleano | O estado do puzzle: concluído, anunciado, escaneável agora, o padrão, o pool de teste, no pool. |
isEntranceFeeActive, entranceFee | booleano, número | Se a taxa de entrada está ativa e seu preço em USD (0 quando desativada). |
nextScanAllowedInMinutes | inteiro | Por quanto tempo um intervalo distribuído fica reservado antes de poder ser entregue a outra pessoa. |
challenges | array | O desafio mais recente, ou um array vazio. |
privateKey, publicKey | string | Apenas para puzzles resolvidos. |
rewards, speed | array, objeto | Presentes apenas em alguns endpoints. |
Objeto Statistics
| Campo | Tipo | Descrição |
|---|---|---|
puzzle | objeto | Os principais números do puzzle (nome, código, contagem de intervalos, carga de trabalho, estado, recompensa). |
scannedLast24H | inteiro | Intervalos escaneados nas últimas 24 horas. |
entranceFeesPaidTotal | número | Taxas de entrada pagas pelo puzzle, em USD. |
topWorkersAlltime | array | Até 50 itens {userId, walletAddress, totalScanned}; aqui userId é 0. |
topWorkersLast24h | array | O mesmo para as últimas 24 horas. |
activeWorkers | array | {walletAddress, workerName} dos workers que enviaram ping nos últimos 30 minutos. |
challenges | array | Até 32 desafios. |
kingdom | objeto | O rei do puzzle: walletAddress, message, image e isPublished. |
topSpeed | objeto | A melhor hora de todas: date, intervalos scanned e keysPerSecond. |
chartData | array | O último mês por hora, do mais recente ao mais antigo: date, dateOnly, hoursOnly e rangesScanned. |
lastRanges | array | Os últimos 200 intervalos escaneados, do mais recente ao mais antigo: hex (mascarado), walletAddress (mascarado), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds e totalSeconds. |
rewards | array | Recompensas do puzzle (sem chaves privadas). |
dateUpdated | data | Quando os números foram calculados. |
currentSpeed | objeto | CurrentSpeed. |
Objeto CurrentSpeed
| Campo | Tipo | Descrição |
|---|---|---|
activeWorkerCount | inteiro | Workers que escanearam nas últimas 6 horas e enviaram ping na última hora. |
keysPerSecondFormatted | string | A velocidade com unidade: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s e assim por diante. |
keysPerSecondRaw | string | A velocidade em chaves por segundo, como texto de número inteiro. |
Objeto Challenge
| Campo | Tipo | Descrição |
|---|---|---|
hex | string | Os caracteres iniciais que todo participante do desafio escaneia. |
dateCreated | data | Quando o desafio começou. |
puzzleId | inteiro | O puzzle. |
Objeto Reward
| Campo | Tipo | Descrição |
|---|---|---|
id, puzzleCode, puzzleId | inteiro | Identificação. |
targetAddress | string | O endereço da chave da recompensa. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | Qual é o prêmio e quem o oferece. Propriedades sem valor são omitidas. |
privateKey | string | Presente apenas depois que a recompensa foi resolvida. |
dateCreated, dateSolved | data | Quando foi criada e resolvida (0001-01-01T00:00:00 enquanto não resolvida). |
Mudanças em relação à documentação antiga
Nada do contrato mudou: cada endpoint, cabeçalho, campo e código de erro da API antiga ainda funciona e responde da mesma forma. Este guia substitui a página antiga, que descrevia três endpoints. O que há de novo aqui:
- Os endpoints de dados públicos, o feed em tempo real, os códigos de erro e os limites de taxa estão documentados. A página antiga não os mencionava.
- Correções do texto antigo: o cabeçalho
UserTokenda requisição de marcação é o token de minerador (a página antiga o chamava de endereço de carteira); o intervalo de ping é de cerca de 2 minutos e no máximo 30 minutos, e o limite é de 360 pings por minuto por token, não 60 por hora; o puzzle do pool de teste é o38. - A URL base é
https://btcpuzzle.info/api; o antigo hostapi.btcpuzzle.infocontinua funcionando. - O hub SignalR não tem mais nenhum método do cliente para o servidor, então ninguém pode enviar eventos falsos. O evento em si não mudou.
- O último intervalo livre de um puzzle agora também é distribuído, e uma janela
CustomRangemuito estreita é ampliada para que não seja possível escolher um intervalo pedindo exatamente um. - As estatísticas públicas não mostram mais o endereço IP de um minerador.