API Dokümantasyonu

Havuz için kendi istemcinizi yazın. Tüm uç noktalar, istekleri, yanıtları ve hatalarıyla.

Genel bakış

btcpuzzle.info API'si, havuz istemcisinin konuştuğu arayüzdür. Taranacak anahtar aralıklarını dağıtır, bir taramanın sonucunu alır ve havuzun herkese açık istatistiklerini yayımlar. btcpuzzle.info açık kaynaklıdır ve herkes bir istemci yazabilir: bu rehber herkese açık tüm uç noktaları, gönderilecek verileri, geri aldığınız verileri ve karşılaşabileceğiniz hataları açıklar. Sorular için: support@btcpuzzle.info.

Bu API bilerek dondurulmuştur: madenciler ve üçüncü taraf araçlar ona bağlıdır. Yollar, header'lar, alan adları (dateProcces ve holded gibi birkaç eski yazım dahil) ve hata kodları değişmez. Yanıtlara yeni alanlar eklenebilir, bu yüzden tanımadığınız alanları yok sayın.

Temel URL

Bu rehberdeki tüm yollar temel URL'ye görelidir:

https://btcpuzzle.info/api

Web sitesi taşınmadan önce yazılmış istemciler, aynı yollarla ve /api öneki olmadan eski host'u kullanmaya devam edebilir:

https://api.btcpuzzle.info

Örneğin GET https://btcpuzzle.info/api/puzzle/codes ve GET https://api.btcpuzzle.info/puzzle/codes aynı yanıtı verir. Yeni istemciler /api içeren temel URL'yi kullanmalıdır.

Hızlı başlangıç

btcpuzzle.info'da ücretsiz bir hesap oluşturun, panelden madenci token'ınızı kopyalayın, ardından bir aralık isteyin:

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

Dönen aralığı altı kanıt adresiyle birlikte tarayın, kanıtı PUT /puzzle/71/range ile gönderin ve tekrarlayın. İki çağrı arasında, havuzun worker'ın çalıştığını bilmesi için zaman zaman ping gönderin.

Kurallar

Sürümleme

Tek bir sürüm vardır ve URL'de sürüm bulunmaz. Eski API'nin sözleşmesi aynen korunur; bkz. Eski dokümantasyona göre değişiklikler.

Kimlik doğrulama

Madenci uç noktaları UserToken header'ı ile tanımlanır: hesabınızın 128 karakterlik madenci token'ı. Bunlar için başka bir giriş veya oturum yoktur. Hesabınızdan istediğiniz zaman yeni bir token oluşturabilirsiniz; eskisi hemen çalışmayı durdurur. Token'ı gizli tutun: ona sahip olan sizin adınıza tarama yapar.

Tüm veri uç noktaları (puzzle'lar, istatistikler, havuz, token) herkese açıktır ve token gerektirmez.

İstekler ve yanıtlar

  • Madenci uç noktalarında istek verileri sorgu dizesinde veya gövdede değil, HTTP header'larında gönderilir. Header adları büyük/küçük harfe duyarlı değildir (UserToken, usertoken ve userToken aynı header'dır). Yalnızca POST /puzzle/{puzzleCode}/save-private-key bir JSON gövdesine sahiptir (Content-Type: application/json).
  • Yanıtlar camelCase özellik adlarıyla UTF-8 JSON'dur. Değeri olmayan özellikler yanıta eklenmez; API asla JSON null yazmaz. Girintilere güvenmeyin.
  • Tarihler UTC'de ISO 8601 biçimindedir (2026-11-18T08:28:25.8176144Z). Para ve tutarlar JSON sayılarıdır.
  • rangeContainsKeys gibi büyük sayılar işaretsiz 64 bit tam sayılardır ve 2^53'ten büyük olabilir: double kullanan dillerde bunları 64 bit tam sayı veya string olarak ayrıştırın.
  • Herkese açık verilerde cüzdan adresleri kısaltılır (ilk 8 karakter, ..., son 8) ve bir aralık HEX'inin üçüncü karakteri X ile değiştirilir (3AB8443, 3AX8443 olur).

Hız sınırları

