ccledger Community API

A non-custodial records and payments API for Canton Network. The on-chain record actions attest and mint are fully live: each writes an immutable record on Canton MainNet and returns an on-chain proof (contract ID, update/transaction ID, ledger offset). Mutual attestation (attest-mutual) is live: it returns pending_signature with the proposal's proof and flips to confirmed when the attestor accepts from their own wallet. On-chain value movement runs through the delegated facilitation flow (plain sender-signed CC transfers only), where you sign from your own wallet and ccledger relays as the application provider — live now.

Built by Blueprint, a Hivemind Capital Partners ecosystem company. Blueprint operates a Canton Network validator on Global MainNet. ccledger is non-custodial, enforced in code: prepaid CC is a non-refundable service credit (“fee credits”) that pays per-action fees only and never funds on-chain value movement — there is no withdrawal endpoint. No validator, no Daml, no keys held by us. Every API key includes 50 trial record actions — top up fee credits for paid tier at 100 RPM. Hold CCL for discount.

Why Use ccledger

1. Immutable on-chain records, no gas fees — Attest, co-sign mutual attestations, and record issuance on Canton MainNet with one call. No wallet to wire up, no gas fees. 50 trial record actions included with every API key (max 25/day). Top up fee credits for paid tier at 100 RPM (2.0 CC fee per record action, 5.0 CC fee for mutual attestation). Hold CCL for discount.
2. Non-custodial value movement (live) — Fee credits never fund value movement. On-chain CC moves from your own wallet via the delegated facilitation flow (transfers only) — you sign a CreateTransferCommand, ccledger relays it as the application provider over Splice’s audited Amulet and Canton Token Standard contracts.
3. On-chain proof — Every response includes contract ID, update/transaction ID, ledger offset, synchronizer ID, and effective timestamp. A verifiable on-chain record — look it up on any Canton participant.
4. Canton Network MainNet — Not a testnet or simulation. Your transactions and records exist on the same global synchronization domain used by major financial institutions.
5. Self-service registration — One POST request returns an API key instantly. No approval process, no KYC, no waiting.
6. Non-custodial, enforced in code — You keep your Loop wallet and keys. Prepaid CC is a non-refundable fee credit: it pays per-action fees only, never funds on-chain value movement, and cannot be withdrawn (there is no withdrawal endpoint). ccledger never holds customer CC as a spendable balance.
7. Query and verify — Retrieve any past action by ID, filter by app name or type, get aggregate statistics. Full audit trail.
8. No infrastructure to manage — Blueprint runs the Canton validator, token-standard integration, and database. 50 trial record actions to get started. Paid tier unlocks unlimited record throughput at 2.0 CC fee per record action (5.0 CC fee for mutual attestation). Hold CCL for discount. You just call the API.

Canton Network

Canton Network is a privacy-enabled, interoperable blockchain network designed for institutional use. Unlike public chains, Canton uses Daml smart contracts with built-in privacy — participants only see data they are authorized to see.

How Canton Works

• Daml smart contracts — Contracts are written in Daml, a purpose-built language for multi-party workflows. Each contract has explicit visibility and authorization rules.
• Global synchronization domain — All participants share a single source of truth without exposing private data. Transactions are atomic across parties.
• Validators — Network participants run validator nodes that host applications and process transactions. Blueprint operates one of these validators.
• Participant nodes — Each validator runs a participant node connected to the global domain. ccledger submits commands through Blueprint’s participant.

What Happens On-Chain

What ccledger does on Canton MainNet depends on the action type:

• Record actions (attest, attest-mutual, mint — all live) — the gateway creates an immutable record contract. The fields written on-chain are the gateway party, a batch id, the data owner, the period timestamps, the dataHash, and submittedBy (your verified API key prefix, so every record is attributable). A mutual attestation additionally records the attestor party, the description and the asset type, and the attestor becomes a co-signatory when they accept.
• Value movement — Plain CC transfers move via the live delegated facilitation flow: the sender signs a CreateTransferCommand from their own wallet and ccledger relays it, exercising Splice’s audited TransferFactory_Transfer. Facilitation covers transfers only — there is no non-custodial escrow or atomic-settlement path today.

Architecture

ccledger is a Spring Boot application running alongside Blueprint’s Canton validator. Here is the complete request flow from your application to on-chain proof.

Infrastructure

Source of Truth

The Canton ledger is the source of truth for on-chain records and value. Attestations, mutual attestations, and issuance records are immutable record contracts. The PostgreSQL database tracks API keys, fee credits, the CCL discount credit, and action history for fast queries and rate-limit enforcement. Records already committed on-chain persist on the ledger regardless of the database.

On-Chain Proof Model

ccledger returns an on-chain proof for every live action. What that proof references depends on the action type.

