API reference

Everything below is exported from the package root: import { ... } from "@cavos/kit".

`Cavos`

The high-level entry point. Most apps only use this.

`Cavos.connect(options): Promise<CavosWallet>`

Unified entry point. Pick a chain and a network environment; the kit resolves the concrete network (sepolia / solana-devnet for testnet, mainnet otherwise) and returns a chain-native wallet. The result is a discriminated union (wallet.chain), so execute() keeps each chain's native signature.

TypeScript

interface ConnectOptions {
  chain: "starknet" | "solana" | "stellar"; // returned wallet is discriminated by this
  network: "testnet" | "mainnet";      // resolves to the chain's concrete network
  appSalt: string;
  auth?: AuthProvider;                  // pass `auth` OR `identity`
  identity?: Identity;
  appId?: string;                       // hosted registry + (Starknet) recovery / (Solana, Stellar) relayer
  backendUrl?: string;                  // defaults to Cavos hosted services
  rpcUrl?: string;
  registry?: WalletRegistry;            // off-chain userId -> wallet map
  recovery?: RecoveryClient;            // device-approval relay (Starknet)
  createSigner?: (keyId: string) => Promise<DeviceSigner>; // native / tests
  // --- Starknet-only ---
  paymasterApiKey?: string;             // sponsors deploy + execute (required on Starknet)
  paymasterUrl?: string;
  classHash?: string;
  // --- Solana-only ---
  programId?: string;                   // device-account program override
  relayer?: SolanaRelayer;              // gasless sponsorship (defaults to hosted when appId set)
  feePayer?: Keypair;                   // self-funded fallback
  // --- Stellar-only (classic `G…` multisig) ---
  stellarRelayer?: StellarRelayer;      // gasless sponsorship (defaults to hosted when appId set)
  stellarSourceKeypair?: StellarKeypair;// self-funded source/fee-payer (advanced)
  stellarDeviceKey?: DeviceUnwrapKey;   // this device's ECDH unwrap key (defaults to persisted WebCrypto)
}

type CavosWallet = Cavos | CavosSolana | CavosStellar; // narrow on `wallet.chain`

chain === "starknet" → Cavos instance (see Starknet).
chain === "solana" → CavosSolana instance (see Solana).
chain === "stellar" → CavosStellar instance (classic G… multisig — see Stellar).

Instance members (Starknet)

Members on the Cavos instance (wallet.chain === "starknet"). The Solana counterpart is CavosSolana — see Solana.

Member	Description
`cavos.address: string`	The smart account address (deterministic).
`cavos.status: "ready" \| "needs-device-approval"`	Whether this device can operate the wallet.
`cavos.pendingRequestId: string \| null`	Device-addition request id when `status` is `needs-device-approval`.
`cavos.identity: Identity`	The authenticated identity.
`cavos.publicKey: DevicePublicKey`	This device's public key.
`cavos.execute(calls): Promise<{ transactionHash }>`	Sign + submit calls, gasless. Requires `status === "ready"`.
`cavos.signMessage(message): Promise<MessageSignature>`	Sign an arbitrary message off-chain with the device key (secp256r1). Uniform return across chains. See After sign-in.
`cavos.signTransaction(calls): Promise<StarknetSignedTransaction>`	Build + sign a multicall WITHOUT submitting. Single-use (binds to nonce + resource bounds).
`cavos.addSigner(pubkey): Promise<{ transactionHash }>`	Authorize another device's key on-chain.
`cavos.enrollPasskey(passkey, params): Promise<{ publicKey, transactionHash? }>`	Create a passkey + register it as an approver. Gasless, idempotent. See Passkeys.
`cavos.addApprover(pubkey): Promise<{ transactionHash? }>`	Register an already-enrolled passkey pubkey as an approver (idempotent). Use to share one passkey across chains.
`cavos.approveThisDeviceWithPasskey({ passkey, submit? }): Promise<{ transactionHash }>`	From a `needs-device-approval` browser, use a synced passkey to authorize this device.
`cavos.passkeyLeafForThisDevice(): Promise<{ leaf, nonce }>`	This device's passkey leaf + on-chain nonce (for batched / multi-chain approval).
`cavos.submitPasskeyApproval(assertion, leaves, leafIndex, nonce, submit?): Promise<{ transactionHash }>`	Submit `add_signer_via_passkey` with a shared assertion. Low-level; prefer `approveThisDeviceWithPasskey`.
`cavos.setupRecovery(code): Promise<{ transactionHash } \| undefined>`	Register a passphrase-derived backup signer. Idempotent. (Starknet only.)

