# Blueprint Canton Chain API — full agent reference

> Everything an agent needs to use https://ccscan.xyz in one file: auth, pagination, every documented endpoint with its response shape, the data model, and worked examples. The machine-readable contract is the OpenAPI 3.1 spec at https://ccscan.xyz/openapi.json; the short index is https://ccscan.xyz/llms.txt.

Base URL: `https://ccscan.xyz` — all endpoints are read-only GETs returning JSON with permissive CORS (`Access-Control-Allow-Origin: *`, GET/OPTIONS).

## Auth & rate limits

- Anonymous: 300 requests/min per IP — enough to explore.
- API key (either header): `Authorization: Bearer <key>` or `X-API-Key: <key>`.
- Plans: Free 300 req/min · Pro 3,000 · Enterprise 30,000 (live: `GET /api/plans`). Keys are `cck_`-prefixed; the rate budget pools across all keys on one account.
- Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds), and `X-Plan`. Over-limit ⇒ `429` + `Retry-After`. Invalid/inactive key ⇒ `401`.
- Fixed one-minute windows: budget resets at the top of each minute.
- Volume quotas: Free includes 10,000 requests/day and 150,000/month (pooled across keys). Quota-capped responses carry `X-Quota-Daily-Limit`/`-Remaining` and `X-Quota-Monthly-Limit`/`-Remaining`; an exhausted quota ⇒ `429` naming the window that resets it. Pro and Enterprise have no volume caps.
- `/api/status`, `/api/live`, and `/api/live/stream` are metering-exempt — they never consume rate or quota budget.
- Self-serve keys: https://ccscan.xyz/pricing.

## Pagination

List endpoints cursor over the monotonic integer `seq` (global insertion order):

- Newest-first: pass `before_seq` (0 = start at the newest), read the page, then pass the response's `next_before_seq` for the next older page.
- Oldest-first (party history only): pass `after_seq` (0 = genesis), chain `next_after_seq`.
- `count: 0` means the range is exhausted. `limit` defaults 25, max 100.
- `before_seq` and `after_seq` are mutually exclusive — sending both returns `400`.

## Errors

| status | meaning |
|---|---|
| 400 | invalid parameter (message names the parameter) |
| 401 | invalid or inactive API key |
| 404 | resource not found |
| 429 | rate limit exceeded — honor `Retry-After` |
| 502 | upstream SV Scan API failure (live-state endpoints) |
| 503 | `{"building": true}` — a supporting index/aggregate is still building; retry later |

## Data model essentials

- Party ids look like `name::1220<fingerprint-hex>`. URL-encode them in paths.
- `tx_type` ∈ `transfer` | `mint` | `tap` | `abort_transfer_instruction`. mint/tap are protocol-defined but not observed on MainNet to date.
- Transfers carry `nature`: `send` (distinct receiver), `reward` (validator/SV/app collecting rewards — no separate recipient), or `self` (self-transfer / coin merge). `kind` refines the transfer mechanism (direct, pre-approved, transfer-instruction).
- The headline `amount` is a JSON number: send = sum of receiver amounts; reward = gross rewards collected; self = sender change; abort = null.
- `rewards` (when present) de-duplicates the validator coupon: validator reward and validator faucet are the same coupon reported in one or both fields — consumers must take max(validator_reward, validator_faucet), never the sum.
- Detail and balance amounts are 10-decimal-place strings for accounting-grade math; never parse them as floats if you need exactness.
- Freshness: the index trails the chain head by seconds (`ingest_cursor_at` in `/api/overview`); balances/holdings/ANS/network come live from the SV Scan API with 30s–1h caches by endpoint.

## Endpoints

### GET /api/overview
Chain head snapshot: `head_seq`, `latest_round`, `latest_tx_date`, `total_tx_est`, `party_count_est`, `tx_24h`, `ingest_cursor_at`, `latest_txs[12]` (TxRow).

### GET /api/txs?before_seq&type&round&day&limit
Global feed, newest-first. Filters combine freely; `day` is UTC `YYYY-MM-DD`. Returns `{count, next_before_seq, txs[]}`.

### GET /api/tx/{key}
One transaction by seq (digits) or full event id (`#1220…:0`). Returns the TxRow fields plus `detail` — the full financial body (sender fees, receiver list with per-receiver fees, balance changes, transfer kind, description).

### GET /api/party/search?q=
Substring search over every party ever seen (~424k). Returns `{parties: [party_id, …]}`.

### GET /api/parties/notable
Curated party directory for discovery: `{parties: [{party, name, tag}], count}` — Blueprint's validator first, then every super validator, then featured-app providers. `tag` ∈ `validator` | `super validator` | `featured app`.

### GET /api/party/{party}/summary
`{party, first_seen, last_seen, tx_count, tx_count_capped, ans}` — `tx_count` is exact up to 100k then capped; `ans` = `{name, user, url, description, expires_at, contract_id}` when registered.

### GET /api/party/{party}/txs?before_seq|after_seq&type&limit
Complete per-party history (both directions). Rows are TxRow plus `roles` ⊆ [`sender`, `receiver`, `balance_change`].

### GET /api/party/{party}/balance
Live balance from the ACS: `{record_time, computed_as_of_round, summary:{total_available_coin, total_unlocked_coin, total_locked_coin, total_coin_holdings, accumulated_holding_fees_total, …}}` — decimal strings.

### GET /api/party/{party}/holdings?after=
Active holding contracts: `{record_time, migration_id, created_events: [event, …], next_page_token}` — each event has `contract_id`, `template_id`, `created_at`, `create_arguments` (amount, lock state).

