NoxHash API 指南 — 自动化您的挖矿操作

为什么挖矿 API 很重要

当您运行超过一两台矿机时,网页仪表盘就不再是查看全部信息的最快方式了。您会希望有一个统一视图,将 NoxHash 的算力与交易所余额、其他运营商的矿池统计数据以及您自己的 BTC 价格提醒并排显示。API 让这一切成为可能,无需任何复制粘贴或屏幕抓取。

NoxHash API 的设计围绕我们从运营商那里反复听到的三种用例:监控、投资组合跟踪和自定义集成。下方的端点名称和 payload 描述了我们预期发布的形态;请将它们视为技术预览,而非最终合约。

身份验证——API Keys 如何工作

每个受保护的请求都需要在 Authorization HTTP header 中以 bearer token 的形式发送 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。

计划的端点参考

下表列出了我们预计在首个公开版本中暴露的端点。在发布前,名称和字段可能会略有调整,因此请在开始编码时查看在线文档。所有端点起初都是只读的;写操作(启动矿机、创建提现请求)将在读取 API 稳定后跟进。

每个列表端点都将使用常见的 ?page=1&per_page=25 查询模式返回分页结果,并附带包含 total、page 和 per_page 的 meta 对象。默认每页限制约 25 项以保持快速响应。

速率限制与 Webhook

当您关心的数据每隔几分钟才变化一次时,每秒轮询 API 是浪费。NoxHash API 将把合理的速率限制与 Webhook 系统结合起来,让您为每项工作选择合适的工具。

速率限制

预计每个密钥的限制以每分钟请求数衡量。每个响应都将包含诸如 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 的 header。当您触及上限时,请求返回 HTTP 429 并附带 Retry-After header——请退避后重试,而不是持续轰炸端点。

事件 Webhook

对于任何对时间敏感的情况——矿机下线、存款确认、租期到期——Webhook 明显优于轮询。您注册一个 URL,NoxHash 后端在事件触发时 POST 一个已签名的 JSON payload,您的服务器实时做出反应。我们计划发布的典型事件:

• miner.status_changed——机器在 Running、Stopped 或 Expired 之间转换。
• deposit.confirmed——入账的 USDT 存款已记入您的钱包。
• withdrawal.processed——BTC 提现在链上完成。
• rental.expiring_soon——在租期结束前约 7 天触发,以便您主动续租。

Payload 将使用 HMAC 密钥签名,以便您的服务器在采取行动前验证其真实性。设计 Webhook 处理器时请遵循 OWASP API Security Top 10 的指导——尤其是在输入验证、身份验证和重放保护方面。

四种值得构建的自动化模式

以下是运营商获得 API 访问权限后最常构建的工作流。它们没有一个是特别复杂的——但每一个都比手动查看网页仪表盘节省了实实在在的时间。

确保 API 密钥安全

API 密钥相当于它能访问的端点的密码——请谨慎对待。下面的习惯设置起来很快,能让泄露的密钥造成的损害大幅降低:

1. 永不将密钥提交到 git。 将它们放在已被 gitignore 的 .env 文件中,或使用诸如 1Password、Doppler 或 AWS Secrets Manager 之类的 secret 管理器。
2. 从服务器而非浏览器调用 API。 客户端 JavaScript 会把您的密钥暴露给任何打开 DevTools 的人。改为通过您自己的后端代理请求。
3. 为每个密钥设置过期时间。 有效期 90 天的密钥在泄漏时能限制影响范围。按照符合您风险承受能力的节奏轮换。
4. 撤销不再使用的密钥。 旧脚本和演示密钥一旦过时,立即从 个人资料 → API Keys 中删除。
5. 监控异常活动。 如果您看到不是自己发出的请求,请立即撤销密钥并调查它可能从哪里泄露。

常见问题