Documentação da API

Crie seu próprio cliente para o pool. Todos os endpoints, com requisições, respostas e erros.

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

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

Por 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, usertoken e userToken são o mesmo cabeçalho). Apenas POST /puzzle/{puzzleCode}/save-private-key tem 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 null em 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 rangeContainsKeys sã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 por X (3AB8443 vira 3AX8443).

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 aContado porLimite
GET /puzzle/{puzzleCode}/rangeUserToken120 requisições a cada 60 segundos
PUT /puzzle/{puzzleCode}/rangeUserToken360 requisições a cada 60 segundos
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 requisições a cada 60 segundos
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 requisições a cada 180 segundos
Todos os outros endpointsEndereço IP20 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.

StatusCorpoSignificado
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).
400problema de validaçãoUm 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.
400detalhes do problemaUm 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiro (1 a 160)SimO 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.
UserTokenheaderstring (128 caracteres)SimSeu token de minerador.
WorkerNameheaderstring (1 a 16 caracteres)NãoO nome deste worker. Apenas letras e números. Armazenado como default quando você não envia nenhum.
SecurityHashheaderstringNãoTexto livre guardado com o intervalo. Opcional.
CustomRangeheaderstringNãoLimita 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

CampoTipoDescrição
hexstringO intervalo a escanear, em maiúsculas e sem preenchimento. É o início das chaves privadas do intervalo.
puzzleCodeinteiroO puzzle ao qual o intervalo pertence (o puzzle padrão quando o que você pediu está concluído).
workloadStartstringAnexado a hex para obter a primeira chave privada do intervalo.
workloadEndstringAnexado 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.
targetAddressstringO endereço do puzzle que você procura. Escaneie-o junto com os endereços de prova.
proofOfWorkAddressesarray de 6 stringsEndereç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

StatusCorpoQuando
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).
400validation problemCabeç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:

  1. Escreva cada chave privada com 64 caracteres hexadecimais maiúsculos, completando com zeros à esquerda.
  2. Concatene as seis strings, na ordem dos endereços, sem nada entre elas.
  3. Calcule o SHA-256 do texto UTF-8 e escreva-o com 64 caracteres hexadecimais minúsculos. Esse é o HashedProofKey da 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 ) )
               = 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87

A 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiro (1 a 160)SimO puzzle do intervalo.
UserTokenheaderstring (128 caracteres)SimSeu token de minerador.
HEXheaderstringSimO hex do intervalo que você escaneou, como o pool o retornou. Exemplo: 3AB8443.
HashedProofKeyheaderstringSimA prova de trabalho: veja Prova de trabalho.
WorkerNameheaderstring (1 a 16 caracteres)NãoO worker que escaneou o intervalo.
GPUNameheaderstringNãoO modelo da placa de vídeo. Usado nas estatísticas públicas.
GPUCountheaderinteiroNãoNúmero de placas do worker. Padrão 1.
IsForceContinueheaderbooleanoNãoDefina 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

StatusCorpoQuando
400{"isSuccess": false}Qualquer recusa: prova errada, intervalo desconhecido, intervalo já marcado, conta banida, puzzle inativo.
400validation problemUm 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimO puzzle do intervalo.
HexheaderstringSimO intervalo que o worker está escaneando agora.
UserTokenheaderstring (128 caracteres)SimSeu token de minerador.
WorkerNameheaderstringSimO 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

StatusCorpoQuando
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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimO puzzle ao qual a chave pertence.
UserTokenheaderstring (128 caracteres)SimSeu token de minerador.
Content-TypeheaderstringSimapplication/json.
namebodystringNãoUm rótulo, por exemplo o nome do worker. Armazenado como Puzzle71 - rig1.
encryptedKeybodystringSimA 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

StatusCorpoQuando
401{"error": "invalid_user_token"}Token desconhecido ou banido.
400problem detailsNada 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

StatusCorpoQuando
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

StatusCorpoQuando
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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimO 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

StatusCorpoQuando
204vazioEsse 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimUm 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

StatusCorpoQuando
400problem detailsO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimUm 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

StatusCorpoQuando
400problem detailsO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimUm 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

StatusCorpoQuando
400problem detailsO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimUm 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

StatusCorpoQuando
400problem detailsO 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

NomeEmTipoObrigatórioDescrição
puzzleCodepathinteiroSimUm 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

StatusCorpoQuando
400problem detailsO 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

CampoTipoDescrição
brandstringnvidia ou amd.
namestringA placa.
keysPerSecondnúmeroVelocidade medida.
dateUpdateddataÚ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

CampoTipoDescrição
idinteiroNúmero da distribuição.
dateProccesdataQuando foi executada. O nome tem a grafia errada e está congelado.
totalUsersinteiroUsuários que receberam tokens.
totalAmountnúmeroBCPZ distribuídos (1 por intervalo escaneado).
descriptionstringTexto 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

CampoTipoDescrição
walletAddressstringEndereço abreviado.
balancenúmeroBCPZ na conta agora.
totalnúmeroTotal de BCPZ ganhos.
mintednúmeroBCPZ 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