Record actions (attest, attest-mutual, mint) record data on-chain: you provide a dataHash — a SHA-256 fingerprint of your off-chain data — and ccledger writes it into an immutable record contract. Your raw data never touches our servers; you hash it locally and send only the hash.

Every action returns:

• contractId — the Canton contract identifier
• transactionId — the Canton update/transaction ID
• ledgerOffset — global sequence number on the ledger
• synchronizerId — which Canton domain processed it
• effectiveAt — when the Canton sequencer committed it

Look any of these up against a Canton participant to independently verify the action.

Getting Started

From zero to on-chain proof in three steps. No wallet, no gas fees. 50 trial transactions included.

Base URL

Step 1: Register for an API Key

One POST request. No approval needed. Returns your key instantly.

The cantonParty field is optional at registration and only echoed back. The first verified top-up permanently binds the sender party to your key; from then on, top-ups must come from that party.

Step 2: Call Any Action Endpoint

Choose from 3 record actions. Here’s an example using attest:

Step 3: Get On-Chain Proof

Every successful action returns a proof object with the on-chain record:

The contractId uniquely identifies the Daml contract on Canton MainNet. The transactionId is the Canton transaction hash. The ledgerOffset is the global sequence number. These are permanent, immutable records.

API Reference

29 REST endpoints. All return JSON. Base URL: https://ccledger.xyz. The reference below covers the core record, query, and account endpoints; the rest form two non-custodial capability groups — the agentic rail (scoped agent keys + signed fee receipts) and the dev on-ramp (sandbox/test mode + signed webhooks), where agent keys are scoped spend handles on prepaid fee credits and receipts/webhooks carry fees and metadata only. For the interactive explorer with try-it-out (and the full endpoint list), see the API Explorer.

Registration

Action Endpoints

Three record actions. The record actions attest and mint are fully live — they write immutable records on Canton MainNet and return an on-chain proof. Attest-mutual returns pending_signature with the proposal's proof, then flips to confirmed when the attestor accepts. On-chain value movement runs through the delegated facilitation flow (you sign from your own wallet, ccledger relays as the application provider; transfers only) — live.

Required Fields (all action types)

Some actions require additional fields: attest-mutual needs attestorParty. See each endpoint below and the Action Types section.

Common Response Fields

Query Endpoints

Balance & Credits

Prepaid CC is a non-refundable service credit (“fee credits”) that pays per-action fees only — it never funds on-chain value movement, and there is no withdrawal endpoint (credits are a one-way prepayment, not a custodial balance). Send CC from your Loop wallet: the first top-up is claimed once via POST /deposit with your deposit code in the memo, and later top-ups auto-credit within seconds. Community tier includes 50 trial record actions (max 25/day) at no cost. Paid tier (100 RPM) costs 2.0 CC fee per record action (5.0 CC for mutual attestation). Simply holding CCL gives you a discount on every action.

Fees (deterministic, no hidden costs)

CCL Discount Curve

Your discount is based on the CCL you hold (cclOnchainHoldings), tracked on your ccledger account. Formula: discount = 50% × (1 - 1/(1 + cclOnchainHoldings/200))

Discount increases with more CCL held (up to ~50%). Hold CCL to lower your CC cost per action — CCL is never spent, only CC is charged at the discounted rate. Your discount is shown in GET /balance (cclOnchainHoldings, discountedCostPerAction, discountedCostPerMutual, discountPercent). The more CCL you hold, the larger your discount.

Action Types

Three record actions — attest, attest-mutual, and mint — all fully live, each writing an immutable record with an on-chain proof. On-chain value movement is a separate live path via the delegated facilitation flow (transfers only). All live actions return the same on-chain proof format.

Computing a Data Hash

JavaScript / Node.js

Python

Bash

On-Chain Proof

Every action response includes a proof object. These fields are your verifiable, on-chain evidence that the action settled on Canton MainNet.

What Makes This Proof Trustworthy

• Finality — Once committed on Canton, a transaction is final, and an attestation record cannot be modified or deleted by anyone, including Blueprint.
• Consensus — The transaction was committed through Canton’s global synchronization protocol, validated by the sequencer and mediator.
• Ordering — The ledgerOffset gives a total ordering of all events. You can prove that record A was created before record B.
• Timestamping — The effectiveAt timestamp is set by the Canton sequencer, not by Blueprint’s application.

Payments — Non-Custodial Facilitation

This is the live way to move Canton Coin through ccledger. You sign the transfer with your own key; ccledger relays it to the ledger as the application provider. ccledger never holds your funds and never sees your private key. Prepaid fee credits are never spent on value movement. Facilitation covers plain sender-signed CC transfers only — there is no non-custodial escrow or atomic-settlement path today.

