Documentation/canton-network-docs/SDKsdApp SDKAPI ReferenceView on canton-network-docs ↗
canton-network-docs/SDKsdApp SDKAPI Reference

Provider API

The Provider API is the low-level interface the dApp SDK is built on. It follows the EIP-1193 request/event pattern and implements CIP-103.
Most dApps should use the high-level SDK. Use the Provider API directly only when building lower-level infrastructure or adapting an existing provider-based integration.

​
OpenRPC specifications

The dApp API is specified in machine-readable OpenRPC documents:

​
Getting a provider

After connecting, obtain the active CIP-0103 provider from the SDK: 
await sdk.init()
await sdk.connect()
const provider = sdk.getConnectedProvider()
if (!provider) throw new Error('Not connected')

​
Methods

Every operation is a request({ method, params }) call. The methods mirror the SDK functions one-to-one.
MethodOutputDescription
connectConnectResultEstablishes a connection to the wallet.
disconnectvoidCloses the session between the client and the provider.
isConnectedConnectResultReports connectivity without triggering login.
statusStatusEventInformation about the connected wallet and network.
getActiveNetworkNetworkDetails of the connected network.
listAccountsAccount[]Lists all accounts the user has access to.
getPrimaryAccountAccountReturns the account set as primary.
signMessageSignMessageResultSigns an arbitrary string message.
prepareExecutevoidPrepares, signs, and executes Daml commands.
ledgerApistringProxies requests to the JSON Ledger API.
// Connect
const result = await provider.request<ConnectResult>({ method: 'connect' })

// Disconnect
await provider.request({ method: 'disconnect' })

// Status
const status = await provider.request<StatusEvent>({ method: 'status' })

// Is connected (no login)
const { isConnected } = await provider.request<ConnectResult>({
    method: 'isConnected',
})

// Active network
const network = await provider.request<Network>({ method: 'getActiveNetwork' })

// List accounts
const accounts = await provider.request<Account[]>({ method: 'listAccounts' })

// Primary account
const account = await provider.request<Account>({ method: 'getPrimaryAccount' })

// Sign a message
const signature = await provider.request<string>({
    method: 'signMessage',
    params: { message: 'Hello, Canton!' },
})

// Execute a transaction
await provider.request({
    method: 'prepareExecute',
    params: { commands: [/* ... */] },
})

// Call the Ledger API
const response = await provider.request<LedgerApiResponse>({
    method: 'ledgerApi',
    params: { requestMethod: 'GET', resource: '/v2/version' },
})

​
Events

Subscribe with on and clean up with removeListener. 
const handler = (status: StatusEvent) =>
    console.log(status.connection.isConnected)

provider.on('statusChanged', handler)
provider.removeListener('statusChanged', handler)
The provider emits statusChanged, accountsChanged, and txChanged. The Async API also emits connected and messageSignature. For payload shapes, see Events.

​
Sync and Async APIs

The dApp API comes in two variants for different wallet deployments:
  • Sync API targets wallets with direct access, such as browser extensions or desktop apps. Methods run in a standard request-response fashion.
  • Async API targets server-side or remote wallets, where operations that need user interaction cannot block. Those methods return a userUrl for the user to complete the action (for example login or transaction approval), and the result arrives later as an event.
ConsiderationSync APIAsync API
DeploymentClient-side (browser extension, desktop)Server-side, remote custody
User interactionDirect, real-timeVia userUrl redirects
Blocking callsSupportedNot supported
TransportpostMessage, in-app bridgesHTTPS, SSE
Key differences in the Async API:
  • connect returns { ...ConnectResult, userUrl } when no session exists; a connected event is emitted after login.
  • prepareExecute returns { userUrl }; a txChanged event is emitted after the prepare phase.
The dApp SDK implements the Sync API interface and relays to an Async API server internally, so dApp code written against the SDK works with both wallet types without changes.

​
Provider interface

Both variants are accessed through a Provider interface, following EIP-1193: 
interface Provider {
    request<T>(args: {
        method: string
        params?: unknown[] | Record<string, unknown>
    }): Promise<T>
    on<T>(event: string, listener: (...args: T[]) => void): Provider
    emit<T>(event: string, ...args: T[]): boolean
    removeListener<T>(event: string, listener: (...args: T[]) => void): Provider
}

​
SDK vs Provider API

dApp SDKProvider API
LevelHigh-level, convenientLow-level, EIP-1193 style
CallsNamed functions (sdk.connect())provider.request({ method })
Eventson* / off* helperson / removeListener
Use whenBuilding a dAppBuilding infrastructure or adapting existing provider code
  • SDK Methods — The high-level equivalents of these request methods.
  • Errors — Standard error codes returned by the API.