> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-references-canton-protobuf-histo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider API

> The low-level CIP-103 provider interface behind the dApp SDK.

The **Provider API** is the low-level interface the dApp SDK is built on. It follows the
[EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) request/event pattern and implements
[CIP-103](https://github.com/canton-foundation/cips/blob/main/cip-0103/cip-0103.md).

<Note>
  Most dApps should use the [high-level SDK](/sdks-tools/sdks/dapp-sdk/reference/sdk-methods).
  Use the Provider API directly only when building lower-level infrastructure or adapting an
  existing provider-based integration.
</Note>

## OpenRPC specifications

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

* **Sync API**: [openrpc-dapp-api.json](https://github.com/canton-network/wallet/blob/main/api-specs/openrpc-dapp-api.json)
* **Async API**: [openrpc-dapp-remote-api.json](https://github.com/canton-network/wallet/blob/main/api-specs/openrpc-dapp-remote-api.json)

## Getting a provider

After connecting, obtain the active CIP-103 provider from the SDK:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

| Method | Output | Description |
| - | - | - |
| `connect` | `ConnectResult` | Establishes a connection to the wallet. |
| `disconnect` | `void` | Closes the session between the client and the provider. |
| `isConnected` | `ConnectResult` | Reports connectivity without triggering login. |
| `status` | `StatusEvent` | Information about the connected wallet and network. |
| `getActiveNetwork` | `Network` | Details of the connected network. |
| `listAccounts` | `Account[]` | Lists all accounts the user has access to. |
| `getPrimaryAccount` | `Account` | Returns the account set as primary. |
| `signMessage` | `SignMessageResult` | Signs an arbitrary string message. |
| `prepareExecute` | `void` | Prepares, signs, and executes Daml commands. |
| `ledgerApi` | `string` | Proxies requests to the JSON Ledger API. |

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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`.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/sdks-tools/sdks/dapp-sdk/reference/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.

| Consideration | Sync API | Async API |
| - | - | - |
| Deployment | Client-side (browser extension, desktop) | Server-side, remote custody |
| User interaction | Direct, real-time | Via `userUrl` redirects |
| Blocking calls | Supported | Not supported |
| Transport | `postMessage`, in-app bridges | HTTPS, 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.

<Note>
  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.
</Note>

## Provider interface

Both variants are accessed through a `Provider` interface, following
[EIP-1193](https://eips.ethereum.org/EIPS/eip-1193):

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 SDK | Provider API |
| - | - | - |
| Level | High-level, convenient | Low-level, EIP-1193 style |
| Calls | Named functions (`sdk.connect()`) | `provider.request({ method })` |
| Events | `on*` / `off*` helpers | `on` / `removeListener` |
| Use when | Building a dApp | Building infrastructure or adapting existing provider code |

## Related

* [SDK Methods](/sdks-tools/sdks/dapp-sdk/reference/sdk-methods) — The high-level equivalents of these request methods.
* [Errors](/sdks-tools/sdks/dapp-sdk/reference/errors) — Standard error codes returned by the API.