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

# API reference

> Reference for the C8WalletProvider API in C8 Wallet SDK.

## Public API: `C8WalletProvider`

| Method | Parameters | Return Type |
| - | - | - |
| `connect()` | None | `Promise<void>` |
| `disconnect()` | None | `Promise<void>` |
| `status()` | None | `Promise<{ connected: boolean; walletVersion?: string }>` |
| `getContractsSetupState()` | `partyId?: string` | `Promise<PartyContractSetupResponse>` |
| `getInstruments()` | None | `Promise<InstrumentListPayload>` |
| `getActiveContracts()` | `input?: GetActiveContractsInput` | `Promise<ActiveContractsPayload>` |
| `getLedgerUpdates()` | `input?: GetLedgerUpdatesInput` | `Promise<LedgerUpdatesPayload>` |
| `getAccounts()` | `instrumentId?: string` | `Promise<AccountListPayload>` |
| `send()` | `input: SendInput` | `Promise<SubmitTransferResultPayload>` |
| `createSwapOffer()` | `input: CreateSwapOfferInput` | `Promise<SubmitTransferResultPayload>` |
| `signMessage()` | `message: string, partyId?: string` | `Promise<string>` |
| `signAndExecute()` | `input: SignAndExecuteInput` | `Promise<void>` |
| `checkTxStatusById()` | `input: { txId: string; partyId?: string }` | `Promise<TransferStatusResponsePayload>` |
| `on()` | `event: T, cb: Listener<C8EventByType<T>>` | `() => boolean` |

***

## Constructor

Creates a new wallet provider instance.

```ts theme={null}
new C8WalletProvider(config)
```

**dappUrl** `string`

URL of the dApp initiating the connection. Defaults to the current page origin.

**dappName** `string` *required*

Name of the dApp. Must match the name registered with the wallet.

**network** `string`

Canton network to connect to. Use `"devnet"`, `"testmainnet"`, or `"mainnet"`. Defaults to `"mainnet"`.

***

## connect

Opens the C8 Wallet popup and establishes the `postMessage` channel. The user sees a connection approval screen in the wallet.

```ts theme={null}
connect(): Promise<void>
```

**returns** `Promise\<void\>`

Resolves when the user approves the connection.

> [!NOTE]
>
> Call interactive methods from a user gesture, such as a button click, to avoid `POPUP_BLOCKED` errors.

***

## disconnect

Closes the wallet popup and tears down the `postMessage` channel. Emits the `disconnected` event.

```ts theme={null}
disconnect(): Promise<void>
```

***

## status

Returns the current connection state.

```ts theme={null}
status(): Promise<{ connected: boolean, walletVersion?: string }>
```

**connected** `boolean`

Whether the wallet is currently connected.

**walletVersion** `string`

Version of the connected wallet (only present when connected).

***

## getContractsSetupState

Returns the connected account's registration and validator-managed contract setup transactions, including all statuses.

```ts theme={null}
getContractsSetupState(partyId?: string): Promise<PartyContractSetupResponse>

interface PartyContractSetupResponse {
  partyId: string;
  contracts: ContractSetupItem[];
}

interface ContractSetupItem {
  id: number;
  code: string;
  partyId: string;
  commandId: string;
  contractId: string | null;
  status: string;
  submittedAt: string | null;
  completedAt: string | null;
}
```

**partyId** `string`

Connected account to query. Defaults to the primary account. The popup provider rejects an unknown party ID before sending a backend request.

**partyId** `string`

Party whose contract setup state you requested.

**contracts** `ContractSetupItem[]`

Setup transactions with their contract code, command ID, status, and contract ID. The contract ID and timestamps can be `null`. Status strings come from the backend.

After you connect, the popup provider queries the selected account's backend with its stored token. If your saved session lacks `validator.backendApiUrl` or an account token, disconnect and reconnect.

> [!NOTE]
>
> This response replaces the deprecated `RegisterStatusResponse`. Read the `contracts` array instead of the old `is...` flags. Embedded wallet hosts must return `PartyContractSetupResponse` for this RPC.

***

## getInstruments

Returns the list of Canton instruments available in the connected wallet.

```ts theme={null}
getInstruments(): Promise<InstrumentListPayload>

type InstrumentListPayload = {
  instruments: Array<{
    instrumentId: string
    name: string
    symbol: string
  }>
}
```

