Skip to content

Commit 615e4d5

Browse files
jp-dfinityjp-dfinity
committed
ic-dashboard skill
1 parent df1d212 commit 615e4d5

5 files changed

Lines changed: 413 additions & 3 deletions

File tree

‎public/.well-known/agent.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
"ckbtc",
1111
"evm-rpc",
1212
"https-outcalls",
13+
"ic-dashboard",
1314
"icrc-ledger",
1415
"internet-identity",
1516
"multi-canister",

‎public/.well-known/ai-plugin.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
"schema_version": "v1",
33
"name_for_human": "IC Skills",
44
"name_for_model": "ic_skills",
5-
"description_for_human": "Agent-readable skill files for Internet Computer (ICP) development. Covers 12 capabilities including ckBTC, ICRC ledger, Internet Identity, stable memory, HTTPS outcalls, EVM RPC, SNS, and more.",
6-
"description_for_model": "Retrieve structured skill files for Internet Computer (ICP) development. Each skill is a markdown document with prerequisites, pitfalls, tested code blocks, and deploy commands. Use the raw GitHub URLs to inject skills directly into context. Available skills: asset-canister, certified-variables, ckbtc, evm-rpc, https-outcalls, icrc-ledger, internet-identity, multi-canister, sns-launch, stable-memory, vetkd, wallet.",
5+
"description_for_human": "Agent-readable skill files for Internet Computer (ICP) development. Covers 13 capabilities including ckBTC, ICRC ledger, Internet Identity, stable memory, HTTPS outcalls, EVM RPC, SNS, and more.",
6+
"description_for_model": "Retrieve structured skill files for Internet Computer (ICP) development. Each skill is a markdown document with prerequisites, pitfalls, tested code blocks, and deploy commands. Use the raw GitHub URLs to inject skills directly into context. Available skills: asset-canister, certified-variables, ckbtc, evm-rpc, https-outcalls, ic-dashboard, icrc-ledger, internet-identity, multi-canister, sns-launch, stable-memory, vetkd, wallet.",
77
"auth": {
88
"type": "none"
99
},

‎public/llms-full.txt‎

Lines changed: 207 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
All IC Skills in a single file for direct context injection.
44
Source: https://github.com/dfinity/icskills
5-
Skills: 12
5+
Skills: 13
66

77

