Документация API

Создайте свой клиент для пула. Все эндпоинты с запросами, ответами и ошибками.

Обзор

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}/rangeUserToken120 запросов за 60 секунд
PUT /puzzle/{puzzleCode}/rangeUserToken360 запросов за 60 секунд
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 запросов за 60 секунд
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 запросов за 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).
400validation problemОбязательный заголовок отсутствует или неверен, либо номер puzzle вне диапазона от 1 до 160. Это объект application/problem+json, в поле errors которого перечислены ошибочные имена.
400problem 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 продлевает удержание).

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathinteger (от 1 до 160)ДаPuzzle для сканирования, например 71. 38 — тестовый пул. Список кодов возвращает GET /puzzle/codes. Вместо завершённого puzzle молча выдаётся puzzle по умолчанию, а в ответе в поле puzzleCode указано, какой puzzle вы получили.
UserTokenheaderstring (128 символов)ДаВаш токен майнера.
WorkerNameheaderstring (от 1 до 16 символов)НетИмя этого воркера. Только буквы и цифры. Если не отправлено, сохраняется как default.
SecurityHashheaderstringНетПроизвольный текст, сохраняемый с диапазоном. Необязательно.
CustomRangeheaderstringНетОграничивает получаемый диапазон: префикс 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"
  ]
}

Поля ответа

ПолеТипОписание
hexstringДиапазон для сканирования, в верхнем регистре без дополнения нулями. Это начало приватных ключей диапазона.
puzzleCodeintegerPuzzle, к которому относится диапазон (puzzle по умолчанию, если запрошенный завершён).
workloadStartstringДобавляется к hex, чтобы получить первый приватный ключ диапазона.
workloadEndstringДобавляется к hex, чтобы получить последний приватный ключ диапазона. Может быть длиннее workloadStart в puzzle, где диапазон охватывает несколько id.
targetAddressstringИскомый адрес 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).
400validation problemЗаголовок отсутствует или имеет неверный формат, либо номер puzzle вне диапазона от 1 до 160.
429{"isSuccess": false, ...}Лимит частоты: 120 в минуту на токен.

Proof of work

Пул хочет быть уверен, что вы действительно просканировали диапазон. Для каждого диапазона он выбирает внутри него шесть приватных ключей и возвращает только их адреса (proofOfWorkAddresses). Сканируя диапазон в поисках целевого адреса, ищите и эти шесть адресов. Когда найдены все шесть приватных ключей:

  1. Запишите каждый приватный ключ как 64 шестнадцатеричных символа в верхнем регистре, дополнив нулями слева.
  2. Склейте шесть строк в порядке адресов без разделителей.
  3. Вычислите 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

Отмечает диапазон как просканированный. Пул проверяет доказательство и, если оно верно, засчитывает диапазон вам. Диапазон можно отметить только один раз.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathinteger (от 1 до 160)ДаPuzzle диапазона.
UserTokenheaderstring (128 символов)ДаВаш токен майнера.
HEXheaderstringДаhex просканированного диапазона в том виде, в каком его вернул пул. Пример: 3AB8443.
HashedProofKeyheaderstringДаДоказательство работы: см. Proof of work.
WorkerNameheaderstring (от 1 до 16 символов)НетВоркер, просканировавший диапазон.
GPUNameheaderstringНетМодель видеокарты. Используется в публичной статистике.
GPUCountheaderintegerНетКоличество карт у воркера. По умолчанию 1.
IsForceContinueheaderbooleanНетУстановите, если воркер продолжил работу, хотя дошёл до конца своего пространства ключей. По умолчанию false.

Пример запроса

curl -X PUT "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1" \
  -H "HEX: 3AB8443" \
  -H "HashedProofKey: 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87" \
  -H "GPUName: RTX 4090" \
  -H "GPUCount: 1"

Пример ответа

200 OK

{
  "isSuccess": true
}

Ошибки

СтатусТелоКогда
400{"isSuccess": false}Любой отказ: неверное доказательство, неизвестный диапазон, уже отмеченный диапазон, заблокированный аккаунт, неактивный puzzle.
400validation problemОбязательный заголовок отсутствует или имеет неверный формат.
429{"isSuccess": false, ...}Лимит частоты: 360 в минуту на токен.

PATCH/puzzle/{puzzleCode}/range/ping

