API 文档

为矿池打造你自己的客户端。每个接口都附有请求、响应和错误说明。

概述

btcpuzzle.info API 就是矿池客户端与之通信的接口。它分发待扫描的密钥范围,接收扫描结果,并发布矿池的公开统计数据。btcpuzzle.info 是开源的,任何人都可以编写客户端:本指南介绍每个公开接口、需要发送的数据、你会收到的数据,以及可能遇到的错误。如有疑问:support@btcpuzzle.info。

此 API 是有意冻结的:矿工和第三方工具都依赖它。路径、请求头、字段名(包括 dateProcces 和 holded 等少数旧拼写)和错误码都不会改变。响应中可能会增加新字段,因此请忽略你不认识的字段。

基础 URL

本指南中的所有路径都相对于基础 URL:

https://btcpuzzle.info/api

在网站迁移之前编写的客户端可以继续使用旧主机,路径相同,只是没有 /api 前缀:

https://api.btcpuzzle.info

例如,GET https://btcpuzzle.info/api/puzzle/codes 和 GET https://api.btcpuzzle.info/puzzle/codes 的响应相同。新客户端应使用带 /api 的基础 URL。

快速开始

在 btcpuzzle.info 上创建一个免费账户,从仪表盘复制你的矿工令牌,然后申请一个范围:

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

扫描返回的范围,同时扫描六个证明地址,用 PUT /puzzle/71/range 发送证明,然后重复。在两次调用之间不时发送 ping,让矿池知道矿工仍在工作。

约定

版本

只有一个版本,URL 中不包含版本号。旧 API 的约定被完全保留;参见与旧文档相比的变化。

身份验证

矿工接口通过 UserToken 请求头识别身份:即你账户的 128 个字符的矿工令牌。它们没有其他登录方式,也没有会话。你可以随时在账户中生成新令牌;旧令牌会立即失效。请对令牌保密:谁持有它,谁就能以你的名义扫描。

所有数据接口(Puzzle、统计、矿池、代币)都是公开的,无需令牌。

请求和响应

  • 对于矿工接口,请求数据放在 HTTP 请求头中,而不是查询字符串或请求体中。请求头名称不区分大小写(UserToken、usertoken 和 userToken 是同一个请求头)。只有 POST /puzzle/{puzzleCode}/save-private-key 带有 JSON 请求体(Content-Type: application/json)。
  • 响应为 UTF-8 编码的 JSON,属性名采用 camelCase。没有值的属性会被省略;API 从不输出 JSON null。不要依赖缩进格式。
  • 日期采用 UTC 时间的 ISO 8601 格式(2026-11-18T08:28:25.8176144Z)。金额和数量为 JSON 数字。
  • rangeContainsKeys 等大数为无符号 64 位整数,可能大于 2^53:在使用双精度浮点数的语言中,请将其解析为 64 位整数或字符串。
  • 公开数据中的钱包地址会被缩略(前 8 个字符、...、后 8 个字符),范围 HEX 的第三个字符会被替换为 X(3AB8443 变为 3AX8443)。

频率限制

以下限制为当前默认值。它们按固定时间窗口计数;运营方可以调整这些限制,因此请读取 429 响应,而不要把这些数字写死在代码中。

适用于计数依据限制
GET /puzzle/{puzzleCode}/rangeUserToken每 60 秒 120 次请求
PUT /puzzle/{puzzleCode}/rangeUserToken每 60 秒 360 次请求
PATCH /puzzle/{puzzleCode}/range/pingUserToken每 60 秒 360 次请求
POST /puzzle/{puzzleCode}/save-private-keyUserToken每 180 秒 10 次请求
其他所有接口IP 地址每个接口每秒 20 次请求,总计每秒 200 次

超出限制的请求会收到 429 Too Many Requests 响应、一个 Retry-After 请求头以及以下响应体:

{
  "isSuccess": false,
  "details": "Quota exceeded."
}

错误

失败时使用以下状态码。响应体因接口而异,因此请先检查状态码。

