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

# Walley Provider API Reference: Methods, Params, and Results

> Complete reference for the Walley dApp SDK provider: connect, disconnect, status, listAccounts, getPrimaryAccount, getActiveNetwork, signMessage, prepareExecute, and ledgerApi.

Every Walley action is invoked through the standard Canton `Provider` interface:

```ts theme={null}
provider.request({ method, params? })
```

Get a provider from the adapter with `new WalleyAdapter().provider()`, or through the dApp SDK discovery registry. Methods that need user approval (`connect`, `signMessage`, `prepareExecute`, `prepareExecuteAndWait`) open a Walley popup; the rest resolve locally from the persisted session.

<Note>
  Methods that require an existing connection — `getPrimaryAccount`, `getActiveNetwork`, `signMessage`, `prepareExecute`, `prepareExecuteAndWait`, and `ledgerApi` — throw if the wallet is not connected. Call `connect` first, or guard with `isConnected` / `status`.
</Note>

## Connection

### `connect`

Opens a popup where the user approves the connection. On success the session is persisted to `localStorage` and restored automatically on subsequent loads.

```ts theme={null}
const result = await provider.request({ method: "connect" });
// { isConnected: true, isNetworkConnected: true }
```

You can optionally have the wallet sign a message as part of the same approval — handy for proving control of the party during login. Pass `signMessage` in `params`; the base64 Ed25519 signature comes back on the result:

```ts theme={null}
const result = await provider.request({
  method: "connect",
  params: { signMessage: { message: "Sign in to Acme dApp" } },
});
// { isConnected: true, isNetworkConnected: true, signature: "<base64>" }
```

### `disconnect`

Clears the active session and removes it from `localStorage`. Returns `null`.

```ts theme={null}
await provider.request({ method: "disconnect" });
```

### `isConnected`

Returns a boolean for the current connection state without opening a popup.

```ts theme={null}
const connected = await provider.request({ method: "isConnected" });
// boolean
```

### `status`

Returns the full provider, connection, network, and session state without opening a popup.

```ts theme={null}
const status = await provider.request({ method: "status" });
// {
//   provider:   { id: "walley", providerType: "browser", userUrl: string },
//   connection: { isConnected: boolean, isNetworkConnected: boolean },
//   network?:   { networkId: string },
//   session?:   { accessToken: string, userId: string }
// }
```

## Accounts & network

### `listAccounts`

Returns an array of wallets. Contains a single entry when connected, and is empty when disconnected.

```ts theme={null}
const accounts = await provider.request({ method: "listAccounts" });
// Wallet[]
```

### `getPrimaryAccount`

Returns the connected wallet. Throws if not connected.

```ts theme={null}
const wallet = await provider.request({ method: "getPrimaryAccount" });
// {
//   primary: true,
//   partyId: string,
//   status: "allocated",
//   hint: string,            // the user's Party Hint, e.g. "walley-alice"
//   publicKey: string,       // base64 Ed25519 public key
//   namespace: string,       // public key fingerprint
//   networkId: string,
//   signingProviderId: "walley"
// }
```

### `getActiveNetwork`

Returns the network the wallet is connected to. Throws if not connected.

```ts theme={null}
const network = await provider.request({ method: "getActiveNetwork" });
// { networkId: string }
```

## Signing & transactions

### `signMessage`

Opens a popup for the user to sign an arbitrary message.

```ts theme={null}
const result = await provider.request({
  method: "signMessage",
  params: { message: "Hello from my dApp!" },
});
// SignMessageResult
```

### `prepareExecute`

Opens a popup for the user to review, sign, and submit Daml commands. Fire-and-forget — resolves to `null` once submitted.

```ts theme={null}
await provider.request({
  method: "prepareExecute",
  params: { commands: [{ type: "create", templateId: "...", argument: { /* ... */ } }] },
});
```

### `prepareExecuteAndWait`

Same as `prepareExecute`, but waits for the transaction to be committed and returns the result.

```ts theme={null}
const result = await provider.request({
  method: "prepareExecuteAndWait",
  params: { commands: [{ type: "create", templateId: "...", argument: { /* ... */ } }] },
});
// PrepareExecuteAndWaitResult
```

See [Transactions & Fees](/build/transactions) for command shapes and the fee model.

### `ledgerApi`

Forwards a read-only Canton JSON Ledger API request through the wallet's authenticated proxy. See [Ledger API](/build/ledger-api) for details.

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

## Error handling

The provider throws standard Canton JSON-RPC errors:

| Situation                                       | Error                                     |
| ----------------------------------------------- | ----------------------------------------- |
| Unknown method                                  | `rpcErrors.methodNotFound`                |
| Action requires a connection that isn't present | `rpcErrors.internal` ("Not connected")    |
| User closes the popup without approving         | `providerErrors.userRejectedRequest`      |
| Popup blocked by the browser                    | `rpcErrors.internal` ("Popup blocked…")   |
| Expired wallet session on a `ledgerApi` call    | `providerErrors.unauthorized` — reconnect |

## Sessions & persistence

* Sessions are stored in `localStorage` under a single key and restored automatically on the next page load.
* The stored session is scoped to your dApp's origin by the browser.
* Call `disconnect` to clear it. There is no server-side session to revoke from the dApp side — the user manages wallet-side access from within Walley.