***

## getActiveContracts

Returns active contracts visible to the connected account. You can filter the Scanner active contract set by template or interface.

```ts theme={null}
getActiveContracts(input?: GetActiveContractsInput): Promise<ActiveContractsPayload>
```

**partyId** `string`

Account party ID. Defaults to the connected primary account. Direct provider requests can only use the primary account.

**templateIds** `string[]`

Template IDs to include.

**interfaceIds** `string[]`

Interface IDs to include.

**activeAtOffset** `string`

Nonnegative signed 64-bit ledger offset for a point-in-time snapshot. Pass the offset as a decimal string.

**includeCreatedEventBlob** `boolean`

Whether each contract should include its Base64-encoded created-event blob. Defaults to `false`.

**limit** `number`

Maximum number of rows to return. Must be a positive 32-bit integer. Defaults to `10000`.

**paginated** `boolean`

Whether Scanner should order rows by contract ID for pagination. Defaults to `true`.

**after** `string`

Contract ID after which Scanner should return rows. Pass the previous contract ID unchanged.

**returns** `Promise\<ActiveContractsPayload\>`

An array of Scanner contract rows.

```ts theme={null}
const contracts = await c8.getActiveContracts({
  templateIds: ["package-id:Module:Template"],
  includeCreatedEventBlob: true,
  limit: 10000,
});

console.log("Active contracts:", contracts);
```

***

## getLedgerUpdates

Returns one page of ledger updates visible to the connected account. Use the returned cursor to request the next page with the same filters.

```ts theme={null}
getLedgerUpdates(input?: GetLedgerUpdatesInput): Promise<LedgerUpdatesPayload>
```

**partyId** `string`

Account party ID. Defaults to the connected primary account. Direct provider requests can only use the primary account.

**templateIds** `string[]`

Template IDs to include.

**cursor** `string`

Cursor returned as `nextCursor` by the previous request. Pass it unchanged.

**eventType** `"created" | "exercised"`

Event type to include.

**consuming** `boolean`

Whether to include consuming or non-consuming exercise events.

**limit** `number`

Maximum number of nodes to return. Must be from `1` through `1000`. Defaults to `500`.

**nodes** `LedgerNode[]`

Ledger nodes in this page.

**nextCursor** `string`

Cursor for the next page, when more updates are available.

**bounds** `\{ floorOffset: number; headOffset: number \}`

Scanner's retained offset range, when available.

**gap** `\{ fromOffset: number; toOffset: number; reason?: string \}`

Lost history detected before or within the requested range, when present.

**complete** `boolean`

Whether this page reached Scanner's current fetch frontier. New updates can arrive later.

```ts theme={null}
const filters = {
  templateIds: ["package-id:Module:Template"],
  limit: 500,
};

const page = await c8.getLedgerUpdates(filters);
const nextPage = page.nextCursor
  ? await c8.getLedgerUpdates({ ...filters, cursor: page.nextCursor })
  : undefined;
```

> [!NOTE]
>
> An empty page can still return a new cursor. If `gap` is present, the result does not represent complete ledger history.

***

## getAccounts

Returns accounts and their holdings. If `instrumentId` is provided, filters to accounts holding that instrument.

```ts theme={null}
getAccounts(instrumentId?: string): Promise<AccountListPayload>

type AccountListPayload = {
  accounts: Array<{
    accountName?: string
    partyId: string
    publicKey: string
    validator: {
      id: string
      name: string
    }
    holdings: Array<{
      instrumentId: string
      balance: number
      balanceUsd: number
    }>
  }>
}
```

**instrumentId** `string`

Optional. Filters accounts to those holding this instrument.

**accountName** `string`

Optional display name for the account.

**partyId** `string`

Canton party identifier for the account.

**publicKey** `string`

Public key associated with the account.

**validator** `ValidatorInfo`

Validator assigned to the account as `{ id: string, name: string }`.

***

## send

Submits a transfer on the Canton ledger. Opens an approval screen in the wallet popup.

```ts theme={null}
send(input): Promise<SubmitTransferResultPayload>
```

**senderPartyId** `string` *required*

Canton `partyId` of the sender.