CampoTipoDescrição
walletAddressstringEndereço abreviado da conta.
mintednúmeroBCPZ enviados.
datedataQuando foi enviado.
txIdstringHash 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 hubhttps://btcpuzzle.info/api/hex_socket
Host antigohttps://api.btcpuzzle.info/hex_socket
ProtocoloSignalR com o protocolo JSON padrão; são oferecidos WebSockets, Server-Sent Events e Long Polling.
EventoPoolStatus
LimiteA 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"
}
CampoTipoDescrição
hexstringO HEX do intervalo com o terceiro caractere substituído por X.
walletAddressstringEndereço abreviado da conta.
workerNamestring ou nullO nome do worker (default quando nenhum foi enviado). Em scanned, é o nome enviado com a requisição de marcação, que pode ser null.
puzzleCodeinteiroO puzzle do intervalo.
statusstringholded 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.

CampoTipoDescrição
idinteiroId no banco de dados (igual a code para puzzles do sistema antigo).
namestringPor exemplo Puzzle 71.
codeinteiroO número do puzzle.
hexStart, hexEndstringPrimeira e última chave privada do puzzle, em hexadecimal.
targetWalletAddressstringO endereço que guarda a recompensa.
hexRangeLengthinteiroComprimento do HEX do intervalo que o pool distribui (a parte da chave que ele escolhe).
rewardnúmeroA recompensa em BTC.
hexStartPool, hexEndPoolstringPrimeiro e último HEX de intervalo. Vazio, a menos que o puzzle esteja no pool.
totalRangesinteiroNúmero de intervalos do puzzle. 0, a menos que o puzzle esteja no pool.
percentagenúmeroPorcentagem dos intervalos que estão escaneados.
totalScanned, rangesScannedLastHourinteiroIntervalos escaneados no total e na última hora (preenchidos nos endpoints de lista).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByváriosNúmeros finais de um puzzle concluído; statisticsFoundBy só está presente quando é conhecido.
rangeContainsKeys, rangeContainsKeyByDefaultinteiroNúmero de chaves privadas (menos uma) em um intervalo. Os dois diferem quando os intervalos abrangem vários ids.
rangesPerKeyinteiroQuantos ids de intervalo um intervalo abrange (1 na maioria dos puzzles).
workloadStart, workloadEndstringA parte da chave privada que um cliente escaneia depois do HEX do intervalo: veja GET range.
customWorkloadStart, customWorkloadEndstringPresente quando o puzzle usa uma carga de trabalho personalizada.
dateStart, dateEnddataDatas planejadas do puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanoO estado do puzzle: concluído, anunciado, escaneável agora, o padrão, o pool de teste, no pool.
isEntranceFeeActive, entranceFeebooleano, númeroSe a taxa de entrada está ativa e seu preço em USD (0 quando desativada).
nextScanAllowedInMinutesinteiroPor quanto tempo um intervalo distribuído fica reservado antes de poder ser entregue a outra pessoa.
challengesarrayO desafio mais recente, ou um array vazio.
privateKey, publicKeystringApenas para puzzles resolvidos.
rewards, speedarray, objetoPresentes apenas em alguns endpoints.

Objeto Statistics

CampoTipoDescrição
puzzleobjetoOs principais números do puzzle (nome, código, contagem de intervalos, carga de trabalho, estado, recompensa).
scannedLast24HinteiroIntervalos escaneados nas últimas 24 horas.
entranceFeesPaidTotalnúmeroTaxas de entrada pagas pelo puzzle, em USD.
topWorkersAlltimearrayAté 50 itens {userId, walletAddress, totalScanned}; aqui userId é 0.
topWorkersLast24harrayO mesmo para as últimas 24 horas.
activeWorkersarray{walletAddress, workerName} dos workers que enviaram ping nos últimos 30 minutos.
challengesarrayAté 32 desafios.
kingdomobjetoO rei do puzzle: walletAddress, message, image e isPublished.
topSpeedobjetoA melhor hora de todas: date, intervalos scanned e keysPerSecond.
chartDataarrayO último mês por hora, do mais recente ao mais antigo: date, dateOnly, hoursOnly e rangesScanned.
lastRangesarrayOs ú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.
rewardsarrayRecompensas do puzzle (sem chaves privadas).
dateUpdateddataQuando os números foram calculados.
currentSpeedobjetoCurrentSpeed.

Objeto CurrentSpeed

CampoTipoDescrição
activeWorkerCountinteiroWorkers que escanearam nas últimas 6 horas e enviaram ping na última hora.
keysPerSecondFormattedstringA velocidade com unidade: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s e assim por diante.
keysPerSecondRawstringA velocidade em chaves por segundo, como texto de número inteiro.

Objeto Challenge

CampoTipoDescrição
hexstringOs caracteres iniciais que todo participante do desafio escaneia.
dateCreateddataQuando o desafio começou.
puzzleIdinteiroO puzzle.

Objeto Reward

CampoTipoDescrição
id, puzzleCode, puzzleIdinteiroIdentificação.
targetAddressstringO endereço da chave da recompensa.
rewardContent, rewardDescription, provider, providerDesc, brandstringQual é o prêmio e quem o oferece. Propriedades sem valor são omitidas.
privateKeystringPresente apenas depois que a recompensa foi resolvida.
dateCreated, dateSolveddataQuando 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 UserToken da 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 é o 38.
  • A URL base é https://btcpuzzle.info/api; o antigo host api.btcpuzzle.info continua 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 CustomRange muito 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.

Me pague um café

Puzzles do pool

O que o pool escaneia agora, o que vem a seguir e os puzzles em que ele já trabalhou.

Escaneando agora1

Próximo2

Escaneados antes4

Todos os 160 puzzles