Сообщает пулу, что воркер всё ещё сканирует свой диапазон. Ping сохраняет удержание диапазона и показывает воркер активным на сайте. Отправляйте его примерно каждые 2 минуты; интервал не должен превышать 30 минут, иначе пул заберёт диапазон обратно.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаPuzzle диапазона.
HexheaderstringДаДиапазон, который воркер сканирует сейчас.
UserTokenheaderstring (128 символов)ДаВаш токен майнера.
WorkerNameheaderstringДаИмя воркера, использованное при запросе диапазона (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; сайт хранит только зашифрованный текст, который вы расшифровываете своим приватным ключом. Ключ появляется на странице найденных ключей в вашей панели.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаPuzzle, к которому относится ключ.
UserTokenheaderstring (128 символов)ДаВаш токен майнера.
Content-TypeheaderstringДаapplication/json.
namebodystringНетМетка, например имя воркера. Сохраняется как Puzzle71 - rig1.
encryptedKeybodystringДаЗашифрованный приватный ключ (клиент отправляет его в 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"}Неизвестный или заблокированный токен.
400problem 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 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаНомер 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 минут).

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаАктивный 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.

Ошибки

СтатусТелоКогда
400problem detailsPuzzle не существует или не является ни активным, ни следующим.

GET/puzzle/{puzzleCode}/speed

Текущая скорость пула на puzzle. Кешируется на 60 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаНомер 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 по умолчанию.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаНомер 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 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаАктивный puzzle.

Пример запроса

curl "https://btcpuzzle.info/api/puzzle/71/rewards"

Пример ответа

200 OK См. Reward. Пустой массив, если у puzzle их нет.

[
  {
    "id": 12,
    "puzzleCode": 71,
    "targetAddress": "1ExampleRewardAddress0000000000000",
    "rewardDescription": "Hardware wallet",
    "provider": "Sponsor",
    "brand": "Example",
    "dateCreated": "2026-11-01T00:00:00Z",
    "dateSolved": "0001-01-01T00:00:00",
    "puzzleId": 71
  }
]

Ошибки

СтатусТелоКогда
400problem detailsPuzzle не активен.

GET/puzzle/{puzzleCode}/challenge

Последние начальные точки челленджей активного puzzle (сначала новые, до 32). Кешируется на 600 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаАктивный puzzle.

Пример запроса

curl "https://btcpuzzle.info/api/puzzle/71/challenge"

Пример ответа

200 OK См. Challenge. Пустой массив, если их нет.

[
  {
    "hex": "3A",
    "dateCreated": "2026-11-18T06:00:00Z",
    "puzzleId": 71
  }
]

Ошибки

СтатусТелоКогда
400problem detailsPuzzle не активен.

GET/puzzle/{puzzleCode}/entrancefee

Вступительный взнос puzzle в USD, если взнос включён. Кешируется на 300 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаАктивный puzzle со вступительным взносом.

Пример запроса

curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"

Пример ответа

200 OK

{
  "fee": 25.0,
  "puzzle": 71
}

Ошибки

СтатусТелоКогда
400problem detailsPuzzle не активен или у него нет вступительного взноса.

GET/puzzle/{puzzleCode}/statistics-by-hex-prefix

Какая часть puzzle просканирована для каждого двухсимвольного префикса HEX диапазона (тепловая карта страницы puzzle). Кешируется на 3600 секунд.

Параметры

ИмяГдеТипОбязательноОписание
puzzleCodepathintegerДаАктивный 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
  }
]

Ошибки

СтатусТелоКогда
400problem detailsPuzzle не активен.

Данные пула

Публичные эндпоинты для чтения данных о пуле в целом, списке 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"
  }
]

Поля ответа

ПолеТипОписание
brandstringnvidia или amd.
namestringВидеокарта.
keysPerSecondnumberИзмеренная скорость.
dateUpdateddateПоследнее обновление.

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

Поля ответа

ПолеТипОписание
idintegerНомер распределения.
dateProccesdateКогда оно выполнено. Имя написано с ошибкой и заморожено.
totalUsersintegerПользователи, получившие токены.
totalAmountnumberРаспределено BCPZ (1 за просканированный диапазон).
descriptionstringТекст результата.

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

Поля ответа

ПолеТипОписание
walletAddressstringСокращённый адрес.
balancenumberBCPZ на аккаунте сейчас.
totalnumberВсего заработано BCPZ.
mintednumberBCPZ, уже выведенные в сеть 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"
  }
]

Поля ответа

ПолеТипОписание
walletAddressstringСокращённый адрес аккаунта.
mintednumberОтправлено BCPZ.
datedateКогда отправлено.
txIdstringХеш транзакции 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"
}
ПолеТипОписание
hexstringHEX диапазона с третьим символом, заменённым на X.
walletAddressstringСокращённый адрес аккаунта.
workerNamestring или nullИмя воркера (default, если не было отправлено). При scanned это имя, отправленное с запросом на отметку, и оно может быть null.
puzzleCodeintegerPuzzle диапазона.
statusstringholded после выдачи диапазона, scanned после его отметки. Написание заморожено.

События доставляются, пока соединение открыто; после переподключения ничего не воспроизводится повторно. Когда оператор отключает поток в реальном времени, соединения отклоняются.