Aşağıdaki sınırlar mevcut varsayılanlardır. Sabit bir zaman penceresinde sayılırlar; işletmeci bunları ayarlayabilir, bu yüzden sayıları koda gömmek yerine 429 yanıtını okuyun.

Uygulandığı yerSayım birimiSınır
GET /puzzle/{puzzleCode}/rangeUserToken60 saniyede 120 istek
PUT /puzzle/{puzzleCode}/rangeUserToken60 saniyede 360 istek
PATCH /puzzle/{puzzleCode}/range/pingUserToken60 saniyede 360 istek
POST /puzzle/{puzzleCode}/save-private-keyUserToken180 saniyede 10 istek
Diğer tüm uç noktalarIP adresiHer uç nokta için saniyede 20 istek, toplamda saniyede 200

Sınırı aşan bir istek 429 Too Many Requests, bir Retry-After header'ı ve şu gövdeyle yanıtlanır:

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

Hatalar

Hatalar aşağıdaki durum kodlarını kullanır. Gövde uç noktaya bağlıdır, bu yüzden önce durum kodunu kontrol edin.

DurumGövdeAnlamı
400{"error": "<code>"}Bir madenci uç noktası isteği reddetti. Kod nedenini söyler: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (yazımı tarihseldir), invalid_request.
400{"isSuccess": false}Bir aralığın işaretleme isteği reddedildi (yanlış kanıt, bilinmeyen veya zaten taranmış aralık, yasaklı kullanıcı, aktif olmayan puzzle).
400doğrulama sorunuGerekli bir header eksik veya geçersiz ya da puzzle numarası 1 ile 160 arasında değil. errors alanı hatalı adları listeleyen bir application/problem+json nesnesidir.
400problem detailsHerkese açık bir veri uç noktasının bu puzzle için verecek yanıtı yok (bilinmeyen veya aktif olmayan puzzle). type, title, status ve traceId içeren application/problem+json.
401{"error": "invalid_user_token"}Madenci token'ı bilinmiyor veya hesap yasaklı (ping ve save-private-key).
404{"error": "range_not_found"}Ping gönderilecek aralık bu worker'da değil.
429{"isSuccess": false, "details": "Quota exceeded."}Hız sınırı. Retry-After saniye kadar bekleyin.

