Ledger Service API

Canton Network access layer providing balance queries, token transfers, party management, and smart contract interactions on the Canton ledger.

Endpoints

Identity & Status

Method	Endpoint	Description
`GET`	`/api/ledger/identity`	Get ledger identity (ledger ID, participant ID, validator name, network)
`GET`	`/api/ledger/time`	Get current ledger time
`GET`	`/api/ledger/status`	Get ledger connection status (participant, synchronizer)
`GET`	`/api/ledger/stats`	Get ledger statistics (total contracts, parties, packages, domains)
`GET`	`/api/ledger/domains`	List connected synchronization domains
`GET`	`/api/ledger/organizations`	List organizations

Parties

Method	Endpoint	Description
`GET`	`/api/ledger/parties`	List tenant's parties (supports pagination via query params)
`POST`	`/api/ledger/parties`	Allocate new party on Canton
`GET`	`/api/ledger/parties/:partyId`	Get a party by ID
`PUT`	`/api/ledger/parties/:partyId`	Update party display name or annotations

Balance & Transfers

Method	Endpoint	Description
`GET`	`/api/ledger/balance/:partyId`	Get CC/Amulet balance for party
`POST`	`/api/ledger/transfer`	Transfer tokens between parties

Contracts

Method	Endpoint	Description
`GET`	`/api/ledger/contracts`	List contracts (supports pagination via query params)
`POST`	`/api/ledger/contracts`	Create contract on ledger
`GET`	`/api/ledger/contracts/:id`	Get contract by ID
`POST`	`/api/ledger/contracts/:id/exercise`	Exercise choice on contract
`POST`	`/api/ledger/contracts/:id/archive`	Archive a contract
`GET`	`/api/ledger/contracts/query`	Query contracts by party and template
`POST`	`/api/ledger/contracts/query`	Advanced filtered contract query (template IDs, status, domain, timestamps, payload search)

Packages

Method	Endpoint	Description
`GET`	`/api/ledger/packages`	List uploaded DAR packages (supports pagination)
`POST`	`/api/ledger/packages`	Upload a DAR package (base64-encoded)
`GET`	`/api/ledger/packages/:packageId`	Get package by ID
`DELETE`	`/api/ledger/packages/:packageId`	Delete a package
`GET`	`/api/ledger/packages/:packageId/templates`	Get templates defined in a package

Commands

Method	Endpoint	Description
`POST`	`/api/ledger/commands`	Submit a command to the Canton ledger (create, exercise, createAndExercise)

Transactions

Method	Endpoint	Description
`GET`	`/api/ledger/transactions`	Get transaction history for a party (supports pagination)
`POST`	`/api/ledger/transactions/query`	Advanced filtered transaction query (template IDs, event types, offsets)

Allocations

Method	Endpoint	Description
`GET`	`/api/ledger/allocations`	List Canton allocations for this tenant (supports pagination)
`POST`	`/api/ledger/allocations`	Create a new Canton allocation for an app
`GET`	`/api/ledger/allocations/:id`	Get allocation by ID
`PUT`	`/api/ledger/allocations/:id/status`	Update allocation status (active, suspended, revoked)
`DELETE`	`/api/ledger/allocations/:id`	Delete/revoke an allocation
`GET`	`/api/ledger/allocations/:id/parties`	List sub-parties under an allocation
`POST`	`/api/ledger/allocations/:id/parties`	Create a sub-party under an allocation

Usage

Method	Endpoint	Description
`GET`	`/api/ledger/usage`	Get usage statistics (filterable by app_id, start_date, end_date)

Get Balance

GET /api/ledger/balance/party::alice::12345
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "data": {
    "partyId": "party::alice::12345",
    "unlocked_cc": "985.50",
    "locked_cc": "14.50",
    "total_cc": "1000.00",
    "connected": true,
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Transfer Tokens

POST /api/ledger/transfer
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "from_party_id": "party::alice::12345",
  "to_party_id": "party::bob::67890",
  "amount": "100.00",
  "reference": "Payment for services"
}

Response