状态码响应体含义
400{"error": "<code>"}矿工接口拒绝了请求。错误码说明了原因:invalid_puzzle、invalid_user_token、reached_of_keyspace、too_much_request、not_eligable(拼写沿用历史)、invalid_request。
400{"isSuccess": false}范围的标记请求被拒绝(证明错误、范围未知或已被扫描、用户被封禁、puzzle 未启用)。
400验证问题缺少必需的请求头或请求头无效,或 puzzle 编号不在 1 到 160 之间。这是一个 application/problem+json 对象,其 errors 列出了出错的名称。
400问题详情公开数据接口对该 puzzle 没有可返回的内容(Puzzle 未知或未启用)。返回包含 type、title、status 和 traceId 的 application/problem+json。
401{"error": "invalid_user_token"}矿工令牌未知或账户已被封禁(ping 和 save-private-key)。
404{"error": "range_not_found"}要 ping 的范围不由此矿工持有。
429{"isSuccess": false, "details": "Quota exceeded."}频率限制。请等待 Retry-After 秒。

验证问题示例(不带 UserToken 请求头的 GET /puzzle/71/range):

{
  "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"
}

缓存和 CORS

公开数据接口会发送 Cache-Control: public, max-age=N;具体值在每个接口中列出,缓存副本由所有调用方共享,因此轮询间隔短于 N 秒只会返回相同的数据。矿工接口从不缓存。浏览器可以从 https://btcpuzzle.info、https://www.btcpuzzle.info 和 http://localhost:3000(最后一个用于旧前端的本地开发)调用 API;原生客户端不受 CORS 影响。

矿工接口

扫描循环的三个调用:获取范围、扫描期间发送 ping、将其标记为已扫描。第四个调用用于保存找到的私钥。这四个调用都使用 UserToken 请求头。

GET/puzzle/{puzzleCode}/range

分发该 puzzle 中一个随机的空闲范围,并为你保留。你持有的范围不会分配给其他人;如果你不标记它,一段时间后它会回到矿池中(ping 可以延长保留时间)。

参数

名称位置类型必填说明
puzzleCode路径整数(1 到 160)是要扫描的 puzzle,例如 71。38 是测试池。GET /puzzle/codes 会列出所有编号。如果请求的是已完成的 puzzle,会静默改为从默认 puzzle 分发,响应中的 puzzleCode 会告诉你实际得到的是哪个 puzzle。
UserToken请求头字符串(128 个字符)是你的矿工令牌。
WorkerName请求头字符串(1 到 16 个字符)否此矿工的名称。只能包含字母和数字。如果未发送,则存储为 default。
SecurityHash请求头字符串否与范围一起保存的自由文本。可选。
CustomRange请求头字符串否限制你得到的范围:HEX 的前缀(2D、3BA)或 start:end(3400000:38FFFFF)。none 或不发送此请求头表示任意范围。过窄的窗口会被矿池放宽,因此你得到的范围可能与你指定的不同。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

响应示例

200 OK

{
  "hex": "3AB8443",
  "puzzleCode": 71,
  "workloadStart": "00000000000",
  "workloadEnd": "fffffffffff",
  "targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
  "proofOfWorkAddresses": [
    "1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
    "15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
    "1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
    "14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
    "1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
    "14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
  ]
}

响应字段

字段类型说明
hex字符串要扫描的范围,大写且不补零。它是该范围内私钥的开头部分。
puzzleCode整数该范围所属的 puzzle(当你请求的 puzzle 已完成时,为默认 puzzle)。
workloadStart字符串追加到 hex 后面,得到该范围的第一个私钥。
workloadEnd字符串追加到 hex 后面,得到该范围的最后一个私钥。在范围跨越多个 ID 的 puzzle 上,它的长度可能比 workloadStart 更长。
targetAddress字符串你要寻找的 puzzle 地址。请将它与证明地址一起扫描。
proofOfWorkAddresses包含 6 个字符串的数组矿池放置在该范围内的六个私钥的地址。找到它们的私钥即可证明扫描:参见工作量证明.

以上例为准,范围从 3AB8443 + 00000000000 = 3AB844300000000000 到 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF。私钥为 64 个十六进制字符;请在左侧补零。

错误

