개요
btcpuzzle.info API는 풀 클라이언트가 통신하는 대상이에요. 스캔할 키 범위를 나눠 주고, 스캔 결과를 받고, 풀의 공개 통계를 게시해요. btcpuzzle.info는 오픈 소스이며 누구나 클라이언트를 만들 수 있어요. 이 가이드는 모든 공개 엔드포인트, 보낼 데이터, 받을 데이터, 마주칠 수 있는 오류를 설명해요. 문의: support@btcpuzzle.info.
이 API는 의도적으로 고정되어 있어요. 마이너와 제3자 도구가 이 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은(는) 같은 응답을 줘요. 새 클라이언트는 /api가 붙은 기본 URL을 사용하세요.
빠른 시작
btcpuzzle.info에서 무료 계정을 만들고, 대시보드에서 마이너 토큰을 복사한 뒤 범위를 요청하세요:
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"반환된 범위를 증명 주소 6개와 함께 스캔하고, PUT /puzzle/71/range(으)로 증명을 보낸 뒤 반복하세요. 두 호출 사이에는 워커가 살아 있음을 풀이 알 수 있도록 가끔 ping을 보내세요.
규칙
버전 관리
버전은 하나뿐이며 URL에 버전이 들어가지 않아요. 이전 API의 계약은 그대로 유지돼요. 자세한 내용은 이전 문서와 달라진 점을 참고하세요.
인증
마이너 엔드포인트는 UserToken 헤더로 식별해요. 계정의 128자 마이너 토큰이에요. 다른 로그인이나 세션은 없어요. 계정에서 언제든 새 토큰을 만들 수 있으며, 이전 토큰은 즉시 작동을 멈춰요. 토큰은 비공개로 보관하세요. 토큰을 가진 사람은 누구나 내 이름으로 스캔해요.
모든 데이터 엔드포인트(puzzle, 통계, 풀, 토큰)는 공개되어 있으며 토큰이 필요 없어요.
요청과 응답
- 마이너 엔드포인트의 요청 데이터는 HTTP 헤더로 보내며, 쿼리 문자열이나 본문에는 넣지 않아요. 헤더 이름은 대소문자를 구분하지 않아요(
UserToken,usertoken및userToken은(는) 같은 헤더예요).POST /puzzle/{puzzleCode}/save-private-key만 JSON 본문을 가져요(Content-Type: application/json). - 응답은 camelCase 속성 이름을 쓰는 UTF-8 JSON이에요. 값이 없는 속성은 생략되며, API는 JSON
null을(를) 절대 쓰지 않아요. 들여쓰기에 의존하지 마세요. - 날짜는 UTC 기준 ISO 8601 형식이에요(
2026-11-18T08:28:25.8176144Z). 금액과 수량은 JSON 숫자예요. -
rangeContainsKeys같은 큰 숫자는 부호 없는 64비트 정수이며 2^53보다 클 수 있어요. double을 쓰는 언어에서는 64비트 정수나 문자열로 파싱하세요. - 공개 데이터의 지갑 주소는 축약되며(앞 8자,
..., 뒤 8자), 범위 HEX의 세 번째 문자는X로 바뀌어요(3AB8443→3AX8443).
요청 한도
아래 한도는 현재 기본값이에요. 고정된 시간 창 단위로 집계되며 운영자가 조정할 수 있으니, 숫자를 코드에 고정하지 말고 429 응답을 확인하세요.
| 적용 대상 | 집계 기준 | 한도 |
|---|---|---|
GET /puzzle/{puzzleCode}/range | UserToken | 60초당 요청 120회 |
PUT /puzzle/{puzzleCode}/range | UserToken | 60초당 요청 360회 |
PATCH /puzzle/{puzzleCode}/range/ping | UserToken | 60초당 요청 360회 |
POST /puzzle/{puzzleCode}/save-private-key | UserToken | 180초당 요청 10회 |
| 그 밖의 모든 엔드포인트 | IP 주소 | 엔드포인트별 초당 요청 20회, 전체 초당 200회 |
한도를 넘은 요청에는 429 Too Many Requests, Retry-After 헤더와 함께 다음 본문으로 응답해요:
{
"isSuccess": false,
"details": "Quota exceeded."
}오류
실패 시에는 아래 상태 코드를 사용해요. 본문은 엔드포인트마다 다르니 상태 코드를 먼저 확인하세요.
| 상태 | 본문 | 의미 |
|---|---|---|
400 | {"error": "<code>"} | 마이너 엔드포인트가 요청을 거부했어요. 코드가 이유를 알려 줘요: invalid_puzzle, invalid_user_token, reached_of_keyspace, too_much_request, not_eligable (철자는 예전 그대로), invalid_request. |
400 | {"isSuccess": false} | 범위 표시 요청이 거부됐어요(잘못된 증명, 알 수 없거나 이미 스캔된 범위, 차단된 사용자, 비활성 puzzle). |
400 | 유효성 검사 문제 | 필수 헤더가 없거나 잘못됐거나, puzzle 번호가 1~160 범위를 벗어났어요. application/problem+json 객체이며 errors에 잘못된 이름이 나열돼요. |
400 | 문제 세부 정보(problem details) | 공개 데이터 엔드포인트가 이 puzzle에 대해 응답할 내용이 없어요(알 수 없거나 비활성인 puzzle). application/problem+json 형식이며 포함 필드는 type, title, status 및 traceId. |
401 | {"error": "invalid_user_token"} | 마이너 토큰을 알 수 없거나 계정이 차단됐어요(ping 및 save-private-key). |
404 | {"error": "range_not_found"} | ping할 범위를 이 워커가 보유하고 있지 않아요. |
429 | {"isSuccess": false, "details": "Quota exceeded."} | 요청 한도 초과. Retry-After초만큼 기다리세요. |
유효성 검사 문제의 예(GET /puzzle/71/range에서 UserToken 헤더를 뺀 경우):
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"UserToken": [
"The UserToken field is required."
]
},
"traceId": "00-e3fc704f799663ec7f42c140ab4c996d-8592b3515c26a5c2-00"
}캐싱과 CORS
공개 데이터 엔드포인트는 Cache-Control: public, max-age=N을(를) 보내요. 값은 각 엔드포인트에 적혀 있으며, 캐시된 사본은 모든 호출자가 공유하므로 N초보다 자주 폴링해도 같은 데이터만 돌아와요. 마이너 엔드포인트는 절대 캐시되지 않아요. 브라우저는 https://btcpuzzle.info, https://www.btcpuzzle.info 및 http://localhost:3000에서 API를 호출할 수 있어요(마지막 주소는 이전 프런트엔드의 로컬 개발용이에요). 네이티브 클라이언트는 CORS의 영향을 받지 않아요.
마이너 엔드포인트
스캔 루프의 세 가지 호출: 범위 받기, 스캔하는 동안 ping 보내기, 스캔됨으로 표시하기. 네 번째 호출은 찾은 키를 저장해요. 네 호출 모두 UserToken 헤더를 사용해요.
GET/puzzle/{puzzleCode}/range
puzzle의 빈 범위를 무작위로 하나 나눠 주고 나를 위해 보유해 둬요. 내가 보유한 범위는 다른 누구에게도 주어지지 않아요. 표시하지 않으면 얼마 후 풀로 돌아가요(ping을 보내면 보유 기간이 연장돼요).
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer(1~160) | 예 | 스캔할 puzzle. 예: 71. 38은(는) 테스트 풀이에요. GET /puzzle/codes이(가) 코드 목록을 보여 줘요. 완료된 puzzle은 아무 알림 없이 기본 puzzle로 대체되며, 어떤 puzzle을 받았는지는 응답의 puzzleCode에서 알 수 있어요. |
UserToken | 헤더 | string(128자) | 예 | 내 마이너 토큰. |
WorkerName | 헤더 | string(1~16자) | 아니요 | 이 워커의 이름. 영문자와 숫자만 가능해요. 보내지 않으면 default(으)로 저장돼요. |
SecurityHash | 헤더 | string | 아니요 | 범위와 함께 보관되는 자유 텍스트. 선택 사항이에요. |
CustomRange | 헤더 | string | 아니요 | 받을 범위를 제한해요: HEX 접두사(2D, 3BA) 또는 start:end (3400000:38FFFFF). none 값이나 헤더가 없으면 아무 범위나 받아요. 너무 좁은 구간은 풀이 넓히므로, 지정한 것과 다른 범위를 받을 수 있어요. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"응답 예시
200 OK
{
"hex": "3AB8443",
"puzzleCode": 71,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"targetAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"proofOfWorkAddresses": [
"1QLLeQ3Hwp9ai7L4KM65e7SxS12skkYUsA",
"15mLWAX7Hno94fntWj6PEx5wCvZz2zAn8a",
"1DazU9YxVrojvnTrcZrymyc6ZrDkvezJEA",
"14Qada8GbVoKUXCtPHBgF7BPjdEhJWo1ph",
"1PmdgtX2NzoSsSf2ANAnFrBzdftyW3CThY",
"14it3UVGsK6JhsV2HPimD46VSpVcXipFwQ"
]
}응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
hex | string | 스캔할 범위로, 패딩 없는 대문자예요. 범위에 속한 개인 키의 앞부분이에요. |
puzzleCode | integer | 범위가 속한 puzzle(요청한 puzzle이 완료된 경우 기본 puzzle). |
workloadStart | string | hex 뒤에 붙이면 범위의 첫 번째 개인 키가 돼요. |
workloadEnd | string | hex 뒤에 붙이면 범위의 마지막 개인 키가 돼요. 범위가 여러 ID에 걸친 puzzle에서는 길이가 workloadStart보다 길 수 있어요. |
targetAddress | string | 찾고 있는 puzzle 주소예요. 증명 주소와 함께 스캔하세요. |
proofOfWorkAddresses | string 6개의 배열 | 풀이 범위 안에 넣어 둔 개인 키 6개의 주소예요. 스캔을 증명하려면 이 주소들의 개인 키를 찾으세요. 참고: 작업 증명. |
위 예시에서 범위는 3AB8443 + 00000000000 = 3AB844300000000000부터 3AB8443 + fffffffffff = 3AB8443FFFFFFFFFFF까지예요. 개인 키는 16진수 64자이며, 왼쪽을 0으로 채워요.
오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | {"error": "invalid_puzzle"} | puzzle이 존재하지 않거나 활성 상태가 아니에요. |
400 | {"error": "invalid_user_token"} | 토큰을 알 수 없거나 차단됐어요. |
400 | {"error": "too_much_request"} | 스캔하지 않은 범위를 너무 많이 보유하고 있거나, 완료하는 속도보다 빠르게 요청하고 있어요. 보유한 범위를 스캔하세요. 보유한 범위는 잠시 후 풀로 돌아가요. |
400 | {"error": "not_eligable"} | puzzle에 참가비가 있고 아직 그 조건을 충족하지 못했어요. |
400 | {"error": "reached_of_keyspace"} | 남은 빈 범위가 없어요(또는 CustomRange에 맞는 범위가 없어요). |
400 | validation problem | 헤더가 없거나 형식이 잘못됐거나, puzzle 번호가 1~160 범위를 벗어났어요. |
429 | {"isSuccess": false, ...} | 요청 한도: 토큰당 분당 120회. |
작업 증명
풀은 범위를 실제로 스캔했는지 확인하고 싶어 해요. 범위마다 그 안에서 개인 키 6개를 골라 주소만 반환해요(proofOfWorkAddresses). 대상 주소를 찾기 위해 범위를 스캔하는 동안 이 6개 주소도 함께 찾으세요. 개인 키 6개를 모두 찾았다면:
- 각 개인 키를 왼쪽을 0으로 채운 대문자 16진수 64자로 쓰세요.
- 6개 문자열을 주소 순서대로, 사이에 아무것도 넣지 않고 이어 붙이세요.
- UTF-8 텍스트의 SHA-256을 구해 소문자 16진수 64자로 쓰세요. 이것이 표시 요청의
HashedProofKey이에요.
ProofKey1 = 000000000000000000000000000000000000000000000003AB8443AB91BBAFE8 // for proofOfWorkAddresses[0]
ProofKey2 = 000000000000000000000000000000000000000000000003AB84435AF1E51FD1 // for proofOfWorkAddresses[1]
...
ProofKey6 = ...
HashedProofKey = lowercase_hex( SHA256( ProofKey1 + ProofKey2 + ProofKey3 + ProofKey4 + ProofKey5 + ProofKey6 ) )
= 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87증명은 범위마다 달라요. 증명 주소는 현재 6개지만, 개수를 가정하지 말고 proofOfWorkAddresses의 길이를 읽으세요.
PUT/puzzle/{puzzleCode}/range
범위를 스캔됨으로 표시해요. 풀이 증명을 확인하고, 올바르면 그 범위를 내가 완료한 것으로 집계해요. 범위는 한 번만 표시할 수 있어요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer(1~160) | 예 | 범위의 puzzle. |
UserToken | 헤더 | string(128자) | 예 | 내 마이너 토큰. |
HEX | 헤더 | string | 예 | 풀이 반환한 그대로의, 스캔한 범위의 hex 값. 예: 3AB8443. |
HashedProofKey | 헤더 | string | 예 | 작업 증명. 참고: 작업 증명. |
WorkerName | 헤더 | string(1~16자) | 아니요 | 범위를 스캔한 워커. |
GPUName | 헤더 | string | 아니요 | 그래픽 카드 모델. 공개 통계에 사용돼요. |
GPUCount | 헤더 | integer | 아니요 | 워커의 카드 수. 기본값 1. |
IsForceContinue | 헤더 | boolean | 아니요 | 워커가 키 공간의 끝에 도달했는데도 계속 진행한 경우 설정하세요. 기본값 false. |
요청 예시
curl -X PUT "https://btcpuzzle.info/api/puzzle/71/range" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1" \
-H "HEX: 3AB8443" \
-H "HashedProofKey: 892a38381912bcce412030d7a403de8a92c0e56f452ba5a865f0bf728ff3fa87" \
-H "GPUName: RTX 4090" \
-H "GPUCount: 1"응답 예시
200 OK
{
"isSuccess": true
}오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | {"isSuccess": false} | 모든 거부: 잘못된 증명, 알 수 없는 범위, 이미 표시된 범위, 차단된 계정, 비활성 puzzle. |
400 | validation problem | 필수 헤더가 없거나 형식이 잘못됐어요. |
429 | {"isSuccess": false, ...} | 요청 한도: 토큰당 분당 360회. |
PATCH/puzzle/{puzzleCode}/range/ping
워커가 아직 범위를 스캔 중임을 풀에 알려요. ping은 범위 보유를 유지하고 웹사이트에 워커를 활성으로 표시해요. 약 2분마다 하나씩 보내세요. 간격이 30분을 넘으면 풀이 범위를 회수해요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 범위의 puzzle. |
Hex | 헤더 | string | 예 | 워커가 지금 스캔 중인 범위. |
UserToken | 헤더 | string(128자) | 예 | 내 마이너 토큰. |
WorkerName | 헤더 | string | 예 | 범위를 요청할 때 사용한 워커 이름(보내지 않았다면 default). |
요청 예시
curl -X PATCH "https://btcpuzzle.info/api/puzzle/71/range/ping" \
-H "Hex: 3AB8443" \
-H "UserToken: <128-character miner token>" \
-H "WorkerName: rig1"응답 예시
200 OK, 본문 없음.
오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | {"error": "invalid_request"} | 헤더가 비어 있어요. |
401 | {"error": "invalid_user_token"} | 알 수 없거나 차단된 토큰. |
404 | {"error": "range_not_found"} | 이 워커는 해당 puzzle에서 그 HEX의 스캔되지 않은 범위를 보유하고 있지 않아요. |
429 | {"isSuccess": false, ...} | 요청 한도: 토큰당 분당 360회. |
POST/puzzle/{puzzleCode}/save-private-key
찾은 개인 키를 암호화해 내 계정에 저장해요. 클라이언트는 내가 준 RSA 공개 키로 키를 암호화하고, 사이트는 암호화된 텍스트만 보관하며, 이는 내 개인 키로 복호화해요. 키는 대시보드의 발견된 키 페이지에 표시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 키가 속한 puzzle. |
UserToken | 헤더 | string(128자) | 예 | 내 마이너 토큰. |
Content-Type | 헤더 | string | 예 | application/json. |
name | 본문 | string | 아니요 | 라벨(예: 워커 이름). Puzzle71 - rig1 형식으로 저장돼요. |
encryptedKey | 본문 | string | 예 | 암호화된 개인 키(클라이언트는 base64로 보내요). |
요청 예시
curl -X POST "https://btcpuzzle.info/api/puzzle/71/save-private-key" \
-H "UserToken: <128-character miner token>" \
-H "Content-Type: application/json" \
-d '{"name": "rig1","encryptedKey": "<encrypted key, base64>"}'응답 예시
200 OK 참고: 속성 이름은 isSuccess가 아니라 success예요.
{
"success": true,
"message": "Key saved successfully."
}오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
401 | {"error": "invalid_user_token"} | 알 수 없거나 차단된 토큰. |
400 | problem details | 아무것도 저장되지 않았어요. 같은 키가 이미 이 계정에 저장되어 있거나, 본문이 없어요. |
429 | {"isSuccess": false, ...} | 요청 한도: 토큰당 180초에 10회. |
puzzle 데이터
풀의 puzzle에 관한 공개 읽기 엔드포인트예요. 토큰이 필요 없어요. Puzzle 객체와 다른 객체는 이 가이드 끝에 설명되어 있어요.
GET/puzzle
풀에 있는 puzzle: 활성 puzzle, 다음 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을 요청했을 때 대신 사용되는 puzzle이에요. 300초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/puzzle/default"응답 예시
200 OK 단일 Puzzle 객체.
{
"id": 71,
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexRangeLength": 7,
"reward": 7.1,
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"percentage": 0.4172,
"rangesScannedLastHour": 612,
"totalScanned": 279997,
"statisticsTotalScanned": 0,
"statisticsFoundOnPool": false,
"statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
"rangeContainsKeyByDefault": 17592186044415,
"rangeContainsKeys": 17592186044415,
"rangesPerKey": 1,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"dateStart": "2026-01-01T00:00:00Z",
"dateEnd": "2027-01-01T00:00:00Z",
"isCompleted": false,
"isNextPuzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
404 | {"error": "puzzle_not_found"} | 기본 puzzle이 설정되지 않았어요. |
GET/puzzle/codes
활성 또는 다음 순서인 puzzle의 번호로, 일반 puzzle이 먼저이고 테스트 풀이 마지막이에요. 300초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/puzzle/codes"응답 예시
200 OK
[71, 72, 73, 38]GET/puzzle/{puzzleCode}/info
데이터베이스에서 읽은 puzzle 하나. 10초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | puzzle 번호. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/info"응답 예시
200 OK 응답: Puzzle 객체. rangesScannedLastHour 같은 런타임 값은 목록 엔드포인트에서만 채워져요.
{
"id": 71,
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexRangeLength": 7,
"reward": 7.1,
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"percentage": 0.4172,
"rangesScannedLastHour": 612,
"totalScanned": 279997,
"statisticsTotalScanned": 0,
"statisticsFoundOnPool": false,
"statisticsFoundDate": "2026-11-18T08:27:56.937996Z",
"rangeContainsKeyByDefault": 17592186044415,
"rangeContainsKeys": 17592186044415,
"rangesPerKey": 1,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"dateStart": "2026-01-01T00:00:00Z",
"dateEnd": "2027-01-01T00:00:00Z",
"isCompleted": false,
"isNextPuzzle": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"isOnPool": true,
"nextScanAllowedInMinutes": 360,
"challenges": []
}오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
204 | 빈 본문 | 해당 puzzle이 없어요. |
GET/puzzle/{puzzleCode}/statistics
puzzle 페이지에 표시되는 모든 것: 합계, 순위, 활성 워커, 최근 스캔된 범위 200개, 시간별 차트. 60초 동안 캐시돼요(서버는 사본 하나를 5분 동안 보관해요).
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 활성 puzzle(또는 테스트 풀). |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/statistics"응답 예시
200 OK 축약됨: 여기서는 배열마다 요소가 하나뿐이며, lastRanges은(는) 최대 200개예요.
{
"puzzle": {
"name": "Puzzle 71",
"code": 71,
"hexStart": "400000000000000000",
"hexEnd": "7fffffffffffffffff",
"targetWalletAddress": "1MVDYgVaSN6iKKEsbzRUAYFrYJadLYZvvZ",
"hexStartPool": "4000000",
"hexEndPool": "7ffffff",
"totalRanges": 67108864,
"totalScanned": 279997,
"rangeContainsKeys": 17592186044415,
"workloadStart": "00000000000",
"workloadEnd": "fffffffffff",
"rangesPerKey": 1,
"isCompleted": false,
"isActive": true,
"isEntranceFeeActive": false,
"entranceFee": 0,
"isDefault": true,
"isTestPool": false,
"reward": 7.1
},
"scannedLast24H": 14702,
"entranceFeesPaidTotal": 0,
"topWorkersAlltime": [
{
"userId": 0,
"walletAddress": "1BvBMSEY...7xJaNVN2",
"totalScanned": 5120
}
],
"topWorkersLast24h": [
{
"userId": 2051875,
"walletAddress": "1BvBMSEY...7xJaNVN2",
"totalScanned": 412
}
],
"activeWorkers": [
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
],
"challenges": [],
"kingdom": {
"walletAddress": "1BvBMSEY...7xJaNVN2",
"message": "Hello pool",
"image": 3,
"isPublished": true
},
"topSpeed": {
"date": "2026-11-10T14:00:00Z",
"scanned": 912,
"keysPerSecond": 4456789012345
},
"chartData": [
{
"date": "2026-11-18T08:00:00Z",
"dateOnly": "2026-11-18",
"hoursOnly": 8,
"rangesScanned": 640
}
],
"lastRanges": [
{
"hex": "10X0",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"startTime": "2026-11-18T07:27:57.603786Z",
"endTime": "2026-11-18T08:22:57.603786Z",
"pingTime": "2026-11-18T08:20:57.603786Z",
"gpuModel": "RTX 4090",
"gpuCount": 1,
"workerName": "rig1",
"isPremiumUser": false,
"isScanned": true,
"isPinged": false,
"keysInSeconds": 20824083.85909091,
"totalSeconds": 3300
}
],
"rewards": [],
"dateUpdated": "2026-11-18T08:28:25.8176144Z",
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}아직 활성화되지 않은 puzzle(다음 순서)의 경우 puzzle, scannedLast24H, entranceFeesPaidTotal, lastRanges 및 dateUpdated만 반환돼요. 필드는 Statistics 객체를 참고하세요.
오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | problem details | puzzle이 존재하지 않거나, 활성 상태도 다음 순서도 아니에요. |
GET/puzzle/{puzzleCode}/speed
현재 puzzle에서의 풀 속도. 60초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | puzzle 번호. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/speed"응답 예시
200 OK 참고: CurrentSpeed. 알 수 없는 puzzle에는 오류가 아니라 0 값으로 응답해요.
{
"puzzleCode": 71,
"currentSpeed": {
"activeWorkerCount": 38,
"keysPerSecondFormatted": "162.3 Bkeys/s",
"keysPerSecondRaw": "162300000000"
}
}GET/puzzle/{puzzleCode}/workers
지금 스캔 중인 워커: 최근 30분 안에 ping을 보낸 범위가 있는 워커예요. 브라우저에는 캐시되지 않으며, 서버가 응답을 60초 동안 보관해요. puzzleCode 0은(는) 기본 puzzle을 뜻해요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | puzzle 번호. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/workers"응답 예시
200 OK 아무도 스캔하지 않거나 puzzle을 알 수 없으면 빈 배열이에요.
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1"
}
]GET/puzzle/{puzzleCode}/workers-pinging
/workers와 같은 목록이에요(클라이언트가 둘 다 사용하므로 별도 경로로 유지해요).
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/workers-pinging"매개변수와 응답은 다음과 같아요: GET /puzzle/{puzzleCode}/workers.
GET/puzzle/{puzzleCode}/rewards
활성 puzzle의 풀 보상: 스폰서가 범위 안의 개인 키에 건 추가 상금이에요(최신순, 최대 32개). 보상의 개인 키는 해결된 뒤에만 표시돼요. 600초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 활성 puzzle. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/rewards"응답 예시
200 OK 참고: Reward. puzzle에 보상이 없으면 빈 배열이에요.
[
{
"id": 12,
"puzzleCode": 71,
"targetAddress": "1ExampleRewardAddress0000000000000",
"rewardDescription": "Hardware wallet",
"provider": "Sponsor",
"brand": "Example",
"dateCreated": "2026-11-01T00:00:00Z",
"dateSolved": "0001-01-01T00:00:00",
"puzzleId": 71
}
]오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | problem details | puzzle이 활성 상태가 아니에요. |
GET/puzzle/{puzzleCode}/challenge
활성 puzzle의 최근 챌린지 시작점(최신순, 최대 32개). 600초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 활성 puzzle. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/challenge"응답 예시
200 OK 참고: Challenge. 없으면 빈 배열이에요.
[
{
"hex": "3A",
"dateCreated": "2026-11-18T06:00:00Z",
"puzzleId": 71
}
]오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | problem details | puzzle이 활성 상태가 아니에요. |
GET/puzzle/{puzzleCode}/entrancefee
참가비가 켜져 있을 때 puzzle의 참가비(USD). 300초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 참가비가 있는 활성 puzzle. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/entrancefee"응답 예시
200 OK
{
"fee": 25.0,
"puzzle": 71
}오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | problem details | puzzle이 활성 상태가 아니거나 참가비가 없어요. |
GET/puzzle/{puzzleCode}/statistics-by-hex-prefix
범위 HEX의 두 글자 접두사별로 puzzle이 얼마나 스캔됐는지 보여 줘요(puzzle 페이지의 히트맵). 3600초 동안 캐시돼요.
매개변수
| 이름 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
puzzleCode | 경로 | integer | 예 | 활성 puzzle. |
요청 예시
curl "https://btcpuzzle.info/api/puzzle/71/statistics-by-hex-prefix"응답 예시
200 OK 접두사마다 요소 하나이며, 정렬 기준은 hexStarts이에요. 속성 pertantageShow은(는) 의도적으로 철자가 틀린 상태로 고정돼 있어요. 70%부터는 숫자가 70%에서 멈추고 isLimitExceeded 값은 true.
[
{
"hexStarts": "40",
"maxRanges": 1048576,
"scannedShow": 4411,
"pertantageShow": 0.37,
"isLimitExceeded": false
}
]오류
| 상태 | 본문 | 발생 조건 |
|---|---|---|
400 | problem details | puzzle이 활성 상태가 아니에요. |
풀 데이터
풀 전체, GPU 목록, BCPZ 토큰에 관한 공개 읽기 엔드포인트예요.
GET/pool/homepage
홈페이지의 puzzle 목록: GET /puzzle와 같은 배열이며, 기본 puzzle에는 speed 값이 들어 있어요. 60초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/pool/homepage"응답: 200, 배열 항목: Puzzle 객체.
GET/pool/gpus
GPU 벤치마크 목록으로, 빠른 순이에요(풀에서의 초당 키 수). 300초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/pool/gpus"응답 예시
200 OK
[
{
"brand": "nvidia",
"name": "RTX 4090",
"keysPerSecond": 4491469067.71,
"dateUpdated": "2026-11-18T08:27:53.190819Z"
}
]응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
brand | string | nvidia 또는 amd. |
name | string | 카드. |
keysPerSecond | number | 측정 속도. |
dateUpdated | date | 마지막 업데이트. |
GET/pool/token-distribute-history
일일 BCPZ 분배 내역, 최신순(최대 180개). 300초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/pool/token-distribute-history"응답 예시
200 OK
[
{
"id": 412,
"dateProcces": "2026-11-17T03:00:19Z",
"totalUsers": 85,
"totalAmount": 516,
"description": "Success: 85/85"
}
]응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
id | integer | 분배 번호. |
dateProcces | date | 실행 시각. 이름의 철자가 틀린 채로 고정돼 있어요. |
totalUsers | integer | 토큰을 받은 사용자 수. |
totalAmount | number | 분배된 BCPZ(스캔된 범위당 1개). |
description | string | 결과 텍스트. |
GET/pool/token-top-50-holders
BCPZ를 가장 많이 받은 계정 50개로, 지갑 주소는 축약돼요. 600초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/pool/token-top-50-holders"응답 예시
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"balance": 2500.25,
"total": 400,
"minted": 200
}
]응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
walletAddress | string | 축약된 주소. |
balance | number | 현재 계정의 BCPZ. |
total | number | 총 획득 BCPZ. |
minted | number | 이미 Polygon 네트워크로 출금한 BCPZ. |
GET/pool/token-mint-history
Polygon 네트워크로의 최근 BCPZ 출금 내역, 최신순(최대 180개). 600초 동안 캐시돼요.
요청 예시
curl "https://btcpuzzle.info/api/pool/token-mint-history"응답 예시
200 OK
[
{
"walletAddress": "1BvBMSEY...7xJaNVN2",
"minted": 100,
"date": "2026-11-15T08:27:58.123754Z",
"txId": "0x1609149d1d218ff590c738ca97b9cac42613c2a248393d66dfad36c3702c3fee"
}
]응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
walletAddress | string | 계정의 축약된 주소. |
minted | number | 전송된 BCPZ. |
date | date | 전송 시각. |
txId | string | Polygon 트랜잭션 해시. 전송이 완료되기 전에는 생략돼요. |
GET/pool/btc-price
거래소에서 가져온 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 |
| 프로토콜 | 기본 JSON 프로토콜을 사용하는 SignalR. WebSockets, Server-Sent Events, Long Polling을 제공해요. |
| 이벤트 | PoolStatus |
| 한도 | negotiate 요청은 IP 요청 한도에 포함돼요. 허브 자체는 연결된 뒤에는 제한되지 않아요. |
연결
SignalR 클라이언트 라이브러리를 사용하세요(JavaScript: @microsoft/signalr; .NET: Microsoft.AspNetCore.SignalR.Client). 내부적으로는 먼저 negotiate를 수행해요:
요청 예시
curl -X POST "https://btcpuzzle.info/api/hex_socket/negotiate?negotiateVersion=1"응답 예시
200 OK
{
"negotiateVersion": 1,
"connectionId": "s7dzEsrMHQKQsCHjvm2faQ",
"connectionToken": "A9SBLfct2OZrZZkvaQMLZw",
"availableTransports": [
{
"transport": "WebSockets",
"transferFormats": [
"Text",
"Binary"
]
},
{
"transport": "ServerSentEvents",
"transferFormats": [
"Text"
]
},
{
"transport": "LongPolling",
"transferFormats": [
"Text",
"Binary"
]
}
]
}import { HubConnectionBuilder } from '@microsoft/signalr';
const hub = new HubConnectionBuilder()
.withUrl('https://btcpuzzle.info/api/hex_socket')
.withAutomaticReconnect()
.build();
hub.on('PoolStatus', (event) => console.log(event));
await hub.start();PoolStatus 이벤트
인수 하나, JSON 객체예요. 이벤트는 범위가 배정될 때와 범위가 스캔됨으로 표시될 때 연결된 모든 클라이언트에 전송돼요.
{
"hex": "3AX8443",
"walletAddress": "1BvBMSEY...7xJaNVN2",
"workerName": "rig1",
"puzzleCode": 71,
"status": "holded"
}| 필드 | 유형 | 설명 |
|---|---|---|
hex | string | 세 번째 문자를 X로 바꾼 범위 HEX. |
walletAddress | string | 계정의 축약된 주소. |
workerName | string 또는 null | 워커 이름(보내지 않으면 default). scanned에서는 표시 요청과 함께 보낸 이름이며, null일 수 있어요. |
puzzleCode | integer | 범위의 puzzle. |
status | string | holded: 범위가 배정된 뒤, scanned: 범위가 표시된 뒤. 철자는 고정돼 있어요. |
이벤트는 연결이 열려 있는 동안 전달되며, 다시 연결한 뒤에 재전송되지 않아요. 운영자가 실시간 피드를 끄면 연결이 거부돼요.
객체
Puzzle 객체
puzzle 목록 엔드포인트와 /puzzle/{puzzleCode}/info에서 반환돼요. 값이 없는 속성은 생략돼요.
| 필드 | 유형 | 설명 |
|---|---|---|
id | integer | 데이터베이스 ID(이전 시스템의 puzzle에서는 code와 같아요). |
name | string | 예를 들어 Puzzle 71. |
code | integer | puzzle 번호. |
hexStart, hexEnd | string | puzzle의 첫 번째와 마지막 개인 키(16진수). |
targetWalletAddress | string | 보상이 들어 있는 주소. |
hexRangeLength | integer | 풀이 배정하는 범위 HEX의 길이(풀이 정하는 키의 부분). |
reward | number | BTC 단위 보상. |
hexStartPool, hexEndPool | string | 첫 번째와 마지막 범위 HEX. puzzle이 풀에 없으면 비어 있어요. |
totalRanges | integer | puzzle의 범위 수. puzzle이 풀에 없으면 0이에요. |
percentage | number | 스캔된 범위의 비율(%). |
totalScanned, rangesScannedLastHour | integer | 전체 및 최근 1시간 동안 스캔된 범위(목록 엔드포인트에서 채워져요). |
statisticsTotalScanned, statisticsFoundOnPool, statisticsFoundDate, statisticsFoundBy | 다양함 | 완료된 puzzle의 최종 수치. statisticsFoundBy은(는) 알려진 경우에만 있어요. |
rangeContainsKeys, rangeContainsKeyByDefault | integer | 범위 하나에 든 개인 키 수(빼기 1). 범위가 여러 ID에 걸치면 두 값이 달라져요. |
rangesPerKey | integer | 범위 하나가 걸쳐 있는 범위 ID 수(대부분의 puzzle은 1). |
workloadStart, workloadEnd | string | 클라이언트가 범위 HEX 뒤에 스캔하는 개인 키 부분. 참고: GET range. |
customWorkloadStart, customWorkloadEnd | string | puzzle이 사용자 지정 작업량을 사용할 때 있어요. |
dateStart, dateEnd | date | puzzle의 예정 날짜. |
isCompleted, isNextPuzzle, isActive, isDefault, isTestPool, isOnPool | boolean | puzzle의 상태: 완료, 공지됨, 지금 스캔 가능, 기본값, 테스트 풀, 풀에 있음. |
isEntranceFeeActive, entranceFee | boolean, number | 참가비가 켜져 있는지와 USD 기준 가격(꺼져 있으면 0). |
nextScanAllowedInMinutes | integer | 배정된 범위가 다른 사람에게 주어질 수 있기 전까지 보유되는 시간. |
challenges | array | 최근 챌린지, 또는 빈 배열. |
privateKey, publicKey | string | 해결된 puzzle에만 있어요. |
rewards, speed | array, object | 일부 엔드포인트에만 있어요. |
Statistics 객체
| 필드 | 유형 | 설명 |
|---|---|---|
puzzle | object | puzzle의 주요 수치(이름, 코드, 범위 수, 작업량, 상태, 보상). |
scannedLast24H | integer | 최근 24시간 동안 스캔된 범위. |
entranceFeesPaidTotal | number | puzzle에 지불된 참가비(USD). |
topWorkersAlltime | array | 최대 50개의 {userId, walletAddress, totalScanned}; userId 값은 0이에요. |
topWorkersLast24h | array | 최근 24시간 기준의 같은 값. |
activeWorkers | array | {walletAddress, workerName}: 최근 30분 동안 ping을 보낸 워커. |
challenges | array | 최대 32개의 챌린지. |
kingdom | object | puzzle의 왕: walletAddress, message, image 및 isPublished. |
topSpeed | object | 역대 최고의 1시간: date, scanned 범위 및 keysPerSecond. |
chartData | array | 지난 한 달의 시간별 데이터, 최신순: date, dateOnly, hoursOnly 및 rangesScanned. |
lastRanges | array | 최근 스캔된 범위 200개, 최신순: hex (마스킹), walletAddress (마스킹), startTime, endTime, pingTime, gpuModel, gpuCount, workerName, isPremiumUser, isScanned, isPinged, keysInSeconds 및 totalSeconds. |
rewards | array | 보상(개인 키 제외). |
dateUpdated | date | 수치가 계산된 시각. |
currentSpeed | object | CurrentSpeed. |
CurrentSpeed 객체
| 필드 | 유형 | 설명 |
|---|---|---|
activeWorkerCount | integer | 최근 6시간 동안 스캔했고 최근 1시간 동안 ping을 보낸 워커. |
keysPerSecondFormatted | string | 단위가 붙은 속도: keys/s, Kkeys/s, Mkeys/s, Bkeys/s, Tkeys/s 등. |
keysPerSecondRaw | string | 초당 키 수로 나타낸 속도(정수 텍스트). |
Challenge 객체
| 필드 | 유형 | 설명 |
|---|---|---|
hex | string | 모든 챌린지 참여자가 스캔하는 시작 문자. |
dateCreated | date | 챌린지 시작 시각. |
puzzleId | integer | puzzle. |
Reward 객체
| 필드 | 유형 | 설명 |
|---|---|---|
id, puzzleCode, puzzleId | integer | 식별자. |
targetAddress | string | 보상 키의 주소. |
rewardContent, rewardDescription, provider, providerDesc, brand | string | 상금의 내용과 제공자. 값이 없는 속성은 생략돼요. |
privateKey | string | 보상이 해결된 뒤에만 있어요. |
dateCreated, dateSolved | date | 생성 및 해결 시각(미해결 시 0001-01-01T00:00:00). |
이전 문서와 달라진 점
계약은 하나도 바뀌지 않았어요. 이전 API의 모든 엔드포인트, 헤더, 필드, 오류 코드가 여전히 작동하며 같은 응답을 줘요. 이 가이드는 엔드포인트 세 개만 설명하던 이전 페이지를 대체해요. 새로 추가된 내용:
- 공개 데이터 엔드포인트, 실시간 피드, 오류 코드, 요청 한도를 문서화했어요. 이전 페이지에는 이 내용이 없었어요.
- 이전 문서의 수정 사항: 표시 요청의
UserToken헤더는 마이너 토큰이에요(이전 페이지에는 지갑 주소라고 되어 있었어요). ping 간격은 약 2분, 최대 30분이며, 한도는 시간당 60회가 아니라 토큰당 분당 360회예요. 테스트 풀 puzzle은38이에요. - 기본 URL은
https://btcpuzzle.info/api이에요. 이전api.btcpuzzle.info호스트도 계속 작동해요. - SignalR 허브에는 더 이상 클라이언트에서 서버로 호출하는 메서드가 없으므로, 누구도 가짜 이벤트를 보낼 수 없어요. 이벤트 자체는 바뀌지 않았어요.
- 이제 puzzle의 마지막 빈 범위도 배정되며, 너무 좁은
CustomRange구간은 넓혀져서 정확히 하나만 요청하는 방식으로 범위를 고를 수 없어요. - 공개 통계에 더 이상 마이너의 IP 주소가 표시되지 않아요.