The Flow

Nonce

/prepare requires the sender’s current nextNonce, read from the Canton Scan transfer-command counter (0 for a party that has never sent). A prepared command is valid for 10 minutes.

Example — prepare, sign, execute, send

Reading the /send result

• success: true — the transfer settled. If reason says “executed by the delegate’s validator automation”, the validator’s own Splice automation executed your pending command before ccledger’s submission landed. That is normal and expected: the payment went through, but updateId is null because it was not our transaction. Verify on-chain via the sender’s history on ccscan. Do not retry.
• success: false with HTTP 200 — a committed on-ledger Failure result (out of funds, expired command, wrong receiver). Definite: no funds moved.
• HTTP 202 needs_reconciliation — the submit was indeterminate and may have committed. Check the transfer-command status on Scan before doing anything else; never blind-retry.
• HTTP 500 — definite pre-commit failure. Nothing moved, nothing to refund.

Full request and response schemas for all six endpoints are in the API Explorer and openapi.json.

Trial Credits & CCL Builder Rewards

Trial Credits

Every new API key includes 50 trial credits (max 25 per day). Trial credits fund the record actions only (attest, attest-mutual, mint), so you can test without paying CC. They never fund value movement.

• 50 total trial credits per API key, non-renewable
• 25/day cap to prevent abuse (resets daily UTC)
• Automatic refund if an action fails definitively before commit — an indeterminate submission is not refunded, it is marked needs_reconciliation
• Check remaining credits via GET /api/v1/community/balance (trialCreditsRemaining, trialDailyUsed)

When trial credits are exhausted, record actions return 402 (see Error Responses). Top up fee credits by sending CC from your Loop wallet to the Blueprint validator (minimum 1.0 CC, maximum 10,000 CC per deposit); the ledger watcher credits them once the transfer is confirmed on-chain, upgrading you to paid tier for unlimited record actions. POST /deposit is available as a manual fallback.

CCL Builder Rewards

Every 10th CC-paid action (not trial) earns 1 CCL Builder Reward on your account, tracked per API key.

• 1 CCL per 10 CC-paid actions (attest, attest-mutual, mint)
• Discount based on the CCL you hold (cclOnchainHoldings), tracked on your ccledger account
• Hold CCL to reduce your CC cost per action — the discount approaches ~50%
• CCL is never spent on actions; only CC is charged at the discounted rate
• See CCL Builder Rewards for full details on the discount curve

CCL Builder Rewards

CCL is an account-based, non-transferable discount credit for the ccledger ecosystem. Hold CCL to reduce your CC cost per action — the discount approaches ~50%. Your discount is based on the CCL you hold, tracked on your ccledger account. The more CCL you hold, the larger your discount.

Discount Curve

Discount is based on cclOnchainHoldings — the CCL you hold on your ccledger account. Formula: discount = 50% × (1 - 1/(1 + cclOnchainHoldings/200))

Discount increases with more CCL held (up to ~50%).

Earning CCL

CCL Builder Rewards are earned automatically. Every 10 CC-paid actions (attest, attest-mutual, mint) earns 1 CCL on your ccledger account. Trial actions do not count — only CC-paid actions earn CCL. Your Canton party is bound on your first verified fee-credit top-up.

Hold to Save

CCL is a discount credit tracked on your ccledger account. The more CCL you hold, the larger your discount on every action — your cclOnchainHoldings drives your discounted rates. CCL is never spent on actions; only CC is charged, at the discounted rate.

Billing Order

Billing follows your tier rather than a fallback chain. A paid-tier key is charged fee credits at your discounted rate, and returns 402 if the balance is short; it does not fall back to trial credits. A community-tier key spends trial credits, and returns 402 once they are gone. A key upgrades to paid automatically on its first credited top-up. CCL is held for the discount only and is never charged.

CCL Endpoint

Your CCL balance, CCL discount balance (cclOnchainHoldings), mint progress, and current discounted rates are all included in the unified GET /api/v1/community/balance endpoint (see Balance & Credits above).

Error Responses

Error response formats vary by endpoint and status code. Below is the exact response body for each error condition.

400 Bad Request

Returned by the registration endpoint when the request body is invalid:

Returned by action endpoints when required fields (appName or dataHash) are missing or invalid:

401 Unauthorized

Returned when the X-API-Key header is missing or contains an invalid key. Note: the 401 response uses {"message":"..."} only — there is no error field.

402 Payment Required (x402/p402-style)

Returned by record actions when trial credits are exhausted (community tier) or fee credits are insufficient (paid tier). The body includes the standard error/message/status plus x402Version: 1 and an accepts array, so an x402/p402 agent client can pay-and-retry with no bespoke integration. Paying = topping up fee credits by sending CC to the payTo gateway party (non-refundable; fees only), then retrying.

