Dokumentacja API

Zbuduj własnego klienta dla puli. Wszystkie endpointy wraz z żądaniami, odpowiedziami i błędami.

Przegląd

API btcpuzzle.info to interfejs, z którym komunikuje się klient puli. Rozdziela zakresy kluczy do skanowania, przyjmuje wynik skanu i publikuje publiczne statystyki puli. btcpuzzle.info jest open source i każdy może napisać klienta: ten przewodnik opisuje każdy publiczny endpoint, dane do wysłania, dane zwrotne i błędy, które możesz napotkać. Pytania: support@btcpuzzle.info.

To API jest celowo zamrożone: zależą od niego minery i narzędzia zewnętrzne. Ścieżki, nagłówki, nazwy pól (łącznie z kilkoma starymi pisowniami, takimi jak dateProcces i holded) i kody błędów się nie zmieniają. Do odpowiedzi mogą dochodzić nowe pola, więc ignoruj pola, których nie znasz.

Bazowy URL

Każda ścieżka w tym przewodniku jest względna wobec bazowego URL:

https://btcpuzzle.info/api

Klienci napisani przed przeniesieniem strony mogą nadal używać starego hosta, z tymi samymi ścieżkami i bez prefiksu /api:

https://api.btcpuzzle.info

Na przykład GET https://btcpuzzle.info/api/puzzle/codes i GET https://api.btcpuzzle.info/puzzle/codes zwracają to samo. Nowi klienci powinni używać bazowego URL z /api.

Szybki start

Załóż darmowe konto na btcpuzzle.info, skopiuj z panelu swój token minera, a potem poproś o zakres:

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Przeskanuj zwrócony zakres razem z sześcioma adresami dowodowymi, wyślij dowód przez PUT /puzzle/71/range i powtarzaj. Między tymi dwoma wywołaniami co jakiś czas wysyłaj ping, aby pula wiedziała, że worker żyje.

Konwencje

Wersjonowanie

Istnieje jedna wersja i nie ma wersji w URL. Kontrakt starego API jest zachowany dokładnie; zobacz Zmiany względem starej dokumentacji.

Uwierzytelnianie

Endpointy minera identyfikują użytkownika po nagłówku UserToken: 128-znakowym tokenie minera Twojego konta. Nie ma dla nich innego logowania ani sesji. Nowy token możesz w każdej chwili utworzyć na swoim koncie; stary od razu przestaje działać. Zachowaj token w tajemnicy: kto go ma, skanuje w Twoim imieniu.

Wszystkie endpointy danych (puzzle, statystyki, pula, token) są publiczne i nie wymagają tokenu.

Żądania i odpowiedzi

  • W endpointach minera dane żądania przesyła się w nagłówkach HTTP, a nie w query stringu ani w body. Wielkość liter w nazwach nagłówków nie ma znaczenia (UserToken, usertoken i userToken to ten sam nagłówek). Tylko POST /puzzle/{puzzleCode}/save-private-key ma body w formacie JSON (Content-Type: application/json).
  • Odpowiedzi to JSON w UTF-8 z nazwami właściwości w camelCase. Właściwości bez wartości są pomijane; API nigdy nie zapisuje JSON-owego null. Nie polegaj na wcięciach.
  • Daty są w formacie ISO 8601 w UTC (2026-11-18T08:28:25.8176144Z). Kwoty pieniężne i ilości to liczby JSON.
  • Duże liczby, takie jak rangeContainsKeys, to 64-bitowe liczby całkowite bez znaku i mogą być większe niż 2^53: w językach używających typu double parsuj je jako 64-bitowe liczby całkowite lub ciągi znaków.
  • Adresy portfeli w danych publicznych są skracane (pierwsze 8 znaków, ..., ostatnie 8), a trzeci znak HEX zakresu jest zastępowany przez X (3AB8443 staje się 3AX8443).

Limity żądań

Poniższe limity to obecne wartości domyślne. Są liczone w stałym oknie czasowym; operator może je dostosować, więc odczytuj odpowiedź 429 zamiast wpisywać liczby na sztywno.

