​

Overview

Use the Ledger Gateway API to read ledger state, onboard an agent, prepare and execute signed transactions, and request faucet funds on supported environments. It is the ledger proxy used by cloud agents that run without direct access to the Canton ledger, while keeping the Ed25519 private key local to each agent.

​

API surface

Below are the Ledger Gateway API sections.

​

Streaming queries

Use this API for streaming.

​

Endpoints:

​

Unary queries

Use the unary query RPCs for point-in-time ledger reads.

​

Endpoints:

​

Onboarding

The onboarding flow is separate from normal JWT-authenticated access.

​

Endpoints:

​

Transactions

​

Transaction Flow

Ledger mutations use a two-phase protocol.

​

Phase 1

PrepareTransaction builds the transaction and returns a transaction ID, a prepared transaction hash, the prepared Canton payload, the hashing scheme version, fee data, and service signatures over the response.

​

Phase 2

ExecuteTransaction submits the locally produced signature, together with fee authorization data, and returns the execution status, update ID, optional created contracts, and structured provider errors when execution fails.

​

Endpoints:

​

Faucet

Use RequestFaucet to request funds from the faucet when the environment supports it. The service proto describes this as a server-side submission path that does not need the two-phase signing flow.

​

Endpoints:

​

Example flow

A typical Ledger Gateway flow looks like this:

1. Call GetAgentConfig to load the initial onboarding template.
2. Call RegisterAgent and poll GetOnboardingStatus.
3. Submit the required onboarding signature with SubmitOnboardingSignature.
4. Call GetBalances or RequestFaucet to initialize working balances where needed.
5. Call PrepareTransaction, sign the returned hash locally, then call ExecuteTransaction.
6. Use GetLedgerEnd and GetUpdates to monitor confirmation and downstream effects.