Обзор
API btcpuzzle.info — это то, с чем общается клиент пула. Он выдаёт диапазоны ключей для сканирования, принимает результат сканирования и публикует публичную статистику пула. 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 отвечают одинаково. Новым клиентам следует использовать базовый URL с /api.
Быстрый старт
Создайте бесплатный аккаунт на btcpuzzle.info, скопируйте токен майнера из панели и запросите диапазон:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"Просканируйте полученный диапазон вместе с шестью адресами для доказательства, отправьте доказательство через PUT /puzzle/71/range и повторите. Между этими двумя вызовами время от времени отправляйте ping, чтобы пул знал, что воркер жив.
Соглашения
Версионирование
Версия одна, и в URL её нет. Контракт старого API сохранён в точности; см. Отличия от старой документации.
Аутентификация
Эндпоинты майнера идентифицируют пользователя по заголовку UserToken: 128-символьному токену майнера вашего аккаунта. Другого входа и сеансов для них нет. Новый токен можно создать в аккаунте в любой момент; старый сразу перестаёт работать. Храните токен в тайне: тот, у кого он есть, сканирует от вашего имени.
Все эндпоинты данных (puzzle, статистика, пул, токен) публичны и не требуют токена.
Запросы и ответы
- Для эндпоинтов майнера данные запроса передаются в HTTP-заголовках, а не в строке запроса или теле. Имена заголовков не чувствительны к регистру (
UserToken,usertokenиuserToken— один и тот же заголовок). Тело JSON (Content-Type: application/json) есть только уPOST /puzzle/{puzzleCode}/save-private-key. - Ответы — JSON в UTF-8 с именами свойств в camelCase. Свойства без значения опускаются; API никогда не пишет JSON
null. Не полагайтесь на отступы. - Даты — ISO 8601 в UTC (
2026-11-18T08:28:25.8176144Z). Деньги и суммы — числа JSON. - Большие числа, такие как
rangeContainsKeys, — беззнаковые 64-битные целые и могут превышать 2^53: в языках, использующих double, разбирайте их как 64-битные целые или строки. - Адреса кошельков в публичных данных сокращены (первые 8 символов,
..., последние 8), а третий символ HEX диапазона заменён наX(3AB8443становится3AX8443).
Ограничения частоты
Ниже приведены текущие лимиты по умолчанию. Они считаются в фиксированном временном окне; оператор может их настраивать, поэтому ориентируйтесь на ответ 429, а не зашивайте числа в код.
| Где действует | Считается по | Лимит |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 120 запросов за 60 секунд |
PUT /puzzle/{puzzleCode}/range | UserToken | 360 запросов за 60 секунд |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 360 запросов за 60 секунд |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 10 запросов за 180 секунд |
| Все остальные эндпоинты | 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. Это объект application/problem+json, в поле errors которого перечислены ошибочные имена. |
400 | problem details | Публичному эндпоинту данных нечего ответить по этому puzzle (неизвестный или неактивный puzzle). application/problem+json с type, title, status и traceId. |
401 | {"error": "invalid_user_token"} | Токен майнера неизвестен или аккаунт заблокирован (ping и save-private-key). |
404 | {"error": "range_not_found"} | Диапазон для ping не удерживается этим воркером. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | Превышен лимит частоты. Подождите Retry-After секунд. |
Пример ошибки валидации (GET /puzzle/71/range без заголовка UserToken):
{
"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 секунд вернёт те же данные. Эндпоинты майнера никогда не кешируются. Браузеры могут вызывать API с https://btcpuzzle.info, https://www.btcpuzzle.info и http://localhost:3000 (последний существует для локальной разработки старого фронтенда); на нативные клиенты CORS не влияет.
Эндпоинты майнера
Три вызова цикла сканирования: получить диапазон, отправлять ping во время сканирования, отметить его как просканированный. Четвёртый вызов сохраняет найденный ключ. Все четыре используют заголовок UserToken.
GET/puzzle/{puzzleCode}/range
Выдаёт случайный свободный диапазон puzzle и удерживает его за вами. Удерживаемый вами диапазон никому другому не выдаётся; если вы его не отметите, через некоторое время он вернётся в пул (ping продлевает удержание).
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer (от 1 до 160) | Да | Puzzle для сканирования, например 71. 38 — тестовый пул. Список кодов возвращает GET /puzzle/codes. Вместо завершённого puzzle молча выдаётся puzzle по умолчанию, а в ответе в поле puzzleCode указано, какой puzzle вы получили. |
UserToken | header | string (128 символов) | Да | Ваш токен майнера. |
WorkerName | header | string (от 1 до 16 символов) | Нет | Имя этого воркера. Только буквы и цифры. Если не отправлено, сохраняется как default. |
SecurityHash | header | string | Нет | Произвольный текст, сохраняемый с диапазоном. Необязательно. |
CustomRange | header | string | Нет | Ограничивает получаемый диапазон: префикс 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 | string | Диапазон для сканирования, в верхнем регистре без дополнения нулями. Это начало приватных ключей диапазона. |
puzzleCode | integer | Puzzle, к которому относится диапазон (puzzle по умолчанию, если запрошенный завершён). |
workloadStart | string | Добавляется к hex, чтобы получить первый приватный ключ диапазона. |
workloadEnd | string | Добавляется к hex, чтобы получить последний приватный ключ диапазона. Может быть длиннее workloadStart в puzzle, где диапазон охватывает несколько id. |
targetAddress | string | Искомый адрес puzzle. Сканируйте его вместе с адресами для доказательства. |
proofOfWorkAddresses | массив из 6 строк | Адреса шести приватных ключей, которые пул разместил внутри диапазона. Найдите их приватные ключи, чтобы доказать сканирование: см. Proof of work. |
В примере выше диапазон идёт от 3AB8443 + 00000000000 = 3AB844300000000000 до 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Приватные ключи — 64 шестнадцатеричных символа; дополняйте нулями слева.
Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | {"error": "invalid_puzzle"} | Puzzle не существует или не активен. |
400 | {"error": "invalid_user_token"} | Токен неизвестен или заблокирован. |
400 | {"error": "too_much_request"} | Вы удерживаете слишком много непросканированных диапазонов или запрашиваете быстрее, чем завершаете. Просканируйте то, что удерживаете; удерживаемые диапазоны вскоре возвращаются в пул. |
400 | {"error": "not_eligable"} | У puzzle есть вступительный взнос, и вы пока не выполняете его условия. |
400 | {"error": "reached_of_keyspace"} | Свободных диапазонов не осталось (или нет подходящих под ваш CustomRange). |
400 | validation problem | Заголовок отсутствует или имеет неверный формат, либо номер puzzle вне диапазона от 1 до 160. |
429 | {"isSuccess": false, ...} | Лимит частоты: 120 в минуту на токен. |
Proof of work
Пул хочет быть уверен, что вы действительно просканировали диапазон. Для каждого диапазона он выбирает внутри него шесть приватных ключей и возвращает только их адреса (proofOfWorkAddresses). Сканируя диапазон в поисках целевого адреса, ищите и эти шесть адресов. Когда найдены все шесть приватных ключей:
- Запишите каждый приватный ключ как 64 шестнадцатеричных символа в верхнем регистре, дополнив нулями слева.
- Склейте шесть строк в порядке адресов без разделителей.
- Вычислите SHA-256 от UTF-8 текста и запишите его как 64 шестнадцатеричных символа в нижнем регистре. Это и есть
HashedProofKeyзапроса на отметку.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87Доказательство для каждого диапазона своё. Сейчас адресов для доказательства шесть; берите длину proofOfWorkAddresses, а не предполагайте её.
PUT/puzzle/{puzzleCode}/range
Отмечает диапазон как просканированный. Пул проверяет доказательство и, если оно верно, засчитывает диапазон вам. Диапазон можно отметить только один раз.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer (от 1 до 160) | Да | Puzzle диапазона. |
UserToken | header | string (128 символов) | Да | Ваш токен майнера. |
HEX | header | string | Да | hex просканированного диапазона в том виде, в каком его вернул пул. Пример: 3AB8443. |
HashedProofKey | header | string | Да | Доказательство работы: см. Proof of work. |
WorkerName | header | string (от 1 до 16 символов) | Нет | Воркер, просканировавший диапазон. |
GPUName | header | string | Нет | Модель видеокарты. Используется в публичной статистике. |
GPUCount | header | integer | Нет | Количество карт у воркера. По умолчанию 1. |
IsForceContinue | header | boolean | Нет | Установите, если воркер продолжил работу, хотя дошёл до конца своего пространства ключей. По умолчанию false. |
Пример запроса
curl -X PUT "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1" \
-H "HEX: 3AB8443" \
-H "HashedProofKey: 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87" \
-H "GPUName: RTX 4090" \
-H "GPUCount: 1"Пример ответа
200 OK
{
"isSuccess": true
}Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | {"isSuccess": false} | Любой отказ: неверное доказательство, неизвестный диапазон, уже отмеченный диапазон, заблокированный аккаунт, неактивный puzzle. |
400 | validation problem | Обязательный заголовок отсутствует или имеет неверный формат. |
429 | {"isSuccess": false, ...} | Лимит частоты: 360 в минуту на токен. |
PATCH/puzzle/{puzzleCode}/range/ping
Сообщает пулу, что воркер всё ещё сканирует свой диапазон. Ping сохраняет удержание диапазона и показывает воркер активным на сайте. Отправляйте его примерно каждые 2 минуты; интервал не должен превышать 30 минут, иначе пул заберёт диапазон обратно.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Puzzle диапазона. |
Hex | header | string | Да | Диапазон, который воркер сканирует сейчас. |
UserToken | header | string (128 символов) | Да | Ваш токен майнера. |
WorkerName | header | string | Да | Имя воркера, использованное при запросе диапазона (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"} | Этот воркер не удерживает непросканированный диапазон с таким HEX в этом puzzle. |
429 | {"isSuccess": false, ...} | Лимит частоты: 360 в минуту на токен. |
POST/puzzle/{puzzleCode}/save-private-key
Сохраняет найденный приватный ключ в вашем аккаунте в зашифрованном виде. Клиент шифрует ключ указанным вами публичным ключом RSA; сайт хранит только зашифрованный текст, который вы расшифровываете своим приватным ключом. Ключ появляется на странице найденных ключей в вашей панели.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Puzzle, к которому относится ключ. |
UserToken | header | string (128 символов) | Да | Ваш токен майнера. |
Content-Type | header | string | Да | application/json. |
name | body | string | Нет | Метка, например имя воркера. Сохраняется как Puzzle71 - rig1. |
encryptedKey | body | string | Да | Зашифрованный приватный ключ (клиент отправляет его в base64). |
Пример запроса
curl -X POST "https://btcpuzzle.info/api/puzzle/71/save-private-key" \
-H "UserToken: <128-character miner token>" \
-H "Content-Type: application/json" \
-d '{"name": "rig1","encryptedKey": "<encrypted key, base64>"}'Пример ответа
200 OK Обратите внимание: свойство называется success, а не isSuccess.
{
"success": true,
"message": "Key saved successfully."
}Ошибки
| Статус | Тело | Когда |
|---|---|---|
401 | {"error": "invalid_user_token"} | Неизвестный или заблокированный токен. |
400 | problem details | Ничего не сохранено: такой ключ уже сохранён для этого аккаунта или тело отсутствует. |
429 | {"isSuccess": false, ...} | Лимит частоты: 10 за 180 секунд на токен. |
Данные puzzle
Публичные эндпоинты для чтения данных о puzzle пула. Токен не нужен. Объект Puzzle и другие объекты описаны в конце руководства.
GET/puzzle
Puzzle, которые есть в пуле: активные, следующие и тестовый пул (а также завершённые, сохранённые для истории). Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/puzzle"Пример ответа
200 OK Массив объектов Puzzle, здесь сокращённый до одного.
[
{
"id": 71,
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexRangeLength": 7,
"reward": 7.1,
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"percentage": 0.4172,
"rangesScannedLastHour": 612,
"totalScanned": 279997,
"statisticsTotalScanned": 0,
"statisticsFoundOnPool": false,
"statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
"rangeContainsKeyByDefault": 17592186044415,
"rangeContainsKeys": 17592186044415,
"rangesPerKey": 1,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"dateStart": "2026-01-01T00:00:00Z",
"dateEnd": "2027-01-01T00:00:00Z",
"isCompleted": false,
"isNextPuzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}
]Ошибки
| Статус | Тело | Когда |
|---|---|---|
404 | [] | В пуле вообще нет puzzle. |
GET/puzzle/all
Все puzzle из базы данных, включая завершённые. Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/all"Отвечает 200 с массивом объектов Puzzle.
GET/puzzle/available
Puzzle, которые можно сканировать в пуле. Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/available"Отвечает 200 с массивом объектов Puzzle.
GET/puzzle/default
Puzzle по умолчанию: тот, на который переключается запрос завершённого puzzle. Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/default"Пример ответа
200 OK Один объект Puzzle.
{
"id": 71,
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexRangeLength": 7,
"reward": 7.1,
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"percentage": 0.4172,
"rangesScannedLastHour": 612,
"totalScanned": 279997,
"statisticsTotalScanned": 0,
"statisticsFoundOnPool": false,
"statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
"rangeContainsKeyByDefault": 17592186044415,
"rangeContainsKeys": 17592186044415,
"rangesPerKey": 1,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"dateStart": "2026-01-01T00:00:00Z",
"dateEnd": "2027-01-01T00:00:00Z",
"isCompleted": false,
"isNextPuzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}Ошибки
| Статус | Тело | Когда |
|---|---|---|
404 | {"error": "puzzle_not_found"} | Puzzle по умолчанию не задан. |
GET/puzzle/codes
Номера активных и следующих puzzle: сначала обычные puzzle, в конце тестовый пул. Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/codes"Пример ответа
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
Один puzzle, прочитанный из базы данных. Кешируется на 10 секунд.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Номер puzzle. |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/info"Пример ответа
200 OK Объект Puzzle. Значения времени выполнения, такие как rangesScannedLastHour, заполняются только в эндпоинтах списков.
{
"id": 71,
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexRangeLength": 7,
"reward": 7.1,
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"percentage": 0.4172,
"rangesScannedLastHour": 612,
"totalScanned": 279997,
"statisticsTotalScanned": 0,
"statisticsFoundOnPool": false,
"statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
"rangeContainsKeyByDefault": 17592186044415,
"rangeContainsKeys": 17592186044415,
"rangesPerKey": 1,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"dateStart": "2026-01-01T00:00:00Z",
"dateEnd": "2027-01-01T00:00:00Z",
"isCompleted": false,
"isNextPuzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}Ошибки
| Статус | Тело | Когда |
|---|---|---|
204 | пусто | Такого puzzle нет. |
GET/puzzle/{puzzleCode}/statistics
Всё, что показывает страница puzzle: итоги, рейтинги, активные воркеры, последние 200 просканированных диапазонов и почасовой график. Кешируется на 60 секунд (а сервер хранит одну копию 5 минут).
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Активный puzzle (или тестовый пул). |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/statistics"Пример ответа
200 OK Сокращено: здесь массивы содержат по одному элементу, а lastRanges — до 200.
{
"puzzle": {
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"totalScanned": 279997,
"rangeContainsKeys": 17592186044415,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"rangesPerKey": 1,
"isCompleted": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"reward": 7.1
},
"scannedLast24H": 14702,
"entranceFeesPaidTotal": 0,
"topWorkersAlltime": [
{
"userId": 0,
"walletAddress": "1BvBMSEY...7xJaNVN2",
"totalScanned": 5120
}
],
"topWorkersLast24h": [
{
"userId": 2051875,
"walletAddress": "1BvBMSEY...7xJaNVN2",
"totalScanned": 412
}
],
"activeWorkers": [
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
],
"challenges": [],
"kingdom": {
"walletAddress": "1BvBMSEY...7xJaNVN2",
"message": "Hello pool",
"image": 3,
"isPublished": true
},
"topSpeed": {
"date": "2026-11-10T14:00:00Z",
"scanned": 912,
"keysPerSecond": 4456789012345
},
"chartData": [
{
"date": "2026-11-18T08:00:00Z",
"dateOnly": "2026-11-18",
"hoursOnly": 8,
"rangesScanned": 640
}
],
"lastRanges": [
{
"hex": "10X0",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"startTime": "2026-11-18T07:27:57.603786Z",
"endTime": "2026-11-18T08:22:57.603786Z",
"pingTime": "2026-11-18T08:20:57.603786Z",
"gpuModel": "RTX 4090",
"gpuCount": 1,
"workerName": "rig1",
"isPremiumUser": false,
"isScanned": true,
"isPinged": false,
"keysInSeconds": 20824083.85909091,
"totalSeconds": 3300
}
],
"rewards": [],
"dateUpdated": "2026-11-18T08:28:25.8176144Z",
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}Для ещё не активного puzzle (следующих) возвращаются только puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges и dateUpdated. Поля описаны в разделе Объект Statistics.
Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | problem details | Puzzle не существует или не является ни активным, ни следующим. |
GET/puzzle/{puzzleCode}/speed
Текущая скорость пула на puzzle. Кешируется на 60 секунд.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Номер 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
Воркеры, которые сканируют сейчас: те, кто отправлял ping по диапазону за последние 30 минут. Браузером не кешируется; сервер хранит ответ 60 секунд. puzzleCode 0 означает puzzle по умолчанию.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Номер 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 | path | integer | Да | Активный puzzle. |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/rewards"Пример ответа
200 OK См. Reward. Пустой массив, если у puzzle их нет.
[
{
"id": 12,
"puzzleCode": 71,
"targetAddress": "1ExampleRewardAddress0000000000000",
"rewardDescription": "Hardware wallet",
"provider": "Sponsor",
"brand": "Example",
"dateCreated": "2026-11-01T00:00:00Z",
"dateSolved": "0001-01-01T00:00:00",
"puzzleId": 71
}
]Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | problem details | Puzzle не активен. |
GET/puzzle/{puzzleCode}/challenge
Последние начальные точки челленджей активного puzzle (сначала новые, до 32). Кешируется на 600 секунд.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Активный puzzle. |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/challenge"Пример ответа
200 OK См. Challenge. Пустой массив, если их нет.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | problem details | Puzzle не активен. |
GET/puzzle/{puzzleCode}/entrancefee
Вступительный взнос puzzle в USD, если взнос включён. Кешируется на 300 секунд.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Активный puzzle со вступительным взносом. |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"Пример ответа
200 OK
{
"fee": 25.0,
"puzzle": 71
}Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | problem details | Puzzle не активен или у него нет вступительного взноса. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
Какая часть puzzle просканирована для каждого двухсимвольного префикса HEX диапазона (тепловая карта страницы puzzle). Кешируется на 3600 секунд.
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|---|---|---|---|
puzzleCode | path | integer | Да | Активный puzzle. |
Пример запроса
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"Пример ответа
200 OK Один элемент на префикс, упорядочены по hexStarts. Свойство pertantageShow намеренно написано с ошибкой (заморожено). Начиная с 70% числа останавливаются на 70%, а isLimitExceeded равно true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]Ошибки
| Статус | Тело | Когда |
|---|---|---|
400 | problem details | Puzzle не активен. |
Данные пула
Публичные эндпоинты для чтения данных о пуле в целом, списке GPU и токене BCPZ.
GET/pool/homepage
Список puzzle главной страницы: тот же массив, что и GET /puzzle, а puzzle по умолчанию содержит свою speed. Кешируется на 60 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/pool/homepage"Отвечает 200 с массивом объектов Puzzle.
GET/pool/gpus
Список тестов GPU, сначала самые быстрые (ключей в секунду в пуле). Кешируется на 300 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/pool/gpus"Пример ответа
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]Поля ответа
| Поле | Тип | Описание |
|---|---|---|
brand | string | nvidia или amd. |
name | string | Видеокарта. |
keysPerSecond | number | Измеренная скорость. |
dateUpdated | date | Последнее обновление. |
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 | integer | Номер распределения. |
dateProcces | date | Когда оно выполнено. Имя написано с ошибкой и заморожено. |
totalUsers | integer | Пользователи, получившие токены. |
totalAmount | number | Распределено BCPZ (1 за просканированный диапазон). |
description | string | Текст результата. |
GET/pool/token-top-50-holders
50 аккаунтов, заработавших больше всего BCPZ, с сокращёнными адресами кошельков. Кешируется на 600 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"Пример ответа
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]Поля ответа
| Поле | Тип | Описание |
|---|---|---|
walletAddress | string | Сокращённый адрес. |
balance | number | BCPZ на аккаунте сейчас. |
total | number | Всего заработано BCPZ. |
minted | number | BCPZ, уже выведенные в сеть Polygon. |
GET/pool/token-mint-history
Последние выводы BCPZ в сеть Polygon, сначала новые (до 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 | string | Сокращённый адрес аккаунта. |
minted | number | Отправлено BCPZ. |
date | date | Когда отправлено. |
txId | string | Хеш транзакции Polygon. Отсутствует, пока перевод не выполнен. |
GET/pool/btc-price
Цена Bitcoin в USD и EUR с биржи. Кешируется на 600 секунд.
Пример запроса
curl "https://btcpuzzle.info/api/pool/btc-price"Пример ответа
200 OK Оба значения равны 0, если источник цены недоступен.
{"usd":66739.06,"eur":60607.25}Поток в реальном времени (SignalR)
Пул публикует каждый занятый и завершённый диапазон в хаб SignalR. Сайт использует его для страницы статуса в реальном времени. Хаб публичный, не требует токена и только отправляет: методов, которые может вызвать клиент, нет.
| URL хаба | https://btcpuzzle.info/api/hex_socket |
| Старый хост | https://api.btcpuzzle.info/hex_socket |
| Протокол | SignalR со стандартным протоколом JSON; доступны 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
Один аргумент — объект JSON. Событие отправляется всем подключённым клиентам, когда диапазон выдан и когда диапазон отмечен как просканированный.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| Поле | Тип | Описание |
|---|---|---|
hex | string | HEX диапазона с третьим символом, заменённым на X. |
walletAddress | string | Сокращённый адрес аккаунта. |
workerName | string или null | Имя воркера (default, если не было отправлено). При scanned это имя, отправленное с запросом на отметку, и оно может быть null. |
puzzleCode | integer | Puzzle диапазона. |
status | string | holded после выдачи диапазона, scanned после его отметки. Написание заморожено. |
События доставляются, пока соединение открыто; после переподключения ничего не воспроизводится повторно. Когда оператор отключает поток в реальном времени, соединения отклоняются.
Объекты
Объект Puzzle
Возвращается эндпоинтами списков puzzle и /puzzle/{puzzleCode}/info. Свойства без значения опускаются.
| Поле | Тип | Описание |
|---|---|---|
id | integer | Id в базе данных (совпадает с code для puzzle старой системы). |
name | string | Например, Puzzle 71. |
code | integer | Номер puzzle. |
hexStart, hexEnd | string | Первый и последний приватный ключ puzzle в шестнадцатеричном виде. |
targetWalletAddress | string | Адрес, на котором лежит награда. |
hexRangeLength | integer | Длина HEX диапазона, который выдаёт пул (часть ключа, которую он выбирает). |
reward | number | Награда в BTC. |
hexStartPool, hexEndPool | string | Первый и последний HEX диапазона. Пусто, если puzzle нет в пуле. |
totalRanges | integer | Количество диапазонов puzzle. 0, если puzzle нет в пуле. |
percentage | number | Процент просканированных диапазонов. |
totalScanned, rangesScannedLastHour | integer | Просканированные диапазоны всего и за последний час (заполняются в эндпоинтах списков). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | разные | Итоговые цифры завершённого puzzle; statisticsFoundBy присутствует, только если известен. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | Количество приватных ключей (минус один) в одном диапазоне. Значения различаются, если диапазон охватывает несколько id. |
rangesPerKey | integer | Сколько id охватывает один диапазон (1 для большинства puzzle). |
workloadStart, workloadEnd | string | Часть приватного ключа, которую клиент сканирует после HEX диапазона: см. GET range. |
customWorkloadStart, customWorkloadEnd | string | Присутствует, если puzzle использует особый workload. |
dateStart, dateEnd | date | Плановые даты puzzle. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | Состояние puzzle: завершён, объявлен, доступен для сканирования сейчас, по умолчанию, тестовый пул, в пуле. |
isEntranceFeeActive, entranceFee | boolean, number | Включён ли вступительный взнос и его цена в USD (0, если выключен). |
nextScanAllowedInMinutes | integer | Сколько выданный диапазон удерживается, прежде чем его можно выдать кому-то другому. |
challenges | array | Последний челлендж или пустой массив. |
privateKey, publicKey | string | Только для решённых puzzle. |
rewards, speed | array, object | Присутствуют только в некоторых эндпоинтах. |
Объект Statistics
| Поле | Тип | Описание |
|---|---|---|
puzzle | object | Основные цифры puzzle (название, код, количество диапазонов, workload, состояние, награда). |
scannedLast24H | integer | Диапазоны, просканированные за последние 24 часа. |
entranceFeesPaidTotal | number | Вступительные взносы, уплаченные за puzzle, USD. |
topWorkersAlltime | array | До 50 элементов {userId, walletAddress, totalScanned}; здесь userId равен 0. |
topWorkersLast24h | array | То же за последние 24 часа. |
activeWorkers | array | {walletAddress, workerName} воркеров, отправлявших ping за последние 30 минут. |
challenges | array | До 32 челленджей. |
kingdom | object | Король puzzle: walletAddress, message, image и isPublished. |
topSpeed | object | Лучший час за всё время: date, scanned (диапазоны) и keysPerSecond. |
chartData | array | Последний месяц по часам, сначала новые: date, dateOnly, hoursOnly и rangesScanned. |
lastRanges | array | Последние 200 просканированных диапазонов, сначала новые: hex (замаскирован), walletAddress (замаскирован), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds и totalSeconds. |
rewards | array | Награды puzzle (без приватных ключей). |
dateUpdated | date | Когда были рассчитаны цифры. |
currentSpeed | object | CurrentSpeed. |
Объект CurrentSpeed
| Поле | Тип | Описание |
|---|---|---|
activeWorkerCount | integer | Воркеры, сканировавшие за последние 6 часов и отправлявшие ping за последний час. |
keysPerSecondFormatted | string | Скорость с единицей измерения: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s и так далее. |
keysPerSecondRaw | string | Скорость в ключах в секунду в виде целого числа текстом. |
Объект Challenge
| Поле | Тип | Описание |
|---|---|---|
hex | string | Начальные символы, которые сканирует каждый участник челленджа. |
dateCreated | date | Когда начался челлендж. |
puzzleId | integer | Puzzle. |
Объект Reward
| Поле | Тип | Описание |
|---|---|---|
id, puzzleCode, puzzleId | integer | Идентификаторы. |
targetAddress | string | Адрес ключа награды. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | Что за приз и кто его предоставляет. Свойства без значения опускаются. |
privateKey | string | Присутствует только после того, как награда найдена. |
dateCreated, dateSolved | date | Когда создана и найдена (0001-01-01T00:00:00, пока не найдена). |
Отличия от старой документации
Контракт не изменился: все эндпоинты, заголовки, поля и коды ошибок старого API по-прежнему работают и отвечают так же. Это руководство заменяет старую страницу, на которой были описаны три эндпоинта. Что здесь нового:
- Задокументированы публичные эндпоинты данных, поток в реальном времени, коды ошибок и лимиты частоты. На старой странице они не упоминались.
- Исправления старого текста: заголовок
UserTokenзапроса на отметку — это токен майнера (старая страница называла его адресом кошелька); интервал ping — около 2 минут и не более 30 минут, а лимит — 360 ping в минуту на токен, а не 60 в час; puzzle тестового пула —38. - Базовый URL —
https://btcpuzzle.info/api; старый хостapi.btcpuzzle.infoпродолжает работать. - У хаба SignalR больше нет методов клиент-сервер, поэтому никто не может отправлять поддельные события. Само событие не изменилось.
- Теперь выдаётся и последний свободный диапазон puzzle, а слишком узкое окно
CustomRangeрасширяется, чтобы нельзя было выбрать диапазон, запросив ровно один. - Публичная статистика больше не показывает IP-адрес майнера.