ic-dashboard

IC ダッシュボード API

これは何か

これらの公開 REST API は dashboard.internetcomputer.org を支えています。OpenAPI 仕様と Swagger UI を通じて、キャニスターのメタデータ、ICRC 台帳、SNS データ、ICP 台帳、ネットワーク指標への読み取り専用アクセスを提供します。エージェントやスクリプトは、オフチェーンから HTTPS 経由で呼び出せます（キャニスターのデプロイやサイクルは不要です）。利用可能な場合は、v2 以上の API バージョンを優先してください。これらのバージョンはカーソルベースのページネーション（after、before、limit）を提供し、ダッシュボードが使用するものと同じインターフェースです。

前提条件

• 任意の HTTP クライアント：curl、fetch、axios、または言語標準の HTTP ライブラリ。
• 読み取り専用の API アクセスには、icp-cli もキャニスターのデプロイも不要です。
• OpenAPI ベースのコード生成を行う場合：任意の OpenAPI ツールを使って openapi.json の URL を利用できます。

API のベース URL とドキュメント

API	ベース URL	OpenAPI 仕様	Swagger／ドキュメント	推奨
IC API	https://ic-api.internetcomputer.org	/api/v3/openapi.json	/api/v3/swagger	キャニスターとサブネットには v4（カーソルページネーション）
ICRC API	https://icrc-api.internetcomputer.org	/openapi.json	/docs	台帳には v2（TestICP やその他の ICRC トークン。メインネット ICP は対象外）
SNS API	https://sns-api.internetcomputer.org	/openapi.json	/docs	SNS、提案、ニューロンには v2
Ledger API（メインネット ICP）	https://ledger-api.internetcomputer.org	/openapi.json	/swagger-ui/	ICP トークンにはこちらを使用。カーソルページネーションには v2
Metrics API	https://metrics-api.internetcomputer.org	/api/v1/openapi.json	/api/v1/docs	v1（新しいバージョンはありません）

仕様と UI の完全な URL：

• IC API: https://ic-api.internetcomputer.org/api/v3/openapi.json — https://ic-api.internetcomputer.org/api/v3/swagger
• ICRC API: https://icrc-api.internetcomputer.org/openapi.json — https://icrc-api.internetcomputer.org/docs
• SNS API: https://sns-api.internetcomputer.org/openapi.json — https://sns-api.internetcomputer.org/docs
• Ledger API: https://ledger-api.internetcomputer.org/openapi.json — https://ledger-api.internetcomputer.org/swagger-ui/
• Metrics API: https://metrics-api.internetcomputer.org/api/v1/openapi.json — https://metrics-api.internetcomputer.org/api/v1/docs

仕組み

1. カーソルページネーション対応の v2 以上の API を優先してください。 IC API v4（/api/v4/canisters、/api/v4/subnets）、ICRC API v2（/api/v2/ledgers、/api/v2/ledgers/{id}/transactions など）、SNS API v2（/api/v2/snses、/api/v2/snses/{id}/proposals、/api/v2/snses/{id}/neurons）では、安定した効率的なページ取得のために after、before、limit を使用します。v2 以上の代替エンドポイントがある場合は、v1 やオフセットベースのエンドポイントを避けてください。
2. 必要なデータに応じて適切な API を選択してください：IC API（キャニスター、サブネット、NNS のニューロン／提案）、メインネット ICP には Ledger API（アカウント、トランザクション、供給量）、その他の ICRC 台帳のみには ICRC API（ckBTC、SNS トークン、testicp。ICRC API ではメインネット ICP を公開していません）、SNS API（SNS の一覧、ニューロン、提案）、Metrics API（ガバナンス、サイクル、ビットコインなど）。
3. パス、クエリ、ボディの正確なスキーマとレスポンス形式を確認するには、OpenAPI 仕様を使用してください。仕様のずれを避けるため、手書きのドキュメントよりも仕様を優先してください。
4. GET（またはドキュメントに記載されたメソッド）で HTTPS 経由で呼び出してください。次または前のページをリクエストするには、v2 以上のレスポンスに含まれるカーソルフィールドを使用します。フィールド名は統一されていません。IC、ICRC、SNS API は next_cursor／previous_cursor を返しますが、Ledger API は next_cursor／prev_cursor を返し、行配列には統一された data ではなくリソース名（accounts、blocks など）を使用します。決めつけず、レスポンス（または OpenAPI 仕様）でフィールド名を確認してください。

ビルドを失敗させるよくある間違い