Объекты

Объект Puzzle

Возвращается эндпоинтами списков puzzle и /puzzle/{puzzleCode}/info. Свойства без значения опускаются.

ПолеТипОписание
idintegerId в базе данных (совпадает с code для puzzle старой системы).
namestringНапример, Puzzle 71.
codeintegerНомер puzzle.
hexStart, hexEndstringПервый и последний приватный ключ puzzle в шестнадцатеричном виде.
targetWalletAddressstringАдрес, на котором лежит награда.
hexRangeLengthintegerДлина HEX диапазона, который выдаёт пул (часть ключа, которую он выбирает).
rewardnumberНаграда в BTC.
hexStartPool, hexEndPoolstringПервый и последний HEX диапазона. Пусто, если puzzle нет в пуле.
totalRangesintegerКоличество диапазонов puzzle. 0, если puzzle нет в пуле.
percentagenumberПроцент просканированных диапазонов.
totalScanned, rangesScannedLastHourintegerПросканированные диапазоны всего и за последний час (заполняются в эндпоинтах списков).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByразныеИтоговые цифры завершённого puzzle; statisticsFoundBy присутствует, только если известен.
rangeContainsKeys, rangeContainsKeyByDefaultintegerКоличество приватных ключей (минус один) в одном диапазоне. Значения различаются, если диапазон охватывает несколько id.
rangesPerKeyintegerСколько id охватывает один диапазон (1 для большинства puzzle).
workloadStart, workloadEndstringЧасть приватного ключа, которую клиент сканирует после HEX диапазона: см. GET range.
customWorkloadStart, customWorkloadEndstringПрисутствует, если puzzle использует особый workload.
dateStart, dateEnddateПлановые даты puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanСостояние puzzle: завершён, объявлен, доступен для сканирования сейчас, по умолчанию, тестовый пул, в пуле.
isEntranceFeeActive, entranceFeeboolean, numberВключён ли вступительный взнос и его цена в USD (0, если выключен).
nextScanAllowedInMinutesintegerСколько выданный диапазон удерживается, прежде чем его можно выдать кому-то другому.
challengesarrayПоследний челлендж или пустой массив.
privateKey, publicKeystringТолько для решённых puzzle.
rewards, speedarray, objectПрисутствуют только в некоторых эндпоинтах.

Объект Statistics

ПолеТипОписание
puzzleobjectОсновные цифры puzzle (название, код, количество диапазонов, workload, состояние, награда).
scannedLast24HintegerДиапазоны, просканированные за последние 24 часа.
entranceFeesPaidTotalnumberВступительные взносы, уплаченные за puzzle, USD.
topWorkersAlltimearrayДо 50 элементов {userId, walletAddress, totalScanned}; здесь userId равен 0.
topWorkersLast24harrayТо же за последние 24 часа.
activeWorkersarray{walletAddress, workerName} воркеров, отправлявших ping за последние 30 минут.
challengesarrayДо 32 челленджей.
kingdomobjectКороль puzzle: walletAddress, message, image и isPublished.
topSpeedobjectЛучший час за всё время: date, scanned (диапазоны) и keysPerSecond.
chartDataarrayПоследний месяц по часам, сначала новые: date, dateOnly, hoursOnly и rangesScanned.
lastRangesarrayПоследние 200 просканированных диапазонов, сначала новые: hex (замаскирован), walletAddress (замаскирован), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds и totalSeconds.
rewardsarrayНаграды puzzle (без приватных ключей).
dateUpdateddateКогда были рассчитаны цифры.
currentSpeedobjectCurrentSpeed.

Объект CurrentSpeed

ПолеТипОписание
activeWorkerCountintegerВоркеры, сканировавшие за последние 6 часов и отправлявшие ping за последний час.
keysPerSecondFormattedstringСкорость с единицей измерения: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s и так далее.
keysPerSecondRawstringСкорость в ключах в секунду в виде целого числа текстом.

Объект Challenge

ПолеТипОписание
hexstringНачальные символы, которые сканирует каждый участник челленджа.
dateCreateddateКогда начался челлендж.
puzzleIdintegerPuzzle.

Объект Reward

ПолеТипОписание
id, puzzleCode, puzzleIdintegerИдентификаторы.
targetAddressstringАдрес ключа награды.
rewardContent, rewardDescription, provider, providerDesc, brandstringЧто за приз и кто его предоставляет. Свойства без значения опускаются.
privateKeystringПрисутствует только после того, как награда найдена.
dateCreated, dateSolveddateКогда создана и найдена (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-адрес майнера.

Угостите меня кофе

Puzzle пула

Что пул сканирует сейчас, что дальше и над какими puzzle он уже работал.

Сканируется1

Далее2

Ранее4

Все 160 puzzle