Hướng Dẫn API NoxHash — Tự Động Hoá Vận Hành Đào Coin

Vì sao API đào coin lại quan trọng

Một khi bạn vận hành nhiều hơn một hoặc hai máy đào, dashboard web không còn là cách nhanh nhất để xem toàn cảnh. Bạn sẽ muốn một màn hình duy nhất kéo hashrate NoxHash nằm cạnh số dư trên sàn, thống kê pool từ các nhà vận hành khác và cảnh báo giá BTC của riêng bạn. API biến điều đó thành hiện thực mà không cần copy-paste hay scrape màn hình.

NoxHash API đang được thiết kế xoay quanh ba trường hợp sử dụng mà chúng tôi nghe thường xuyên từ các nhà vận hành: giám sát, theo dõi danh mục và tích hợp tùy chỉnh. Tên endpoint và payload dưới đây mô tả hình dạng mà chúng tôi dự kiến phát hành; hãy xem chúng như bản xem trước kỹ thuật chứ không phải hợp đồng đã chốt.

Xác thực — Cách API Keys hoạt động

Mọi request được bảo vệ sẽ cần một API key gửi trong header HTTP Authorization dưới dạng bearer token. Đây là mẫu chuẩn được hầu hết các REST API hiện đại sử dụng và giúp khóa không lọt vào URL, log referer hay lịch sử trình duyệt.

Ví dụ request (mã giả curl)

Đoạn code bên dưới minh họa hình dạng kỳ vọng. Thay nxh_live_... bằng khóa bạn đã copy từ trang Hồ sơ.

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

Một response thành công trả về JSON với mảng data và metadata phân trang. Request không được xác thực trả về HTTP 401; request không có scope hợp lệ trả về 403.

Tham chiếu endpoint dự kiến

Bảng dưới liệt kê các endpoint chúng tôi dự kiến mở trong lần phát hành công khai đầu tiên. Tên và field có thể thay đổi nhẹ trước khi ra mắt, vì vậy hãy kiểm tra tài liệu trực tiếp khi bạn bắt đầu code. Toàn bộ endpoint chỉ đọc khi khởi đầu; các thao tác ghi (khởi động máy đào, tạo yêu cầu rút tiền) sẽ đến sau khi API đọc đã ổn định.

Mọi endpoint dạng list sẽ trả về kết quả phân trang theo mẫu truy vấn chung ?page=1&per_page=25, kèm object meta chứa total, page và per_page. Mặc định giới hạn khoảng 25 item mỗi trang để giữ thời gian phản hồi nhanh.

Giới hạn tốc độ và Webhook

Poll API mỗi giây là lãng phí khi dữ liệu bạn quan tâm chỉ thay đổi vài phút một lần. NoxHash API sẽ kết hợp giới hạn tốc độ hợp lý với hệ thống webhook để bạn chọn đúng công cụ cho từng việc.

Giới hạn tốc độ

Hãy chờ đợi giới hạn trên mỗi khóa tính bằng số request mỗi phút. Mọi response sẽ bao gồm header như X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Khi chạm trần, request trả về HTTP 429 kèm header Retry-After — hãy lùi lại và thử lại thay vì dồn dập endpoint.

Webhook cho sự kiện

Với bất cứ thứ gì cần xử lý theo thời gian thực — máy đào offline, nạp tiền được xác nhận, hợp đồng thuê hết hạn — webhook rõ ràng tốt hơn polling. Bạn đăng ký một URL, backend NoxHash POST payload JSON đã ký khi sự kiện xảy ra, và server của bạn phản ứng theo thời gian thực. Các sự kiện điển hình chúng tôi dự kiến phát hành:

• miner.status_changed — một máy chuyển giữa Running, Stopped hoặc Expired.
• deposit.confirmed — một khoản nạp USDT đến được cộng vào ví của bạn.
• withdrawal.processed — một khoản rút BTC hoàn tất trên chain.
• rental.expiring_soon — kích hoạt khoảng 7 ngày trước khi hợp đồng thuê kết thúc để bạn có thể gia hạn chủ động.

Payload sẽ được ký bằng HMAC secret để server của bạn có thể xác minh tính xác thực trước khi hành động. Hãy làm theo hướng dẫn trong OWASP API Security Top 10 khi thiết kế trình xử lý webhook — đặc biệt là về xác thực đầu vào, authentication và bảo vệ chống replay.

Bốn mẫu tự động hóa đáng xây dựng

Dưới đây là các quy trình phổ biến nhất mà nhà vận hành xây dựng sau khi có quyền truy cập API. Không có gì quá xa lạ — nhưng mỗi mẫu tiết kiệm thời gian thực tế so với kiểm tra dashboard web thủ công.

Giữ API Key của bạn an toàn

Một API key tương đương mật khẩu của bạn cho các endpoint nó có thể truy cập — hãy đối xử tương xứng. Các thói quen dưới đây nhanh chóng thiết lập và giúp khóa bị lộ ít gây thiệt hại hơn nhiều:

1. Không bao giờ commit khóa vào git. Đặt chúng trong file .env đã được gitignore, hoặc dùng trình quản lý secret như 1Password, Doppler hoặc AWS Secrets Manager.
2. Gọi API từ server, không phải từ trình duyệt. JavaScript phía client chuyển khóa của bạn cho bất kỳ ai mở DevTools. Hãy proxy request qua backend của chính bạn thay vào đó.
3. Đặt hạn dùng cho mỗi khóa. Một khóa có hạn 90 ngày giới hạn bán kính thiệt hại nếu nó lộ. Xoay vòng theo lịch phù hợp với khả năng chịu rủi ro của bạn.
4. Thu hồi khóa bạn không còn dùng. Xóa các script cũ và khóa demo khỏi Hồ sơ → API Keys ngay khi chúng lỗi thời.
5. Giám sát hoạt động bất thường. Nếu bạn thấy request không phải do mình thực hiện, hãy thu hồi khóa ngay lập tức và điều tra xem nó có thể đã lộ ở đâu.

Câu hỏi thường gặp