# CC Ledger — Complete Reference for AI Agents > Canton Network access for developers and AI agents — without running a validator, writing Daml, or integrating with Canton directly. 15 REST endpoints + 15 MCP tools. Every API call creates an immutable on-chain record on Canton MainNet with cryptographic proof. ## Overview CC Ledger is operated by Blueprint Infrastructure, LLC (a Hivemind Capital Partners ecosystem company). It provides Canton Network — a privacy-enabled, regulated blockchain for institutional financial operations — through standard REST and MCP interfaces. Any app or agent can create immutable Daml smart contracts on Canton MainNet without managing Canton infrastructure. Every API call returns cryptographic proof: contract ID, transaction ID, ledger offset, synchronizer ID, and effective timestamp. The Canton ledger is the source of truth. Registration bindings, deposits, actions, CCL mints, and mutual attestations are all on-chain Daml contracts. The PostgreSQL database is an operational cache for fast queries and rate-limit enforcement. Live endpoint: https://ccledger.theblueprint.xyz OpenAPI spec: https://ccledger.theblueprint.xyz/openapi.json MCP server: https://ccledger.theblueprint.xyz/mcp --- ## Quick Start ### Step 1: Register for an API key ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/register \ -H "Content-Type: application/json" \ -d '{"appName": "my-agent-app", "cantonParty": "user-party::1220abc123def456..."}' ``` **Strongly recommended: provide your Canton party ID (`cantonParty`) at registration.** Get it from your Loop wallet at [loop.canton.network](https://loop.canton.network). Without a cantonParty, you are limited to trial credits only -- there is no way to deposit CC, earn CCL Builder Rewards, or receive action discounts. With it: CC deposits from your Loop wallet are auto-credited to your balance, CCL tokens are minted to your Canton party, and you unlock the full discount curve. You can add it later, but you will need it before your first CC deposit. If not set at registration, the first deposit permanently binds the sender party to your API key. Response: ```json { "apiKey": "cb_community_a1b2c3d4e5f6...", "appName": "my-agent-app", "cantonParty": "user-party::1220abc123def456...", "tier": "community", "rateLimitRpm": 10, "scopes": ["community:write"], "trialCreditsRemaining": 50, "message": "Store this API key securely -- it will not be shown again." } ``` Your community tier key gives you 50 trial transactions (max 25/day) plus access to query, balance, and stats endpoints (10 RPM). No deposit needed to start testing. ### Step 2: Use your trial credits (no deposit needed) Your API key comes with 50 trial transactions (max 25/day). You can immediately submit actions — the trial credits work for all action types. Once exhausted, send CC from your Loop wallet to the Blueprint validator (auto-credited) to continue. ### Step 3: Send CC from your Loop wallet (optional — after trial) Canton Coin (CC) is the native asset on Canton MainNet. Send CC from your Loop wallet to the Blueprint validator address. Your balance is auto-credited within seconds -- no API call needed. This upgrades your API key from community tier (10 RPM, 50 trial TX) to paid tier (100 RPM, unlimited actions at 2.0 CC base per action). Every 10th CC-paid action earns 1 CCL token -- CCL, the CIP-56 builder rewards token for the CC Ledger ecosystem, is minted on-chain to your Canton party. Hold CCL to reduce your CC cost per action (up to ~50% off). CCL is transferable via your Loop wallet and tradeable on any Canton DEX. A background service watches the Canton ledger and auto-detects CC sent from your registered cantonParty to the Blueprint validator. Your CC balance and tier upgrade happen automatically. POST /deposit exists as a manual fallback for edge cases or if auto-detection hasn't caught up yet: ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/deposit \ -H "Content-Type: application/json" \ -H "X-Api-Key: cb_community_a1b2c3d4e5f6..." \ -d '{"transactionId": "canton-mainnet-tx-id-here", "amount": 10.0}' ``` ### How to Fund Your CC Ledger Account CC Ledger uses Canton Coin (CC) — the native asset on Canton Network — for prepaid actions. Here's how to fund your account: #### Step 1: Get Canton Coin (CC) - **Coinbase**: CC is available on [Coinbase](https://www.coinbase.com). Buy CC directly with USD/EUR. - **Canton Network**: Learn more at [canton.network](https://www.canton.network) #### Step 2: Transfer CC to Your Loop Wallet - Download the **Loop wallet** from [loop.canton.network](https://loop.canton.network) - Transfer CC from Coinbase to your Loop wallet address #### Step 3: Send CC to the Blueprint Validator Send CC from your Loop wallet to the Blueprint validator party: ``` blueprint-validator-1::1220daab58adcae026bd2ca7ad95014f678bda3ce2a6f91b744cf3ec3d87f09deeac ``` Your balance is auto-credited within seconds. No API call needed. Your API key is automatically upgraded to paid tier (100 RPM, unlimited actions at 2.0 CC each). POST /deposit is available as a manual fallback if auto-detection hasn't processed your transfer yet. ### Step 4: Submit an action (trial credit or 2.0 CC per action) ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/attest \ -H "Content-Type: application/json" \ -H "X-Api-Key: cb_community_a1b2c3d4e5f6..." \ -d '{ "appName": "my-agent-app", "dataHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "dataOwner": "agent-1", "description": "Attestation of data integrity" }' ``` Response: ```json { "actionId": "7f3a9b2c-1d4e-5f6a-8b9c-0d1e2f3a4b5c", "actionType": "attest", "status": "confirmed", "appName": "my-agent-app", "dataHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "mintedAt": "2026-03-04T14:30:00.000Z", "proof": { "contractId": "005a1b2c3d4e5f...", "transactionId": "12345abcdef67890", "ledgerOffset": 2001542, "synchronizerId": "global-domain::1220abcdef", "effectiveAt": "2026-03-04T14:30:00.000Z", "packageId": null, "templateId": null }, "rewardMarkerCreated": false } ``` ### Step 5: Query your actions ```bash curl https://ccledger.theblueprint.xyz/api/v1/community/actions \ -H "X-Api-Key: cb_community_a1b2c3d4e5f6..." ``` --- ## Action Types ### attest Record data integrity proofs, audit trails, compliance records. Provide a dataHash (hex-encoded hash of your data). Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: dataOwner, dataId, description, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/attest \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","dataOwner":"alice","description":"Invoice attestation"}' ``` ### transfer Record asset transfers, token movements, payment records. Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: sender, recipient, assetId, amount, currency, reference, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/transfer \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","sender":"alice","recipient":"bob","amount":"100.00","currency":"USD"}' ``` ### lock Record asset locks — escrow, collateral, time-locks. Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: owner, assetId, amount, currency, duration, reference, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/lock \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","owner":"alice","assetId":"ETH","amount":"5.0"}' ``` ### unlock Release assets from lock or escrow. Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: owner, assetId, amount, currency, lockId, reference, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/unlock \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","owner":"alice","assetId":"ETH","amount":"5.0"}' ``` ### mint Create tokens, NFTs, certificates. Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: owner, tokenId, tokenName, amount, metadata, reference, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/mint \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","owner":"creator","tokenId":"nft-001","tokenName":"MY-TOKEN","amount":"1"}' ``` ### settle Finalize trades, payments, batch operations. Cost: 2.0 CC. Required fields: appName, dataHash Optional fields: parties, settlementId, amount, currency, reference, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/settle \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","parties":"alice,bob","settlementId":"trade-001","amount":"50000.00","currency":"USD"}' ``` ### attest-mutual Create a mutual attestation proposal requiring a counter-party signature. Cost: 5.0 CC. Required fields: appName, dataHash, attestorParty Optional fields: dataOwner, dataId, description, assetType ```bash curl -X POST https://ccledger.theblueprint.xyz/api/v1/community/attest-mutual \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{"appName":"my-app","dataHash":"abc123...","attestorParty":"alice","dataOwner":"bob","description":"Mutual attestation of trade terms"}' ``` Response: ```json { "actionId": "7f3a9b2c-1d4e-5f6a-8b9c-0d1e2f3a4b5c", "actionType": "attest-mutual", "status": "pending_signature", "appName": "my-app", "dataHash": "abc123...", "mintedAt": "2026-03-04T14:30:00.000Z", "proof": { "contractId": "005a1b2c3d4e5f...", "transactionId": "12345abcdef67890", "ledgerOffset": 2001542, "synchronizerId": "global-domain::1220abcdef", "effectiveAt": "2026-03-04T14:30:00.000Z", "packageId": null, "templateId": null }, "proposalContractId": "005a1b2c3d4e5f...", "attestorParty": "alice", "signingInstructions": "Attestation proposal created on-chain. The attestor party must exercise the Accept choice on the proposal contract using their Canton wallet to complete the mutual attestation." } ``` #### Mutual Attestation Workflow 1. **Submit proposal**: POST /attest-mutual with the attestorParty field set to the counter-party's Canton party ID. 2. **Receive proposal**: The response includes a proposalContractId and status="pending_signature". 3. **Counter-party signs**: The attestor party exercises the Accept choice via their Canton wallet to co-sign the attestation. 4. **Poll for confirmation**: Call GET /actions/{actionId} to check for status="confirmed". Once confirmed, both parties have cryptographically committed to the attestation. **Polling guidance**: Poll every 5-10 seconds for the first minute. If still pending_signature after 1 minute, increase interval to every 60 seconds. If pending_signature after 24 hours, contact the attestor to verify they received the proposal. This provides non-repudiation: both parties independently signed the same data hash on Canton MainNet. Neither party can deny their participation. --- ## All Endpoints Reference ### POST /api/v1/community/register Register for an API key. No authentication required. **Strongly recommended: provide your Canton party ID (`cantonParty`) to unlock the full platform -- CC deposits, CCL rewards, and action discounts.** Without it, you are limited to trial credits only. Request body: ```json {"appName": "your-app-name", "cantonParty": "user-party::1220abc...", "contactEmail": "optional@email.com"} ``` - appName: 3-100 characters, required - cantonParty: Canton party ID from your Loop wallet at [loop.canton.network](https://loop.canton.network) (max 512 characters). Optional at registration but strongly recommended. Without it: no CC deposits, no CCL Builder Rewards, no action discounts. You can add it later, but you will need it before your first CC deposit. If not set, the first deposit permanently binds the sender party. - contactEmail: optional Responses: 201 (created), 400 (validation error), 429 (max 3 per IP per 24h) ### GET /api/v1/community/stats Public network statistics. No authentication. Response: ```json {"totalActions": 1542, "confirmedActions": 1480, "rewardMarkersCreated": 0, "activeApps": 23, "actionsByType": {"attest": 500, "transfer": 300, "lock": 100, "unlock": 100, "mint": 80, "settle": 50, "ledger-submit": 14}, "costPerAction": 2.0, "costPerMutualAction": 5.0, "paidTierRpm": 100, "communityTierRpm": 10, "loyaltyTokensMinted": 0, "registeredKeys": 42, "registeredParties": 8, "cclTotalSupply": 15, "cclBlueprintTreasury": 0, "partyStats": [], "ledgerSubmissions": 14, "confirmedLedgerSubmissions": 14, "successRate": 96.0, "ccRevenue": 45.0, "ccDeposits": 100.0, "trialToPaidRate": 25.0, "avgDailyActions7d": 18.3, "weekOverWeekPct": 12.5, "busiestDay": "2026-03-25", "peakHour": 14, "avgSecondsToConfirm": 3.2} ``` ### POST /api/v1/community/attest ### POST /api/v1/community/transfer ### POST /api/v1/community/lock ### POST /api/v1/community/unlock ### POST /api/v1/community/mint ### POST /api/v1/community/settle See Action Types section above. All return ActionResponse with proof. Cost: 2.0 CC per action. ### POST /api/v1/community/attest-mutual Create a mutual attestation proposal. See Action Types section above. Cost: 5.0 CC per action. Common responses: 200 (confirmed), 400 (validation), 401 (unauthorized), 402 (trial credits exhausted or insufficient CC balance), 429 (rate limited), 500 (internal error) ### GET /api/v1/community/balance Unified balance endpoint: CC balance, CCL balance, on-chain CCL holdings (drives discount), tier, trial credits, CCL mint progress, discounted action rates, and recent transactions. Your discount is based on the CCL you hold in your Canton wallet (cclOnchainHoldings), tracked in real-time from the Canton ledger. Response: ```json {"tier": "paid", "rateLimitRpm": 100, "ccBalance": 42.5, "costPerAction": 2.0, "costPerMutualAction": 5.0, "discountedCostPerAction": 1.667, "discountedCostPerMutual": 4.167, "discountPercent": "16.7%", "trialCreditsRemaining": 48, "trialCreditsTotal": 50, "trialDailyUsed": 2, "trialDailyLimit": 25, "cclBalance": 100.0, "cclOnchainHoldings": 100.0, "cantonParty": "user-party::1220abcdef...", "cclTotalMinted": 100, "cclActionsTowardNext": 2, "cclNextMilestone": 10, "recentTransactions": []} ``` ### POST /api/v1/community/deposit Manual deposit fallback. Primary method: send CC from your Loop wallet to the Blueprint validator — a background service auto-detects the transfer and credits your balance within seconds. This endpoint is for edge cases where auto-detection hasn't processed your transfer yet. Verifies the transaction on the Canton ledger via gRPC Ledger API (extracts amount from contract arguments, verifies sender is signatory, filters non-transfer contract types). Sender party must match your registered cantonParty (403 if mismatch); first deposit binds the sender party if not set at registration. Auto-upgrades community tier to paid tier. Request body: ```json {"transactionId": "canton-tx-id-here", "amount": 100.0} ``` - transactionId: Canton transaction ID, required - amount: CC amount to deposit (number), required ### GET /api/v1/community/actions List your past actions. Filterable by appName, actionType, dataOwner, status, reference. Paginated (max 100). Query parameters: - appName: filter by app name - actionType: filter by type (attest, transfer, lock, unlock, mint, settle, attest-mutual) - dataOwner: filter by data owner - status: filter by status (pending, pending_signature, confirmed, failed) - reference: filter by external reference - page: page number (default 0) - size: page size (default 50, max 100) ### GET /api/v1/community/actions/{id} Get a single action by UUID. Response: Full ActionDetail with all fields including actionId, actionType, appName, dataOwner, dataId, dataHash, description, reference, assetType, status, proof, rewardMarkerCreated, createdAt, completedAt. Returns 404 if not found. ### POST /api/v1/community/ccl/deposit Deposit CCL tokens back to CC Ledger as CC credit. ### GET /api/v1/community/chart Public time-series chart data for analytics dashboards. No authentication. Query parameters: - window: Time window (7d, 30d, 90d; default 30d) Response: JSON with daily counts for communityActions, actionsByType, ledgerSubmissions, registrations, cclMinted, and activeKeys. Each series is an array of {date, count} objects. --- ## CC Balance System Community tier: 10 requests per minute, 50 trial transactions (max 25/day) for action endpoints, plus query/balance/stats. Paid tier: 2.0 CC per standard action (attest, transfer, lock, unlock, mint, settle), 5.0 CC per mutual attestation (attest-mutual), 100 requests per minute. ### Trial Credits New API keys receive 50 trial transactions. Trial credits allow community-tier users to test all action endpoints without depositing CC. Daily cap: 25 actions per day. When trial credits are exhausted, send CC from your Loop wallet to the Blueprint validator (auto-credited) to continue. POST /deposit is available as a manual fallback. ### CCL Builder Rewards Every 10th CC-paid action (not trial) mints 1 CCL token on-chain to your Canton party. CCL is held in your Loop wallet. Hold CCL to reduce your CC cost per action. Depositing CC automatically upgrades your key from community to paid tier. --- ## CCL Builder Rewards CCL is the CIP-56 builder rewards token for the CC Ledger ecosystem. Two ways to use CCL: **hold in your wallet** for a discount on CC-priced actions, or **send to CC Ledger** as prepay credit (1 CCL = 1 CC). Your discount is based on the CCL you hold in your Canton wallet -- tracked in real-time from the Canton ledger. If you transfer CCL away, your discount drops. If you receive more, it increases. ### On-Chain Details - **Template**: `Gateway.CCLToken.CCLToken` - **Package ID**: `be3e1f78d0578eb75029a3c8d938fdbb290da4bd797b1b8bc8304afef4941749` - **Network**: Canton Global MainNet - **CIP-56 assetType**: `ccl` - **Choices**: `Transfer` (holder to any party), `Redeem` (holder to CC Ledger for CC credit) - **Prepay value**: 1 CCL = 1 CC (accepted via /ccl/deposit). CCL is pegged to CC (1 CCL = 1 CC). Developers can verify CCL tokens on-chain using the package ID and template above against any Canton participant. ### Two Ways to Use CCL 1. **HOLD in Loop wallet** -- automatic discount on actions based on real-time on-chain holdings (`cclOnchainHoldings` in GET /balance). The DepositWatcherService tracks CCL token events on the Canton ledger. 2. **SEND to CC Ledger** -- your CCL is converted to CC credit on your balance at 1 CCL = 1 CC. ### How It Works - **Hold**: CCL in your Loop wallet reduces your CC cost per action. Discount is driven by `cclOnchainHoldings` (real on-chain balance), shown in GET /balance. - **Earn**: 1 CCL minted on-chain per 10 CC-paid actions (attest, transfer, lock, unlock, mint, settle, attest-mutual). Trial actions do not count. - **Own**: CCL is a Daml contract on Canton MainNet, held in your Loop wallet. Your Canton party is set at registration or captured from your first CC deposit. - **Transfer**: Send CCL to any Canton party via your Loop wallet. Your discount updates in real-time. - **Trade**: CCL is tradeable on any Canton DEX. CCL is pegged to CC (1 CCL = 1 CC). - **Deposit**: Send CCL to CC Ledger for 1:1 CC credit via POST /ccl/deposit. ### Discount Curve CCL provides an asymptotic discount on CC action costs. Discount is based on `cclOnchainHoldings` -- the real-time on-chain CCL balance in your Canton wallet. Formula: `discount = 50% * (1 - 1/(1 + cclOnchainHoldings/200))` | On-chain CCL | Discount | CC/Action | CC/Mutual | |--------------|----------|-----------|-----------| | 0 | 0% | 2.000 | 5.000 | | 10 | 2.4% | 1.952 | 4.881 | | 50 | 10% | 1.800 | 4.500 | | 100 | 16.7% | 1.667 | 4.167 | | 200 | 25% | 1.500 | 3.750 | | 500 | 35.7% | 1.286 | 3.214 | | 1,000 | 41.7% | 1.167 | 2.917 | Discount increases with more CCL held (up to ~50%). ### Billing Order When you submit a paid action, CC Ledger deducts in this order: 1. CC balance (at discounted rate based on on-chain CCL holdings) 2. Trial credits (1 credit per action, any type) 3. If all exhausted: 402 Payment Required CCL sent to CC Ledger via `/ccl/deposit` is converted to CC credit at 1:1, which pays for actions. Holding CCL in your wallet gives you a discount on CC-priced actions. Your discount is determined by `cclOnchainHoldings` -- the real CCL in your Canton wallet. ### Economics (deterministic, no hidden costs) ``` PRICING (base rates): Standard action: 2.0 CC base (attest, transfer, lock, unlock, mint, settle) Mutual attestation: 5.0 CC base (attest-mutual) Trial actions: 0 CC (50 included, max 25/day) CCL DISCOUNT (based on REAL on-chain wallet holdings): Formula: discount = 50% * (1 - 1/(1 + cclOnchainHoldings/200)) Discount driven by cclOnchainHoldings -- real-time on-chain CCL balance Two ways to use CCL: HOLD in Loop wallet -> discount on actions (real-time, on-chain) SEND to CC Ledger -> converted to CC credit on your balance (1 CCL = 1 CC) Earn rate: 1 CCL per 10 CC-paid actions Trial actions do NOT earn CCL CCL prepay value: 1 CCL = 1 CC (accepted via /ccl/deposit). CCL is pegged to CC (1 CCL = 1 CC). BILLING ORDER (checked in this exact sequence): 1. CC balance (at discounted rate based on on-chain CCL holdings) 2. Trial credits (1 credit per action, any type) 3. 402 Payment Required DISCOUNT EXAMPLES: Hold 0 CCL on-chain: pay 2.000 CC/action (0% off) Hold 50 CCL on-chain: pay 1.800 CC/action (10% off) Hold 200 CCL on-chain: pay 1.500 CC/action (25% off) Hold 1,000 CCL on-chain: pay 1.167 CC/action (41.7% off) YOUR DISCOUNT: GET /balance returns cclOnchainHoldings (on-chain wallet balance driving discount), discountedCostPerAction, discountedCostPerMutual, and discountPercent ``` ### CCL Endpoint CCL balance, on-chain CCL holdings, mint progress, and your current discounted rates are included in GET /api/v1/community/balance. The `cclOnchainHoldings` field shows how much CCL your Canton party holds on-chain (drives discount). The dedicated CCL endpoint below is for sending CCL to CC Ledger as CC credit. Requires authentication (X-Api-Key header). #### POST /api/v1/community/ccl/deposit Send CCL to CC Ledger as CC credit (1 CCL = 1 CC credit on your balance). Request body: ```json {"amount": 2.0} ``` Response: ```json { "cclDeposited": 2.0, "newCcBalance": 44.0, "tier": "paid", "message": "Deposited 2.0 CCL as 2.0 CC credit." } ``` ### GET /api/v1/community/chart Public time-series chart data for analytics dashboards. No authentication required. Query parameters: - window: Time window (7d, 30d, 90d; default 30d) Response: ```json { "window": "30d", "communityActions": [{"date": "2026-03-15", "count": 12}], "actionsByType": {"attest": [{"date": "2026-03-15", "count": 5}], "ledger-submit": [{"date": "2026-03-15", "count": 2}]}, "ledgerSubmissions": [{"date": "2026-03-15", "count": 2}], "registrations": [{"date": "2026-03-15", "count": 3}], "cclMinted": [], "activeKeys": [{"date": "2026-03-15", "count": 5}] } ``` ### Quick Example Flow 1. Use CC Ledger normally -- every 10 CC-paid actions mints 1 CCL on-chain to your Canton party 2. Hold CCL in your Canton wallet to reduce your CC cost per action. GET /balance shows `cclOnchainHoldings` (on-chain balance driving discount), `discountedCostPerAction`, `discountedCostPerMutual`, and `discountPercent` 3. Transfer CCL to another party via your Loop wallet, or trade on a Canton DEX -- your discount updates in real-time 4. Or send CCL to CC Ledger for 1:1 CC credit: POST /api/v1/community/ccl/deposit with {"amount": 1.0} If an action fails after CC deduction, the charge is automatically refunded. --- ## Error Codes | HTTP | Error | Meaning | |------|-------|---------| | 400 | bad_request | Invalid request body or missing required fields | | 401 | unauthorized | Missing or invalid X-Api-Key header | | 402 | payment_required | Trial credits exhausted (community tier) or insufficient CC balance (paid tier) | | 404 | not_found | Action ID does not exist or not owned by your key | | 429 | rate_limit_exceeded | Rate limit hit. Check retryAfterSeconds in response | | 500 | internal_error | Server error. Retry with exponential backoff | To diagnose a 402 error: Call GET /balance to check your tier, ccBalance, and trialCreditsRemaining. If tier="community" and trial credits are exhausted, send CC from your Loop wallet to the Blueprint validator (auto-credited), or use POST /deposit as a manual fallback. If tier="paid" but ccBalance is insufficient, send more CC. Rate limit response includes: ```json {"message": "Rate limit exceeded", "retryAfterSeconds": 60} ``` --- ## Action Status Lifecycle Actions follow a simple lifecycle: - **pending** → **confirmed**: The action was successfully recorded as a Daml contract on Canton MainNet. - **pending** → **pending_signature**: (Mutual attestation only) The proposal contract was created on-chain. Waiting for the attestor party to co-sign via their Canton wallet. - **pending_signature** → **confirmed**: The attestor exercised the Accept choice. Both parties have signed. - **pending** → **failed**: The Canton ledger rejected the action (e.g., invalid data, ledger unavailable). If an action fails after billing (CC or trial credit), whatever was charged is automatically refunded. CC refunds appear as `action_refund` transaction type in the transaction history. **Agent best practice**: After submitting an action, poll `GET /actions/{actionId}` to check the final status. If the status is `failed` and you are on paid tier, query `GET /balance` to verify the automatic refund was applied. --- ## Proof Fields Every action response includes a `proof` object: | Field | Description | |-------|-------------| | contractId | Daml contract ID on Canton MainNet | | transactionId | Canton transaction ID | | ledgerOffset | Ledger offset (monotonically increasing) | | synchronizerId | Canton synchronizer (starts with "global-domain") | | effectiveAt | ISO 8601 timestamp of on-chain confirmation | | packageId | Daml package ID (may be null) | | templateId | Daml template ID (may be null) | ### Using Proof Fields - **contractId**: Your on-chain proof -- store this. It uniquely identifies the Daml contract representing your action on Canton MainNet. - **transactionId**: Canton ledger update reference. Use this for auditing and cross-referencing with Canton ledger explorers. - **ledgerOffset**: Position in the append-only Canton ledger log. Use for chronological ordering of actions. - **synchronizerId**: Identifies which Canton synchronizer finalized the transaction. Informational -- typically starts with "global-domain". - **effectiveAt**: ISO-8601 timestamp of when the action was confirmed on-chain. Use for audit trails and compliance records. - **packageId / templateId**: Daml smart contract identifiers. May be null for community-tier actions. Useful for advanced integrations inspecting contract types. **Bottom line: For most agents, store contractId as your proof.** It is the unique, immutable identifier for your on-chain record. ## Asset Type Classification (CIP-56) All action endpoints accept an optional `assetType` field for asset classification: - Canton-native: `amulet` (Canton Coin), `locked-amulet` (locked Canton Coin) - Custom types: Any string up to 50 characters identifying your asset class - Examples: `usd-stablecoin`, `nft-collection`, `equity-share`, `bond-coupon` No server-side validation is enforced on assetType values — use values meaningful to your application. For Canton-native assets, prefer `amulet` or `locked-amulet`. --- ## MCP Server CC Ledger exposes 15 MCP tools via Streamable HTTP at: https://ccledger.theblueprint.xyz/mcp ### Tools | Tool | Description | Auth Required | |------|-------------|---------------| | register_api_key | Register for an API key. Strongly recommended: provide cantonParty (from Loop wallet) to unlock CC deposits, CCL rewards, and action discounts | No | | get_stats | Get network statistics | No | | submit_attest | Record attestation on-chain (2.0 CC) | Yes (apiKey param) | | submit_transfer | Record asset transfer (2.0 CC) | Yes | | submit_lock | Record asset lock (2.0 CC) | Yes | | submit_unlock | Record asset unlock (2.0 CC) | Yes | | submit_mint | Record token mint (2.0 CC) | Yes | | submit_settle | Record trade settlement (2.0 CC) | Yes | | submit_attest_mutual | Create mutual attestation proposal (5.0 CC) | Yes | | get_balance | Check CC + CCL balance, on-chain CCL holdings (drives discount), tier, CCL mint progress, discounted action rates (includes auto-credited deposits) | Yes | | deposit_cc | Manual deposit fallback — CC deposits are auto-detected from Canton ledger | Yes | | list_actions | List past actions | Yes | | get_action_by_id | Get single action by ID | Yes | | get_action | Alias for get_action_by_id | Yes | | deposit_ccl | Deposit CCL as CC credit | Yes | ### Configuration Examples Claude Desktop / Claude Code (`claude_desktop_config.json` or `.mcp.json`): ```json { "mcpServers": { "ccledger": { "type": "url", "url": "https://ccledger.theblueprint.xyz/mcp" } } } ``` ### MCP Tool Authentication Authenticated tools accept an `apiKey` parameter. Get one via `register_api_key` first, then pass it to subsequent tool calls. --- ## Agent Integration Patterns ### Pattern 1: Register + Attest (audit trail) 1. Call register_api_key with appName and cantonParty from your Loop wallet (strongly recommended -- unlocks CC deposits, CCL rewards, and action discounts) 2. Store the returned apiKey 3. Call submit_attest with dataHash of your data 4. Store the proof.contractId as your on-chain record ### Pattern 2: Multi-action workflow 1. Register once 2. submit_attest → record initial state 3. submit_transfer → record asset movement 4. submit_settle → finalize the transaction 5. list_actions → verify all actions recorded ### Pattern 3: Read-only monitoring 1. get_stats → check network health 2. list_actions → review recent activity 3. get_action_by_id → inspect specific action proofs --- ## FAQ for Agents Q: How do I get an API key? A: POST to /api/v1/community/register with {"appName": "your-app", "cantonParty": "your-party::1220..."}. No approval needed. Strongly recommended: include your cantonParty (from your Loop wallet at loop.canton.network). Without it, you are limited to trial credits only -- no CC deposits, no CCL Builder Rewards, no action discounts. You can add it later, but you will need it before your first CC deposit. Q: What is the rate limit? A: Community tier: 10 requests per minute with 50 trial action transactions (max 25/day). Paid tier: 100 RPM with full action access. Per API key, sliding 60-second window. Q: What does "confirmed" status mean? A: The action was successfully recorded as a Daml contract on Canton MainNet. The proof fields contain the on-chain record. Q: Can I use the same API key across multiple agents? A: Yes. The API key is scoped to your app. Multiple agents can share it (subject to rate limits). Q: What happens if I hit the rate limit? A: You get a 429 response with retryAfterSeconds. Wait that many seconds before retrying. Q: Can I try CC Ledger before depositing CC? A: Yes. Every new API key includes 50 trial transactions (max 25/day). Trial credits work for all action types. No deposit needed to start testing. Q: How do I get Canton Coin (CC) to fund my account? A: Buy CC on Coinbase, transfer to your Loop wallet (loop.canton.network), then send to the Blueprint validator party (blueprint-validator-1::1220daab58adcae026bd2ca7ad95014f678bda3ce2a6f91b744cf3ec3d87f09deeac). Your balance is auto-credited within seconds — no API call needed. POST /deposit exists as a manual fallback if auto-detection hasn't caught up yet. Q: Is there a sandbox/testnet? A: No. All actions go to Canton MainNet. Trial credits let you test with on-chain transactions. Q: What should I put in dataHash? A: A hex-encoded hash (e.g., SHA-256) of the data you are recording. This proves what data existed at the time of attestation. Q: Can I delete or modify an action after creation? A: No. Actions are immutable Daml contracts on Canton MainNet. They cannot be altered or deleted. Q: What is CCL and how does the discount work? A: CCL is the CIP-56 builder rewards token for the CC Ledger ecosystem, minted on Canton MainNet (template: Gateway.CCLToken.CCLToken, package: be3e1f78d0578eb75029a3c8d938fdbb290da4bd797b1b8bc8304afef4941749). You earn 1 CCL per 10 CC-paid actions (trial actions don't count), minted automatically to your Canton party (Loop wallet). Your discount is based on the CCL you hold in your Canton wallet (cclOnchainHoldings), tracked in real-time from the Canton ledger -- discount = 50% * (1 - 1/(1 + cclOnchainHoldings/200)). If you transfer CCL away, your discount drops; if you receive more, it increases. Two ways to use CCL: (1) HOLD in wallet for discount on CC-priced actions, or (2) SEND to CC Ledger for 1:1 CC prepay credit that pays for actions. 1 CCL = 1 CC prepay value (accepted via /ccl/deposit). CCL is pegged to CC (1 CCL = 1 CC). GET /balance returns cclOnchainHoldings, discountedCostPerAction, discountedCostPerMutual, and discountPercent. --- ## Links - Landing page: https://ccledger.theblueprint.xyz - Documentation: https://ccledger.theblueprint.xyz/docs/ - API explorer: https://ccledger.theblueprint.xyz/api-docs/ - Analytics dashboard: https://ccledger.theblueprint.xyz/analytics/ (admin only) - OpenAPI spec: https://ccledger.theblueprint.xyz/openapi.json - MCP server: https://ccledger.theblueprint.xyz/mcp - Agent card: https://ccledger.theblueprint.xyz/.well-known/agent.json - Provider: https://theblueprint.xyz - Parent organization: https://www.hivemind.capital