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 }>
getInstruments()	None	Promise<InstrumentListPayload>
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 }	Promise<TransferStatusResponsePayload>
on()	event: T, cb: Listener<C8EventByType<T>>	() => boolean

---

Constructor

Creates a new wallet provider instance.

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.

connect(): Promise<void>

returns · Promise<void>

Resolves when the user approves the connection.

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.

disconnect(): Promise<void>

---

status

Returns the current connection state.

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).

---

getInstruments

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

getInstruments(): Promise<InstrumentListPayload>

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

---

getAccounts

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

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.

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.

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

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 for the full example.

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 for the full event reference.

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.

checkTxStatusById(input): Promise<TransferStatusResponsePayload>

txId · string · required

Transaction ID returned by send().

returns · Promise<TransferStatusResponsePayload>

Current ledger status for the given transaction.