`Cavos.recover(options): Promise<Cavos>`

Recover after losing every device using a saved recovery code. (Starknet path; Solana uses CavosSolana.recover. On Stellar you reconnect on the fresh device and call wallet.approveThisDeviceWithRecovery(code) — the recovery code unlocks the control key, which authorizes the new device's slot.)

TypeScript

interface RecoveryOptions {
  code: string;
  identity: Identity;
  network: "testnet" | "mainnet";
  appSalt: string;
  paymasterApiKey: string;
  appId?: string;
  backendUrl?: string;
  rpcUrl?: string;
  paymasterUrl?: string;
  classHash?: string;
  registry?: WalletRegistry;
  createSigner?: (keyId: string) => Promise<DeviceSigner>;
}

Authentication

Export	Description
`CavosAuth`	Hosted login: `getGoogleOAuthUrl`, `getAppleOAuthUrl`, `handleCallback`, `sendOtp`, `verifyOtp`, `sendMagicLink`, `authenticate`.
`StaticIdentity`	Wrap a `{ userId, email }` you already have as an `AuthProvider`.
`AuthProvider`, `Identity`	Types for the auth contract.
`deriveAddressSeed(input)`	Poseidon hash of `{ userId, appSalt }` → `address_seed`.

Recovery & multi-device

Export	Description
`RecoveryClient`, `PendingDeviceRequest`	Interface for the non-custodial device-approval relay.
`HttpRecoveryClient`	HTTP implementation talking to the Cavos backend.
`WalletRegistry`, `RegisteredWallet`	Off-chain `userId` → wallet map (cross-device recognition).
`InMemoryWalletRegistry`, `HttpWalletRegistry`	Registry implementations.
`BackupSigner`	Passphrase-derived signer (`DeviceSigner`).
`generateRecoveryCode()`	New high-entropy recovery code.
`deriveBackupKey(code)`	Deterministic keypair from a recovery code.

Passkeys

A second factor for approving new devices — not a transaction signer. See Passkeys.

Export	Description
`PasskeySigner`	Browser WebAuthn signer. `static isSupported()`, `enroll({ userId, userName, displayName? })` (creates a synced discoverable credential), `assert(challenge)` (produces a `PasskeyAssertion`).
`PasskeySignerOptions`, `PasskeyEnrollParams`, `EnrolledPasskey`	Types for passkey construction + enrollment.
`PasskeyAssertion`	Parsed WebAuthn assertion (`authenticatorData`, `clientDataJSON`, `r`, `s`, `challengeOffset`).
`approveDeviceEverywhere(wallets, passkey)`	Low-level/advanced: approve this device across multiple independently-managed chain wallets with a single passkey prompt. Only touches wallets whose `status === "needs-device-approval"`; submits per-chain in parallel with error isolation. Returns `{ chain, transactionHash?, error? }[]`. Most apps target one chain and use `approveThisDeviceWithPasskey` instead.
`PasskeyApprovable`	Structural interface implemented by `Cavos` and `CavosSolana` — what `approveDeviceEverywhere` operates on. Classic Stellar is not part of the batch: its passkey factor is a WebAuthn-PRF secret, so approve a Stellar device with `CavosStellar.approveThisDeviceWithPasskey(prfOutput)` separately.

Passkey approval on Starknet mainnet is not yet available (the mainnet account class hasn't been re-declared with the add_signer_via_passkey surface). Use it on Sepolia, or on Solana / Stellar (relayer-routed). On Starknet mainnet, fall back to multi-device / recovery.

Signers

Export	Description
`WebCryptoSigner`	Browser silent device signer (non-extractable P-256 in IndexedDB). `loadOrCreate`, `create`, `load`.
`PasskeySigner`	Browser WebAuthn passkey signer — see Passkeys.
`DeviceSigner`, `DevicePublicKey`, `DeviceSignature`	Signer types (shared across chains).

Chain adapters & constants

Starknet

Export	Description
`StarknetAdapter`	Computes addresses, builds deploy/initialize/add/remove calls, serializes signatures.
`STARKNET_NETWORKS`, `StarknetNetwork`	Network configs (`sepolia`, `mainnet`).
`DEVICE_ACCOUNT_CLASS_HASH`, `UDC_ADDRESS`	Deployed class hash + Universal Deployer address.
`StarknetDeviceSigner`	Drop-in starknet.js `SignerInterface` backed by a device signer.

Solana

Export	Description
`CavosSolana`	High-level Solana client — the analogue of `Cavos`. `connect`, `execute(amount, destination)` (SOL transfer), `executeInstructions(instructions)` (arbitrary CPI), `signMessage(message)` (off-chain, P-256), `signTransaction(amount, destination)` (device precompile signature, relayer-bound), `addSigner`, `setupRecovery`, static `recover`. Returned by `Cavos.connect({ chain: "solana" })`.
`InstructionData`, `InstructionAccount`	Serializable instruction shape for `executeInstructions` (mirrors the on-chain Borsh layout).
`SolanaRelayer`, `SolanaRelayerOptions`	Cavos gasless sponsoring relayer (co-signs as fee payer). Activated by `appId`.
`SolanaAdapter`, `SolanaAdapterOptions`	Low-level adapter: PDA derivation, the `[secp256r1 precompile, program]` instruction builders, signature encoding.
`compressedPubkey`, `encodeLowSSignature`, `buildSecp256r1Instruction`, `anchorDiscriminator`	Low-level Solana helpers.
`SOLANA_NETWORKS`, `SolanaNetwork`	Network configs (`solana-devnet`, `solana-mainnet`, `solana-localnet`).
`DEVICE_ACCOUNT_PROGRAM_ID`, `SECP256R1_PROGRAM_ID`	Cavos device-account program id + native secp256r1 precompile id.
`deriveAddressSeedSolana`	SHA-256 `address_seed` from `{ userId, appSalt }` (Solana variant of `deriveAddressSeed`).

Stellar

Classic G… multisig account (self-custodial, no backend/registry). Live on testnet and mainnet.

Export	Description
`CavosStellar`	High-level Stellar client — the analogue of `Cavos`. `connect`, `execute(amount, destination)` (native XLM transfer, stroops), `signMessage(message)` (off-chain, ed25519 control key), `signTransaction(amount, destination)` (signed inner XDR, not submitted), `balance()` (XLM, stroops), `enrollPasskey(prfOutput)` (add a WebAuthn-PRF passkey unlock factor), `setupRecovery(code)` (add a recovery-code unlock factor), `approveThisDeviceWithPasskey(prfOutput)`, `approveThisDeviceWithRecovery(code)`, `hasPasskey`, `isReady`, `controlAddress`. Returned by `Cavos.connect({ chain: "stellar" })`.
`StellarAdapter`, `StellarAdapterOptions`	Low-level adapter over Horizon: deterministic master-key derivation, account creation/payment/data-entry transaction builders, fee-bump wrapping, submit.
`StellarRelayer`, `StellarRelayerOptions`, `StellarRelayKind`	Cavos gasless sponsoring relayer (signs/submits/fee-bumps via a relayer source). Activated by `appId`.
`ConnectStellarOptions`, `StellarConnectStatus`	Option/status types for `CavosStellar.connect`.
`STELLAR_NETWORKS`, `StellarNetwork`, `HORIZON_URL`, `XLM_DECIMALS`	Network configs + Horizon endpoints (`stellar-testnet`, `stellar-mainnet`).
`DeviceUnwrapKey`, `LocalDeviceUnwrapKey`, `WebCryptoDeviceUnwrapKey`, `WebCryptoUnwrapKeyOptions`, `deviceSlotId`	This device's ECDH key that unwraps the account's control-key envelope (defaults to a persisted WebCrypto key in the browser).
`PasskeyPrf`, `PasskeyPrfOptions`, `PasskeyPrfEnrollParams`	WebAuthn PRF helper: a synced passkey derives a stable secret that unlocks the control key (Stellar's passkey factor is a PRF secret, not an on-chain assertion).
`deriveStellarAddress`, `deriveStellarMasterKeypair`, `generateControlKey`	Deterministic master-address/keypair derivation + control-key generation.
`generateDEK`, `sealControlSeed`, `openControlSeed`, `wrapDEK`, `unwrapDEK`, `eciesWrapDEK`, `eciesUnwrapDEK`, `derivePasskeyKEK`, `deriveRecoveryKEK`	Envelope crypto: seal the control key under a DEK and wrap the DEK per unlock factor (device / passkey / recovery).
`toDataEntries`, `fromDataEntries`, `AccountEnvelope`	Serialize the on-chain control-key envelope to/from account data entries.
`deriveAddressSeedStellar`	SHA-256 `address_seed` from `{ userId, appSalt }` (Stellar variant of `deriveAddressSeed`).

Shared interface types

Export	Description
`ChainAdapter`, `ChainCall`, `ComputeAddressParams`	Multi-chain interface types.
`Chain` (`"starknet" \| "solana" \| "stellar"`), `NetworkEnv` (`"testnet" \| "mainnet"`), `CavosWallet`	Unified connect types.
`MessageSignature`	`{ signature: Uint8Array; publicKey: string; curve: "secp256r1" \| "ed25519" }` — off-chain message signature. See After sign-in.
`SignedTransaction`, `StarknetSignedTransaction`, `StellarSignedTransaction`, `SolanaSignedTransaction`	Sign-without-submit result, chain-specific (narrow on `chain`).
`SignatureCurve`	`"secp256r1" \| "ed25519"` — which curve a `MessageSignature` was produced with.
`CAVOS_MESSAGE_PREFIX`, `prefixedMessageBytes(message)`	The off-chain message prefix scheme (`"Cavos Signed Message:\n<len>\n"`).

React (`@cavos/kit/react`)

React bindings shipped in the same package under the /react subpath. See React for the full guide.

Export	Description
`CavosProvider`	Wrap your app once; manages one chain's wallet + mounts the auth modal. Props: `config: CavosConfig`, `modal?: CavosModalConfig`, `children`.
`useCavos()`	Primary hook — full wallet surface: state (`address`, `wallet`, `chain`, `walletStatus`, `user`, `isAuthenticated`), login, `execute` (Starknet), device/recovery wrappers, `logout`.
`useCavosAuth()`	Thin subset for components that only open the modal and read auth state (`openModal`, `closeModal`, `isAuthenticated`, `address`, `user`, `walletStatus`, `logout`).
`CavosAuthModal`	Customizable login modal. Renders as a bottom sheet automatically on mobile (`max-width: 640px`).
`CavosConfig`, `CavosModalConfig`, `CavosAuthModalProps`, `CavosProviderProps`, `CavosContextValue`, `UserInfo`, `WalletStatus`	Type-only exports for the React layer.

CavosAuthModalProps / CavosModalConfig include theming (theme, backgroundColor, primaryColor, radius), branding (appName, appLogo, appLogoSize), providers, emailMode, secureStep, and onSuccess.

Chain and NetworkEnv are exported from the core entry (@cavos/kit), not from @cavos/kit/react. Import them from import type { Chain } from "@cavos/kit".

Low-level crypto (advanced)

Export	Description
`signatureToFelts`, `recoverYParity`	secp256r1 signature ↔ 5-felt Starknet encoding.
`u256ToFelts`, `bytesToBigInt`, `bytesToHex`, `hexToBytes`, `bigIntTo32Bytes`	Encoding helpers.

On this page