403 Forbidden

POST /deposit returns 403 when the transaction sender does not match the Canton party bound to your key by its first verified top-up.

404 Not Found

Returned by GET /api/v1/community/actions/{actionId} when the action ID does not exist or does not belong to your API key:

429 Too Many Requests

Returned when you exceed the rate limit. The API-key rate limiter includes retryAfterSeconds in the JSON body and a Retry-After HTTP header. The registration rate limiter returns a standard error response.

500 Internal Server Error

Returned when the Canton ledger operation fails (e.g., participant unavailable). Returns an ErrorResponse carrying the action id, so you can look the action up afterwards with GET /actions/{actionId}:

400 Bad Request (attest-mutual attestorParty)

Returned when attestorParty cannot take part in the attestation: the party is unknown on the Global Synchronizer, or its participant has not vetted ccledger’s gateway package. Any fee credit or trial debit is refunded, so nothing is charged.

503 Service Unavailable

Returned only if the operator has switched a capability off with its emergency kill-switch (for example POST /attest-mutual or the facilitation endpoints). Nothing is charged — no fee credit or trial debit. The response body names the switched-off capability and what remains available.

Security Model

ccledger is designed with a minimal trust surface. Here is exactly what the API can and cannot do.

1. Non-custodial, enforced in code — ccledger never holds customer CC as a spendable value balance. Prepaid CC is a non-refundable fee credit: it pays per-action fees only, never funds on-chain value movement, and cannot be withdrawn (no withdrawal endpoint exists). ccledger never holds customer CC as a spendable value balance.
2. Your data is private — Only you can see your action detail, proofs and balance. Note that the unauthenticated GET /stats endpoint publishes aggregate network stats and a leaderboard of app name, Canton party, tier and action counts for keys with a bound Canton party; spend and CCL holdings are never exposed.
3. On-chain proof, off-chain data — You send a hash, not raw data. ccledger never sees your underlying records. The hash is stored on-chain as proof, but the data it represents remains entirely within your system.
4. Rate limiting — Community tier: 10 RPM (50 trial TX, max 25/day). Paid tier: 100 RPM. Registration: 3 per IP per 24 hours.
5. TLS everywhere — All connections use HTTPS with automatic certificate management. No plaintext data in transit.
6. Top-up verification — Fee-credit top-ups are verified on-chain via the Canton Ledger API. Your Canton party is bound on the first verified top-up (the verified transfer is the proof of control), and later top-ups must come from the bound party. Amounts are extracted from on-chain contract arguments, not user-supplied.

Rate Limits

Rate limits protect the shared infrastructure and ensure fair access for all developers.

When rate limited, the API returns HTTP 429 with a JSON body. For API-key rate limits, the response includes a retryAfterSeconds field. See Error Responses for exact response formats.

MCP Server

ccledger exposes 28 MCP tools via Streamable HTTP. AI agents (Claude Desktop, Claude Code, LangChain, CrewAI, etc.) can connect and call the API with zero friction.

Endpoint

Core tools

These are the core record, query, verification, and account tools. The remaining tools cover three non-custodial capability groups — the agentic rail (scoped agent keys + signed fee receipts), the dev on-ramp (sandbox/test mode + signed webhooks), and the facilitation flow (facilitation_status, facilitation_onboard, facilitation_prepare, facilitation_execute, facilitation_send — the full sender-signed transfer sequence) — for 28 tools in total. Agent keys are scoped spend handles on prepaid fee credits; receipts and webhooks carry fees and metadata only, never value movement. See the API Explorer or openapi.json for the complete list.

Connect from Claude Desktop / Claude Code

Add to your claude_desktop_config.json or project .mcp.json:

AI Discovery Files

• llms.txt — LLM-optimized overview (llmstxt.org spec)
• llms-full.txt — Complete reference for agents
• .well-known/agent.json — A2A agent card
• openapi.json — OpenAPI 3.1 spec with x-llm-hint annotations

FAQ

Verification

How to verify that your on-chain records are real and immutable.

Via the API

Query any action by its ID to retrieve the full proof:

Via the Stats Endpoint

Verify aggregate counts match your expectations:

Data Hash Verification

To verify that a record matches your original data:

1. Retrieve the action from the API using its actionId
2. Recompute the SHA-256 hash of your original data
3. Compare the hash against the dataHash field in the response
4. If they match, the on-chain record corresponds to your original data

Canton Participant Verification

For maximum independence, you can verify contracts directly against a Canton participant. The contractId in the proof object is the canonical Daml contract identifier on the global domain. Any Canton participant with visibility to Blueprint’s contracts can look up this ID.