88
---
@@ -2858,6 +2858,212 @@ fn transform_normalize(args: TransformArgs) -> HttpRequestResult {
28582858
```
28592859

28602860

2861+
---
2862+
2863+
---
2864+
id: ic-dashboard
2865+
name: IC Dashboard APIs
2866+
category: Integration
2867+
description: "Use the public REST APIs that power dashboard.internetcomputer.org. Get data for canisters, ledgers, SNS, and metrics."
2868+
endpoints: 12
2869+
version: 1.0.0
2870+
status: stable
2871+
dependencies: []
2872+
requires: []
2873+
tags: [dashboard, api, rest, openapi, swagger, ic-api, icrc-api, sns-api, ledger-api, metrics-api]
2874+
---
2875+
2876+
# IC Dashboard APIs
2877+
2878+
## What This Is
2879+
2880+
These public REST APIs power **dashboard.internetcomputer.org**. They expose read-only access to canister metadata, ICRC ledgers, SNS data, the ICP ledger, and network metrics via OpenAPI specs and Swagger UI. Agents and scripts can call them over HTTPS from off-chain (no canister deployment or cycles required). **Prefer v2 or higher API versions** where available; they provide cursor-based pagination (`after`, `before`, `limit`) and are the same surface the dashboard uses.
2881+
2882+
## Prerequisites
2883+
2884+
- Any HTTP client: `curl`, `fetch`, `axios`, or the language’s native HTTP library.
2885+
- No `icp-cli` or canister deployment needed for read-only API access.
2886+
- For OpenAPI-based codegen: optional use of the `openapi.json` URLs with your preferred OpenAPI tooling.
2887+
2888+
## API Base URLs and Docs
2889+
2890+
| API | Base URL | OpenAPI spec | Swagger / Docs | Prefer |
2891+
|-----|----------|--------------|----------------|--------|
2892+
| IC API | `https://ic-api.internetcomputer.org` | `/api/v3/openapi.json` | `/api/v3/swagger` | v4 for canisters, subnets (cursor pagination) |
2893+
| ICRC API | `https://icrc-api.internetcomputer.org` | `/openapi.json` | `/docs` | v2 for ledgers (TestICP and other ICRC tokens; **not** mainnet ICP) |
2894+
| SNS API | `https://sns-api.internetcomputer.org` | `/openapi.json` | `/docs` | v2 for snses, proposals, neurons |
2895+
| Ledger API (mainnet ICP) | `https://ledger-api.internetcomputer.org` | `/openapi.json` | `/swagger-ui/` | Use for **ICP token**; v2 for cursor pagination |
2896+
| Metrics API | `https://metrics-api.internetcomputer.org` | `/api/v1/openapi.json` | `/api/v1/docs` | v1 (no newer version) |
2897+
2898+
Full URLs for specs and UI:
2899+
2900+
- IC API: https://ic-api.internetcomputer.org/api/v3/openapi.json — https://ic-api.internetcomputer.org/api/v3/swagger
2901+
- ICRC API: https://icrc-api.internetcomputer.org/openapi.json — https://icrc-api.internetcomputer.org/docs
2902+
- SNS API: https://sns-api.internetcomputer.org/openapi.json — https://sns-api.internetcomputer.org/docs
2903+
- Ledger API: https://ledger-api.internetcomputer.org/openapi.json — https://ledger-api.internetcomputer.org/swagger-ui/
2904+
- Metrics API: https://metrics-api.internetcomputer.org/api/v1/openapi.json — https://metrics-api.internetcomputer.org/api/v1/docs
2905+
2906+
## How It Works
2907+
2908+
1. **Prefer v2+ APIs with cursor pagination.** IC API v4 (`/api/v4/canisters`, `/api/v4/subnets`), ICRC API v2 (`/api/v2/ledgers`, `/api/v2/ledgers/{id}/transactions`, etc.), and SNS API v2 (`/api/v2/snses`, `/api/v2/snses/{id}/proposals`, `/api/v2/snses/{id}/neurons`) use `after`, `before`, and `limit` for stable, efficient paging. Avoid v1/offset-based endpoints when a v2+ alternative exists.
2909+
2. **Choose the right API** for the data you need: IC API (canisters, subnets, NNS neurons/proposals), **Ledger API for mainnet ICP** (accounts, transactions, supply), ICRC API for **other** ICRC ledgers only (ckBTC, SNS tokens, testicp — ICRC API does not expose mainnet ICP), SNS API (SNS list, neurons, proposals), Metrics API (governance, cycles, Bitcoin, etc.).
2910+
3. **Use the OpenAPI spec** to get exact path, query, and body schemas and response shapes; prefer the spec over hand-written docs to avoid drift.
2911+
4. **Call over HTTPS** with `GET` (or documented method). Use the `next_cursor` / `previous_cursor` from v2+ responses to request the next or previous page.
2912+
2913+
## Mistakes That Break Your Build
2914+
2915+
1. **Wrong base URL or API version.** IC API uses `/api/v3/` (and v4 for canisters/subnets); ICRC has `/api/v1/` and `/api/v2/` (ICRC API does not serve mainnet ICP — use Ledger API). Ledger API uses unversioned paths for some endpoints (e.g. `/accounts`, `/supply/total/latest`) and `/v2/` for cursor-paginated lists. Metrics API uses `/api/v1/`. Using the wrong prefix returns 404 or wrong schema.
2916+
2917+
2. **Canister ID format.** Canister IDs in paths and queries must match the principal-like pattern: 27 characters, five groups of five plus a final three (e.g. `ryjl3-tyaaa-aaaaa-aaaba-cai`). Subnet IDs use the longer pattern (e.g. 63 chars). Sending a raw principal string in the wrong encoding or length causes 422 or 400.
2918+
2919+
3. **Using ICRC API for mainnet ICP.** ICRC API exposes **test ICP (TestICP) only**, not mainnet ICP. For mainnet ICP token data (accounts, transactions, supply) use **Ledger API** (`ledger-api.internetcomputer.org`). Use ICRC API for other ICRC ledgers (e.g. ckBTC, SNS tokens) and for TestICP.
2920+
2921+
4. **ICRC API: ledger_canister_id in path.** ICRC endpoints require `ledger_canister_id` in the path (e.g. `/api/v2/ledgers/{ledger_canister_id}/transactions`). Use the canister ID of the ledger you want (e.g. ckBTC `mxzaz-hqaaa-aaaar-qaada-cai`). Do not use ICRC API for mainnet ICP — use Ledger API instead.
2922+
2923+
5. **Using v1 or offset-based pagination when v2+ exists.** Always prefer v2 or higher endpoints that support cursor pagination (`after`, `before`, `limit`). IC API v4 (canisters, subnets), ICRC API v2 (ledgers, accounts, transactions), and SNS API v2 (snses, proposals, neurons) return `next_cursor`/`previous_cursor` and accept cursor query params. Older v1/offset/`max_*_index` endpoints are legacy; using the wrong pagination model returns empty or incorrect pages.
2924+
2925+
6. **Timestamps.** Most time-range query params (`start`, `end`) expect Unix seconds (integer). Sending milliseconds or ISO strings causes validation errors (422).
2926+
2927+
7. **Account identifier format.** Ledger API and ICRC/ICP endpoints use **account identifiers** (hex hashes), not raw principals, for account-specific paths. Use the same encoding the API documents (e.g. 64-char hex for account_identifier where required).
2928+
2929+
8. **Assuming authentication.** These public dashboard APIs do not require API keys or auth for the documented read endpoints. If you get 401/403, confirm you are not hitting a different environment or a write endpoint that requires auth.
2930+
2931+
## Implementation
2932+
2933+
### IC API — Canisters and subnets (prefer v4 with cursor pagination)
2934+
2935+
```bash
2936+
# List canisters (v4: cursor pagination, next_cursor/previous_cursor in response)
2937+
curl -s "https://ic-api.internetcomputer.org/api/v4/canisters?limit=5"
2938+
2939+
# Next page: use after= from previous response's next_cursor (see OpenAPI for cursor format)
2940+
# curl -s "https://ic-api.internetcomputer.org/api/v4/canisters?limit=5&after=..."
2941+
2942+
# Get one canister by ID (v3; no v4 single-canister endpoint)
2943+
curl -s "https://ic-api.internetcomputer.org/api/v3/canisters/ryjl3-tyaaa-aaaaa-aaaba-cai"
2944+
2945+
# List subnets (v4: cursor pagination)
2946+
curl -s "https://ic-api.internetcomputer.org/api/v4/subnets?limit=10"
2947+
2948+
# List NNS proposals (v3; use limit)
2949+
curl -s "https://ic-api.internetcomputer.org/api/v3/proposals?limit=5"
2950+
```
2951+
2952+
### ICRC API — Other ICRC ledgers only (v2 with cursor pagination)
2953+
2954+
ICRC API exposes **TestICP and other ICRC ledgers (e.g. ckBTC, SNS tokens), not mainnet ICP.** For mainnet ICP use Ledger API.
2955+
2956+
```bash
2957+
# List ledgers (v2: after/before/limit, next_cursor/previous_cursor in response)
2958+
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=10"
2959+
2960+
# Get one ledger (e.g. ckBTC — mainnet ICP is not on ICRC API)
2961+
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai"
2962+
2963+
# List transactions for a ledger (v2: cursor pagination)
2964+
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai/transactions?limit=5"
2965+
2966+
# List accounts for a ledger (v2: after/before/limit)
2967+
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers/mxzaz-hqaaa-aaaar-qaada-cai/accounts?limit=10"
2968+
```
2969+
2970+
### SNS API — SNS list and proposals (prefer v2 with cursor pagination)
2971+
2972+
```bash
2973+
# List SNSes (v2: after/before/limit, next_cursor/previous_cursor)
2974+
curl -s "https://sns-api.internetcomputer.org/api/v2/snses?limit=10"
2975+
2976+
# List proposals for an SNS root canister (v2: cursor pagination)
2977+
# Replace ROOT_CANISTER_ID with a real SNS root canister ID
2978+
curl -s "https://sns-api.internetcomputer.org/api/v2/snses/ROOT_CANISTER_ID/proposals?limit=5"
2979+
2980+
# List neurons for an SNS (v2: after/before/limit)
2981+
curl -s "https://sns-api.internetcomputer.org/api/v2/snses/ROOT_CANISTER_ID/neurons?limit=10"
2982+
```
2983+
2984+
### Ledger API — Mainnet ICP token (prefer v2 for cursor pagination)
2985+
2986+
```bash
2987+
# List accounts (v2: after/before/limit, next_cursor/prev_cursor)
2988+
curl -s "https://ledger-api.internetcomputer.org/v2/accounts?limit=10"
2989+
2990+
# Get account by account_identifier (64-char hex)
2991+
curl -s "https://ledger-api.internetcomputer.org/accounts/ACCOUNT_IDENTIFIER"
2992+
2993+
# List transactions (v2: cursor pagination)
2994+
curl -s "https://ledger-api.internetcomputer.org/v2/transactions?limit=10"
2995+
2996+
# Total supply (latest)
2997+
curl -s "https://ledger-api.internetcomputer.org/supply/total/latest"
2998+
```
2999+
3000+
### Metrics API
3001+
3002+
```bash
3003+
# Average cycle burn rate
3004+
curl -s "https://metrics-api.internetcomputer.org/api/v1/average-cycle-burn-rate"
3005+
3006+
# Governance metrics
3007+
curl -s "https://metrics-api.internetcomputer.org/api/v1/governance-metrics"
3008+
3009+
# ICP/XDR conversion rates (with optional start/end/step)
3010+
curl -s "https://metrics-api.internetcomputer.org/api/v1/icp-xdr-conversion-rates?start=1700000000&end=1700086400&step=86400"
3011+
```
3012+
3013+
### Fetching OpenAPI spec (for codegen or validation)
3014+
3015+
```bash
3016+
# IC API v3
3017+
curl -s "https://ic-api.internetcomputer.org/api/v3/openapi.json" -o ic-api-v3.json
3018+
3019+
# ICRC API
3020+
curl -s "https://icrc-api.internetcomputer.org/openapi.json" -o icrc-api.json
3021+
3022+
# SNS API
3023+
curl -s "https://sns-api.internetcomputer.org/openapi.json" -o sns-api.json
3024+
3025+
# Ledger API
3026+
curl -s "https://ledger-api.internetcomputer.org/openapi.json" -o ledger-api.json
3027+
3028+
# Metrics API v1
3029+
curl -s "https://metrics-api.internetcomputer.org/api/v1/openapi.json" -o metrics-api-v1.json
3030+
```
3031+
3032+
## Deploy & Test
3033+
3034+
No canister deployment is required. These are external HTTP APIs. Test from the shell or your app:
3035+
3036+
```bash
3037+
# Smoke test: IC API root
3038+
curl -s -o /dev/null -w "%{http_code}" "https://ic-api.internetcomputer.org/api/v3/"
3039+
# Expected: 200
3040+
3041+
# Smoke test: ICRC ledgers list
3042+
curl -s -o /dev/null -w "%{http_code}" "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=1"
3043+
# Expected: 200
3044+
```
3045+
3046+
## Verify It Works
3047+
3048+
```bash
3049+
# 1. IC API returns canister list with data array
3050+
curl -s "https://ic-api.internetcomputer.org/api/v3/canisters?limit=1" | head -c 200
3051+
# Expected: JSON with "data" or similar key and at least one canister
3052+
3053+
# 2. ICRC API returns ledger list
3054+
curl -s "https://icrc-api.internetcomputer.org/api/v2/ledgers?limit=1" | head -c 200
3055+
# Expected: JSON with "data" and ledger entries
3056+
3057+
# 3. Ledger API returns supply (array of [timestamp, value])
3058+
curl -s "https://ledger-api.internetcomputer.org/supply/total/latest"
3059+
# Expected: JSON array with two elements (timestamp and supply string)
3060+
3061+
# 4. OpenAPI specs are valid JSON
3062+
curl -s "https://ic-api.internetcomputer.org/api/v3/openapi.json" | python3 -c "import sys,json; json.load(sys.stdin); print('OK')"
3063+
# Expected: OK
3064+
```
3065+
3066+
28613067
---
28623068

28633069
---

‎public/llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ curl -sL https://raw.githubusercontent.com/dfinity/icskills/main/skills/<skill-i
1919
- [ckBTC Integration](https://raw.githubusercontent.com/dfinity/icskills/main/skills/ckbtc/SKILL.md): Accept, send, and manage ckBTC in your canister. Covers minting, transfers, balance checks, and UTXO management.
2020
- [EVM RPC Integration](https://raw.githubusercontent.com/dfinity/icskills/main/skills/evm-rpc/SKILL.md): Call Ethereum and EVM chains from IC canisters. JSON-RPC, transaction signing, and cross-chain workflows.
2121
- [HTTPS Outcalls](https://raw.githubusercontent.com/dfinity/icskills/main/skills/https-outcalls/SKILL.md): Make HTTP requests from canisters to external APIs. Consensus-safe request patterns, transform functions, and cost management.
22+
- [IC Dashboard APIs](https://raw.githubusercontent.com/dfinity/icskills/main/skills/ic-dashboard/SKILL.md): Use the public REST APIs that power dashboard.internetcomputer.org. Get data for canisters, ledgers, SNS, and metrics.
2223
- [ICRC Ledger Standard](https://raw.githubusercontent.com/dfinity/icskills/main/skills/icrc-ledger/SKILL.md): Deploy and interact with ICRC-1/ICRC-2 token ledgers. Minting, approvals, transfers, and metadata.
2324
- [Internet Identity Auth](https://raw.githubusercontent.com/dfinity/icskills/main/skills/internet-identity/SKILL.md): Integrate Internet Identity authentication into frontend and backend canisters. Delegation, session management, and anchor handling.
2425
- [Multi-Canister Architecture](https://raw.githubusercontent.com/dfinity/icskills/main/skills/multi-canister/SKILL.md): Design and deploy multi-canister dapps with inter-canister calls, shared state patterns, and upgrade strategies.

0 commit comments

Comments
 (0)