> ## Documentation Index
> Fetch the complete documentation index at: https://docs.silvana.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Ledger Gateway API

# 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 <br />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 <br />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.

<CardGroup cols={2}>
  <Card title="SDK Interaction Flow" href="/sdk/reference/sdk-interaction-flow">
    Read more about transaction mechanics in Silvana.
  </Card>
</CardGroup>

### Endpoints:

| **Endpoint**         | **Use Сase**                                                                                                                                                           |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PrepareTransaction` | Build a transaction and return the hash and prepared payload to sign <br />locally.                                                                                    |
| `ExecuteTransaction` | Submit the signed transaction for execution.                                                                                                                           |
| `PreparePayFee`      | Build a fee-payment transaction and return the hash and prepared payload to sign <br />locally. Used as the fee leg for DvP, multicall, and other authenticated flows. |
| `ExecutePayFee`      | Submit the signed fee-payment transaction. Pairs with `PreparePayFee`.                                                                                                 |

## 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:

| **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:

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.