{
  "data": {
    "transactionId": "tx_abc123",
    "from_party_id": "party::alice::12345",
    "to_party_id": "party::bob::67890",
    "amount": "100.00",
    "status": "completed",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Allocate Party

POST /api/ledger/parties
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "displayName": "Treasury Wallet",
  "partyHint": "treasury"
}

Response

{
  "data": {
    "partyId": "party::treasury::54321",
    "displayName": "Treasury Wallet",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Parties

GET /api/ledger/parties
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "data": [
    {
      "partyId": "party::alice::12345",
      "displayName": "Alice",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "partyId": "party::treasury::54321",
      "displayName": "Treasury Wallet",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Contract

POST /api/ledger/contracts
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "templateId": "Tenzro.Token:Asset",
  "payload": {
    "owner": "party::alice::12345",
    "amount": "1000.00",
    "symbol": "USDC"
  }
}

Exercise Choice

POST /api/ledger/contracts/contract_abc123/exercise
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "choice": "Transfer",
  "argument": {
    "newOwner": "party::bob::67890",
    "amount": "100.00"
  }
}

Update Party

PUT /api/ledger/parties/party::treasury::54321
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "displayName": "Main Treasury",
  "annotations": {
    "role": "treasury",
    "department": "finance"
  }
}

Response

{
  "data": {
    "partyId": "party::treasury::54321",
    "displayName": "Main Treasury",
    "isLocal": true,
    "annotations": {
      "role": "treasury",
      "department": "finance"
    }
  }
}

Upload Package

POST /api/ledger/packages
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "name": "my-token-model",
  "version": "1.0.0",
  "dar_content": "<base64-encoded DAR file>"
}

Response

{
  "data": {
    "packageId": "pkg_abc123",
    "name": "my-token-model",
    "version": "1.0.0",
    "uploadedAt": "2024-01-15T10:30:00Z",
    "modules": ["Tenzro.Token", "Tenzro.Token.Types"]
  }
}

Get Package Templates

GET /api/ledger/packages/pkg_abc123/templates
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "data": [
    {
      "templateId": "Tenzro.Token:Asset",
      "moduleName": "Tenzro.Token",
      "templateName": "Asset",
      "choices": ["Transfer", "Split", "Merge", "Archive"],
      "signatories": ["owner"],
      "observers": ["regulator"]
    }
  ]
}

Submit Command

POST /api/ledger/commands
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "partyId": "party::alice::12345",
  "commands": [
    {
      "type": "create",
      "templateId": "Tenzro.Token:Asset",
      "payload": {
        "owner": "party::alice::12345",
        "amount": "500.00"
      }
    }
  ]
}

Response

{
  "data": {
    "success": true,
    "transactionId": "tx_cmd_456"
  }
}

Get Transaction History

GET /api/ledger/transactions?partyId=party::alice::12345&limit=50
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "transactions": [
    {
      "transactionId": "tx_abc123",
      "commandId": "cmd_001",
      "offset": "000000000000001234",
      "effectiveAt": "2024-01-15T10:30:00Z",
      "events": [
        {
          "type": "created",
          "contractId": "contract_xyz",
          "templateId": "Tenzro.Token:Asset",
          "payload": { "owner": "party::alice::12345", "amount": "1000.00" }
        }
      ]
    }
  ]
}

Filtered Contract Query

POST /api/ledger/contracts/query
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "party_id": "party::alice::12345",
  "template_ids": ["Tenzro.Token:Asset"],
  "status": "active",
  "domain_id": "global-domain",
  "created_after": "2024-01-01T00:00:00Z",
  "payload_search": "USDC"
}

Create Allocation

POST /api/ledger/allocations
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "appId": "my-defi-app",
  "appName": "My DeFi Application",
  "network": "devnet",
  "maxTransactionsPerDay": 10000,
  "maxContracts": 5000,
  "maxParties": 100
}

Response

{
  "data": {
    "id": "alloc_789",
    "appId": "my-defi-app",
    "appName": "My DeFi Application",
    "tenantId": "your-tenant-id",
    "participantId": "participant::abc",
    "partyId": "party::my-defi-app::99999",
    "network": "devnet",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Pagination

List endpoints support cursor-based pagination via query parameters:

GET /api/ledger/contracts?pageSize=25&pageToken=eyJvZmZzZXQiOjI1fQ==
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "items": [...],
  "nextPageToken": "eyJvZmZzZXQiOjUwfQ==",
  "totalSize": 150,
  "hasMore": true
}

Paginated list endpoints: /api/ledger/contracts, /api/ledger/parties, /api/ledger/packages, /api/ledger/transactions, /api/ledger/allocations.

Get Ledger Time

GET /api/ledger/time
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "data": {
    "currentTime": "2024-01-15T10:30:00Z",
    "ledgerEffectiveTime": "2024-01-15T10:30:00Z"
  }
}

Get Ledger Stats

GET /api/ledger/stats
X-API-Key: tnz_yourtenant_yoursecretkey
X-Tenant-Id: your-tenant-id

Response

{
  "data": {
    "totalContracts": 1250,
    "activeContracts": 890,
    "totalParties": 45,
    "totalPackages": 12,
    "connectedDomains": 2
  }
}

Canton Network Integration

The Ledger Service connects to Canton Network, a privacy-first enterprise blockchain. Key concepts:

Parties - Identities on the ledger that can own contracts
Contracts - Smart contract instances with state
Choices - Actions that can be exercised on contracts
Domains - Synchronization domains for privacy isolation

Error Codes

Code	Description
`PARTY_NOT_FOUND`	Party does not exist
`INSUFFICIENT_BALANCE`	Not enough balance for transfer
`CONTRACT_NOT_FOUND`	Contract does not exist or is archived
`INVALID_CHOICE`	Choice not available on contract
`DOMAIN_UNAVAILABLE`	Synchronization domain not available