libwallet library

Pure Dart client for the libwallet cryptocurrency wallet library.

Communicates with the Go library via direct FFI calls (NativeCallable.listener) — no sockets, no background-disconnection issues, no IPC.

Quick Start

import 'package:libwallet/libwallet.dart';

final client = LibwalletClient.initialize('/path/to/data');

// Check connectivity
await client.info.ping();

// List wallets
final wallets = await client.wallets.list();

// Create a wallet with progress tracking
await for (final event in client.wallets.create(
  name: 'My Wallet',
  keys: [
    KeyDescription.storeKey(storeKey),
    KeyDescription.remoteKey(remoteKey),
    KeyDescription.password('my-password'),
  ],
)) {
  switch (event) {
    case Progress(:final fraction):
      print('Progress: ${(fraction * 100).toStringAsFixed(1)}%');
    case Complete(:final value):
      print('Created wallet: ${value.id}');
  }
}

// Listen for requests (connect / sign prompts from dApps)
client.pendingRequests.listen((req) {
  // route to your approval UI
});

client.dispose();

Classes

Account: A blockchain account derived from a wallet.
AccountApi: Account CRUD and management.
AddNetworkRequest: dApp is asking to add a new network to the user's configuration (wallet_addEthereumChain). Approval saves the Network without activating it — distinct from ChainSwitchRequest which also changes the active network.
AddressFormat: One receive-address format available for a Bitcoin-family account on a specific chain. Returned by AccountApi.addressFormats.
AddressFormatsResult: Result of AccountApi.addressFormats: every receive-address shape the account can render on a specific Bitcoin-family chain.
AddressListing: Full HD address listing for a Bitcoin-family account.
AgentIdentity: Verified agent identity returned by ClawdWallet:pair.
Amount: Fixed-point decimal amount matching Go's wltobj.Amount.
ApprovalPreview: The result of SwapApi.buildApproval — everything a UI needs to render the "Approve <token> for <spender>" sheet plus the underlying Transaction to sign.
Asset: An asset (native currency or token) with balance information.
AssetApi: Asset listing and balance queries.
BalanceChange: Signed native-balance delta for one address across the simulation. Negative means the address lost balance (paid gas, sent value, etc.).
BalancesChangedEvent: Balances changed on the current account / network. Fired by the background poller every 60 s when anything differs from the previous snapshot (or immediately on app resume from background).
BitcoinIO: One input or output of a bitcoin-family transaction.
BitcoinUTXO: One unspent output entry returned by AccountApi.listUTXOs.
BitcoinUTXOList: The Account:listUTXOs response shape.
ChainMigration: One entry in a multi-chain promote/migrate request — which BIP32 derivation path on the source mnemonic wallet to migrate into a fresh MPC wallet. Built from ProbeActivityRow rows the user ticked.
ChainSwitchRequest: Every network switch comes through this single request type — whether the dApp explicitly asked for a specific chain (wallet_switchEthereumChain) or triggered it implicitly by calling an action method on a chain family that doesn't match the wallet's current network.
ClawdWalletApi: ClawdWallet pairing API.
Complete<T>: The completed result of a long-running operation.
ConnectRequest: dApp is requesting access to one or more of the user's accounts — eth_requestAccounts, wallet_requestPermissions, solana_connect, solana_requestAccounts, mpurse_getAddress.
Contact: A saved contact address.
ContactApi: Contact CRUD.
ContractLabel: One curated registry entry. Mirrors the Go-side wltcontract.Entry.
ContractsApi: Curated contract-label registry — known smart contracts (swap routers, marketplaces, lending pools, AMM vaults) baked into libwallet with stable display labels.
Crash: A crash event record.
CrashApi: Crash event listing and management.
CreateAgentWalletResult: Result of WalletApi.createAgentWallet.
CuratedToken: A vetted well-known token from the per-chain curated registry (e.g. USDT, USDC, WBTC on EVM; USDC, SOL, ChiefPussy on Solana).
DeviceShareEntry: One StoreKey-typed share's private key, paired with the WalletKey id that owns it. The host produces this from its platform keystore at confirm time (old device); the host consumes it from DeviceTransferImportResult.deviceShares at import time (new device).
DeviceTransferImportResult: Result of WalletApi.importFromDevice on the NEW device. The wallet has already been written to libwallet's local store by the time the future resolves; walletId is the canonical id the host uses to fetch the wallet via WalletApi.get.
DeviceTransferSession: One open device-transfer session, returned by WalletApi.exportToDevice. The host paints pairingCode as a QR code on the OLD device's screen; the user scans it on the NEW device which then calls WalletApi.importFromDevice with the same string.
DiscoveredToken: Result of Token:discoverToken.
Effect: One observable transfer the simulated tx will cause. Sourced from erigon's debug_traceCall callTracer — every ERC-20 Transfer / Approval event and every value-carrying CALL / CREATE at any depth.
FfiTransport: FFI-based transport that communicates with the Go library via direct function calls.
FiatQuote: Price quote data from CoinMarketCap or similar.
HdAddress: One address entry in an HD address listing.
InfoApi: Info endpoints: ping, version, paths, first_run, onboarding.
JsEvent: A JavaScript-originated event (chainChanged, accountsChanged, etc.).
KeyDescription: Describes a key used for signing operations.
LibwalletClient: Main client for interacting with the libwallet Go library.
LibwalletEvent: Base class for events pushed from libwallet.
LifecycleApi: Lifecycle management — informs libwallet about the host app's foreground/background/resumed state so long-running TSS operations can pause or resume safely.
LogEvent: A leveled log line emitted by the Go side of libwallet.
MaxSendableResult: Result of TransactionApi.maxSendable.
MessageSignRequest: Unified arbitrary-data signature request — covers personal_sign, eth_signTypedData*, solana_signMessage, mpurse_signMessage. NOT a transaction; typically used for login (Sign-In With Ethereum/Solana) or off-chain attestations.
NameApi: ENS (.eth) and SNS (.sol) name resolution.
NameResolution: Result of resolving an ENS or SNS name to a blockchain address.
Network: A blockchain network configuration.
NetworkApi: Network CRUD and management.
NextAddress: The next available HD address.
Nft: A non-fungible token.
NftApi: NFT listing and fetching.
NftAttribute: An NFT metadata attribute.
NftListing: Result of NftApi.list — NFTs plus the network/account context they belong to (so the caller can render them without re-fetching).
OnboardingState: Onboarding state returned by Info:onboarding.
OnlineStatusEvent: Network connectivity status changed.
PendingRequest: A Web3 request awaiting user action.
ProbeActivityRow: One row of Wallet:probeActivity output — a (chain, BIP variant) candidate with its derived address and on-chain activity flag.
Progress<T>: A progress update during a long-running operation — a single fraction between 0.0 (just started) and 1.0 (complete). The Go side reports fine-grained progress (e.g. one tick per safe prime found during ECDSA pre-param generation) mapped into a smooth 0..1 range so consumers can bind it directly to a progress bar without worrying about phases.
ProgressOr<T>: Represents either a progress update or a completed result.
QuoteAttempt: One provider's result from Swap:quotes. Exactly one of quote / error is populated:
RemoteKeyApi: RemoteKey management for 2FA recovery keys.
RemoteKeySession: Result of RemoteKeyApi.create / RemoteKeyApi.reshare.
RemoteKeyValidation: Result of RemoteKeyApi.validate — the new RemoteKey identifier.
RequestApi: Request approval/rejection for Web3 interactions.
RequestEvent: A Web3 request pending user action. The event carries the full request payload so the UI can render the prompt immediately without a follow-up Request/<id> round-trip.
ReservedAmount: One reservation line item: an amount held back from the balance that the user cannot send.
RpcTestResult: Result of NetworkApi.testRpc.
SignedMessage: Result of AccountApi.signMessage.
SigningKey: Key description with ID for transaction signing.
StoreKeyApi: StoreKey management for biometric/device-secured keys.
StoreKeyPair
SwapAvailability: Result of SwapApi.availability — feature-flag for the UI.
SwapQuote: A swap quote returned by SwapApi.quote.
SwapResult: The result of SwapApi.execute: a successfully broadcast swap.
SwapRouteHop: One hop in a multi-hop swap path.
SwapTokenRef: A token by address + decimals. Pass address: "NATIVE" for the chain's native currency (SOL on Solana, ETH on Ethereum).
Token: A registered token (ERC-20, SPL, etc.).
TokenApi: Token CRUD and discovery.
Transaction: A blockchain transaction.
TransactionApi: Transaction creation, validation, signing, and history.
TransactionSignRequest: Unified on-chain transaction-signing request — covers eth_sendTransaction, solana_signTransaction, solana_signAndSendTransaction, mpurse_signRawTransaction. The chain family is on chain; the original RPC method on method.
TransactionSimulation: Result of TransactionApi.simulate(...).
Transport: Abstract transport layer for communicating with the Go library.
TxHistoryUpdatedEvent: Fires after a background sweep inserted new on-chain transactions into the local Transaction table for the current (account, network). The payload reports how many rows were added; the host can then re-query client.transactions.list() to render them.
TxSignBalanceChange: Signed native-balance delta for one address — a row in TransactionSignRequest.balanceChanges. Negative = loss.
TxSignBitcoinIO: One input or output of a Bitcoin-family tx.
TxSignEffect: One observable transfer or approval — a row in TransactionSignRequest.effects.
TxSignWarning: Advisory finding about a sign request. Stable code values drive UI copy; severity is "info" / "warn" / "block".
UnknownEvent: An unrecognized event type.
UnknownPendingRequest: Catch-all for request types the Dart layer doesn't know about yet — lets consumers switch exhaustively without losing forward-compatibility when the Go side adds new types.
UnsignedTransaction: Typed builder for Transaction:validate and Transaction:signAndSend input.
VersionInfo: Full version metadata returned by InfoApi.versionInfo.
Wallet: A TSS wallet with distributed key management.
WalletApi: Wallet CRUD, backup, restore, reshare, and multi-create operations.
WalletBackupEntry: One entry in a wallet backup bundle — a single encrypted wallet file.
WalletConnectApi: WalletConnect v2 integration.
WalletInfo: Host-wallet identity block sent to libwallet via InfoApi.setWalletInfo.
WalletKey: An individual key share in a TSS wallet.
WalletKeyApi: Wallet/Key operations.
Warning: One advisory about a pending transaction surfaced by Transaction:simulate.
WarningSeverity: Severity bucket for a Warning.
WatchAssetRequest: dApp is asking the wallet to start tracking a custom token (wallet_watchAsset, EIP-747).
WcSession: A WalletConnect v2 session record (pairing, proposed, or active).
WcSessionProposal: A pending wc_sessionPropose delivered via the wc_session_propose event. Fields come straight from the broadcast event data.
WcSessionRequest: A pending wc_sessionRequest delivered via the wc_session_request event — a JSON-RPC call the dApp wants the wallet to handle.
Web3Api: Web3 JSON-RPC proxy + webview injection helper.
Web3Connection: A Web3 site connection to a wallet account.
Web3ConnectionApi: Web3/Connection management.