DotyczyLiczone naLimit
GET /puzzle/{puzzleCode}/rangeUserToken120 żądań na 60 sekund
PUT /puzzle/{puzzleCode}/rangeUserToken360 żądań na 60 sekund
PATCH /puzzle/{puzzleCode}/range/pingUserToken360 żądań na 60 sekund
POST /puzzle/{puzzleCode}/save-private-keyUserToken10 żądań na 180 sekund
Każdy inny endpointAdres IP20 żądań na sekundę dla każdego endpointu, łącznie 200 na sekundę

Żądanie ponad limit otrzymuje odpowiedź 429 Too Many Requests, nagłówek Retry-After i takie body:

{
  "isSuccess": false,
  "details": "Quota exceeded."
}

Błędy

Niepowodzenia zwracają poniższe kody statusu. Body zależy od endpointu, więc najpierw sprawdzaj kod statusu.

StatusBodyZnaczenie
400{"error": "<code>"}Endpoint minera odrzucił żądanie. Kod mówi dlaczego: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (pisownia historyczna), invalid_request.
400{"isSuccess": false}Żądanie oznaczenia zakresu zostało odrzucone (błędny dowód, nieznany lub już przeskanowany zakres, zablokowany użytkownik, nieaktywne puzzle).
400problem walidacjiBrakuje wymaganego nagłówka lub jest nieprawidłowy albo numer puzzle jest spoza zakresu od 1 do 160. To obiekt application/problem+json, którego errors wymienia błędne nazwy.
400problem detailsPubliczny endpoint danych nie ma nic do zwrócenia dla tego puzzle (nieznane lub nieaktywne puzzle). application/problem+json z polami type, title, status i traceId.
401{"error": "invalid_user_token"}Token minera jest nieznany lub konto jest zablokowane (ping i save-private-key).
404{"error": "range_not_found"}Zakres do pingowania nie jest zajęty przez tego workera.
429{"isSuccess": false, "details": "Quota exceeded."}Limit żądań. Odczekaj Retry-After sekund.

Przykład problemu walidacji (GET /puzzle/71/range bez nagłówka 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"
}

Cache i CORS

Publiczne endpointy danych wysyłają Cache-Control: public, max-age=N; wartość jest podana przy każdym endpoincie, a kopia w cache jest wspólna dla wszystkich wywołujących, więc odpytywanie częściej niż co N sekund zwraca tylko te same dane. Endpointy minera nigdy nie są cache'owane. Przeglądarki mogą wywoływać API z https://btcpuzzle.info, https://www.btcpuzzle.info i http://localhost:3000 (ostatni istnieje na potrzeby lokalnego rozwoju starego frontendu); CORS nie dotyczy klientów natywnych.

Endpointy minera

Trzy wywołania pętli skanowania: pobierz zakres, wysyłaj ping podczas skanowania, oznacz go jako przeskanowany. Czwarte wywołanie zapisuje znaleziony klucz. Wszystkie cztery używają nagłówka UserToken.

GET/puzzle/{puzzleCode}/range

Wydaje losowy wolny zakres puzzle i rezerwuje go dla Ciebie. Nikt inny nie dostanie zakresu, który masz zarezerwowany; jeśli go nie oznaczysz, po pewnym czasie wraca do puli (ping przedłuża rezerwację).

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowita (od 1 do 160)TakPuzzle do skanowania, np. 71. 38 to pula testowa. GET /puzzle/codes wymienia kody. Dla ukończonego puzzle zakres jest bez ostrzeżenia wydawany z domyślnego puzzle, a odpowiedź podaje w puzzleCode, które puzzle otrzymałeś.
UserTokennagłówekciąg znaków (128 znaków)TakTwój token minera.
WorkerNamenagłówekciąg znaków (od 1 do 16 znaków)NieNazwa tego workera. Tylko litery i cyfry. Zapisywana jako default, gdy jej nie wyślesz.
SecurityHashnagłówekciąg znakówNieDowolny tekst przechowywany z zakresem. Opcjonalny.
CustomRangenagłówekciąg znakówNieOgranicza otrzymywany zakres: prefiks HEX (2D, 3BA) lub start:end (3400000:38FFFFF). none lub brak nagłówka oznacza dowolny zakres. Bardzo wąskie okno jest poszerzane przez pulę, więc możesz dostać inny zakres niż podany.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/71/range" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Przykładowa odpowiedź

200 OK

{
  "hex": "3AB8443",
  "puzzleCode": 71,
  "workloadStart": "00000000000",
  "workloadEnd": "fffffffffff",
  "targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
  "proofOfWorkAddresses": [
    "1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
    "15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
    "1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
    "14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
    "1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
    "14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
  ]
}

