ic-dashboard

IC Dashboard API

这是什么

这些公开的 REST API 为 dashboard.internetcomputer.org 提供支持。它们通过 OpenAPI 规范和 Swagger UI，提供对 canister 元数据、ICRC 账本、SNS 数据、ICP 账本和网络指标的只读访问。Agent 和脚本可以通过 HTTPS 从链下调用这些 API（无需部署 canister 或消耗 cycles）。如有可用版本，请优先使用 v2 或更高版本的 API；这些版本提供基于游标的分页（after、before、limit），并且与仪表板使用的是同一套 API。

前置条件

• 任意 HTTP 客户端：curl、fetch、axios 或该语言的原生 HTTP 库。
• 只读访问 API 无需 icp-cli 或部署 canister。
• 如需基于 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	canister、子网使用 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 代币请使用此 API；游标分页使用 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（canister、子网、NNS 神经元/提案）、主网 ICP 使用 Ledger API（账户、交易、供应量）、ICRC API 仅用于其他 ICRC 账本（ckBTC、SNS 代币、testicp；ICRC API 不提供主网 ICP）、SNS API（SNS 列表、神经元、提案）、Metrics API（治理、cycles、Bitcoin 等）。
3. 使用 OpenAPI 规范获取准确的路径、查询参数和请求体架构以及响应结构；优先参考规范而不是手写文档，以避免信息过时。
4. 通过 HTTPS 调用，使用 GET（或文档中规定的方法）。使用 v2+ 响应中的游标字段请求下一页或上一页。字段名称并不统一：IC、ICRC 和 SNS API 返回 next_cursor / previous_cursor，但 Ledger API 返回 next_cursor / prev_cursor，并且行数组会以对应资源命名（accounts、blocks 等），而不是统一使用 data。请从响应（或 OpenAPI 规范）中读取字段名称，不要想当然。

会导致构建失败的错误

1. 基础 URL 或 API 版本错误。 IC API 使用 /api/v3/（canister/subnet 使用 v4）；ICRC 使用 /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 个字符，外加最后 3 个字符，例如 ryjl3-tyaaa-aaaaa-aaaba-cai。Principal 的长度并非固定：subnet ID 最长可达 63 个字符（十组各 5 个字符，外加最后 3 个字符），而管理 canister aaaaa-aa 这样的短 ID 也属于有效 principal。以错误的编码或长度发送原始 principal 字符串会导致 422 或 400。

3. 将 ICRC API 用于主网 ICP。 ICRC API 仅提供测试 ICP（TestICP），不提供主网 ICP。要获取主网 ICP 代币数据（账户、交易、供应量），请使用 Ledger API（ledger-api.internetcomputer.org）。其他 ICRC 账本（例如 ckBTC、SNS 代币）以及 TestICP 请使用 ICRC API。

4. ICRC API：路径中的 ledger_canister_id。 ICRC 端点要求在路径中包含 ledger_canister_id（例如 /api/v2/ledgers/{ledger_canister_id}/transactions）。请使用目标账本的 Canister ID（例如 ckBTC 的 mxzaz-hqaaa-aaaar-qaada-cai）。不要将 ICRC API 用于主网 ICP — 请改用 Ledger API。

5. 在存在 v2+ 版本时使用 v1 或基于偏移量的分页。 始终优先使用支持游标分页（after、before、limit）的 v2 或更高版本端点。IC API v4（canister、subnet）、ICRC API v2（账本、账户、交易）和 SNS API v2（snses、提案、神经元）会返回 next_cursor/previous_cursor，并接受游标查询参数 — Ledger API v2 也使用游标分页，但字段名为 prev_cursor。旧版 v1/偏移量/max_*_index 端点已弃用；使用错误的分页模式会返回空页面或错误的页面。

6. 时间戳。 大多数时间范围查询参数（start、end）要求使用 Unix 秒（整数）。发送毫秒或 ISO 字符串会导致验证错误（422）。

7. 账户标识符格式。 Ledger API 和 ICRC/ICP 端点的账户专用路径使用账户标识符（十六进制哈希），而不是原始 principal。请使用 API 文档规定的编码方式（例如需要 account_identifier 时使用 64 个字符的十六进制字符串）。

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 账本（使用支持游标分页的 v2）

ICRC API 提供TestICP 和其他 ICRC 账本（例如 ckBTC、SNS 代币），不提供主网 ICP。 主网 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 列表和提案（优先使用支持游标分页的 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。请从 Shell 或应用中测试：

# 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