状态码响应体何时出现
400{"error": "invalid_puzzle"}该 puzzle 不存在或未启用。
400{"error": "invalid_user_token"}令牌未知或已被封禁。
400{"error": "too_much_request"}你持有太多尚未扫描的范围,或者你申请的速度快于完成的速度。请先扫描你持有的范围;被持有的范围会在短时间后回到矿池。
400{"error": "not_eligable"}该 puzzle 需要入场费,而你尚未满足其条件。
400{"error": "reached_of_keyspace"}没有剩余的空闲范围(或没有符合你 CustomRange 的范围)。
400validation problem缺少请求头或请求头格式错误,或 puzzle 编号不在 1 到 160 之间。
429{"isSuccess": false, ...}频率限制:每个令牌每分钟 120 次。

工作量证明

矿池需要确认你确实扫描了该范围。对于每个范围,它会在其中选取六个私钥,只返回它们的地址(proofOfWorkAddresses)。在范围内扫描目标地址的同时,也要扫描这六个地址。找到全部六个私钥后:

  1. 将每个私钥写成 64 个大写十六进制字符,在左侧补零。
  2. 按地址的顺序将六个字符串直接拼接起来,中间不加任何内容。
  3. 对该 UTF-8 文本计算 SHA-256,并写成 64 个小写十六进制字符。这就是标记请求中的 HashedProofKey。
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
               = 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87

每个范围的证明都不同。证明地址目前为六个;请读取 proofOfWorkAddresses 的长度,而不要假定其数量。

PUT/puzzle/{puzzleCode}/range

将一个范围标记为已扫描。矿池会检查证明,如果正确,就将该范围计为你已完成。一个范围只能被标记一次。

参数

名称位置类型必填说明
puzzleCode路径整数(1 到 160)是该范围所属的 puzzle。
UserToken请求头字符串(128 个字符)是你的矿工令牌。
HEX请求头字符串是你扫描的范围的 hex,与矿池返回的一致。示例:3AB8443。
HashedProofKey请求头字符串是工作量证明:参见工作量证明.
WorkerName请求头字符串(1 到 16 个字符)否扫描该范围的矿工。
GPUName请求头字符串否显卡型号。用于公开统计。
GPUCount请求头整数否该矿工的显卡数量。默认为 1。
IsForceContinue请求头布尔值否当矿工在到达其密钥空间末尾后仍继续运行时设置此项。默认为 false。

请求示例

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"

响应示例

200 OK

{
  "isSuccess": true
}

错误

状态码响应体何时出现
400{"isSuccess": false}任何拒绝情况:证明错误、范围未知、范围已被标记过、账户被封禁、puzzle 未启用。
400validation problem缺少必需的请求头或请求头格式错误。
429{"isSuccess": false, ...}频率限制:每个令牌每分钟 360 次。

PATCH/puzzle/{puzzleCode}/range/ping

告诉矿池某个矿工仍在扫描其范围。ping 会保持对该范围的持有,并在网站上将该矿工显示为活跃。大约每 2 分钟发送一次;间隔不得超过 30 分钟,否则矿池会收回该范围。

参数

名称位置类型必填说明
puzzleCode路径整数是该范围所属的 puzzle。
Hex请求头字符串是该矿工当前正在扫描的范围。
UserToken请求头字符串(128 个字符)是你的矿工令牌。
WorkerName请求头字符串是申请该范围时使用的矿工名称(如果当时未发送,则为 default)。

请求示例

curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
  -H "Hex: 3AB8443" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

响应示例

200 OK,响应体为空。

错误

状态码响应体何时出现
400{"error": "invalid_request"}某个请求头为空。
401{"error": "invalid_user_token"}令牌未知或已被封禁。
404{"error": "range_not_found"}此矿工在该 puzzle 上没有持有具有该 HEX 的未扫描范围。
429{"isSuccess": false, ...}频率限制:每个令牌每分钟 360 次。

POST/puzzle/{puzzleCode}/save-private-key

以加密形式将找到的私钥保存到你的账户。客户端用你提供的 RSA 公钥加密该私钥;网站只保留加密文本,你可以用自己的私钥解密。该私钥会显示在你仪表盘的“已找到的密钥”页面上。

参数

名称位置类型必填说明
puzzleCode路径整数是该私钥所属的 puzzle。
UserToken请求头字符串(128 个字符)是你的矿工令牌。
Content-Type请求头字符串是application/json.
name请求体字符串否一个标签,例如矿工名称。存储为 Puzzle71 - rig1。
encryptedKey请求体字符串是加密后的私钥(客户端以 base64 发送)。