Pola odpowiedzi

PoleTypOpis
hexciąg znakówZakres do skanowania, wielkimi literami, bez dopełnienia. To początek kluczy prywatnych zakresu.
puzzleCodeliczba całkowitaPuzzle, do którego należy zakres (domyślne puzzle, gdy to, o które prosiłeś, jest ukończone).
workloadStartciąg znakówDołączane do hex, aby uzyskać pierwszy klucz prywatny zakresu.
workloadEndciąg znakówDołączane do hex, aby uzyskać ostatni klucz prywatny zakresu. Może być dłuższe niż workloadStart w puzzle, których zakresy obejmują kilka id.
targetAddressciąg znakówAdres puzzle, którego szukasz. Skanuj go razem z adresami dowodowymi.
proofOfWorkAddressestablica 6 ciągów znakówAdresy sześciu kluczy prywatnych umieszczonych przez pulę w zakresie. Znajdź ich klucze prywatne, aby udowodnić skan: zobacz Proof of work.

W powyższym przykładzie zakres biegnie od 3AB8443 + 00000000000 = 3AB844300000000000 do 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF. Klucze prywatne mają 64 znaki szesnastkowe; dopełnij je zerami z lewej strony.

Błędy

StatusBodyKiedy
400{"error": "invalid_puzzle"}Puzzle nie istnieje lub nie jest aktywne.
400{"error": "invalid_user_token"}Token jest nieznany lub zablokowany.
400{"error": "too_much_request"}Masz zarezerwowanych zbyt wiele nieprzeskanowanych zakresów albo prosisz o nie szybciej, niż je kończysz. Skanuj to, co masz; zarezerwowane zakresy wracają do puli po krótkim czasie.
400{"error": "not_eligable"}Puzzle ma wpisowe, a Ty jeszcze nie spełniasz jego warunków.
400{"error": "reached_of_keyspace"}Nie został żaden wolny zakres (lub żaden pasujący do Twojego CustomRange).
400validation problemBrakujący lub błędny nagłówek albo numer puzzle spoza zakresu od 1 do 160.
429{"isSuccess": false, ...}Limit żądań: 120 na minutę na token.

Proof of work

Pula chce mieć pewność, że naprawdę przeskanowałeś zakres. Z każdym zakresem wybiera w nim sześć kluczy prywatnych i zwraca tylko ich adresy (proofOfWorkAddresses). Skanując zakres w poszukiwaniu adresu docelowego, szukaj też tych sześciu adresów. Gdy znajdziesz wszystkie sześć kluczy prywatnych:

  1. Zapisz każdy klucz prywatny jako 64 wielkie znaki szesnastkowe, dopełnione zerami z lewej strony.
  2. Połącz sześć ciągów w kolejności adresów, bez niczego pomiędzy.
  3. Oblicz SHA-256 tekstu UTF-8 i zapisz go jako 64 małe znaki szesnastkowe. To jest HashedProofKey żądania oznaczenia.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

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

Dowód jest inny dla każdego zakresu. Obecnie adresów dowodowych jest sześć; odczytuj długość proofOfWorkAddresses zamiast to zakładać.

PUT/puzzle/{puzzleCode}/range

Oznacza zakres jako przeskanowany. Pula sprawdza dowód i, jeśli jest poprawny, zalicza Ci zakres jako ukończony. Zakres można oznaczyć tylko raz.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowita (od 1 do 160)TakPuzzle zakresu.
UserTokennagłówekciąg znaków (128 znaków)TakTwój token minera.
HEXnagłówekciąg znakówTakWartość hex przeskanowanego zakresu, w postaci zwróconej przez pulę. Przykład: 3AB8443.
HashedProofKeynagłówekciąg znakówTakProof of work: zobacz Proof of work.
WorkerNamenagłówekciąg znaków (od 1 do 16 znaków)NieWorker, który przeskanował zakres.
GPUNamenagłówekciąg znakówNieModel karty graficznej. Używany w publicznych statystykach.
GPUCountnagłówekliczba całkowitaNieLiczba kart workera. Domyślnie 1.
IsForceContinuenagłówekwartość logicznaNieUstaw, gdy worker kontynuował mimo osiągnięcia końca swojej przestrzeni kluczy. Domyślnie false.

