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"

返された範囲を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}/rangeUserToken60秒あたり120リクエスト
PUT /puzzle/{puzzleCode}/rangeUserToken60秒あたり360リクエスト
PATCH /puzzle/{puzzleCode}/range/pingUserToken60秒あたり360リクエスト
POST /puzzle/{puzzleCode}/save-private-keyUserToken180秒あたり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に合う範囲がありません)。
400validation problemヘッダーがないか形式が誤っている、または puzzle 番号が1~160の範囲外です。
429{"isSuccess": false, ...}レート制限:トークンごとに毎分120。

プルーフ・オブ・ワーク

プールは、あなたが本当に範囲をスキャンしたことを確かめたいと考えています。範囲ごとに、その中から6つの秘密鍵を選び、そのアドレスだけを返します(proofOfWorkAddresses)。範囲でターゲットアドレスをスキャンするときに、これら6つのアドレスもスキャンしてください。6つの秘密鍵をすべて見つけたら:

  1. 各秘密鍵を、左側をゼロで埋めた64文字の大文字の16進数で書きます。
  2. 6つの文字列を、アドレスの順番どおりに、間に何も入れずに連結します。
  3. その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。
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:プロパティはisSuccessではなくsuccessであることに注意してください。

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

エラー

ステータスボディ条件
401{"error": "invalid_user_token"}トークンが不明か、追放されています。
400problem 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オブジェクトをご覧ください。

エラー

ステータスボディ条件
400problem detailsPuzzle が存在しないか、有効でも次の 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 detailsPuzzle が有効ではありません。

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 detailsPuzzle が有効ではありません。

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 detailsPuzzle が有効でないか、参加費がありません。

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
  }
]

エラー

ステータスボディ条件
400problem detailsPuzzle が有効ではありません。

プールデータ

プール全体、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ハブに公開します。ウェブサイトはこれをライブの状況ページに使っています。ハブは公開されていてトークンは不要で、送信のみを行います。クライアントが呼び出せるメソッドはありません。

ハブのURLhttps://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アドレスは表示されなくなりました。

コーヒーをおごる

プールの puzzle

プールが現在スキャン中のもの、次のもの、すでに取り組んだ puzzle。

スキャン中1

次2

スキャン済み4

全160puzzle