API Documentation

Build your own client for the pool. Every endpoint, with requests, responses and errors.

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/api

Clients written before the website moved can keep using the legacy host, with the same paths and no /api prefix:

https://api.btcpuzzle.info

For 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, usertoken and userToken are the same header). Only POST /puzzle/{puzzleCode}/save-private-key has 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 rangeContainsKeys are 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 by X (3AB8443 becomes 3AX8443).

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 toCounted perLimit
GET /puzzle/{puzzleCode}/rangeUserToken120 requests per 60 seconds
PUT /puzzle/{puzzleCode}/rangeUserToken360 requests per 60 seconds
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 requests per 60 seconds
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 requests per 180 seconds
Every other endpointIP address20 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.

StatusBodyMeaning
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).
400validation problemA 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.
400problem detailsA 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

NameInTypeRequiredDescription
puzzleCodepathinteger (1 to 160)YesThe 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.
UserTokenheaderstring (128 characters)YesYour miner token.
WorkerNameheaderstring (1 to 16 characters)NoThe name of this worker. Letters and digits only. Stored as default when you send none.
SecurityHashheaderstringNoFree text kept with the range. Optional.
CustomRangeheaderstringNoLimits 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

FieldTypeDescription
hexstringThe range to scan, in upper case without padding. It is the beginning of the private keys of the range.
puzzleCodeintegerThe puzzle the range belongs to (the default puzzle when the one you asked for is completed).
workloadStartstringAppended to hex to get the first private key of the range.
workloadEndstringAppended 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.
targetAddressstringThe puzzle address you are looking for. Scan it together with the proof addresses.
proofOfWorkAddressesarray of 6 stringsAddresses 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

StatusBodyWhen
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).
400validation problemMissing 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:

  1. Write each private key as 64 upper-case hexadecimal characters, padded with zeros on the left.
  2. Concatenate the six strings, in the order of the addresses, with nothing between them.
  3. Take the SHA-256 of the UTF-8 text and write it as 64 lower-case hexadecimal characters. That is the HashedProofKey of the flag request.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

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

The 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

NameInTypeRequiredDescription
puzzleCodepathinteger (1 to 160)YesThe puzzle of the range.
UserTokenheaderstring (128 characters)YesYour miner token.
HEXheaderstringYesThe hex of the range you scanned, as the pool returned it. Example: 3AB8443.
HashedProofKeyheaderstringYesThe proof of work: see Proof of work.
WorkerNameheaderstring (1 to 16 characters)NoThe worker that scanned the range.
GPUNameheaderstringNoThe graphics card model. Used for the public statistics.
GPUCountheaderintegerNoNumber of cards of the worker. Default 1.
IsForceContinueheaderbooleanNoSet 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

StatusBodyWhen
400{"isSuccess": false}Any refusal: wrong proof, unknown range, a range that was already flagged, banned account, inactive puzzle.
400validation problemA 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesThe puzzle of the range.
HexheaderstringYesThe range the worker is scanning now.
UserTokenheaderstring (128 characters)YesYour miner token.
WorkerNameheaderstringYesThe 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

StatusBodyWhen
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

NameInTypeRequiredDescription
puzzleCodepathintegerYesThe puzzle the key belongs to.
UserTokenheaderstring (128 characters)YesYour miner token.
Content-TypeheaderstringYesapplication/json.
namebodystringNoA label, for example the worker name. Stored as Puzzle71 - rig1.
encryptedKeybodystringYesThe 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

StatusBodyWhen
401{"error": "invalid_user_token"}Unknown or banned token.
400problem detailsNothing 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

StatusBodyWhen
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

StatusBodyWhen
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

NameInTypeRequiredDescription
puzzleCodepathintegerYesThe 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

StatusBodyWhen
204emptyNo 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesAn 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

StatusBodyWhen
400problem detailsThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesAn 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

StatusBodyWhen
400problem detailsThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesAn 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

StatusBodyWhen
400problem detailsThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesAn 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

StatusBodyWhen
400problem detailsThe 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

NameInTypeRequiredDescription
puzzleCodepathintegerYesAn 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

StatusBodyWhen
400problem detailsThe 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

FieldTypeDescription
brandstringnvidia or amd.
namestringThe card.
keysPerSecondnumberMeasured speed.
dateUpdateddateLast 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

FieldTypeDescription
idintegerDistribution number.
dateProccesdateWhen it ran. The name is misspelled and frozen.
totalUsersintegerUsers who received tokens.
totalAmountnumberBCPZ distributed (1 per scanned range).
descriptionstringResult 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

FieldTypeDescription
walletAddressstringShortened address.
balancenumberBCPZ on the account now.
totalnumberBCPZ earned in total.
mintednumberBCPZ 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

