ccledger Community API

A non-custodial records and payments API for Canton Network. The on-chain record actions — attest, attest-mutual, 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). Unlock is live and free (it releases a previously created lock back to its owner). The legacy balance-funded value endpoints — transfer, lock, settle — are permanently disabled (HTTP 403 non_custodial); on-chain value movement is moving to the delegated facilitation flow, where you sign from your own wallet and ccledger relays as the featured application — rolling out 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, 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 (rolling out) — The balance-funded transfer/lock/settle mode is permanently disabled (403 non_custodial): fee credits never fund value movement. On-chain CC will move from your own wallet via the delegated facilitation flow — you sign a CreateTransferCommand, ccledger relays it as the featured application over Splice’s audited Amulet and Canton Token Standard contracts. Unlock remains live and free for previously created locks.
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). The balance-funded value endpoints are hard-gated at 403 — 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) — live today — the gateway creates an immutable record contract. The key fields recorded on-chain are listed below.
• Unlock — live and free — releases a previously created LockedAmulet (LockedAmulet_UnlockV2) back to its owner.
• Value movement (transfer, lock, settle) — the balance-funded mode is permanently disabled (403 non_custodial). When the delegated facilitation flow ships, the sender signs a CreateTransferCommand from their own wallet and ccledger relays it, exercising Splice’s Amulet and Canton Token Standard choices (TransferFactory_Transfer; LockedAmulet escrow; the allocation flow AllocationFactory_Allocate → Allocation_ExecuteTransfer).

Once created, an attestation record is immutable — it exists on Canton MainNet for the lifetime of the network, and no one, including Blueprint, can modify or delete it. Every live action returns an on-chain proof (contract ID, update/transaction ID, ledger offset) you can verify against the Canton participant.

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; unlock releases are real Amulet transactions. 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.

Unlock releases a previously created lock: the proof references the on-chain Amulet transaction that released the LockedAmulet back to its owner.

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 7 action types. 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

15 REST endpoints. All return JSON. Base URL: https://ccledger.xyz. For the interactive explorer with try-it-out, see the API Explorer.

Registration

Action Endpoints

Seven action endpoints. The record actions (attest, attest-mutual, mint) are fully live — they write immutable records on Canton MainNet and return an on-chain proof. Unlock is live and free. The balance-funded value endpoints (transfer, lock, settle) are permanently disabled by the enforced non-custodial policy and return HTTP 403 non_custodial; on-chain value movement is moving to the delegated facilitation flow (you sign from your own wallet, ccledger relays as the featured application) — rolling out, not yet callable.

Required Fields (all action types)

Some actions require additional fields: attest-mutual needs attestorParty; unlock needs lockId. The disabled value endpoints kept their request shapes (transfer: recipient + amount; lock: amount + duration; settle: recipient party + amount) for the facilitation rollout, but currently return 403 before validation. 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 and your fee credits are auto-credited 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

Seven action types. Three write immutable records (attest, attest-mutual, mint) — fully live. Unlock is live and free. The balance-funded value actions (transfer, lock, settle) are permanently disabled (403 non_custodial); value movement arrives via the delegated facilitation flow (rolling out). 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.

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, and mint — so you can test without paying CC. They never fund value movement (the balance-funded transfer/lock/settle endpoints are disabled for everyone — 403 non_custodial).

• 50 total trial credits per API key, non-renewable
• 25/day cap to prevent abuse (resets daily UTC)
• Automatic refund if a trial action fails on-chain
• Check remaining credits via GET /api/v1/community/balance (trialCreditsRemaining, trialDailyUsed)

When trial credits are exhausted, record actions return 402 (x402/p402-style — see Error Responses). Top up fee credits by sending CC from your Loop wallet to the Blueprint validator (auto-credited; minimum 1.0 CC) to upgrade 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; unlock is free and does not count)
• 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; unlock is free and does not count) 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

When you submit an action, ccledger deducts in this order: fee credits (at the discounted rate based on the CCL you hold) → trial credits → 402 if all exhausted. 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

Returned by POST /transfer, POST /lock, and POST /settle on every call — the balance-funded value-movement mode is permanently disabled by the enforced non-custodial policy. This is a 403, not a 402: no payment or tier unlocks it. Do not retry; use record actions today, and the delegated facilitation flow for value movement once it ships. (The message names /lock or /settle on those endpoints.)

POST /deposit also 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 ActionResponse with status: "failed" and a null proof:

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). The balance-funded value endpoints (transfer, lock, settle) are hard-gated at 403 non_custodial.
2. Your data is private — Only you can see your actions and balance. No one else can access your data.
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 15 MCP tools via Streamable HTTP. AI agents (Claude Desktop, Claude Code, LangChain, CrewAI, etc.) can connect and call the API with zero friction.

Endpoint

Tools (15)

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.