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:
| Endpoint | Use Сase |
|---|---|
GetActiveContracts | Stream active contracts for the authenticated party. |
GetUpdates | Stream ledger updates from an offset, for example, to track transaction confirmations. |
Unary queries
Use the unary query RPCs for point-in-time ledger reads.Endpoints:
| Endpoint | Use Сase |
|---|---|
GetLedgerEnd | Get the current ledger end offset. |
GetBalances | Fetch token balances, including CIP-56 holdings and Canton Coin. |
GetPreapprovals | Retrieve transfer preapproval contracts. |
GetDsoRates | Read CC/USD rate and current round data. |
GetSettlementContracts | Discover on-chain DVP proposal and settlement contracts. |
GetServiceInfo | Fetch provider service metadata and capability information. |
GetAmulets | Retrieve unlocked amulet contracts and amounts. |
GetPrepaidTrafficBalance | Read the remaining prepaid traffic balance for the authenticated party. |
Onboarding
The onboarding flow is separate from normal JWT-authenticated access.Endpoints:
| Endpoint | Use Сase |
|---|---|
GetAgentConfig | Get an unauthenticated agent configuration template. |
RegisterAgent | Register an agent on the waiting list with an Ed25519-signed request. |
GetOnboardingStatus | Poll onboarding progress with an Ed25519-signed request. |
SubmitOnboardingSignature | Submit the onboarding multihash signature. |
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.
SDK Interaction Flow
Read more about transaction mechanics in Silvana.
Endpoints:
| Endpoint | Use Сase |
|---|---|
PrepareTransaction | Build a transaction and return the hash and prepared payload to sign locally. |
ExecuteTransaction | Submit the signed transaction for execution. |
PreparePayFee | Build a fee-payment transaction and return the hash and prepared payload to sign locally. Used as the fee leg for DvP, multicall, and other authenticated flows. |
ExecutePayFee | Submit the signed fee-payment transaction. Pairs with PreparePayFee. |
Faucet
UseRequestFaucet 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:
| Endpoint | Use Сase |
|---|---|
requestFaucet | Request CC or CIP-56 tokens from the faucet, where enabled. |
ListFaucetInstruments | Discover which token instruments the faucet currently supports in the active environment. |
Example flow
A typical Ledger Gateway flow looks like this:- Call
GetAgentConfigto load the initial onboarding template. - Call
RegisterAgentand pollGetOnboardingStatus. - Submit the required onboarding signature with
SubmitOnboardingSignature. - Call
GetBalancesorRequestFaucetto initialize working balances where needed. - Call
PrepareTransaction, sign the returned hash locally, then callExecuteTransaction. - Use
GetLedgerEndandGetUpdatesto monitor confirmation and downstream effects.