Przykładowe żądanie

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"

Przykładowa odpowiedź

200 OK

{
  "isSuccess": true
}

Błędy

StatusBodyKiedy
400{"isSuccess": false}Każda odmowa: błędny dowód, nieznany zakres, zakres już oznaczony, zablokowane konto, nieaktywne puzzle.
400validation problemBrakuje wymaganego nagłówka lub jest błędny.
429{"isSuccess": false, ...}Limit żądań: 360 na minutę na token.

PATCH/puzzle/{puzzleCode}/range/ping

Informuje pulę, że worker nadal skanuje swój zakres. Ping podtrzymuje rezerwację zakresu i pokazuje workera na stronie jako aktywnego. Wysyłaj go mniej więcej co 2 minuty; odstęp nie może przekroczyć 30 minut, inaczej pula odbierze zakres.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakPuzzle zakresu.
Hexnagłówekciąg znakówTakZakres, który worker teraz skanuje.
UserTokennagłówekciąg znaków (128 znaków)TakTwój token minera.
WorkerNamenagłówekciąg znakówTakNazwa workera użyta przy żądaniu zakresu (default, jeśli żadnej nie wysłano).

Przykładowe żądanie

curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
  -H "Hex: 3AB8443" \
  -H "UserToken: <128-character miner token>" \
  -H "WorkerName: rig1"

Przykładowa odpowiedź

200 OK z pustym body.

Błędy

StatusBodyKiedy
400{"error": "invalid_request"}Nagłówek jest pusty.
401{"error": "invalid_user_token"}Nieznany lub zablokowany token.
404{"error": "range_not_found"}Ten worker nie ma zarezerwowanego nieprzeskanowanego zakresu o tym HEX w tym puzzle.
429{"isSuccess": false, ...}Limit żądań: 360 na minutę na token.

POST/puzzle/{puzzleCode}/save-private-key

Zapisuje znaleziony klucz prywatny na Twoim koncie w postaci zaszyfrowanej. Klient szyfruje klucz podanym mu kluczem publicznym RSA; strona przechowuje tylko zaszyfrowany tekst, który odszyfrowujesz swoim kluczem prywatnym. Klucz pojawia się na stronie znalezionych kluczy w Twoim panelu.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakPuzzle, do którego należy klucz.
UserTokennagłówekciąg znaków (128 znaków)TakTwój token minera.
Content-Typenagłówekciąg znakówTakapplication/json.
namebodyciąg znakówNieEtykieta, np. nazwa workera. Zapisywana jako Puzzle71 - rig1.
encryptedKeybodyciąg znakówTakZaszyfrowany klucz prywatny (klient wysyła go w base64).

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Zwróć uwagę, że właściwość to success, a nie isSuccess.

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

Błędy

StatusBodyKiedy
401{"error": "invalid_user_token"}Nieznany lub zablokowany token.
400problem detailsNic nie zapisano: ten sam klucz jest już zapisany dla tego konta albo brakuje body.
429{"isSuccess": false, ...}Limit żądań: 10 na 180 sekund na token.

Dane puzzli

Publiczne endpointy odczytu dotyczące puzzli w puli. Token nie jest potrzebny. Obiekt Puzzle i pozostałe obiekty są opisane na końcu tego przewodnika.

GET/puzzle

Puzzle obecne w puli: aktywne, następne i pula testowa (oraz ukończone, zachowane dla historii). Cache na 300 sekund.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Tablica obiektów Puzzle, tutaj skrócona do jednego.

[
  {
    "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": []
  }
]

Błędy

StatusBodyKiedy
404[]Pula nie ma żadnego puzzle.

GET/puzzle/all

Wszystkie puzzle z bazy danych, łącznie z ukończonymi. Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/all"

Zwraca 200 z tablicą obiektów Puzzle.

GET/puzzle/available

Puzzle, które można skanować w puli. Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/available"

Zwraca 200 z tablicą obiektów Puzzle.

GET/puzzle/default

Domyślne puzzle: to, na które przechodzi żądanie dotyczące ukończonego puzzle. Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/default"

Przykładowa odpowiedź

200 OK Pojedynczy obiekt 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": []
}

Błędy

StatusBodyKiedy
404{"error": "puzzle_not_found"}Nie ustawiono domyślnego puzzle.

GET/puzzle/codes