FieldTypeDescription
walletAddressstringShortened address of the account.
mintednumberBCPZ sent.
datedateWhen it was sent.
txIdstringPolygon 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 URLhttps://btcpuzzle.info/api/hex_socket
Legacy hosthttps://api.btcpuzzle.info/hex_socket
ProtocolSignalR with the default JSON protocol; WebSockets, Server-Sent Events and Long Polling are offered.
EventPoolStatus
LimitThe 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"
}
FieldTypeDescription
hexstringThe range HEX with its third character replaced by X.
walletAddressstringShortened address of the account.
workerNamestring or nullThe worker name (default when none was sent). On scanned it is the name sent with the flag request, which can be null.
puzzleCodeintegerThe puzzle of the range.
statusstringholded 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.

FieldTypeDescription
idintegerDatabase id (the same as code for puzzles of the old system).
namestringFor example Puzzle 71.
codeintegerThe puzzle number.
hexStart, hexEndstringFirst and last private key of the puzzle, in hexadecimal.
targetWalletAddressstringThe address that holds the reward.
hexRangeLengthintegerLength of the range HEX the pool hands out (the part of the key it chooses).
rewardnumberThe reward in BTC.
hexStartPool, hexEndPoolstringFirst and last range HEX. Empty unless the puzzle is on the pool.
totalRangesintegerNumber of ranges of the puzzle. 0 unless the puzzle is on the pool.
percentagenumberPercent of the ranges that are scanned.
totalScanned, rangesScannedLastHourintegerScanned ranges in total and in the last hour (filled in the list endpoints).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByvariousFinal figures of a completed puzzle; statisticsFoundBy is only present when known.
rangeContainsKeys, rangeContainsKeyByDefaultintegerNumber of private keys (minus one) in one range. The two differ when ranges span several ids.
rangesPerKeyintegerHow many range ids one range spans (1 for most puzzles).
workloadStart, workloadEndstringThe part of the private key a client scans after the range HEX: see GET range.
customWorkloadStart, customWorkloadEndstringPresent when the puzzle uses a custom workload.
dateStart, dateEnddatePlanned dates of the puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanThe state of the puzzle: finished, announced, scannable now, the default, the test pool, on the pool.
isEntranceFeeActive, entranceFeeboolean, numberWhether the entry fee is on and its price in USD (0 when off).
nextScanAllowedInMinutesintegerHow long a handed-out range is held before it can be given to somebody else.
challengesarrayThe latest challenge, or an empty array.
privateKey, publicKeystringOnly for solved puzzles.
rewards, speedarray, objectPresent only on some endpoints.

Statistics object

FieldTypeDescription
puzzleobjectThe main figures of the puzzle (name, code, range counts, workload, state, reward).
scannedLast24HintegerRanges scanned in the last 24 hours.
entranceFeesPaidTotalnumberEntry fees paid for the puzzle, USD.
topWorkersAlltimearrayUp to 50 of {userId, walletAddress, totalScanned}; userId is 0 here.
topWorkersLast24harrayThe same for the last 24 hours.
activeWorkersarray{walletAddress, workerName} of the workers pinging in the last 30 minutes.
challengesarrayUp to 32 challenges.
kingdomobjectThe king of the puzzle: walletAddress, message, image and isPublished.
topSpeedobjectThe best hour ever: date, scanned ranges and keysPerSecond.
chartDataarrayThe last month by hour, newest first: date, dateOnly, hoursOnly and rangesScanned.
lastRangesarrayThe last 200 scanned ranges, newest first: hex (masked), walletAddress (masked), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds and totalSeconds.
rewardsarrayRewards of the puzzle (without private keys).
dateUpdateddateWhen the figures were computed.
currentSpeedobjectCurrentSpeed.

CurrentSpeed object

FieldTypeDescription
activeWorkerCountintegerWorkers that scanned in the last 6 hours and pinged in the last hour.
keysPerSecondFormattedstringThe speed with a unit: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s and so on.
keysPerSecondRawstringThe speed in keys per second as an integer text.

Challenge object

FieldTypeDescription
hexstringThe starting characters every challenge participant scans.
dateCreateddateWhen the challenge started.
puzzleIdintegerThe puzzle.

Reward object

FieldTypeDescription
id, puzzleCode, puzzleIdintegerIdentification.
targetAddressstringThe address of the reward key.
rewardContent, rewardDescription, provider, providerDesc, brandstringWhat the prize is and who gives it. Properties without a value are left out.
privateKeystringPresent only after the reward was solved.
dateCreated, dateSolveddateWhen 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 UserToken header 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 is 38.
  • The base URL is https://btcpuzzle.info/api; the old api.btcpuzzle.info host 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 CustomRange window 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.

Buy me a coffee

Pool puzzles

What the pool scans now, what comes next, and the puzzles it has already worked on.

Scanning now1

Next2

Scanned before4

All 160 puzzles