Bir doğrulama sorunu örneği (UserToken header'ı olmadan GET /puzzle/71/range):

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

Önbellek ve CORS

Herkese açık veri uç noktaları Cache-Control: public, max-age=N gönderir; değer her uç noktayla birlikte listelenir ve önbellekteki kopya tüm çağıranlar arasında paylaşılır, bu yüzden N saniyeden sık sorgulamak yalnızca aynı veriyi döndürür. Madenci uç noktaları asla önbelleğe alınmaz. Tarayıcılar API'yi https://btcpuzzle.info, https://www.btcpuzzle.info ve http://localhost:3000 adreslerinden çağırabilir (sonuncusu eski arayüzün yerel geliştirmesi için vardır); yerel (native) istemciler CORS'tan etkilenmez.

Madenci uç noktaları

Tarama döngüsünün üç çağrısı: bir aralık al, tararken ping gönder, taranmış olarak işaretle. Dördüncü bir çağrı bulunan bir anahtarı saklar. Dördü de UserToken header'ını kullanır.

GET/puzzle/{puzzleCode}/range

Puzzle'ın rastgele boş bir aralığını verir ve sizin için ayırır. Ayırdığınız bir aralık başka kimseye verilmez; işaretlemezseniz bir süre sonra havuza geri döner (ping, ayırma süresini uzatır).

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathinteger (1 ile 160 arası)EvetTaranacak puzzle, örneğin 71. 38 test havuzudur. GET /puzzle/codes kodları listeler. Tamamlanmış bir puzzle için istek sessizce varsayılan puzzle'dan karşılanır ve yanıt, hangi puzzle'ı aldığınızı puzzleCode içinde belirtir.
UserTokenheaderstring (128 karakter)EvetMadenci token'ınız.
WorkerNameheaderstring (1 ile 16 karakter)HayırBu worker'ın adı. Yalnızca harf ve rakam. Hiç göndermezseniz default olarak saklanır.
SecurityHashheaderstringHayırAralıkla birlikte saklanan serbest metin. İsteğe bağlı.
CustomRangeheaderstringHayırAldığınız aralığı sınırlar: HEX'in bir öneki (2D, 3BA) veya start:end (3400000:38FFFFF). none veya header olmaması herhangi bir aralık anlamına gelir. Çok dar bir pencere havuz tarafından genişletilir, bu yüzden belirttiğinizden farklı bir aralık alabilirsiniz.

Örnek istek

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

Örnek yanıt

200 OK

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

Yanıt alanları

AlanTürAçıklama
hexstringTaranacak aralık, büyük harfle ve dolgu olmadan. Aralıktaki özel anahtarların başlangıç kısmıdır.
puzzleCodeintegerAralığın ait olduğu puzzle (istediğiniz puzzle tamamlanmışsa varsayılan puzzle).
workloadStartstringAralığın ilk özel anahtarını elde etmek için hex sonuna eklenir.
workloadEndstringAralığın son özel anahtarını elde etmek için hex sonuna eklenir. Aralıkları birden fazla kimliği kapsayan puzzle'larda uzunluğu workloadStart değerinden fazla olabilir.
targetAddressstringAradığınız puzzle adresi. Kanıt adresleriyle birlikte tarayın.
proofOfWorkAddresses6 string'lik diziHavuzun aralığın içine yerleştirdiği altı özel anahtarın adresleri. Taramayı kanıtlamak için bunların özel anahtarlarını bulun: bkz. İş kanıtı.

Yukarıdaki örnekte aralık 3AB8443 + 00000000000 = 3AB844300000000000 değerinden 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF değerine kadar uzanır. Özel anahtarlar 64 onaltılık karakterdir; sol tarafı sıfırla doldurun.

Hatalar

DurumGövdeNe zaman
400{"error": "invalid_puzzle"}Puzzle mevcut değil veya aktif değil.
400{"error": "invalid_user_token"}Token bilinmiyor veya yasaklı.
400{"error": "too_much_request"}Taramadığınız çok fazla aralığı elinizde tutuyorsunuz ya da bitirdiğinizden daha hızlı istiyorsunuz. Elinizdekileri tarayın; ayrılmış aralıklar kısa bir süre sonra havuza geri döner.
400{"error": "not_eligable"}Puzzle'ın giriş ücreti var ve henüz koşullarını karşılamıyorsunuz.
400{"error": "reached_of_keyspace"}Boş aralık kalmadı (veya CustomRange değerinize uyan aralık yok).
400validation problemEksik veya hatalı biçimlendirilmiş header ya da 1 ile 160 dışında bir puzzle numarası.
429{"isSuccess": false, ...}Hız sınırı: token başına dakikada 120.

İş kanıtı

Havuz, aralığı gerçekten taradığınızdan emin olmak ister. Her aralıkta, aralığın içinden altı özel anahtar seçer ve yalnızca bunların adreslerini döndürür (proofOfWorkAddresses). Aralığı hedef adres için tararken bu altı adresi de tarayın. Altı özel anahtarın hepsini bulduğunuzda:

  1. Her özel anahtarı, sol tarafı sıfırla doldurulmuş 64 büyük harfli onaltılık karakter olarak yazın.
  2. Altı dizeyi, adreslerin sırasıyla, aralarına hiçbir şey koymadan birleştirin.
  3. UTF-8 metnin SHA-256 değerini alın ve 64 küçük harfli onaltılık karakter olarak yazın. İşaretleme isteğinin HashedProofKey değeri budur.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8   // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1   // for proofOfWorkAddresses[1]
...
ProofKey6 = ...

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

Kanıt her aralık için farklıdır. Kanıt adresi sayısı bugün altıdır; bunu varsaymak yerine proofOfWorkAddresses uzunluğunu okuyun.

PUT/puzzle/{puzzleCode}/range

Bir aralığı taranmış olarak işaretler. Havuz kanıtı kontrol eder ve doğruysa aralığı sizin için tamamlanmış sayar. Bir aralık yalnızca bir kez işaretlenebilir.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathinteger (1 ile 160 arası)EvetAralığın puzzle'ı.
UserTokenheaderstring (128 karakter)EvetMadenci token'ınız.
HEXheaderstringEvetTaradığınız aralığın, havuzun döndürdüğü şekliyle hex değeri. Örnek: 3AB8443.
HashedProofKeyheaderstringEvetİş kanıtı: bkz. İş kanıtı.
WorkerNameheaderstring (1 ile 16 karakter)HayırAralığı tarayan worker.
GPUNameheaderstringHayırEkran kartı modeli. Herkese açık istatistikler için kullanılır.
GPUCountheaderintegerHayırWorker'ın kart sayısı. Varsayılan 1.
IsForceContinueheaderbooleanHayırWorker, anahtar alanının sonuna ulaşmasına rağmen devam ettiyse ayarlayın. Varsayılan false.

Örnek istek

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"

Örnek yanıt

200 OK

{
  "isSuccess": true
}

Hatalar

DurumGövdeNe zaman
400{"isSuccess": false}Her türlü ret: yanlış kanıt, bilinmeyen aralık, zaten işaretlenmiş bir aralık, yasaklı hesap, aktif olmayan puzzle.
400validation problemGerekli bir header eksik veya hatalı biçimlendirilmiş.
429{"isSuccess": false, ...}Hız sınırı: token başına dakikada 360.

PATCH/puzzle/{puzzleCode}/range/ping

Havuza bir worker'ın hâlâ aralığını taradığını bildirir. Ping, aralığın ayrılmış kalmasını sağlar ve worker'ı web sitesinde aktif gösterir. Yaklaşık 2 dakikada bir gönderin; aralık 30 dakikadan uzun olmamalıdır, aksi halde havuz aralığı geri alır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAralığın puzzle'ı.
HexheaderstringEvetWorker'ın şu an taradığı aralık.
UserTokenheaderstring (128 karakter)EvetMadenci token'ınız.
WorkerNameheaderstringEvetAralık istenirken kullanılan worker adı (hiç gönderilmediyse default).

Örnek istek

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

Örnek yanıt

Boş gövdeli 200 OK.

Hatalar

DurumGövdeNe zaman
400{"error": "invalid_request"}Bir header boş.
401{"error": "invalid_user_token"}Bilinmeyen veya yasaklı token.
404{"error": "range_not_found"}Bu worker'da, o puzzle'da o HEX'e sahip taranmamış bir aralık yok.
429{"isSuccess": false, ...}Hız sınırı: token başına dakikada 360.

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

Bulunan bir özel anahtarı hesabınızda şifreli olarak saklar. İstemci anahtarı kendisine verdiğiniz RSA public key ile şifreler; site yalnızca şifreli metni tutar ve siz onu private key'inizle çözersiniz. Anahtar panelinizdeki bulunan anahtarlar sayfasında görünür.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAnahtarın ait olduğu puzzle.
UserTokenheaderstring (128 karakter)EvetMadenci token'ınız.
Content-TypeheaderstringEvetapplication/json.
namebodystringHayırBir etiket, örneğin worker adı. Puzzle71 - rig1 olarak saklanır.
encryptedKeybodystringEvetŞifrelenmiş özel anahtar (istemci bunu base64 olarak gönderir).

Örnek istek

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

Örnek yanıt

200 OK Özelliğin isSuccess değil, success olduğuna dikkat edin.

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

Hatalar

DurumGövdeNe zaman
401{"error": "invalid_user_token"}Bilinmeyen veya yasaklı token.
400problem detailsHiçbir şey kaydedilmedi: aynı anahtar bu hesap için zaten saklanmış veya gövde eksik.
429{"isSuccess": false, ...}Hız sınırı: token başına 180 saniyede 10.

Puzzle verileri

Havuzun puzzle'ları hakkında herkese açık okuma uç noktaları. Token gerekmez. Puzzle nesnesi ve diğer nesneler bu rehberin sonunda açıklanmıştır.

GET/puzzle

Havuzdaki puzzle'lar: aktif olanlar, sıradakiler ve test havuzu (ve geçmiş için tutulan tamamlanmış olanlar). 300 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK Bir Puzzle nesneleri dizisi, burada bire kısaltılmıştır.

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

Hatalar

DurumGövdeNe zaman
404[]Havuzda hiç puzzle yok.

GET/puzzle/all

Veritabanındaki tüm puzzle'lar, tamamlananlar dahil. 300 saniye önbelleğe alınır.

Örnek istek

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

Bir Puzzle nesneleri dizisiyle 200 yanıtı verir.

GET/puzzle/available

Havuzda taranabilen puzzle'lar. 300 saniye önbelleğe alınır.

Örnek istek

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

Bir Puzzle nesneleri dizisiyle 200 yanıtı verir.

GET/puzzle/default

Varsayılan puzzle: tamamlanmış bir puzzle için yapılan isteğin yönlendirildiği puzzle. 300 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK Tek bir Puzzle nesnesi.

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

Hatalar

DurumGövdeNe zaman
404{"error": "puzzle_not_found"}Varsayılan puzzle ayarlanmamış.

GET/puzzle/codes

Aktif veya sıradaki puzzle'ların numaraları; önce normal puzzle'lar, en son test havuzu. 300 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK

[71, 72, 73, 38]

GET/puzzle/{puzzleCode}/info

Veritabanından okunan tek bir puzzle. 10 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetPuzzle numarası.

Örnek istek

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

Örnek yanıt

200 OK Bir Puzzle nesnesi. rangesScannedLastHour gibi çalışma zamanı değerleri yalnızca liste uç noktalarında doldurulur.

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

Hatalar

DurumGövdeNe zaman
204boşBöyle bir puzzle yok.

GET/puzzle/{puzzleCode}/statistics

Puzzle sayfasının gösterdiği her şey: toplamlar, sıralamalar, aktif worker'lar, son 200 taranan aralık ve saatlik bir grafik. 60 saniye önbelleğe alınır (ve sunucu bir kopyayı 5 dakika tutar).

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAktif bir puzzle (veya test havuzu).

Örnek istek

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

Örnek yanıt

200 OK Kısaltılmıştır: diziler burada tek eleman içerir, lastRanges ise 200'e kadar.

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

Henüz aktif olmayan bir puzzle için (sıradakiler) yalnızca puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges ve dateUpdated döndürülür. Alanlar için bkz. Statistics nesnesi.

Hatalar

DurumGövdeNe zaman
400problem detailsPuzzle mevcut değil veya ne aktif ne de sıradaki.

GET/puzzle/{puzzleCode}/speed

Havuzun bir puzzle'daki şu anki hızı. 60 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetPuzzle numarası.

Örnek istek

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

Örnek yanıt

200 OK Bkz. CurrentSpeed. Bilinmeyen bir puzzle hata ile değil, sıfır değerleriyle yanıtlanır.

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

GET/puzzle/{puzzleCode}/workers

Şu an tarama yapan worker'lar: son 30 dakikada ping gönderdikleri bir aralığı olanlar. Tarayıcı tarafından önbelleğe alınmaz; sunucu yanıtı 60 saniye tutar. puzzleCode 0 varsayılan puzzle anlamına gelir.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetPuzzle numarası.

Örnek istek

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

Örnek yanıt

200 OK Kimse taramıyorsa veya puzzle bilinmiyorsa boş bir dizi.

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

GET/puzzle/{puzzleCode}/workers-pinging

/workers ile aynı liste (istemciler ikisini de kullandığı için ayrı bir yol olarak tutulur).

Örnek istek

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

GET /puzzle/{puzzleCode}/workers ile aynı parametreler ve yanıt.

GET/puzzle/{puzzleCode}/rewards

Aktif bir puzzle'ın havuz ödülleri: sponsorların aralıkların içindeki özel anahtarlara koyduğu ek ödüller (en yeni önce, en fazla 32). Bir ödülün özel anahtarı yalnızca çözüldükten sonra gösterilir. 600 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAktif bir puzzle.

Örnek istek

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

Örnek yanıt

200 OK Bkz. Reward. Puzzle'ın ödülü yoksa boş bir dizi.

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

Hatalar

DurumGövdeNe zaman
400problem detailsPuzzle aktif değil.

GET/puzzle/{puzzleCode}/challenge

Aktif bir puzzle'ın en son challenge başlangıç noktaları (en yeni önce, en fazla 32). 600 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAktif bir puzzle.

Örnek istek

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

Örnek yanıt

200 OK Bkz. Challenge. Hiç yoksa boş bir dizi.

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

Hatalar

DurumGövdeNe zaman
400problem detailsPuzzle aktif değil.

GET/puzzle/{puzzleCode}/entrancefee

Ücret açıkken bir puzzle'ın USD cinsinden giriş ücreti. 300 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetGiriş ücreti olan aktif bir puzzle.

Örnek istek

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

Örnek yanıt

200 OK

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

Hatalar

DurumGövdeNe zaman
400problem detailsPuzzle aktif değil veya giriş ücreti yok.

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

Aralık HEX'inin her iki karakterlik öneki için puzzle'ın ne kadarının tarandığı (puzzle sayfasındaki ısı haritası). 3600 saniye önbelleğe alınır.

Parametreler

AdKonumTürZorunluAçıklama
puzzleCodepathintegerEvetAktif bir puzzle.

Örnek istek

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

Örnek yanıt

200 OK Önek başına bir eleman, hexStarts değerine göre sıralı. pertantageShow özelliği bilerek yanlış yazılmıştır (dondurulmuş). %70'ten itibaren sayılar %70'te durur ve isLimitExceeded true olur.

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

Hatalar

DurumGövdeNe zaman
400problem detailsPuzzle aktif değil.

Havuz verileri

Bir bütün olarak havuz, GPU listesi ve BCPZ token hakkında herkese açık okuma uç noktaları.

GET/pool/homepage

Ana sayfanın puzzle listesi: GET /puzzle ile aynı dizi; varsayılan puzzle speed değerini de taşır. 60 saniye önbelleğe alınır.

Örnek istek

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

Bir Puzzle nesneleri dizisiyle 200 yanıtı verir.

GET/pool/gpus

GPU benchmark listesi, en hızlı önce (havuzdaki saniye başına anahtar). 300 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK

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

Yanıt alanları

AlanTürAçıklama
brandstringnvidia veya amd.
namestringKart.
keysPerSecondnumberÖlçülen hız.
dateUpdateddateSon güncelleme.

GET/pool/token-distribute-history

Günlük BCPZ dağıtımları, en yeni önce (en fazla 180). 300 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK

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

Yanıt alanları

AlanTürAçıklama
idintegerDağıtım numarası.
dateProccesdateNe zaman çalıştığı. Ad yanlış yazılmıştır ve dondurulmuştur.
totalUsersintegerToken alan kullanıcılar.
totalAmountnumberDağıtılan BCPZ (taranan aralık başına 1).
descriptionstringSonuç metni.

GET/pool/token-top-50-holders

En çok BCPZ kazanan 50 hesap, cüzdan adresleri kısaltılmış. 600 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK

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

Yanıt alanları

AlanTürAçıklama
walletAddressstringKısaltılmış adres.
balancenumberHesaptaki mevcut BCPZ.
totalnumberToplam kazanılan BCPZ.
mintednumberPolygon ağına zaten çekilmiş BCPZ.

GET/pool/token-mint-history

Polygon ağına yapılan en son BCPZ çekimleri, en yeni önce (en fazla 180). 600 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK

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

Yanıt alanları

AlanTürAçıklama
walletAddressstringHesabın kısaltılmış adresi.
mintednumberGönderilen BCPZ.
datedateNe zaman gönderildiği.
txIdstringPolygon işlem hash'i. Aktarım tamamlanmadığı sürece yanıta eklenmez.

GET/pool/btc-price

Bir borsadan alınan USD ve EUR cinsinden Bitcoin fiyatı. 600 saniye önbelleğe alınır.

Örnek istek

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

Örnek yanıt

200 OK Fiyat kaynağına ulaşılamadığında iki değer de 0 olur.

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

Canlı akış (SignalR)

Havuz, alınan ve bitirilen her aralığı bir SignalR hub'ına yayımlar. Web sitesi bunu canlı durum sayfası için kullanır. Hub herkese açıktır, token gerektirmez ve yalnızca gönderir: bir istemcinin çağırabileceği hiçbir metot yoktur.

Hub URL'sihttps://btcpuzzle.info/api/hex_socket
Eski hosthttps://api.btcpuzzle.info/hex_socket
ProtokolVarsayılan JSON protokolüyle SignalR; WebSockets, Server-Sent Events ve Long Polling sunulur.
OlayPoolStatus
SınırNegotiate isteği IP hız sınırına sayılır. Bağlandıktan sonra hub'ın kendisi sınırlı değildir.

Bağlanma

Bir SignalR istemci kütüphanesi kullanın (JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). Arka planda önce negotiate yapar:

Örnek istek

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

Örnek yanıt

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 olayı

Tek argüman, bir JSON nesnesi. Olay, bir aralık dağıtıldığında ve bir aralık taranmış olarak işaretlendiğinde bağlı tüm istemcilere gönderilir.

{
  "hex": "3AX8443",
  "walletAddress": "1BvBMSEY...7xJaNVN2",
  "workerName": "rig1",
  "puzzleCode": 71,
  "status": "holded"
}
AlanTürAçıklama
hexstringÜçüncü karakteri X ile değiştirilmiş aralık HEX'i.
walletAddressstringHesabın kısaltılmış adresi.
workerNamestring veya nullWorker adı (hiç gönderilmediyse default). scanned olayında işaretleme isteğiyle gönderilen addır ve null olabilir.
puzzleCodeintegerAralığın puzzle'ı.
statusstringBir aralık dağıtıldıktan sonra holded, bir aralık işaretlendikten sonra scanned. Yazım dondurulmuştur.

Olaylar bağlantı açıkken iletilir; yeniden bağlanıldıktan sonra hiçbir şey tekrar gönderilmez. İşletmeci canlı akışı kapattığında bağlantılar reddedilir.

Nesneler

Puzzle nesnesi

Puzzle liste uç noktaları ve /puzzle/{puzzleCode}/info tarafından döndürülür. Değeri olmayan özellikler yanıta eklenmez.

AlanTürAçıklama
idintegerVeritabanı kimliği (eski sistemin puzzle'ları için code ile aynı).
namestringÖrneğin Puzzle 71.
codeintegerPuzzle numarası.
hexStart, hexEndstringPuzzle'ın onaltılık ilk ve son özel anahtarı.
targetWalletAddressstringÖdülü tutan adres.
hexRangeLengthintegerHavuzun dağıttığı aralık HEX'inin uzunluğu (anahtarın havuzun seçtiği kısmı).
rewardnumberBTC cinsinden ödül.
hexStartPool, hexEndPoolstringİlk ve son aralık HEX'i. Puzzle havuzda değilse boştur.
totalRangesintegerPuzzle'ın aralık sayısı. Puzzle havuzda değilse 0.
percentagenumberTaranan aralıkların yüzdesi.
totalScanned, rangesScannedLastHourintegerToplam ve son bir saatte taranan aralıklar (liste uç noktalarında doldurulur).
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundByçeşitliTamamlanmış bir puzzle'ın son rakamları; statisticsFoundBy yalnızca biliniyorsa bulunur.
rangeContainsKeys, rangeContainsKeyByDefaultintegerBir aralıktaki özel anahtar sayısı (eksi bir). Aralıklar birden fazla kimliği kapsadığında ikisi farklıdır.
rangesPerKeyintegerBir aralığın kaç aralık kimliğini kapsadığı (çoğu puzzle için 1).
workloadStart, workloadEndstringİstemcinin aralık HEX'inden sonra taradığı özel anahtar kısmı: bkz. GET range.
customWorkloadStart, customWorkloadEndstringPuzzle özel bir iş yükü kullanıyorsa bulunur.
dateStart, dateEnddatePuzzle'ın planlanan tarihleri.
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPoolbooleanPuzzle'ın durumu: bitti, duyuruldu, şu an taranabilir, varsayılan, test havuzu, havuzda.
isEntranceFeeActive, entranceFeeboolean, numberGiriş ücretinin açık olup olmadığı ve USD cinsinden fiyatı (kapalıyken 0).
nextScanAllowedInMinutesintegerDağıtılan bir aralığın başka birine verilebilmeden önce ne kadar süre ayrılmış tutulduğu.
challengesarrayEn son challenge ya da boş bir dizi.
privateKey, publicKeystringYalnızca çözülmüş puzzle'lar için.
rewards, speedarray, objectYalnızca bazı uç noktalarda bulunur.

Statistics nesnesi

AlanTürAçıklama
puzzleobjectPuzzle'ın ana rakamları (ad, kod, aralık sayıları, iş yükü, durum, ödül).
scannedLast24HintegerSon 24 saatte taranan aralıklar.
entranceFeesPaidTotalnumberPuzzle için ödenen giriş ücretleri, USD.
topWorkersAlltimearrayEn fazla 50 adet {userId, walletAddress, totalScanned}; burada userId 0 olur.
topWorkersLast24harrayAynısı, son 24 saat için.
activeWorkersarraySon 30 dakikada ping gönderen worker'ların {walletAddress, workerName} bilgisi.
challengesarrayEn fazla 32 challenge.
kingdomobjectPuzzle'ın kralı: walletAddress, message, image ve isPublished.
topSpeedobjectTüm zamanların en iyi saati: date, scanned aralıklar ve keysPerSecond.
chartDataarraySon bir ay, saat saat, en yeni önce: date, dateOnly, hoursOnly ve rangesScanned.
lastRangesarraySon 200 taranan aralık, en yeni önce: hex (maskeli), walletAddress (maskeli), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds ve totalSeconds.
rewardsarrayPuzzle'ın ödülleri (özel anahtarlar olmadan).
dateUpdateddateRakamların hesaplandığı zaman.
currentSpeedobjectCurrentSpeed.

CurrentSpeed nesnesi

AlanTürAçıklama
activeWorkerCountintegerSon 6 saatte tarama yapmış ve son bir saatte ping göndermiş worker'lar.
keysPerSecondFormattedstringBirimiyle hız: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s vb.
keysPerSecondRawstringTam sayı metni olarak saniye başına anahtar cinsinden hız.

Challenge nesnesi

AlanTürAçıklama
hexstringHer challenge katılımcısının taradığı başlangıç karakterleri.
dateCreateddateChallenge'ın başladığı zaman.
puzzleIdintegerPuzzle.

Reward nesnesi

AlanTürAçıklama
id, puzzleCode, puzzleIdintegerKimlik.
targetAddressstringÖdül anahtarının adresi.
rewardContent, rewardDescription, provider, providerDesc, brandstringÖdülün ne olduğu ve kimin verdiği. Değeri olmayan özellikler yanıta eklenmez.
privateKeystringYalnızca ödül çözüldükten sonra bulunur.
dateCreated, dateSolveddateOluşturulma ve çözülme zamanı (çözülmemişken 0001-01-01T00:00:00).

Eski dokümantasyona göre değişiklikler

Sözleşmede hiçbir şey değişmedi: eski API'nin tüm uç noktaları, header'ları, alanları ve hata kodları hâlâ çalışır ve aynı yanıtı verir. Bu rehber, üç uç noktayı açıklayan eski sayfanın yerini alır. Yenilikler:

  • Herkese açık veri uç noktaları, canlı akış, hata kodları ve hız sınırları belgelendi. Eski sayfa bunlardan bahsetmiyordu.
  • Eski metnin düzeltmeleri: işaretleme isteğinin UserToken header'ı madenci token'ıdır (eski sayfa bunu cüzdan adresi olarak adlandırıyordu); ping aralığı yaklaşık 2 dakika ve en fazla 30 dakikadır, sınır ise saatte 60 değil, token başına dakikada 360 ping'dir; test havuzu puzzle'ı 38'dir.
  • Temel URL https://btcpuzzle.info/api'dir; eski api.btcpuzzle.info host'u çalışmaya devam eder.
  • SignalR hub'ında artık istemciden sunucuya bir metot yoktur, bu yüzden kimse sahte olay gönderemez. Olayın kendisi değişmedi.
  • Bir puzzle'ın son boş aralığı da artık dağıtılır ve çok dar bir CustomRange penceresi genişletilir; böylece tam olarak tek bir aralık istenerek bir aralık seçilemez.
  • Herkese açık istatistikler artık bir madencinin IP adresini göstermez.

Bana bir kahve ısmarla

Havuz puzzle'ları

Havuzun şu an taradığı, sıradaki ve daha önce üzerinde çalıştığı puzzle'lar.

Şu an taranıyor1

Sıradaki2

Önceden taranan4

Tüm puzzle'lar (160)