Numery puzzli aktywnych lub następnych, najpierw zwykłe puzzle, na końcu pula testowa. Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/codes"

Przykładowa odpowiedź

200 OK

[71, 72, 73, 38]

GET/puzzle/{puzzleCode}/info

Jedno puzzle, odczytane z bazy danych. Cache na 10 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakNumer puzzle.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Obiekt Puzzle. Wartości wyliczane w czasie działania, takie jak rangesScannedLastHour, są wypełniane tylko w endpointach list.

{
  "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": []
}

Błędy

StatusBodyKiedy
204pusteNie ma takiego puzzle.

GET/puzzle/{puzzleCode}/statistics

Wszystko, co pokazuje strona puzzle: sumy, rankingi, aktywne workery, ostatnie 200 przeskanowanych zakresów i wykres godzinowy. Cache na 60 sekund (a serwer przechowuje jedną kopię przez 5 minut).

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakAktywne puzzle (lub pula testowa).

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Skrócona: tablice zawierają tu po jednym elemencie, a lastRanges do 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"
  }
}

Dla puzzle, które nie jest jeszcze aktywne (następne), zwracane są tylko puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges i dateUpdated. Opis pól znajdziesz w obiekcie Statistics.

Błędy

StatusBodyKiedy
400problem detailsPuzzle nie istnieje albo nie jest ani aktywne, ani następne.

GET/puzzle/{puzzleCode}/speed

Obecna prędkość puli w danym puzzle. Cache na 60 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakNumer puzzle.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Zobacz CurrentSpeed. Dla nieznanego puzzle zwracane są wartości zerowe, nigdy błąd.

{
  "puzzleCode": 71,
  "currentSpeed": {
    "activeWorkerCount": 38,
    "keysPerSecondFormatted": "162.3 Bkeys/s",
    "keysPerSecondRaw": "162300000000"
  }
}

GET/puzzle/{puzzleCode}/workers

Workery, które teraz skanują: te z zakresem pingowanym w ciągu ostatnich 30 minut. Nie jest cache'owane przez przeglądarkę; serwer przechowuje odpowiedź przez 60 sekund. puzzleCode 0 oznacza domyślne puzzle.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakNumer puzzle.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Pusta tablica, gdy nikt nie skanuje lub puzzle jest nieznane.

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "workerName": "rig1"
  }
]

GET/puzzle/{puzzleCode}/workers-pinging

Ta sama lista co /workers (zachowana jako osobna ścieżka, bo klienci używają obu).

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"

Te same parametry i odpowiedź co GET /puzzle/{puzzleCode}/workers.

GET/puzzle/{puzzleCode}/rewards

Nagrody puli dla aktywnego puzzle: dodatkowe nagrody, które sponsorzy umieszczają na kluczach prywatnych w zakresach (od najnowszych, maksymalnie 32). Klucz prywatny nagrody jest pokazywany dopiero po jej rozwiązaniu. Cache na 600 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakAktywne puzzle.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Zobacz Reward. Pusta tablica, gdy puzzle nie ma nagród.

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

Błędy

StatusBodyKiedy
400problem detailsPuzzle nie jest aktywne.

GET/puzzle/{puzzleCode}/challenge

Najnowsze punkty startowe wyzwań aktywnego puzzle (od najnowszych, maksymalnie 32). Cache na 600 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakAktywne puzzle.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK Zobacz Challenge. Pusta tablica, gdy nie ma żadnego.

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

Błędy

StatusBodyKiedy
400problem detailsPuzzle nie jest aktywne.

GET/puzzle/{puzzleCode}/entrancefee

Wpisowe puzzle w USD, gdy opłata jest włączona. Cache na 300 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakAktywne puzzle z wpisowym.

Przykładowe żądanie

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

Przykładowa odpowiedź

200 OK

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

Błędy

StatusBodyKiedy
400problem detailsPuzzle nie jest aktywne lub nie ma wpisowego.

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

Jaka część puzzle jest przeskanowana dla każdego dwuznakowego prefiksu HEX zakresu (mapa cieplna na stronie puzzle). Cache na 3600 sekund.

Parametry

NazwaGdzieTypWymaganyOpis
puzzleCodeścieżkaliczba całkowitaTakAktywne puzzle.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"

Przykładowa odpowiedź

