Reading Ledger State Through the Walley Ledger API Proxy

The ledgerApi method lets your dApp read ledger state on behalf of the connected user. It forwards a Canton JSON Ledger API request through Walley’s authenticated, read-only proxy and returns the upstream response. This implements the CIP-0103 ledgerApi provider method. Unlike prepareExecute, ledgerApi does not open a popup and does not submit transactions. It’s a read path that runs against the user’s existing session token.

The proxy itself is plain HTTPS. If you want to call it without the SDK, or from outside the browser, see the HTTP API.

Making a request

const { response } = await provider.request({
  method: "ledgerApi",
  params: {
    requestMethod: "GET",
    resource: "/v2/state/active-contracts",
  },
});

const data = JSON.parse(response);

Parameters

Field	Type	Description
`requestMethod`	string	The HTTP method for the upstream Ledger API call, e.g. `"GET"` or `"POST"`.
`resource`	string	The Ledger API path, e.g. `/v2/state/active-contracts`. A leading slash is optional.
`body`	string (optional)	A JSON string request body. When present, the proxy sends `Content-Type: application/json`.

Result

// { response: string }

The response is the raw upstream body as a string. Parse it with JSON.parse for JSON endpoints.

Example with a body

const { response } = await provider.request({
  method: "ledgerApi",
  params: {
    requestMethod: "POST",
    resource: "/v2/state/active-contracts",
    body: JSON.stringify({ filter: { filtersByParty: {} }, verbose: false }),
  },
});

Authentication & tokens

The proxy authenticates with the short-lived access token issued when the user connected. You don’t manage the token directly (the SDK attaches it automatically), but you do need to handle expiry.

Access tokens are short-lived. When a token has expired, a ledgerApi call throws providerErrors.unauthorized. Recover by calling connect again to refresh the session, then retry the request.

import { providerErrors } from "@canton-network/core-rpc-errors";

async function readLedger(params) {
  try {
    return await provider.request({ method: "ledgerApi", params });
  } catch (err) {
    if (err.code === providerErrors.unauthorized().code) {
      await provider.request({ method: "connect" }); // refresh session
      return provider.request({ method: "ledgerApi", params });
    }
    throw err;
  }
}

Proxy origin

The wallet names the proxy host in its connect response. The SDK checks that host before attaching the token: by default it allows the wallet origin, an https sibling subdomain (walley.cc to api.walley.cc), and loopback in development. Narrow it with allowedApiOrigins, either an origin list or a predicate. Pass a list if your wallet host sits on a multi-label public suffix such as example.co.uk, which the default reads as two labels.

new WalleyAdapter({ allowedApiOrigins: ["https://api.walley.cc"] });
new WalleyAdapter({ allowedApiOrigins: (url) => url.hostname.endsWith(".walley.cc") });

Errors

Condition	Error
Not connected / no access token in session	`rpcErrors.internal`
Proxy host outside the permitted set	`rpcErrors.internal` (no request is sent)
Session token expired (HTTP 401)	`providerErrors.unauthorized` (reconnect and retry)
Transport failure reaching the proxy	`rpcErrors.internal`
Upstream returns a non-2xx status	`rpcErrors.internal`, with the status and body in the message

When to use it

Use ledgerApi to read contracts and ledger state. No popup, and no fee.
Use prepareExecute / prepareExecuteAndWait to write. These require user approval in a popup.

Overview

Typescript SDK (dApp)

Python SDK

HTTP API

gRPC API

Reading Ledger State Through the Walley Ledger API Proxy

Making a request

Parameters

Result

Example with a body

Authentication & tokens

Proxy origin

Errors

When to use it

​Making a request

​Parameters

​Result

​Example with a body

​Authentication & tokens

​Proxy origin

​Errors

​When to use it

Making a request

Parameters

Result

Example with a body

Authentication & tokens

Proxy origin

Errors

When to use it