**instrumentId** `string` *required*

Asset to transfer.

**amount** `number` *required*

Transfer amount.

**receiverPartyId** `string` *required*

Canton `partyId` of the recipient.

**memo** `string`

Optional text memo attached to the transfer.

**metadata** `Record\<string, string\>`

Optional arbitrary key-value metadata.

**txId** `string`

Transaction ID assigned by the Canton ledger. Use it with `checkTxStatusById`.

***

## createSwapOffer

Creates a multi-leg swap offer and opens the wallet approval UI. Amounts in swap legs are decimal strings.

```ts theme={null}
createSwapOffer(input: {
  partyId: string;
  swap: MultiLegSwapSpecRequest;
  commandId?: string;
}): Promise<SubmitTransferResultPayload>
```

**partyId** `string` *required*

Party creating the swap offer.

**commandId** `string`

Optional idempotency key for the submission.

**swap.swapId** `string` *required*

Unique identifier for the swap.

**swap.acceptorPartyId** `string` *required*

Party allowed to accept the swap.

**swap.creatorLegs** `SwapLegRequest[]` *required*

Assets the creator provides. Each leg contains `receiver`, `instrument`, `amount`, `legId`, and an optional `reason`.

**swap.acceptorLegs** `SwapLegRequest[]` *required*

Assets the acceptor provides. Each leg uses the same shape as a creator leg.

**swap.creatorTransferLegs** `SwapTransferLegRequest[]` *required*

Additional transfer legs supplied by the creator. Pass an empty array when the swap has none.

**swap.settleBefore** `string` *required*

ISO 8601 timestamp after which the swap can no longer settle.

**swap.meta** `Record\<string, string\>` *required*

Application metadata for the swap. Pass an empty object when you have no metadata.

**txId** `string`

Transaction ID assigned after the wallet submits the swap offer.

See [Multi-leg swap offers](https://docs.cantor8.tech/wallet-sdk/transfer-types.md#multi-leg-swap-offers) for a complete example.

***

## signMessage

Asks the wallet to sign an arbitrary string. You can bind the request to a specific account by passing its party ID.

```ts theme={null}
signMessage(message: string, partyId?: string): Promise<string>
```

**message** `string` *required*

Message to show in the wallet approval UI and sign.

**partyId** `string`

Optional party whose account should sign the message.

**returns** `Promise\<string\>`

Signature string returned by the wallet.

***

## signAndExecute

Signs and executes custom DAML commands via the connected wallet. Use this for templates, choices, and contract workflows beyond the SDK's high-level methods. See [Transactions and signing](https://docs.cantor8.tech/wallet-sdk/transfer-types.md#sign-and-execute-custom-daml-commands) for the full example.

```ts theme={null}
signAndExecute(input): Promise<void>
```

**note** `string` *required*

Human-readable note shown to the user in the wallet UI.

**partyId** `string` *required*

The party submitting the command.

**commandId** `string` *required*

Unique idempotency key for this submission (e.g. a UUID).

**commandsJson** `string` *required*

JSON-serialized array of DAML commands (`CreateCommand`, `ExerciseCommand`, etc.).

**disclosedContracts** `string` *required*

JSON-serialized array of contracts disclosed to the participant to authorize the command.

***

## on

Subscribes to a wallet event. Returns an unsubscribe function. See [Events](https://docs.cantor8.tech/wallet-sdk/events.md) for the full event reference.

```ts theme={null}
on<T extends C8EventType>(event: T, cb: Listener<C8EventByType<T>>): () => boolean
```

**event** `string` *required*

Event type to subscribe to (e.g. `"connected"`, `"txChanged"`).

**cb** `Listener` *required*

Callback invoked with the typed event payload.

**returns** `() =\> boolean`

Unsubscribe function. Call it to remove the listener.

***

## checkTxStatusById

Polls the Canton ledger for the current status of a previously submitted transaction.

```ts theme={null}
checkTxStatusById(input): Promise<TransferStatusResponsePayload>
```

**txId** `string` *required*

Transaction ID returned by `send()`.

**partyId** `string`

Optional connected account whose backend and token the popup provider uses to check the transaction. Defaults to the primary account.

**returns** `Promise\<TransferStatusResponsePayload\>`

Current ledger status for the given transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.