1. ベース URL または API バージョンの誤り。 IC API は /api/v3/（canister／subnet には v4）を使用します。ICRC API は /api/v1/ と /api/v2/ を使用します（ICRC API はメインネット ICP を提供しません。Ledger API を使用してください）。Ledger API は一部のエンドポイント（例：/accounts、/supply/total/latest）でバージョンなしのパスを使用し、カーソルページネーション対応のリストには /v2/ を使用します。Metrics API は /api/v1/ を使用します。誤ったプレフィックスを使用すると、404 エラーまたは誤ったスキーマが返されます。

2. Canister ID の形式。 パスやクエリで使用する Canister ID は principal テキストです。CRC32(blob) · blob の小文字 Base32 エンコードで、5 文字ごとにグループ分けされます。最後のグループのみ、1～5 文字にできます。メインネットの Canister ID は 27 文字で、5 文字のグループが4 つと、最後に 3 文字のグループがあります（例：ryjl3-tyaaa-aaaaa-aaaba-cai）。Principal の長さは固定ではありません。Subnet ID は最大 63 文字（5 文字のグループが 10 個と、最後に 3 文字のグループ）で、管理 canister の aaaaa-aa のような短いものも有効な principal です。誤ったエンコードや長さの raw principal 文字列を送信すると、422 または 400 が返されます。

3. メインネット ICP に ICRC API を使用する。 ICRC API が提供するのはテスト ICP（TestICP）のみで、メインネット ICP は提供しません。メインネット ICP のトークンデータ（アカウント、トランザクション、供給量）には、Ledger API（ledger-api.internetcomputer.org）を使用してください。その他の ICRC ledger（例：ckBTC、SNS トークン）や TestICP には ICRC API を使用してください。

4. ICRC API：パス内の ledger_canister_id。 ICRC エンドポイントでは、パス内に ledger_canister_id が必要です（例：/api/v2/ledgers/{ledger_canister_id}/transactions）。対象の ledger の Canister ID を使用してください（例：ckBTC の mxzaz-hqaaa-aaaar-qaada-cai）。メインネット ICP には ICRC API を使用せず、代わりに Ledger API を使用してください。

5. v2 以降があるのに v1 またはオフセットベースのページネーションを使用する。 カーソルページネーション（after、before、limit）に対応する v2 以降のエンドポイントを常に優先してください。IC API v4（canister、subnet）、ICRC API v2（ledger、アカウント、トランザクション）、SNS API v2（snses、proposal、neuron）は next_cursor／previous_cursor を返し、カーソルのクエリパラメーターを受け取ります。Ledger API v2 もカーソルでページネーションしますが、フィールド名は prev_cursor です。古い v1／オフセット／max_*_index エンドポイントはレガシーです。誤ったページネーション方式を使うと、空のページや不正なページが返されます。

6. タイムスタンプ。 時間範囲のクエリパラメーター（start、end）の大半は、Unix 秒（整数）を想定しています。ミリ秒や ISO 形式の文字列を送信すると、検証エラー（422）が発生します。

7. アカウント識別子の形式。 Ledger API と ICRC／ICP エンドポイントでは、アカウント固有のパスに raw principal ではなくアカウント識別子（16 進数ハッシュ）を使用します。API のドキュメントに記載されたエンコード形式（例：account_identifier に 64 文字の 16 進数が必要な場合はその形式）を使用してください。

8. 認証が必要だと思い込む。 これらの公開ダッシュボード API では、ドキュメントに記載された読み取りエンドポイントに API キーや認証は必要ありません。401／403 が発生した場合は、別の環境や認証が必要な書き込みエンドポイントにアクセスしていないか確認してください。

実装

IC API — Canister と subnet（カーソルページネーション対応の v4 を優先）

# List canisters (v4: cursor pagination, next_cursor/previous_cursor in response)
curl -s "https://ic-api.internetcomputer.org/api/v4/canisters?limit=5"

# Next page: use after= from previous response's next_cursor (see OpenAPI for cursor format)
# curl -s "https://ic-api.internetcomputer.org/api/v4/canisters?limit=5&after=..."

# Get one canister by ID (v3; no v4 single-canister endpoint)
curl -s "https://ic-api.internetcomputer.org/api/v3/canisters/ryjl3-tyaaa-aaaaa-aaaba-cai"

# List subnets (v4: cursor pagination)
curl -s "https://ic-api.internetcomputer.org/api/v4/subnets?limit=10"

# List NNS proposals (v3; use limit)
curl -s "https://ic-api.internetcomputer.org/api/v3/proposals?limit=5"

