NoxHash API 가이드 — 채굴 운영 자동화하기

마이닝 API가 중요한 이유

마이너를 한두 대보다 더 많이 운영하기 시작하면 웹 대시보드는 더 이상 모든 것을 가장 빨리 확인하는 방법이 아닙니다. NoxHash 해시레이트를 거래소 잔액, 다른 운영자의 풀 통계, 자신의 BTC 가격 알림과 나란히 끌어오는 단일 뷰가 필요합니다. API는 복사-붙여넣기나 화면 스크래핑 없이 이를 가능하게 합니다.

NoxHash API는 운영자들로부터 반복적으로 듣는 세 가지 사용 사례를 중심으로 설계되고 있습니다: 모니터링, 포트폴리오 추적, 커스텀 통합입니다. 아래의 엔드포인트 이름과 페이로드는 저희가 출시할 것으로 예상하는 형태를 설명하며, 확정된 계약이 아닌 기술 미리보기로 봐 주시기 바랍니다.

인증 — API Keys 작동 방식

보호된 모든 요청에는 Authorization HTTP 헤더에 bearer 토큰으로 전송되는 API 키가 필요합니다. 이는 대부분의 최신 REST API가 따르는 표준 패턴이며 키가 URL, referer 로그, 브라우저 기록에 남지 않도록 합니다.

요청 예시 (curl 의사 코드)

아래 스니펫은 예상되는 형태를 보여 줍니다. nxh_live_...를 프로필 페이지에서 복사한 키로 교체하세요.

curl -X GET "https://noxhash.com/api/v1/miners" \
  -H "Authorization: Bearer nxh_live_YOUR_KEY_HERE" \
  -H "Accept: application/json"

성공적인 응답은 data 배열과 페이징 메타데이터가 포함된 JSON을 반환합니다. 인증되지 않은 요청은 HTTP 401을 반환하고, 유효한 scope가 없는 요청은 403을 반환합니다.

계획된 엔드포인트 레퍼런스

아래 표는 첫 공개 릴리스에서 노출할 것으로 예상되는 엔드포인트를 나열합니다. 출시 전에 이름과 필드가 약간 변경될 수 있으므로, 코딩을 시작할 때는 라이브 문서를 확인하시기 바랍니다. 시작 시 모든 엔드포인트는 읽기 전용이며, 쓰기 작업(마이너 시작, 출금 요청 생성)은 read API가 안정화된 후에 추가됩니다.

모든 목록 엔드포인트는 공통 ?page=1&per_page=25 쿼리 패턴을 사용하여 페이징된 결과를 반환하며, total, page, per_page를 포함하는 meta 객체가 함께 제공됩니다. 기본값은 응답 속도를 빠르게 유지하기 위해 페이지당 약 25개 항목으로 제한됩니다.

속도 제한과 웹훅

관심 있는 데이터가 몇 분에 한 번씩 변할 때 매초 API를 폴링하는 것은 낭비입니다. NoxHash API는 합리적인 속도 제한과 웹훅 시스템을 결합하여 각 작업에 맞는 도구를 선택할 수 있도록 합니다.

속도 제한

분당 요청 수로 측정되는 키별 제한을 예상하시면 됩니다. 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset와 같은 헤더가 포함됩니다. 상한에 도달하면 요청은 Retry-After 헤더와 함께 HTTP 429를 반환합니다 — 엔드포인트를 계속 두드리지 말고 뒤로 물러섰다가 재시도하세요.

이벤트용 웹훅

시간에 민감한 모든 것 — 마이너 오프라인, 입금 확인, 임대 만료 — 에 대해 웹훅은 폴링보다 확실히 우수합니다. URL을 등록하면 NoxHash 백엔드가 이벤트 발생 시 서명된 JSON 페이로드를 POST하고, 서버는 실시간으로 반응합니다. 출시 예정인 일반적 이벤트:

• miner.status_changed — 장비가 Running, Stopped, Expired 사이를 전환합니다.
• deposit.confirmed — 수신된 USDT 입금이 지갑에 입금됩니다.
• withdrawal.processed — BTC 출금이 온체인에서 완료됩니다.
• rental.expiring_soon — 임대 종료 약 7일 전에 발생하여 미리 갱신할 수 있습니다.

페이로드는 HMAC 시크릿으로 서명되어 서버가 조치를 취하기 전에 진위를 확인할 수 있습니다. 웹훅 핸들러를 설계할 때는 OWASP API Security Top 10의 지침을 따르세요 — 특히 입력 검증, 인증, 리플레이 보호와 관련하여 중요합니다.

구축할 만한 네 가지 자동화 패턴

다음은 운영자가 API 접근 권한을 얻은 후 가장 많이 구축하는 워크플로입니다. 어느 것도 특별하진 않지만, 웹 대시보드를 수동으로 확인하는 것에 비해 실질적인 시간을 절약해 줍니다.

API 키를 안전하게 유지하기

API 키는 접근 가능한 엔드포인트에 대한 비밀번호와 같으니 그에 맞게 다루시기 바랍니다. 아래 습관은 빠르게 설정할 수 있으며 키가 유출되었을 때의 피해를 훨씬 줄여 줍니다:

1. 키를 절대 git에 커밋하지 마세요. gitignore된 .env 파일에 넣거나 1Password, Doppler, AWS Secrets Manager 같은 시크릿 관리자를 사용하세요.
2. 브라우저가 아닌 서버에서 API를 호출하세요. 클라이언트 측 JavaScript는 DevTools를 여는 누구에게나 키를 전달합니다. 대신 자체 백엔드를 통해 요청을 프록시하세요.
3. 각 키에 만료 시간을 설정하세요. 90일 만료 키는 유출 시 피해 반경을 제한합니다. 위험 허용 범위에 맞는 일정으로 순환시키세요.
4. 더 이상 사용하지 않는 키를 취소하세요. 구식이 되는 즉시 오래된 스크립트와 데모 키를 프로필 → API Keys에서 삭제하세요.
5. 비정상 활동을 모니터링하세요. 자신이 만들지 않은 요청이 보이면 즉시 키를 취소하고 어디에서 유출되었을지 조사하세요.

자주 묻는 질문