请求示例

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>"}'

响应示例

200 OK 注意属性名是 success,而不是 isSuccess。

{
  "success": true,
  "message": "Key saved successfully."
}

错误

状态码响应体何时出现
401{"error": "invalid_user_token"}令牌未知或已被封禁。
400problem details未保存任何内容:此账户已存储过相同的私钥,或缺少请求体。
429{"isSuccess": false, ...}频率限制:每个令牌每 180 秒 10 次。

Puzzle 数据

关于矿池 puzzle 的公开只读接口。无需令牌。Puzzle 对象及其他对象在本指南末尾说明。

GET/puzzle

矿池中的 puzzle:进行中的、接下来的和测试池(以及为保留历史而保存的已完成 puzzle)。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/puzzle"

响应示例

200 OK 一个 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": []
  }
]

错误

状态码响应体何时出现
404[]矿池中没有任何 puzzle。

GET/puzzle/all

数据库中的所有 puzzle,包括已完成的。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/puzzle/all"

返回 200 和一个 Puzzle 对象数组。

GET/puzzle/available

可以在矿池中扫描的 puzzle。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/puzzle/available"

返回 200 和一个 Puzzle 对象数组。

GET/puzzle/default

默认 puzzle:请求已完成的 puzzle 时会回退到的那个 puzzle。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/puzzle/default"

响应示例

200 OK 单个 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": []
}

错误

状态码响应体何时出现
404{"error": "puzzle_not_found"}未设置默认 puzzle。

GET/puzzle/codes

进行中或接下来的 puzzle 的编号,普通 puzzle 在前,测试池在最后。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/puzzle/codes"

响应示例

200 OK

[71, 72, 73, 38]

GET/puzzle/{puzzleCode}/info

从数据库读取的单个 puzzle。缓存 10 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是Puzzle 编号。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/info"

响应示例

200 OK 一个 Puzzle 对象。rangesScannedLastHour 等运行时数值只在列表接口中填充。

{
  "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": []
}

错误

状态码响应体何时出现
204空不存在该 puzzle。

GET/puzzle/{puzzleCode}/statistics

Puzzle 页面显示的所有内容:总计、排行、活跃矿工、最近扫描的 200 个范围以及按小时的图表。缓存 60 秒(服务器还会保留一份副本 5 分钟)。

参数

名称位置类型必填说明
puzzleCode路径整数是一个进行中的 puzzle(或测试池)。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/statistics"

响应示例

200 OK 已缩减:此处数组只保留一个元素,而 lastRanges 最多 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"
  }
}

对于尚未启用的 puzzle(接下来的 puzzle),只返回 puzzle、scannedLast24H、entranceFeesPaidTotal、lastRanges 和 dateUpdated。字段说明参见 Statistics 对象。

错误

状态码响应体何时出现
400problem details该 puzzle 不存在,或既未启用也不在接下来的队列中。

GET/puzzle/{puzzleCode}/speed

矿池当前在某个 puzzle 上的速度。缓存 60 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是Puzzle 编号。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/speed"

响应示例

200 OK 参见 CurrentSpeed。未知的 puzzle 会返回零值,而不会返回错误。

{
  "puzzleCode": 71,
  "currentSpeed": {
    "activeWorkerCount": 38,
    "keysPerSecondFormatted": "162.3 Bkeys/s",
    "keysPerSecondRaw": "162300000000"
  }
}

GET/puzzle/{puzzleCode}/workers

当前正在扫描的矿工:即在过去 30 分钟内对其范围发送过 ping 的矿工。浏览器不缓存;服务器会保留响应 60 秒。puzzleCode 为 0 表示默认 puzzle。

参数

名称位置类型必填说明
puzzleCode路径整数是Puzzle 编号。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/workers"

响应示例

200 OK 没有人在扫描或 puzzle 未知时,返回空数组。

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "workerName": "rig1"
  }
]

GET/puzzle/{puzzleCode}/workers-pinging

与 /workers 相同的列表(因为客户端两者都在使用,所以保留为单独的路径)。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"