Enums

NetworkType

Constants

libwalletPackageVersion → const String

Exceptions / Errors

LibwalletException: Exception thrown when libwallet returns an error response.
PairingAgentUnreachableException: The agent could not be contacted within the timeout — typically Spot transport failure or the agent host being offline. Retry by asking the user to scan a fresh URL (the token survives unless the agent actually processed and consumed it; if in doubt, generate a new one).
PairingBadRequestException: The agent rejected the request as malformed. Indicates a contract mismatch — usually a libwallet / agent version drift. Updating either side normally resolves it.
PairingException: Common base for every pair() failure.
PairingIdentityMismatchException: The agent_spot_id in the response did not equal the agent parameter in the URL the user opened. Treat as a redirection attack and surface a loud, security-flavoured error — DO NOT proceed to keygen with the returned identity.
PairingTokenConsumedException: The token has already been used for a successful pair. Tokens are single-use; re-run clawdwallet pair for a fresh URL.
PairingTokenExpiredException: The token's 5-minute TTL elapsed between agent generation and the mobile attempting to pair. Re-run clawdwallet pair for a fresh URL.
PairingTokenInvalidException: The agent did not recognise the token — typo, wrong agent, or the agent process was restarted (tokens are in-memory only).
PairingURLMalformedException: The pairing URL didn't parse, used the wrong scheme, or was missing agent / token. No Spot traffic happens — this is caught locally.
SwapError: Typed error returned inside a QuoteAttempt when a provider couldn't quote. The code is stable across releases; apps should branch on it rather than the message (which is informational and locale-free English).

libwallet library

Quick Start

Classes

Enums

Constants

Exceptions / Errors

libwallet package

libwallet library