NoxHash APIガイド — マイニング運用を自動化する

マイニングAPIが重要な理由

マイナーを1〜2台以上運用するようになると、ウェブダッシュボードは全体を見渡す最速の手段ではなくなります。NoxHashのハッシュレートを取引所の残高、他オペレーターのプール統計、自身のBTC価格アラートと並べて表示できる単一のビューが欲しくなるはずです。APIがあれば、コピペやスクリーンスクレイピングなしでそれが可能になります。

NoxHash APIは、オペレーターから繰り返し聞く3つのユースケースを中心に設計されています:モニタリング、ポートフォリオ追跡、カスタム統合です。以下のエンドポイント名とペイロードは、私たちが出荷を見込んでいる形状を示しており、確定した契約ではなくテクニカルプレビューとしてご覧ください。

認証 — API Keysの動作

保護されたすべてのリクエストには、Authorization HTTPヘッダーでベアラートークンとして送信されるAPIキーが必要です。これはほとんどの最新のREST APIが採用している標準パターンであり、キーをURL、リファラーログ、ブラウザ履歴から遠ざけます。

リクエスト例(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を返し、有効なスコープがないリクエストは403を返します。

計画中のエンドポイントリファレンス

以下の表は、最初のパブリックリリースで公開する予定のエンドポイント一覧です。リリース前に名前やフィールドが若干変更される可能性があるため、コーディングを開始する際にはライブドキュメントを確認してください。すべてのエンドポイントは最初は読み取り専用で、書き込み操作(マイナーの起動、出金リクエストの作成)は読み取りAPIが安定した後に続く予定です。

すべてのリスト系エンドポイントは、共通の?page=1&per_page=25クエリパターンを使ってページング結果を返し、total、page、per_pageを含むmetaオブジェクトが付随します。デフォルトではレスポンスタイムを速く保つため、1ページあたり約25件に制限されます。

レート制限とウェブフック

気にしているデータが数分に1回しか変わらないのに、APIを毎秒ポーリングするのは無駄です。NoxHash APIは合理的なレート制限とウェブフックシステムを組み合わせ、各タスクに適したツールを選べるようにします。

レート制限

キーごとに1分あたりのリクエスト数で測定される制限を想定しておいてください。すべてのレスポンスには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のガイダンスに従ってください — 特に入力検証、認証、リプレイ保護に関してです。

構築する価値のある4つの自動化パターン

以下は、オペレーターがAPIアクセスを得た後に最もよく構築するワークフローです。どれも目新しいものではありませんが、それぞれウェブダッシュボードを手動で確認するのと比べて実際の時間を節約してくれます。

APIキーを安全に保つ

APIキーは、それがアクセスできるエンドポイントに対するパスワードと同等です — それに見合った扱いをしてください。以下の習慣はすばやく設定でき、キーが漏洩した場合の被害をはるかに小さくします:

1. キーを絶対にgitにコミットしない。 gitignoreされた.envファイルに置くか、1Password、Doppler、AWS Secrets Managerのようなシークレットマネージャーを使いましょう。
2. ブラウザではなくサーバーからAPIを呼び出す。 クライアントサイドJavaScriptは、DevToolsを開いた誰にでもあなたのキーを渡してしまいます。代わりに自身のバックエンド経由でリクエストをプロキシしてください。
3. 各キーに有効期限を設定する。 90日の有効期限のあるキーは、漏洩時の被害範囲を限定します。リスク許容度に合ったスケジュールでローテーションしましょう。
4. 使わなくなったキーを失効させる。 古くなった瞬間に、古いスクリプトやデモ用キーをプロフィール → API Keysから削除してください。
5. 異常なアクティビティを監視する。 自分が行っていないリクエストが見えたら、すぐにキーを失効させ、どこから漏れた可能性があるかを調査してください。

よくある質問