参数和响应与 GET /puzzle/{puzzleCode}/workers 相同。

GET/puzzle/{puzzleCode}/rewards

进行中 puzzle 的矿池奖励:赞助商放在范围内某些私钥上的额外奖品(最新的在前,最多 32 个)。奖励的私钥只有在被解开后才会显示。缓存 600 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是一个进行中的 puzzle。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/rewards"

响应示例

200 OK 参见 Reward。该 puzzle 没有奖励时返回空数组。

[
  {
    "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
  }
]

错误

状态码响应体何时出现
400problem details该 puzzle 未启用。

GET/puzzle/{puzzleCode}/challenge

进行中 puzzle 最近的挑战起点(最新的在前,最多 32 个)。缓存 600 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是一个进行中的 puzzle。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/challenge"

响应示例

200 OK 参见 Challenge。没有挑战时返回空数组。

[
  {
    "hex": "3A",
    "dateCreated": "2026-11-18T06:00:00Z",
    "puzzleId": 71
  }
]

错误

状态码响应体何时出现
400problem details该 puzzle 未启用。

GET/puzzle/{puzzleCode}/entrancefee

Puzzle 的入场费(USD),仅在入场费开启时有效。缓存 300 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是一个设有入场费的进行中 puzzle。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"

响应示例

200 OK

{
  "fee": 25.0,
  "puzzle": 71
}

错误

状态码响应体何时出现
400problem details该 puzzle 未启用或没有入场费。

GET/puzzle/{puzzleCode}/statistics-by-hex-prefix

按范围 HEX 的每个两字符前缀统计 puzzle 的扫描量(即 puzzle 页面的热力图)。缓存 3600 秒。

参数

名称位置类型必填说明
puzzleCode路径整数是一个进行中的 puzzle。

请求示例

curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"

响应示例

200 OK 每个前缀一个元素,按 hexStarts 排序。属性 pertantageShow 是有意保留的错误拼写(已冻结)。达到 70% 后,数值停留在 70%,且 isLimitExceeded 为 true。

[
  {
    "hexStarts": "40",
    "maxRanges": 1048576,
    "scannedShow": 4411,
    "pertantageShow": 0.37,
    "isLimitExceeded": false
  }
]

错误

状态码响应体何时出现
400problem details该 puzzle 未启用。

矿池数据

关于矿池整体、GPU 列表和 BCPZ 代币的公开只读接口。

GET/pool/homepage

首页的 puzzle 列表:与 GET /puzzle 相同的数组,且默认 puzzle 附带其 speed。缓存 60 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/homepage"

返回 200 和一个 Puzzle 对象数组。

GET/pool/gpus

GPU 基准测试列表,最快的在前(矿池中的每秒密钥数)。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/gpus"

响应示例

200 OK

[
  {
    "brand": "nvidia",
    "name": "RTX 4090",
    "keysPerSecond": 4491469067.71,
    "dateUpdated": "2026-11-18T08:27:53.190819Z"
  }
]

响应字段

字段类型说明
brand字符串nvidia 或 amd。
name字符串显卡。
keysPerSecond数字实测速度。
dateUpdated日期最后更新时间。

GET/pool/token-distribute-history

每日的 BCPZ 发放记录,最新的在前(最多 180 条)。缓存 300 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/token-distribute-history"

响应示例

200 OK

[
  {
    "id": 412,
    "dateProcces": "2026-11-17T03:00:19Z",
    "totalUsers": 85,
    "totalAmount": 516,
    "description": "Success: 85/85"
  }
]

响应字段

字段类型说明
id整数发放编号。
dateProcces日期运行时间。此名称拼写有误且已冻结。
totalUsers整数收到代币的用户数。
totalAmount数字发放的 BCPZ(每个已扫描范围 1 个)。
description字符串结果文本。

GET/pool/token-top-50-holders

赚取 BCPZ 最多的 50 个账户,钱包地址已缩略。缓存 600 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/token-top-50-holders"

响应示例

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "balance": 2500.25,
    "total": 400,
    "minted": 200
  }
]

响应字段

字段类型说明
walletAddress字符串缩略地址。
balance数字账户当前的 BCPZ。
total数字累计赚取的 BCPZ。
minted数字已提现到 Polygon 网络的 BCPZ。

