概要
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"返された範囲を6つの証明用アドレスとともにスキャンし、PUT /puzzle/71/rangeで証明を送信して、これを繰り返します。2つの呼び出しの間には、ワーカーが動作中であることをプールに知らせるため、ときどきpingを送ってください。
規約
バージョン管理
バージョンは1つだけで、URLにバージョンは含まれません。旧APIの仕様はそのまま維持されています。旧ドキュメントからの変更点をご覧ください。
認証
マイナー用エンドポイントはUserTokenヘッダー、つまりアカウントの128文字のマイナートークンで識別されます。それ以外のログインやセッションはありません。アカウントからいつでも新しいトークンを作成でき、古いトークンはすぐに使えなくなります。トークンは非公開にしてください。トークンを持つ人は誰でもあなたの名前でスキャンできます。
データ用のエンドポイント(puzzle、統計、プール、トークン)はすべて公開されており、トークンは不要です。
リクエストとレスポンス
- マイナー用エンドポイントでは、リクエストのデータはクエリ文字列やボディではなくHTTPヘッダーで送ります。ヘッダー名は大文字・小文字を区別しません(
UserToken、usertoken、userTokenは同じヘッダーです)。JSONのボディ(Content-Type: application/json)を持つのはPOST /puzzle/{puzzleCode}/save-private-keyだけです。 - レスポンスはUTF-8のJSONで、プロパティ名はcamelCaseです。値のないプロパティは省略され、APIがJSONの
nullを書き出すことはありません。インデントには依存しないでください。 - 日付はUTCのISO 8601形式です(
2026-11-18T08:28:25.8176144Z)。金額と数量はJSONの数値です。 rangeContainsKeysのような大きな数値は符号なし64ビット整数で、2^53より大きくなることがあります。doubleを使う言語では、64ビット整数または文字列として解析してください。- 公開データのウォレットアドレスは短縮され(先頭8文字、
...、末尾8文字)、範囲HEXの3文字目は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 | 検証エラー(validation problem) | 必須のヘッダーがないか無効、または puzzle 番号が1~160の範囲外です。errorsに問題のある名前を列挙したapplication/problem+jsonオブジェクトです。 |
400 | 問題の詳細(problem details) | 公開データ用のエンドポイントが、この 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の影響を受けません。
マイナー用エンドポイント
スキャンのループを構成する3つの呼び出し:範囲を取得し、スキャン中にpingを送り、スキャン済みとしてマークします。4つ目の呼び出しは見つかった鍵を保存します。4つともUserTokenヘッダーを使います。
GET/puzzle/{puzzleCode}/range
Puzzle の空いている範囲をランダムに配布し、あなたのために確保します。あなたが確保している範囲が他の人に渡されることはありません。マークしなかった場合、しばらくするとプールに戻ります(pingを送ると確保が延長されます)。
パラメーター
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
PuzzleCode | パス | 整数(1~160) | はい | スキャンする puzzle(例:71)。38はテストプールです。コードの一覧はGET /puzzle/codesで取得できます。完了した puzzle を指定すると、通知なくデフォルト puzzle から配布され、どの puzzle が割り当てられたかは応答のPuzzleCodeで示されます。 |
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個の配列 | プールが範囲内に配置した6つの秘密鍵のアドレス。スキャンを証明するには、これらの秘密鍵を見つけてください。プルーフ・オブ・ワークをご覧ください。 |
上の例では、範囲は3AB8443 + 00000000000 = 3AB844300000000000から3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFFまでです。秘密鍵は64文字の16進数です。左側をゼロで埋めてください。
エラー
| ステータス | ボディ | 条件 |
|---|---|---|
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。 |
プルーフ・オブ・ワーク
プールは、あなたが本当に範囲をスキャンしたことを確かめたいと考えています。範囲ごとに、その中から6つの秘密鍵を選び、そのアドレスだけを返します(proofOfWorkAddresses)。範囲でターゲットアドレスをスキャンするときに、これら6つのアドレスもスキャンしてください。6つの秘密鍵をすべて見つけたら:
- 各秘密鍵を、左側をゼロで埋めた64文字の大文字の16進数で書きます。
- 6つの文字列を、アドレスの順番どおりに、間に何も入れずに連結します。
- そのUTF-8テキストのSHA-256を取り、64文字の小文字の16進数で書きます。これがマークリクエストの
HashedProofKeyです。
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87証明は範囲ごとに異なります。証明用アドレスの数は現在6つですが、決め打ちせずにproofOfWorkAddressesの長さを読み取ってください。
PUT/puzzle/{puzzleCode}/range
範囲をスキャン済みとしてマークします。プールは証明を確認し、正しければその範囲をあなたの完了分として計上します。範囲をマークできるのは1回だけです。
パラメーター
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
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:プロパティはisSuccessではなくsuccessであることに注意してください。
{
"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:有効なもの、次のもの、テストプール(および履歴として保持されている完了済みのもの)。300秒キャッシュされます。
リクエストの例
curl "https://btcpuzzle.info/api/puzzle"レスポンスの例
200 OK:Puzzleオブジェクトの配列(ここでは1つに省略)。
[
{
"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,
"isNext Puzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}
]エラー
| ステータス | ボディ | 条件 |
|---|---|---|
404 | [] | プールに puzzle が1つもありません。 |
GET/puzzle/all
データベースにあるすべての puzzle(完了済みを含む)。300秒キャッシュされます。
リクエストの例
curl "https://btcpuzzle.info/api/puzzle/all"Puzzleオブジェクトの配列とともに200を返します。
GET/puzzle/available
プールでスキャンできる puzzle。300秒キャッシュされます。
リクエストの例
curl "https://btcpuzzle.info/api/puzzle/available"Puzzleオブジェクトの配列とともに200を返します。
GET/puzzle/default
デフォルト puzzle:完了した puzzle へのリクエストの代わりに使われる puzzle。300秒キャッシュされます。
リクエストの例
curl "https://btcpuzzle.info/api/puzzle/default"レスポンスの例
200 OK:Puzzleオブジェクト1つ。
{
"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,
"isNext Puzzle": 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
データベースから読み取った1つの 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,
"isNext Puzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}エラー
| ステータス | ボディ | 条件 |
|---|---|---|
204 | 空 | 該当する puzzle がありません。 |
GET/puzzle/{puzzleCode}/statistics
Puzzle ページに表示されるすべての情報:合計、ランキング、アクティブなワーカー、直近200件のスキャン済み範囲、1時間ごとのグラフ。60秒キャッシュされます(サーバーは1つのコピーを5分間保持します)。
パラメーター
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
PuzzleCode | パス | 整数 | はい | 有効な puzzle(またはテストプール)。 |
リクエストの例
curl "https://btcpuzzle.info/api/puzzle/71/statistics"レスポンスの例
200 OK:省略版です。ここでは配列の要素は1つですが、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 が存在しないか、有効でも次の 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の2文字のプレフィックスごとに、puzzle がどれだけスキャンされたか(puzzle ページのヒートマップ)。3,600秒キャッシュされます。
パラメーター
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
PuzzleCode | パス | 整数 | はい | 有効な puzzle。 |
リクエストの例
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"レスポンスの例
200 OK:プレフィックスごとに1要素で、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"Puzzleオブジェクトの配列とともに200を返します。
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つにつき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
取引所から取得したUSDとEURでのBitcoin価格。600秒キャッシュされます。
リクエストの例
curl "https://btcpuzzle.info/api/pool/btc-price"レスポンスの例
200 OK:価格の取得元に接続できない場合、どちらの値も0になります。
{"usd":66739.06,"eur":60607.25}リアルタイムフィード(SignalR)
プールは、確保されたすべての範囲と完了したすべての範囲をSignalRハブに公開します。ウェブサイトはこれをライブの状況ページに使っています。ハブは公開されていてトークンは不要で、送信のみを行います。クライアントが呼び出せるメソッドはありません。
| ハブのURL | https://btcpuzzle.info/api/hex_socket |
| 旧ホスト | https://api.btcpuzzle.info/hex_socket |
| プロトコル | デフォルトのJSONプロトコルを使うSignalR。WebSockets、Server-Sent Events、Long Pollingを提供しています。 |
| イベント | PoolStatus |
| 制限 | negotiateリクエストはIPのレート制限にカウントされます。接続後のハブ自体には制限はありません。 |
接続
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イベント
引数は1つで、JSONオブジェクトです。このイベントは、範囲が配布されたときと、範囲がスキャン済みとしてマークされたときに、接続中のすべてのクライアントに送られます。
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| フィールド | 型 | 説明 |
|---|---|---|
hex | 文字列 | 3文字目を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 の最初と最後の秘密鍵(16進数)。 |
targetWalletAddress | 文字列 | 報酬を保有するアドレス。 |
hexRangeLength | 整数 | プールが配布する範囲HEXの長さ(プールが選ぶ鍵の部分)。 |
reward | 数値 | BTC建ての報酬。 |
hexStartPool, hexEndPool | 文字列 | 最初と最後の範囲HEX。puzzle がプールにない場合は空。 |
totalRanges | 整数 | Puzzle の範囲の数。puzzle がプールにない場合は0。 |
percentage | 数値 | スキャン済みの範囲の割合(%)。 |
totalScanned, rangesScannedLastHour | 整数 | スキャン済みの範囲の合計と直近1時間の数(一覧用のエンドポイントで設定)。 |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | 各種 | 完了した puzzle の最終データ。statisticsFoundByは判明している場合のみ含まれます。 |
rangeContainsKeys, rangeContainsKeyByDefault | 整数 | 1つの範囲にある秘密鍵の数(から1を引いたもの)。範囲が複数のIDにまたがる場合、2つの値は異なります。 |
rangesPerKey | 整数 | 1つの範囲がまたがる範囲IDの数(ほとんどの puzzle では1)。 |
workloadStart, workloadEnd | 文字列 | クライアントが範囲HEXの後ろでスキャンする秘密鍵の部分。GET rangeをご覧ください。 |
customWorkloadStart, customWorkloadEnd | 文字列 | Puzzle がカスタムのワークロードを使う場合に含まれます。 |
dateStart, dateEnd | 日付 | Puzzle の予定日。 |
isCompleted, isNext Puzzle, isActive, isDefault, isTestPool, isOnPool | 真偽値 | Puzzle の状態:完了、告知済み、現在スキャン可能、デフォルト、テストプール、プールにある。 |
isEntranceFeeActive, entranceFee | 真偽値、数値 | 参加費が有効かどうかと、そのUSD建ての価格(オフの場合は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 | オブジェクト | 過去最高の1時間:date、scanned(範囲数)、keysPerSecond。 |
chartData | 配列 | 直近1か月の1時間ごとのデータ(新しい順):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時間にスキャンし、直近1時間に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のすべてのエンドポイント、ヘッダー、フィールド、エラーコードは引き続き動作し、同じ応答を返します。このガイドは、3つのエンドポイントを説明していた旧ページに代わるものです。新しくなった点:
- 公開データ用のエンドポイント、リアルタイムフィード、エラーコード、レート制限を文書化しました。旧ページではこれらに触れていませんでした。
- 旧テキストの訂正:マークリクエストの
UserTokenヘッダーはマイナートークンです(旧ページではウォレットアドレスとされていました)。pingの間隔は約2分で最大30分、制限は1時間に60ではなくトークンごとに毎分360pingです。テストプールの puzzle は38です。 - ベースURLは
https://btcpuzzle.info/apiです。旧ホストのapi.btcpuzzle.infoも引き続き動作します。 - SignalRハブにはクライアントからサーバーへのメソッドがなくなったため、偽のイベントを送ることはできません。イベント自体は変わっていません。
- Puzzle の最後の空き範囲も配布されるようになり、非常に狭い
CustomRangeの指定は広げられるため、ちょうど1つの範囲を指定して選ぶことはできなくなりました。 - 公開統計にマイナーのIPアドレスは表示されなくなりました。