概述
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}/range | UserToken | 每 60 秒 120 次请求 |
PUT /puzzle/{puzzleCode}/range | UserToken | 每 60 秒 360 次请求 |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 每 60 秒 360 次请求 |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 每 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 的范围)。 |
400 | validation problem | 缺少请求头或请求头格式错误,或 puzzle 编号不在 1 到 160 之间。 |
429 | {"isSuccess": false, ...} | 频率限制:每个令牌每分钟 120 次。 |
工作量证明
矿池需要确认你确实扫描了该范围。对于每个范围,它会在其中选取六个私钥,只返回它们的地址(proofOfWorkAddresses)。在范围内扫描目标地址的同时,也要扫描这六个地址。找到全部六个私钥后:
- 将每个私钥写成 64 个大写十六进制字符,在左侧补零。
- 按地址的顺序将六个字符串直接拼接起来,中间不加任何内容。
- 对该 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 未启用。 |
400 | validation 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"} | 令牌未知或已被封禁。 |
400 | problem 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 对象。
错误
| 状态码 | 响应体 | 何时出现 |
|---|---|---|
400 | problem 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
}
]错误
| 状态码 | 响应体 | 何时出现 |
|---|---|---|
400 | problem 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
}
]错误
| 状态码 | 响应体 | 何时出现 |
|---|---|---|
400 | problem 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
}错误
| 状态码 | 响应体 | 何时出现 |
|---|---|---|
400 | problem 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
}
]错误
| 状态码 | 响应体 | 何时出现 |
|---|---|---|
400 | problem 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 URL | https://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 地址。