Overview
The btcpuzzle.info API is what the pool client talks to. It hands out key ranges to scan, takes the result of a scan, and publishes the public statistics of the pool. btcpuzzle.info is open source and anyone can write a client: this guide describes every public endpoint, the data to send, the data you get back and the errors you can meet. Questions: support@btcpuzzle.info.
This API is frozen on purpose: miners and third-party tools depend on it. Paths, headers, field names (including a few old spellings such as dateProcces and holded) and error codes do not change. New fields may be added to responses, so ignore fields you do not know.
Base URL
Every path in this guide is relative to the base URL:
https://btcpuzzle.info/apiClients written before the website moved can keep using the legacy host, with the same paths and no /api prefix:
https://api.btcpuzzle.infoFor example GET https://btcpuzzle.info/api/puzzle/codes and GET https://api.btcpuzzle.info/puzzle/codes answer the same. New clients should use the base URL with /api.
Quick start
Create a free account on btcpuzzle.info, copy your miner token from the dashboard, then ask for a range:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Scan the returned range together with the six proof addresses, send the proof with PUT /puzzle/71/range, and repeat. Between the two calls send a ping from time to time so the pool knows the worker is alive.
Conventions
Versioning
There is a single version and no version in the URL. The contract of the old API is kept exactly; see Changes from the old documentation.
Authentication
The miner endpoints are identified by the UserToken header: the 128-character miner token of your account. There is no other login and no session for them. You can create a new token from your account at any time; the old one stops working at once. Keep the token private: whoever has it scans in your name.
All the data endpoints (puzzles, statistics, pool, token) are public and need no token.
Requests and responses
- Request data goes in HTTP headers, not in the query string or body, for the miner endpoints. Header names are not case-sensitive (
UserToken,usertokenanduserTokenare the same header). OnlyPOST /puzzle/{puzzleCode}/save-private-keyhas a JSON body (Content-Type: application/json). - Responses are JSON in UTF-8 with camelCase property names. Properties with no value are left out; the API never writes a JSON
null. Do not rely on the indentation. - Dates are ISO 8601 in UTC (
2026-11-18T08:28:25.8176144Z). Money and amounts are JSON numbers. - Large numbers such as
rangeContainsKeysare unsigned 64-bit integers and can be larger than 2^53: parse them as 64-bit integers or strings in languages that use doubles. - Wallet addresses in public data are shortened (first 8 characters,
..., last 8) and the third character of a range HEX is replaced byX(3AB8443becomes3AX8443).
Rate limits
The limits below are the current defaults. They are counted in a fixed time window; the operator can tune them, so read the 429 answer rather than hard-coding the numbers.
| Applies to | Counted per | Limit |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 requests per 60 seconds |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 requests per 60 seconds |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 requests per 60 seconds |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 requests per 180 seconds |
| Every other endpoint | IP address | 20 requests per second for each endpoint, 200 per second in total |
A request over the limit is answered with 429 Too Many Requests, a Retry-After header and this body:
{
"isSuccess": false,
"details": "Quota exceeded."
}Errors
Failures use the status codes below. The body depends on the endpoint, so check the status code first.
| Status | Body | Meaning |
|---|---|---|
400 | {"error": "<code>"} | A miner endpoint refused the request. The code says why: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (the spelling is historical), invalid_request. |
400 | {"isSuccess": false} | The flag request of a range was refused (wrong proof, unknown or already scanned range, banned user, inactive puzzle). |
400 | validation problem | A required header is missing or invalid, or the puzzle number is outside 1 to 160. It is an application/problem+json object whose errors lists the faulty names. |
400 | problem details | A public data endpoint has nothing to answer for this puzzle (unknown or inactive puzzle). application/problem+json with type, title, status and traceId. |
401 | {"error": "invalid_user_token"} | The miner token is unknown or the account is banned (ping and save-private-key). |
404 | {"error": "range_not_found"} | The range to ping is not held by this worker. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Rate limit. Wait for Retry-After seconds. |
Example of a validation problem (GET /puzzle/71/range without the UserToken header):
{
"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"
}Caching and CORS
Public data endpoints send Cache-Control: public, max-age=N; the value is listed with each endpoint, and a cached copy is shared by all callers, so polling faster than N seconds only returns the same data. Miner endpoints are never cached. Browsers may call the API from https://btcpuzzle.info, https://www.btcpuzzle.info and http://localhost:3000 (the last one exists for local development of the old frontend); native clients are not affected by CORS.
Miner endpoints
The three calls of the scanning loop: get a range, ping while you scan it, flag it as scanned. A fourth call stores a found key. All four use the UserToken header.
GET/puzzle/{puzzleCode}/range
Hands out a random free range of the puzzle and holds it for you. Nobody else is given a range you hold; if you do not flag it, it returns to the pool after a while (a ping extends the hold).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer (1 to 160) | Yes | The puzzle to scan, for example 71. 38 is the test pool. GET /puzzle/codes lists the codes. A completed puzzle is silently served from the default puzzle, and the answer says which puzzle you got in puzzleCode. |
UserToken | header | string (128 characters) | Yes | Your miner token. |
WorkerName | header | string (1 to 16 characters) | No | The name of this worker. Letters and digits only. Stored as default when you send none. |
SecurityHash | header | string | No | Free text kept with the range. Optional. |
CustomRange | header | string | No | Limits the range you get: a prefix of the HEX (2D, 3BA) or start:end (3400000:38FFFFF). none or no header means any range. A very narrow window is widened by the pool, so you may get a different range than you named. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Example response
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}Response fields
| Field | Type | Description |
|---|---|---|
hex | string | The range to scan, in upper case without padding. It is the beginning of the private keys of the range. |
puzzleCode | integer | The puzzle the range belongs to (the default puzzle when the one you asked for is completed). |
workloadStart | string | Appended to hex to get the first private key of the range. |
workloadEnd | string | Appended to hex to get the last private key of the range. Its length can be longer than workloadStart on puzzles whose ranges span several ids. |
targetAddress | string | The puzzle address you are looking for. Scan it together with the proof addresses. |
proofOfWorkAddresses | array of 6 strings | Addresses of six private keys the pool placed inside the range. Find their private keys to prove the scan: see Proof of work. |
With the example above the range runs from 3AB8443 + 00000000000 = 3AB844300000000000 to 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Private keys are 64 hexadecimal characters; pad on the left with zeros.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "invalid_puzzle"} | The puzzle does not exist or is not active. |
400 | {"error": "invalid_user_token"} | The token is unknown or banned. |
400 | {"error": "too_much_request"} | You hold too many ranges you have not scanned, or you ask faster than you finish. Scan what you hold; held ranges return to the pool after a short time. |
400 | {"error": "not_eligable"} | The puzzle has an entry fee and you do not meet its conditions yet. |
400 | {"error": "reached_of_keyspace"} | No free range is left (or none that fits your CustomRange). |
400 | validation problem | Missing or malformed header, or a puzzle number outside 1 to 160. |
429 | {"isSuccess": false, ...} | Rate limit: 120 per minute per token. |
Proof of work
The pool wants to be sure that you really scanned the range. With every range it picks six private keys inside it and returns only their addresses (proofOfWorkAddresses). While you scan the range for the target address, scan for these six addresses too. When you have found all six private keys:
- Write each private key as 64 upper-case hexadecimal characters, padded with zeros on the left.
- Concatenate the six strings, in the order of the addresses, with nothing between them.
- Take the SHA-256 of the UTF-8 text and write it as 64 lower-case hexadecimal characters. That is the
HashedProofKeyof the flag request.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87The proof is different for every range. The number of proof addresses is six today; read the length of proofOfWorkAddresses instead of assuming it.
PUT/puzzle/{puzzleCode}/range
Marks a range as scanned. The pool checks the proof and, if it is right, counts the range as done for you. A range can be flagged only once.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer (1 to 160) | Yes | The puzzle of the range. |
UserToken | header | string (128 characters) | Yes | Your miner token. |
HEX | header | string | Yes | The hex of the range you scanned, as the pool returned it. Example: 3AB8443. |
HashedProofKey | header | string | Yes | The proof of work: see Proof of work. |
WorkerName | header | string (1 to 16 characters) | No | The worker that scanned the range. |
GPUName | header | string | No | The graphics card model. Used for the public statistics. |
GPUCount | header | integer | No | Number of cards of the worker. Default 1. |
IsForceContinue | header | boolean | No | Set it when the worker continued although it had reached the end of its keyspace. Default false. |
Example request
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"Example response
200 OK
{
"isSuccess": true
}Errors
| Status | Body | When |
|---|---|---|
400 | {"isSuccess": false} | Any refusal: wrong proof, unknown range, a range that was already flagged, banned account, inactive puzzle. |
400 | validation problem | A required header is missing or malformed. |
429 | {"isSuccess": false, ...} | Rate limit: 360 per minute per token. |
PATCH/puzzle/{puzzleCode}/range/ping
Tells the pool that a worker is still scanning its range. A ping keeps the hold on the range and shows the worker as active on the website. Send one about every 2 minutes; the interval must not be longer than 30 minutes, or the pool takes the range back.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | The puzzle of the range. |
Hex | header | string | Yes | The range the worker is scanning now. |
UserToken | header | string (128 characters) | Yes | Your miner token. |
WorkerName | header | string | Yes | The worker name used when the range was requested (default if none was sent). |
Example request
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Example response
200 OK with an empty body.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "invalid_request"} | A header is empty. |
401 | {"error": "invalid_user_token"} | Unknown or banned token. |
404 | {"error": "range_not_found"} | This worker does not hold an unscanned range with that HEX on that puzzle. |
429 | {"isSuccess": false, ...} | Rate limit: 360 per minute per token. |
POST/puzzle/{puzzleCode}/save-private-key
Stores a found private key on your account, encrypted. The client encrypts the key with the RSA public key you gave it; the site keeps only the encrypted text, which you decrypt with your private key. The key appears on the found keys page of your dashboard.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | The puzzle the key belongs to. |
UserToken | header | string (128 characters) | Yes | Your miner token. |
Content-Type | header | string | Yes | application/json. |
name | body | string | No | A label, for example the worker name. Stored as Puzzle71 - rig1. |
encryptedKey | body | string | Yes | The encrypted private key (the client sends it in base64). |
Example request
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>"}'Example response
200 OK Note that the property is success, not isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Errors
| Status | Body | When |
|---|---|---|
401 | {"error": "invalid_user_token"} | Unknown or banned token. |
400 | problem details | Nothing was saved: the same key is already stored for this account, or the body is missing. |
429 | {"isSuccess": false, ...} | Rate limit: 10 per 180 seconds per token. |
Puzzle data
Public read endpoints about the puzzles of the pool. No token is needed. The Puzzle object and the other objects are described at the end of this guide.
GET/puzzle
The puzzles that are on the pool: the active ones, the next ones and the test pool (and the completed ones kept for the history). Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/puzzle"Example response
200 OK An array of Puzzle objects, shortened here to one.
[
{
"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": []
}
]Errors
| Status | Body | When |
|---|---|---|
404 | [] | The pool has no puzzle at all. |
GET/puzzle/all
Every puzzle of the database, completed ones included. Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/puzzle/all"Answers 200 with an array of Puzzle objects.
GET/puzzle/available
The puzzles that can be scanned on the pool. Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/puzzle/available"Answers 200 with an array of Puzzle objects.
GET/puzzle/default
The default puzzle: the one a request for a completed puzzle falls back to. Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/puzzle/default"Example response
200 OK A single Puzzle object.
{
"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": []
}Errors
| Status | Body | When |
|---|---|---|
404 | {"error": "puzzle_not_found"} | No default puzzle is set. |
GET/puzzle/codes
The numbers of the puzzles that are active or next, normal puzzles first and the test pool last. Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/puzzle/codes"Example response
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
One puzzle, read from the database. Cached for 10 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | The puzzle number. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/info"Example response
200 OK A Puzzle object. Runtime values such as rangesScannedLastHour are filled only in the list endpoints.
{
"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": []
}Errors
| Status | Body | When |
|---|---|---|
204 | empty | No such puzzle. |
GET/puzzle/{puzzleCode}/statistics
Everything the puzzle page shows: totals, rankings, active workers, the last 200 scanned ranges and an hourly chart. Cached for 60 seconds (and the server keeps one copy for 5 minutes).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | An active puzzle (or the test pool). |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Example response
200 OK Shortened: the arrays hold one element here, and lastRanges up to 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"
}
}For a puzzle that is not active yet (the next ones) only puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges and dateUpdated are returned. See Statistics object for the fields.
Errors
| Status | Body | When |
|---|---|---|
400 | problem details | The puzzle does not exist or is neither active nor next. |
GET/puzzle/{puzzleCode}/speed
The speed of the pool on a puzzle now. Cached for 60 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | The puzzle number. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/speed"Example response
200 OK See CurrentSpeed. An unknown puzzle answers with the zero values, never with an error.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
The workers that are scanning now: the ones with a range they pinged in the last 30 minutes. Not cached by the browser; the server keeps the answer for 60 seconds. puzzleCode 0 means the default puzzle.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | The puzzle number. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/workers"Example response
200 OK An empty array when nobody is scanning or the puzzle is unknown.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
The same list as /workers (kept as a separate path because clients use both).
Example request
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"Same parameters and answer as GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
The pool rewards of an active puzzle: extra prizes that sponsors put on private keys inside the ranges (newest first, up to 32). The private key of a reward is shown only after it was solved. Cached for 600 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | An active puzzle. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Example response
200 OK See Reward. An empty array when the puzzle has none.
[
{
"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
}
]Errors
| Status | Body | When |
|---|---|---|
400 | problem details | The puzzle is not active. |
GET/puzzle/{puzzleCode}/challenge
The latest challenge starting points of an active puzzle (newest first, up to 32). Cached for 600 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | An active puzzle. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Example response
200 OK See Challenge. An empty array when there is none.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Errors
| Status | Body | When |
|---|---|---|
400 | problem details | The puzzle is not active. |
GET/puzzle/{puzzleCode}/entrancefee
The entry fee of a puzzle in USD, when the fee is on. Cached for 300 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | An active puzzle with an entry fee. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Example response
200 OK
{
"fee": 25.0,
"puzzle": 71
}Errors
| Status | Body | When |
|---|---|---|
400 | problem details | The puzzle is not active or has no entry fee. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
How much of the puzzle is scanned for each two-character prefix of the range HEX (the heat map of the puzzle page). Cached for 3600 seconds.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
puzzleCode | path | integer | Yes | An active puzzle. |
Example request
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Example response
200 OK One element per prefix, ordered by hexStarts. The property pertantageShow is misspelled on purpose (frozen). From 70% on the numbers stop at 70% and isLimitExceeded is true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Errors
| Status | Body | When |
|---|---|---|
400 | problem details | The puzzle is not active. |
Pool data
Public read endpoints about the pool as a whole, the GPU list and the BCPZ token.
GET/pool/homepage
The puzzle list of the home page: the same array as GET /puzzle, and the default puzzle carries its speed. Cached for 60 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/homepage"Answers 200 with an array of Puzzle objects.
GET/pool/gpus
The GPU benchmark list, fastest first (keys per second on the pool). Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/gpus"Example response
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Response fields
| Field | Type | Description |
|---|---|---|
brand | string | nvidia or amd. |
name | string | The card. |
keysPerSecond | number | Measured speed. |
dateUpdated | date | Last update. |
GET/pool/token-distribute-history
The daily BCPZ distributions, newest first (up to 180). Cached for 300 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/token-distribute-history"Example response
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]Response fields
| Field | Type | Description |
|---|---|---|
id | integer | Distribution number. |
dateProcces | date | When it ran. The name is misspelled and frozen. |
totalUsers | integer | Users who received tokens. |
totalAmount | number | BCPZ distributed (1 per scanned range). |
description | string | Result text. |
GET/pool/token-top-50-holders
The 50 accounts with the most BCPZ earned, wallet addresses shortened. Cached for 600 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Example response
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Response fields
| Field | Type | Description |
|---|---|---|
walletAddress | string | Shortened address. |
balance | number | BCPZ on the account now. |
total | number | BCPZ earned in total. |
minted | number | BCPZ already withdrawn to the Polygon network. |
GET/pool/token-mint-history
The latest BCPZ withdrawals to the Polygon network, newest first (up to 180). Cached for 600 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/token-mint-history"Example response
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]Response fields
| Field | Type | Description |
|---|---|---|
walletAddress | string | Shortened address of the account. |
minted | number | BCPZ sent. |
date | date | When it was sent. |
txId | string | Polygon transaction hash. Left out while the transfer is not done. |
GET/pool/btc-price
The Bitcoin price in USD and EUR, from an exchange. Cached for 600 seconds.
Example request
curl "https://btcpuzzle.info/api/pool/btc-price"Example response
200 OK Both values are 0 when the price source is not reachable.
{"usd":66739.06,"eur":60607.25}Realtime feed (SignalR)
The pool publishes every claimed and finished range to a SignalR hub. The website uses it for the live status page. The hub is public, needs no token, and only sends: there are no methods a client can call.
| Hub URL | https://btcpuzzle.info/api/hex_socket |
| Legacy host | https://api.btcpuzzle.info/hex_socket |
| Protocol | SignalR with the default JSON protocol; WebSockets, Server-Sent Events and Long Polling are offered. |
| Event | PoolStatus |
| Limit | The negotiate request counts for the IP rate limit. The hub itself is not limited once connected. |
Connecting
Use a SignalR client library (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Under the hood it negotiates first:
Example request
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"Example response
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 event
One argument, a JSON object. The event is sent to all connected clients when a range is handed out and when a range is flagged as scanned.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Field | Type | Description |
|---|---|---|
hex | string | The range HEX with its third character replaced by X. |
walletAddress | string | Shortened address of the account. |
workerName | string or null | The worker name (default when none was sent). On scanned it is the name sent with the flag request, which can be null. |
puzzleCode | integer | The puzzle of the range. |
status | string | holded after a range was handed out, scanned after a range was flagged. The spelling is frozen. |
Events are delivered while the connection is open; nothing is replayed after a reconnect. When the operator switches the live feed off, connections are refused.
Objects
Puzzle object
Returned by the puzzle list endpoints and /puzzle/{puzzleCode}/info. Properties without a value are left out.
| Field | Type | Description |
|---|---|---|
id | integer | Database id (the same as code for puzzles of the old system). |
name | string | For example Puzzle 71. |
code | integer | The puzzle number. |
hexStart, hexEnd | string | First and last private key of the puzzle, in hexadecimal. |
targetWalletAddress | string | The address that holds the reward. |
hexRangeLength | integer | Length of the range HEX the pool hands out (the part of the key it chooses). |
reward | number | The reward in BTC. |
hexStartPool, hexEndPool | string | First and last range HEX. Empty unless the puzzle is on the pool. |
totalRanges | integer | Number of ranges of the puzzle. 0 unless the puzzle is on the pool. |
percentage | number | Percent of the ranges that are scanned. |
totalScanned, rangesScannedLastHour | integer | Scanned ranges in total and in the last hour (filled in the list endpoints). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | various | Final figures of a completed puzzle; statisticsFoundBy is only present when known. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | Number of private keys (minus one) in one range. The two differ when ranges span several ids. |
rangesPerKey | integer | How many range ids one range spans (1 for most puzzles). |
workloadStart, workloadEnd | string | The part of the private key a client scans after the range HEX: see GET range. |
customWorkloadStart, customWorkloadEnd | string | Present when the puzzle uses a custom workload. |
dateStart, dateEnd | date | Planned dates of the puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | The state of the puzzle: finished, announced, scannable now, the default, the test pool, on the pool. |
isEntranceFeeActive, entranceFee | boolean, number | Whether the entry fee is on and its price in USD (0 when off). |
nextScanAllowedInMinutes | integer | How long a handed-out range is held before it can be given to somebody else. |
challenges | array | The latest challenge, or an empty array. |
privateKey, publicKey | string | Only for solved puzzles. |
rewards, speed | array, object | Present only on some endpoints. |
Statistics object
| Field | Type | Description |
|---|---|---|
puzzle | object | The main figures of the puzzle (name, code, range counts, workload, state, reward). |
scannedLast24H | integer | Ranges scanned in the last 24 hours. |
entranceFeesPaidTotal | number | Entry fees paid for the puzzle, USD. |
topWorkersAlltime | array | Up to 50 of {userId, walletAddress, totalScanned}; userId is 0 here. |
topWorkersLast24h | array | The same for the last 24 hours. |
activeWorkers | array | {walletAddress, workerName} of the workers pinging in the last 30 minutes. |
challenges | array | Up to 32 challenges. |
kingdom | object | The king of the puzzle: walletAddress, message, image and isPublished. |
topSpeed | object | The best hour ever: date, scanned ranges and keysPerSecond. |
chartData | array | The last month by hour, newest first: date, dateOnly, hoursOnly and rangesScanned. |
lastRanges | array | The last 200 scanned ranges, newest first: hex (masked), walletAddress (masked), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds and totalSeconds. |
rewards | array | Rewards of the puzzle (without private keys). |
dateUpdated | date | When the figures were computed. |
currentSpeed | object | CurrentSpeed. |
CurrentSpeed object
| Field | Type | Description |
|---|---|---|
activeWorkerCount | integer | Workers that scanned in the last 6 hours and pinged in the last hour. |
keysPerSecondFormatted | string | The speed with a unit: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s and so on. |
keysPerSecondRaw | string | The speed in keys per second as an integer text. |
Challenge object
| Field | Type | Description |
|---|---|---|
hex | string | The starting characters every challenge participant scans. |
dateCreated | date | When the challenge started. |
puzzleId | integer | The puzzle. |
Reward object
| Field | Type | Description |
|---|---|---|
id, puzzleCode, puzzleId | integer | Identification. |
targetAddress | string | The address of the reward key. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | What the prize is and who gives it. Properties without a value are left out. |
privateKey | string | Present only after the reward was solved. |
dateCreated, dateSolved | date | When it was created and solved (0001-01-01T00:00:00 while unsolved). |
Changes from the old documentation
Nothing of the contract changed: every endpoint, header, field and error code of the old API still works and answers the same. This guide replaces the old page, which described three endpoints. What is new here:
- The public data endpoints, the realtime feed, the error codes and the rate limits are documented. The old page did not mention them.
- Corrections of the old text: the
UserTokenheader of the flag request is the miner token (the old page called it a wallet address); the ping interval is about 2 minutes and at most 30 minutes, and the limit is 360 pings per minute per token, not 60 per hour; test pool puzzle is38. - The base URL is
https://btcpuzzle.info/api; the oldapi.btcpuzzle.infohost keeps working. - The SignalR hub has no client-to-server method any more, so nobody can send fake events. The event itself did not change.
- The last free range of a puzzle is now handed out too, and a very narrow
CustomRangewindow is widened so that a range cannot be picked by asking for exactly one. - The public statistics no longer show the IP address of a miner.