### GET /api/party/{party}/validator
Validator/SV/app-provider status: role flags, liveness (`network_round`, `our_round`, `rounds_behind` → `active`|`inactive`|`unknown` — measured by round progress, Canton issues no liveness rewards), recent activity, and exact lifetime reward totals (sv/app/validator, de-duplicated).

### GET /api/party/{party}/validator/rewards
Weekly reward series for charting: `{weeks[], rewards[], collections[], total, incomplete}`.

### GET /api/rounds?before&limit
Bulk round summaries, newest-first: `{latest_round, next_before, rounds: [{round, txs, started, ended, first_seq, last_seq, duration_s}]}`. Page back with `before`; `limit` max 100.

### GET /api/round/{n}?before_seq&limit
Mining-round detail: `{round, count, first_seq, last_seq, started, ended, txs[]}` (cursor-paginated within the round).

### GET /api/ans?prefix&page_size
Canton Name Service directory (prefix filter, `page_size` max 1000).

### GET /api/network
DSO info, super-validator list (reward weights, joined rounds), AmuletRules (CC) configuration, component versions.

### GET /api/netstat
One-call network-economics snapshot: `{oracle_price, round, round_opens_at, round_closes_at, tick_seconds, issuance_per_year, app_reward_pct, validator_reward_pct, traffic_price, holding_fee_rate, sv_count, voting_threshold, featured_apps, version}`. Built from shared 30–600s upstream caches.

### GET /api/governance?limit=
Decoded DSO governance: `{open[], closed[], categories{}, tally{open,accepted,rejected,expired}, archived_total}`. Each proposal: `{tracking_cid, title, action, category, status, requester, votes_for, votes_against, expires_at, completed_at}`. `limit` 5–200 (default 40); the local archive extends closed history past the scan's ~100-item window.

### GET /api/governance/{cid}
One proposal by tracking contract id — everything in the list row plus `all_votes[]` (every SV's accept/reject + reason), `action_raw`, and `sv_count` (current electorate size for the tally denominator). `404` if unknown.

### GET /api/governance/participation
Per-SV voting participation across all archived decided proposals: `{svs: [{sv, name, voted, accepted, rejected, rate}], decided}`. Cached ~5 min.

### GET /api/validators
Trailing-7d validator leaderboard: `{validators: [{party, rewards, days_active, is_sv}], daily: [{day, rewards, actives}], computed_at}` — background-computed; `pending:true` until the first rollup.

### GET /api/sync
`{network_round, our_round, rounds_behind, synced}` — our index height vs the network head round.

### GET /api/featured-apps
On-chain FeaturedAppRight registry with per-app reward/tx metrics over 24h/7d windows and a daily reward series.

### GET /api/stats/daily
Per-day aggregates from genesis: `{days: [{day, tx_count, transfers, mints, taps, aborts, cc_transferred, cc_minted, cc_tapped, sv_rewards, app_rewards, validator_rewards, cc_fees_burned, reward_collections}], aggregated_to_seq, econ_to_seq, head_seq, complete, econ_complete}`. Rewards mint new CC, fees burn (Canton burn-mint economics); `complete=false` while the genesis backfill is still walking.

### GET /api/stats/recent?days=14
Always-current trailing daily counts (last entry is the partial current day).

### GET /api/price
Canton Coin market data (CoinGecko): usd, usd_market_cap, usd_24h_change, btc. Cached 120s.

### GET /api/search?q=
Universal classifier: returns `{results: [{kind: tx|round|party, key, label}]}` for a seq, round number, event id, party fragment, or ANS name.

### GET /api/status
Service health: `{status, uptime_seconds, index:{head_seq, latest_tx_at, lag_seconds}, scan_api, live_feed, aggregates, network_version}`. Metering-exempt.

### GET /api/live
Real-time chain pulse, served entirely from memory and metering-exempt (a 2s poll is always safe): `{available, now, t0, ts[], seqs[], rounds[], head_seq, round, last_tx_at, tps_10s, tps_60s, tps_5m, interval}` — ~3 minutes of ~2s head-seq samples (`ts[i]` are offsets from `t0`) plus instant/1m/5m throughput. `available:false` only in the first seconds after a deploy.

### GET /api/live/stream
Server-Sent Events push of the same payload — plus each newly indexed transaction in `txs[]` — emitted the moment the chain head moves (sub-second latency). First event arrives immediately with a ~30-tx backfill; streams recycle after ~120s and `EventSource` reconnects transparently; at connection capacity returns `503` (fall back to polling `/api/live`). Metering-exempt.

### GET /healthz
`{"status": "ok"}` liveness probe.

## Worked examples

```
# chain head + the 12 newest transactions
curl -s https://ccscan.xyz/api/overview

# page the global feed back from the head, 50 at a time
curl -s 'https://ccscan.xyz/api/txs?limit=50'
curl -s 'https://ccscan.xyz/api/txs?limit=50&before_seq=<next_before_seq>'

# one transaction, full financial detail
curl -s https://ccscan.xyz/api/tx/320000000

# find a party, then read its history oldest-first
curl -s 'https://ccscan.xyz/api/party/search?q=cumberland'
curl -s 'https://ccscan.xyz/api/party/<party-id-url-encoded>/txs?after_seq=0&limit=100'

# authenticated request (higher rate tier)
curl -s -H 'Authorization: Bearer cck_…' https://ccscan.xyz/api/overview

# live push — every new transaction as a server-sent event
curl -sN https://ccscan.xyz/api/live/stream
```

## Links

- OpenAPI spec: https://ccscan.xyz/openapi.json
- Human docs: https://ccscan.xyz/docs/
- Interactive reference: https://ccscan.xyz/api-docs/
- Keys & pricing: https://ccscan.xyz/pricing
- Commercial access, SLAs, dedicated capacity: https://theblueprint.xyz