200 OK Jeden element na prefiks, posortowane według hexStarts. Właściwość pertantageShow ma celowo błędną pisownię (zamrożoną). Od 70% liczby zatrzymują się na 70%, a isLimitExceeded ma wartość true.

[
  {
    "hexStarts": "40",
    "maxRanges": 1048576,
    "scannedShow": 4411,
    "pertantageShow": 0.37,
    "isLimitExceeded": false
  }
]

Błędy

StatusBodyKiedy
400problem detailsPuzzle nie jest aktywne.

Dane puli

Publiczne endpointy odczytu dotyczące puli jako całości, listy GPU i tokenu BCPZ.

GET/pool/homepage

Lista puzzli ze strony głównej: ta sama tablica co GET /puzzle, a domyślne puzzle zawiera swoje speed. Cache na 60 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/homepage"

Zwraca 200 z tablicą obiektów Puzzle.

GET/pool/gpus

Lista benchmarków GPU, od najszybszych (klucze na sekundę w puli). Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/gpus"

Przykładowa odpowiedź

200 OK

[
  {
    "brand": "nvidia",
    "name": "RTX 4090",
    "keysPerSecond": 4491469067.71,
    "dateUpdated": "2026-11-18T08:27:53.190819Z"
  }
]

Pola odpowiedzi

PoleTypOpis
brandciąg znakównvidia lub amd.
nameciąg znakówKarta.
keysPerSecondliczbaZmierzona prędkość.
dateUpdateddataOstatnia aktualizacja.

GET/pool/token-distribute-history

Dzienne dystrybucje BCPZ, od najnowszych (maksymalnie 180). Cache na 300 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/token-distribute-history"

Przykładowa odpowiedź

200 OK

[
  {
    "id": 412,
    "dateProcces": "2026-11-17T03:00:19Z",
    "totalUsers": 85,
    "totalAmount": 516,
    "description": "Success: 85/85"
  }
]

Pola odpowiedzi

PoleTypOpis
idliczba całkowitaNumer dystrybucji.
dateProccesdataKiedy się odbyła. Nazwa ma błędną pisownię i jest zamrożona.
totalUsersliczba całkowitaUżytkownicy, którzy otrzymali tokeny.
totalAmountliczbaRozdane BCPZ (1 za przeskanowany zakres).
descriptionciąg znakówTekst wyniku.

GET/pool/token-top-50-holders

50 kont z największą liczbą zdobytych BCPZ, ze skróconymi adresami portfeli. Cache na 600 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/token-top-50-holders"

Przykładowa odpowiedź

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "balance": 2500.25,
    "total": 400,
    "minted": 200
  }
]

Pola odpowiedzi

PoleTypOpis
walletAddressciąg znakówSkrócony adres.
balanceliczbaBCPZ obecnie na koncie.
totalliczbaŁącznie zdobyte BCPZ.
mintedliczbaBCPZ już wypłacone do sieci Polygon.

GET/pool/token-mint-history

Najnowsze wypłaty BCPZ do sieci Polygon, od najnowszych (maksymalnie 180). Cache na 600 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/token-mint-history"

Przykładowa odpowiedź

200 OK

[
  {
    "walletAddress": "1BvBMSEY...7xJaNVN2",
    "minted": 100,
    "date": "2026-11-15T08:27:58.123754Z",
    "txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
  }
]

Pola odpowiedzi

PoleTypOpis
walletAddressciąg znakówSkrócony adres konta.
mintedliczbaWysłane BCPZ.
datedataKiedy zostały wysłane.
txIdciąg znakówHash transakcji w Polygon. Pomijany, dopóki przelew nie zostanie zrealizowany.

GET/pool/btc-price

Cena Bitcoina w USD i EUR z giełdy. Cache na 600 sekund.

Przykładowe żądanie

curl "https://btcpuzzle.info/api/pool/btc-price"

Przykładowa odpowiedź

200 OK Obie wartości wynoszą 0, gdy źródło ceny jest nieosiągalne.

{"usd":66739.06,"eur":60607.25}

Strumień na żywo (SignalR)

Pula publikuje każdy zajęty i ukończony zakres w hubie SignalR. Strona używa go na stronie statusu na żywo. Hub jest publiczny, nie wymaga tokenu i tylko wysyła: nie ma metod, które klient mógłby wywołać.