ICRC API — その他の ICRC ledger のみ（カーソルページネーション対応の v2）

ICRC API が提供するのは、メインネット ICP ではなく、TestICP とその他の ICRC ledger（例：ckBTC、SNS トークン）です。 メインネット ICP には Ledger API を使用してください。

# List ledgers (v2: after/before/limit, next_cursor/previous_cursor in response)
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=10"

# Get one ledger (e.g. ckBTC — mainnet ICP is not on ICRC API)
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai"

# List transactions for a ledger (v2: cursor pagination)
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai/transactions?limit=5"

# List accounts for a ledger (v2: after/before/limit)
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai/accounts?limit=10"

SNS API — SNS の一覧と proposal（カーソルページネーション対応の v2 を優先）

# List SNSes (v2: after/before/limit, next_cursor/previous_cursor)
curl -s "https://sns-api.internetcomputer.org/api/v2/snses?limit=10"

# List proposals for an SNS root canister (v2: cursor pagination)
# Replace ROOT_CANISTER_ID with a real SNS root canister ID
curl -s "https://sns-api.internetcomputer.org/api/v2/snses/ROOT_CANISTER_ID/proposals?limit=5"

# List neurons for an SNS (v2: after/before/limit)
curl -s "https://sns-api.internetcomputer.org/api/v2/snses/ROOT_CANISTER_ID/neurons?limit=10"

Ledger API — メインネット ICP トークン（カーソルページネーションには v2 を優先）

# List accounts (v2: after/before/limit). Note this API's own naming:
# rows come back under `accounts` (not `data`), and the back-cursor is
# `prev_cursor` (not `previous_cursor` as on the IC/ICRC/SNS APIs).
curl -s "https://ledger-api.internetcomputer.org/v2/accounts?limit=10"

# Get account by account_identifier (64-char hex)
curl -s "https://ledger-api.internetcomputer.org/accounts/ACCOUNT_IDENTIFIER"

# List transactions (v2: cursor pagination)
curl -s "https://ledger-api.internetcomputer.org/v2/transactions?limit=10"

# Total supply (latest)
curl -s "https://ledger-api.internetcomputer.org/supply/total/latest"

Metrics API

# Average cycle burn rate
curl -s "https://metrics-api.internetcomputer.org/api/v1/average-cycle-burn-rate"

# Governance metrics
curl -s "https://metrics-api.internetcomputer.org/api/v1/governance-metrics"

# ICP/XDR conversion rates (with optional start/end/step)
curl -s "https://metrics-api.internetcomputer.org/api/v1/icp-xdr-conversion-rates?start=1700000000&end=1700086400&step=86400"

OpenAPI 仕様の取得（コード生成または検証用）

# IC API v3
curl -s "https://ic-api.internetcomputer.org/api/v3/openapi.json" -o ic-api-v3.json

# ICRC API
curl -s "https://icrc-api.internetcomputer.org/openapi.json" -o icrc-api.json

# SNS API
curl -s "https://sns-api.internetcomputer.org/openapi.json" -o sns-api.json

# Ledger API
curl -s "https://ledger-api.internetcomputer.org/openapi.json" -o ledger-api.json

# Metrics API v1
curl -s "https://metrics-api.internetcomputer.org/api/v1/openapi.json" -o metrics-api-v1.json

デプロイとテスト

Canister のデプロイは不要です。これらは外部 HTTP API です。シェルまたはアプリからテストしてください。

# Smoke test: IC API root
curl -s -o /dev/null -w "%{http_code}" "https://ic-api.internetcomputer.org/api/v3/"
# Expected: 200

# Smoke test: ICRC ledgers list
curl -s -o /dev/null -w "%{http_code}" "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=1"
# Expected: 200

動作確認

# 1. IC API returns canister list with data array (v4 — the preferred list endpoint)
curl -s "https://ic-api.internetcomputer.org/api/v4/canisters?limit=1" | head -c 200
# Expected: JSON with "data", "next_cursor" and "previous_cursor" keys, and one canister

# 2. ICRC API returns ledger list
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=1" | head -c 200
# Expected: JSON with "data" and ledger entries

# 3. Ledger API returns supply (array of [timestamp, value])
curl -s "https://ledger-api.internetcomputer.org/supply/total/latest"
# Expected: JSON array with two elements (timestamp and supply string)

# 4. OpenAPI specs are valid JSON
curl -s "https://ic-api.internetcomputer.org/api/v3/openapi.json" | python3 -c "import sys,json; json.load(sys.stdin); print('OK')"
# Expected: OK