iceFetch は、Minecraft Bedrock の NetherNet サーバーのステータス確認と、サーバーが提示する ICE candidate の取得ができる、小さな無料の JSON API を公開しています。サイト上のツールと同じことを行えます。

エンドポイント

# ステータス
curl "https://icefetch.tools.kt04.com/api/info?host=play.example.net&port=19132"

# candidate
curl -X POST https://icefetch.tools.kt04.com/api/offer \
  -H 'content-type: application/json' \
  -d '{"host":"play.example.net","port":19132}'

/api/offer のボディ: host（必須）、port（既定 19132）、networkId（任意・10 進 uint64）、tls（自動判定。true/false で強制）、fresh（120 秒キャッシュを無視）。

リクエスト / レスポンスの型

// GET /api/info  — クエリ文字列
host   : string            // 必須 — ホスト名または IP
port   : number            // 任意、既定 19132
tls    : "true" | "false"  // 任意 — 省略時は自動判定

// 200 →
{ ok: boolean, status: number, tls: boolean, info: object | null }


// POST /api/offer  — Content-Type: application/json
{
  host      : string,   // 必須
  port?     : number,   // 既定 19132
  networkId?: string,   // 10進 uint64（1〜20桁）。省略時はランダム
  tls?      : boolean,  // 省略時は自動判定
  fresh?    : boolean   // true = 120 秒キャッシュを無視
}

// 200 →
{
  ok: boolean,
  answer: string,             // 生の SDP answer
  candidates: Candidate[],
  answerFingerprint: string,
  iceUfrag: string,
  exhausted: boolean,         // 200 だが candidate 0 件 = サーバーの UDP ポートプール枯渇
  cached?: boolean, stale?: boolean
}

Candidate = {
  raw: string, foundation: string, component: number, transport: string,
  priority: number, address: string, port: number, type: string,
  relatedAddress?: string, relatedPort?: number
}

エラー時はどちらのエンドポイントも { ok: false, error: … }（error は文字列、または { httpStatus, body } 等のオブジェクト）を 4xx/5xx ステータスで返します。

レート制限

制限は 3 種類あり、それぞれ独立して適用されます。

• バースト（クライアント IP ごと）: API 全体で 1 分あたり最大 20 リクエスト。超過すると HTTP 429 を返します。急なスパイクをならすためのもので、月間クォータとは別です。
• 対象サーバーごとのスロットル: 同一サーバー（host:port）はキャッシュミス時に 1 分あたり最大 2 回しか probe しません。これにより /api/offer がサーバーの NetherNet UDP ポートプールを枯渇させることはありません。同じサーバーへの繰り返しの照会は、120 秒の間キャッシュから返されます。スロットル中でキャッシュもない場合は { ok: false, error: "target throttled …" } を返します（fresh:true は本当にライブ probe が必要なときだけ）。
• 月間クォータ（エンドポイントごと）: API キーを付けなければ IP ごとに、付ければキーごとに数えます:

すべての応答に、現在のクォータがヘッダで含まれます。

X-RateLimit-Scope:     ip | key
X-RateLimit-Limit:     <月間の上限>
X-RateLimit-Remaining: <今月の残り回数>
X-RateLimit-Reset:     <クォータがリセットされる unix 時刻>

クォータを使い切ると、API は HTTP 429 を Retry-After ヘッダとともに返します。

API キーの送り方

次のいずれかのヘッダでキーを送ります。

X-API-Key: ice_xxxxxxxx
# または
Authorization: Bearer ice_xxxxxxxx

API キーを取得

ツール解説記事APIプライバシー規約 · iceFetch は Mojang および Microsoft とは無関係です。