URL hubahttps://btcpuzzle.info/api/hex_socket
Stary hosthttps://api.btcpuzzle.info/hex_socket
ProtokółSignalR z domyślnym protokołem JSON; dostępne są WebSockets, Server-Sent Events i Long Polling.
ZdarzeniePoolStatus
LimitŻądanie negotiate wlicza się do limitu żądań na IP. Sam hub po połączeniu nie jest ograniczany.

Łączenie

Użyj biblioteki klienckiej SignalR (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Pod spodem najpierw wykonywane jest negotiate:

Przykładowe żądanie

curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"

Przykładowa odpowiedź

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();

Zdarzenie PoolStatus

Jeden argument, obiekt JSON. Zdarzenie jest wysyłane do wszystkich połączonych klientów, gdy zakres zostaje wydany i gdy zakres zostaje oznaczony jako przeskanowany.

{
  "hex": "3AX8443",
  "walletAddress": "1BvBMSEY...7xJaNVN2",
  "workerName": "rig1",
  "puzzleCode": 71,
  "status": "holded"
}
PoleTypOpis
hexciąg znakówHEX zakresu z trzecim znakiem zastąpionym przez X.
walletAddressciąg znakówSkrócony adres konta.
workerNameciąg znaków lub nullNazwa workera (default, gdy żadnej nie wysłano). Przy scanned jest to nazwa wysłana w żądaniu oznaczenia, która może być null.
puzzleCodeliczba całkowitaPuzzle zakresu.
statusciąg znakówholded po wydaniu zakresu, scanned po oznaczeniu zakresu. Pisownia jest zamrożona.

Zdarzenia są dostarczane, dopóki połączenie jest otwarte; po ponownym połączeniu nic nie jest odtwarzane. Gdy operator wyłączy strumień na żywo, połączenia są odrzucane.

Obiekty

Obiekt Puzzle

Zwracany przez endpointy list puzzli oraz /puzzle/{puzzleCode}/info. Właściwości bez wartości są pomijane.

PoleTypOpis
idliczba całkowitaId w bazie danych (takie samo jak code dla puzzli ze starego systemu).
nameciąg znakówNa przykład Puzzle 71.
codeliczba całkowitaNumer puzzle.
hexStart, hexEndciąg znakówPierwszy i ostatni klucz prywatny puzzle, szesnastkowo.
targetWalletAddressciąg znakówAdres, na którym jest nagroda.
hexRangeLengthliczba całkowitaDługość HEX zakresu wydawanego przez pulę (części klucza, którą wybiera pula).
rewardliczbaNagroda w BTC.
hexStartPool, hexEndPoolciąg znakówPierwszy i ostatni HEX zakresu. Puste, chyba że puzzle jest w puli.
totalRangesliczba całkowitaLiczba zakresów puzzle. 0, chyba że puzzle jest w puli.
percentageliczbaProcent przeskanowanych zakresów.
totalScanned, rangesScannedLastHourliczba całkowitaPrzeskanowane zakresy łącznie i w ostatniej godzinie (wypełniane w endpointach list).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByróżneKońcowe liczby ukończonego puzzle; statisticsFoundBy występuje tylko wtedy, gdy jest znane.
rangeContainsKeys, rangeContainsKeyByDefaultliczba całkowitaLiczba kluczy prywatnych (minus jeden) w jednym zakresie. Obie wartości różnią się, gdy zakresy obejmują kilka id.
rangesPerKeyliczba całkowitaIle id zakresów obejmuje jeden zakres (1 dla większości puzzli).
workloadStart, workloadEndciąg znakówCzęść klucza prywatnego, którą klient skanuje po HEX zakresu: zobacz GET range.
customWorkloadStart, customWorkloadEndciąg znakówWystępuje, gdy puzzle używa niestandardowego obciążenia.
dateStart, dateEnddataPlanowane daty puzzle.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolwartość logicznaStan puzzle: ukończone, zapowiedziane, skanowalne teraz, domyślne, pula testowa, w puli.
isEntranceFeeActive, entranceFeewartość logiczna, liczbaCzy wpisowe jest włączone i jego cena w USD (0, gdy wyłączone).
nextScanAllowedInMinutesliczba całkowitaJak długo wydany zakres jest zarezerwowany, zanim może zostać przydzielony komuś innemu.
challengestablicaNajnowsze wyzwanie lub pusta tablica.
privateKey, publicKeyciąg znakówTylko dla rozwiązanych puzzli.
rewards, speedtablica, obiektWystępuje tylko w niektórych endpointach.

Obiekt Statistics

PoleTypOpis
puzzleobiektGłówne dane puzzle (nazwa, kod, liczby zakresów, obciążenie, stan, nagroda).
scannedLast24Hliczba całkowitaZakresy przeskanowane w ostatnich 24 godzinach.
entranceFeesPaidTotalliczbaWpisowe zapłacone za puzzle, USD.
topWorkersAlltimetablicaDo 50 elementów {userId, walletAddress, totalScanned}; userId ma tu wartość 0.
topWorkersLast24htablicaTo samo dla ostatnich 24 godzin.
activeWorkerstablica{walletAddress, workerName} workerów pingujących w ostatnich 30 minutach.
challengestablicaDo 32 wyzwań.
kingdomobiektKról puzzle: walletAddress, message, image i isPublished.
topSpeedobiektNajlepsza godzina w historii: date, scanned zakresów i keysPerSecond.
chartDatatablicaOstatni miesiąc godzina po godzinie, od najnowszych: date, dateOnly, hoursOnly i rangesScanned.
lastRangestablicaOstatnie 200 przeskanowanych zakresów, od najnowszych: hex (zamaskowany), walletAddress (zamaskowany), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds i totalSeconds.
rewardstablicaNagrody puzzle (bez kluczy prywatnych).
dateUpdateddataKiedy obliczono dane.
currentSpeedobiektCurrentSpeed.

Obiekt CurrentSpeed

PoleTypOpis
activeWorkerCountliczba całkowitaWorkery, które skanowały w ostatnich 6 godzinach i pingowały w ostatniej godzinie.
keysPerSecondFormattedciąg znakówPrędkość z jednostką: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s itd.
keysPerSecondRawciąg znakówPrędkość w kluczach na sekundę jako tekst liczby całkowitej.

Obiekt Challenge

PoleTypOpis
hexciąg znakówPoczątkowe znaki skanowane przez każdego uczestnika wyzwania.
dateCreateddataKiedy wyzwanie się rozpoczęło.
puzzleIdliczba całkowitaPuzzle.

Obiekt Reward

PoleTypOpis
id, puzzleCode, puzzleIdliczba całkowitaIdentyfikator.
targetAddressciąg znakówAdres klucza nagrody.
rewardContent, rewardDescription, provider, providerDesc, brandciąg znakówCzym jest nagroda i kto ją funduje. Właściwości bez wartości są pomijane.
privateKeyciąg znakówWystępuje dopiero po rozwiązaniu nagrody.
dateCreated, dateSolveddataKiedy została utworzona i rozwiązana (0001-01-01T00:00:00, dopóki nierozwiązana).

Zmiany względem starej dokumentacji

Kontrakt nie zmienił się w niczym: każdy endpoint, nagłówek, pole i kod błędu starego API nadal działa i zwraca to samo. Ten przewodnik zastępuje starą stronę, która opisywała trzy endpointy. Co nowego:

  • Udokumentowano publiczne endpointy danych, strumień na żywo, kody błędów i limity żądań. Stara strona o nich nie wspominała.
  • Poprawki starego tekstu: nagłówek UserToken żądania oznaczenia to token minera (stara strona nazywała go adresem portfela); ping wysyła się mniej więcej co 2 minuty, maksymalnie co 30 minut, a limit wynosi 360 pingów na minutę na token, a nie 60 na godzinę; puzzle puli testowej to 38.
  • Bazowy URL to https://btcpuzzle.info/api; stary host api.btcpuzzle.info nadal działa.
  • Hub SignalR nie ma już żadnej metody klient–serwer, więc nikt nie może wysyłać fałszywych zdarzeń. Samo zdarzenie się nie zmieniło.
  • Ostatni wolny zakres puzzle jest teraz również wydawany, a bardzo wąskie okno CustomRange jest poszerzane, aby nie dało się wybrać zakresu, prosząc dokładnie o jeden.
  • Publiczne statystyki nie pokazują już adresu IP minera.

Postaw mi kawę

Puzzle puli

Co pula skanuje teraz, co będzie dalej i nad jakimi puzzle już pracowała.

Skanowane teraz1

Następne2

Skanowane wcześniej4

Wszystkie puzzle (160)