GET/pool/token-mint-history

最近提现到 Polygon 网络的 BCPZ,最新的在前(最多 180 条)。缓存 600 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/token-mint-history"

响应示例

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "minted": 100,
    "date": "2026-11-15T08:27:58.123754Z",
    "txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
  }
]

响应字段

字段类型说明
walletAddress字符串账户的缩略地址。
minted数字已发送的 BCPZ。
date日期发送时间。
txId字符串Polygon 交易哈希。转账尚未完成时省略。

GET/pool/btc-price

来自交易所的比特币美元和欧元价格。缓存 600 秒。

请求示例

curl "https://btcpuzzle.info/api/pool/btc-price"

响应示例

200 OK 无法连接价格来源时,两个值均为 0。

{"usd":66739.06,"eur":60607.25}

实时推送(SignalR)

矿池会将每个被认领和已完成的范围发布到一个 SignalR hub。网站用它来驱动实时状态页面。该 hub 是公开的,无需令牌,并且只负责发送:客户端没有可调用的方法。

Hub URLhttps://btcpuzzle.info/api/hex_socket
旧主机https://api.btcpuzzle.info/hex_socket
协议使用默认 JSON 协议的 SignalR;提供 WebSockets、Server-Sent Events 和 Long Polling。
事件PoolStatus
限制negotiate 请求计入 IP 频率限制。连接建立后,hub 本身不受限制。

连接

请使用 SignalR 客户端库(JavaScript:@microsoft/signalr;.NET:Microsoft.AspNetCore.SignalR.Client)。它在底层会先进行协商(negotiate):

请求示例

curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"

响应示例

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();

PoolStatus 事件

一个参数,为 JSON 对象。当范围被分发以及范围被标记为已扫描时,该事件会发送给所有已连接的客户端。

{
  "hex": "3AX8443",
  "walletAddress": "1BvBMSEY...7xJaNVN2",
  "workerName": "rig1",
  "puzzleCode": 71,
  "status": "holded"
}
字段类型说明
hex字符串第三个字符被替换为 X 的范围 HEX。
walletAddress字符串账户的缩略地址。
workerName字符串或 null矿工名称(未发送时为 default)。在 scanned 时,它是随标记请求发送的名称,可能为 null。
puzzleCode整数该范围所属的 puzzle。
status字符串范围被分发后为 holded,范围被标记后为 scanned。拼写已冻结。

事件在连接打开期间送达;重新连接后不会重放任何事件。当运营方关闭实时推送时,连接会被拒绝。

对象

Puzzle 对象

由 puzzle 列表接口和 /puzzle/{puzzleCode}/info 返回。没有值的属性会被省略。

字段类型说明
id整数数据库 ID(对于旧系统中的 puzzle,与 code 相同)。
name字符串例如 Puzzle 71。
code整数Puzzle 编号。
hexStart, hexEnd字符串Puzzle 的第一个和最后一个私钥,十六进制表示。
targetWalletAddress字符串持有奖励的地址。
hexRangeLength整数矿池分发的范围 HEX 的长度(即它所选定的私钥部分)。
reward数字以 BTC 计的奖励。
hexStartPool, hexEndPool字符串第一个和最后一个范围 HEX。除非 puzzle 在矿池中,否则为空。
totalRanges整数Puzzle 的范围数量。除非 puzzle 在矿池中,否则为 0。
percentage数字已扫描范围的百分比。
totalScanned, rangesScannedLastHour整数已扫描范围的总数和过去一小时的数量(在列表接口中填充)。
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy多种已完成 puzzle 的最终数据;statisticsFoundBy 仅在已知时出现。
rangeContainsKeys, rangeContainsKeyByDefault整数一个范围中的私钥数量(减一)。当范围跨越多个 ID 时,两者不同。
rangesPerKey整数一个范围跨越多少个范围 ID(大多数 puzzle 为 1)。
workloadStart, workloadEnd字符串客户端在范围 HEX 之后扫描的私钥部分:参见 GET range。
customWorkloadStart, customWorkloadEnd字符串当 puzzle 使用自定义工作量时出现。
dateStart, dateEnd日期Puzzle 的计划日期。
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool布尔值Puzzle 的状态:已完成、已公布、当前可扫描、默认 puzzle、测试池、在矿池中。
isEntranceFeeActive, entranceFee布尔值,数字入场费是否开启及其美元价格(关闭时为 0)。
nextScanAllowedInMinutes整数已分发的范围在可以分配给其他人之前被保留的时长。
challenges数组最近的挑战,或空数组。
privateKey, publicKey字符串仅适用于已解开的 puzzle。
rewards, speed数组,对象仅在部分接口中出现。

Statistics 对象

字段类型说明
puzzle对象Puzzle 的主要数据(名称、编号、范围数量、工作量、状态、奖励)。
scannedLast24H整数过去 24 小时扫描的范围数。
entranceFeesPaidTotal数字为该 puzzle 支付的入场费,单位 USD。
topWorkersAlltime数组最多 50 个 {userId, walletAddress, totalScanned};此处 userId 为 0。
topWorkersLast24h数组同上,统计过去 24 小时。
activeWorkers数组过去 30 分钟内发送过 ping 的矿工的 {walletAddress, workerName}。
challenges数组最多 32 个挑战。
kingdom对象该 puzzle 的国王:walletAddress、message、image 和 isPublished。
topSpeed对象历史最佳的一小时:date、scanned 范围数和 keysPerSecond。
chartData数组过去一个月按小时的数据,最新的在前:date、dateOnly、hoursOnly 和 rangesScanned。
lastRanges数组最近扫描的 200 个范围,最新的在前:hex(已遮蔽)、walletAddress(已遮蔽)、startTime、endTime、pingTime、gpuModel、gpuCount、workerName、isPremiumUser、isScanned、isPinged、keysInSeconds 和 totalSeconds。
rewards数组该 puzzle 的奖励(不含私钥)。
dateUpdated日期数据的计算时间。
currentSpeed对象CurrentSpeed.

CurrentSpeed 对象

字段类型说明
activeWorkerCount整数过去 6 小时内扫描过且过去一小时内发送过 ping 的矿工。
keysPerSecondFormatted字符串带单位的速度:keys/s、Kkeys/s、Mkeys/s、Bkeys/s、Tkeys/s 等。
keysPerSecondRaw字符串以整数文本表示的每秒密钥数。

Challenge 对象

字段类型说明
hex字符串每个挑战参与者扫描的起始字符。
dateCreated日期挑战开始的时间。
puzzleId整数Puzzle。

Reward 对象

字段类型说明
id, puzzleCode, puzzleId整数标识。
targetAddress字符串奖励私钥的地址。
rewardContent, rewardDescription, provider, providerDesc, brand字符串奖品是什么以及由谁提供。没有值的属性会被省略。
privateKey字符串仅在奖励被解开后出现。
dateCreated, dateSolved日期创建和解开的时间(未解开时为 0001-01-01T00:00:00)。

与旧文档相比的变化

约定没有任何改变:旧 API 的每个接口、请求头、字段和错误码仍然有效,响应也完全相同。本指南取代了旧页面,旧页面只介绍了三个接口。新增内容如下:

  • 记录了公开数据接口、实时推送、错误码和频率限制。旧页面没有提到这些内容。
  • 对旧文本的更正:标记请求的 UserToken 请求头是矿工令牌(旧页面称其为钱包地址);ping 间隔约为 2 分钟,最多 30 分钟,限制为每个令牌每分钟 360 次 ping,而不是每小时 60 次;测试池 puzzle 为 38。
  • 基础 URL 为 https://btcpuzzle.info/api;旧的 api.btcpuzzle.info 主机仍然可用。
  • SignalR hub 不再提供客户端到服务器的方法,因此任何人都无法发送伪造事件。事件本身没有变化。
  • Puzzle 的最后一个空闲范围现在也会被分发,过窄的 CustomRange 窗口会被放宽,从而无法通过精确指定来挑选某个范围。
  • 公开统计不再显示矿工的 IP 地址。

请我喝杯咖啡

矿池 puzzle

矿池现在扫描的 puzzle、接下来的 puzzle,以及已经处理过的 puzzle。

正在扫描1

下一个2

曾经扫描4

全部 160 个 puzzle