Cavos: embedded Stellar wallets

Cavos (@cavos/kit) gives each user a classic Stellar G… account inside your app. The user signs in with Google, Apple, GitHub, Telegram, or an email code. The account key is derived from a per-user MasterDEK on the user's device, so there is no seed phrase and no extension. The Cavos relayer sponsors the account's XLM reserves and pays fees, so the user never needs to hold lumens.

The same package also ships Solana and Starknet adapters. This skill covers Stellar only.

• Docs: https://docs.cavos.xyz/docs/stellar (agent index: https://docs.cavos.xyz/llms.txt)
• Package: https://www.npmjs.com/package/@cavos/kit
• Dashboard (app ID, gas, callback URLs): https://cavos.xyz/dashboard

When to use this skill

• The app needs Stellar accounts for users who do not have a wallet
• Onboarding must be gasless: the app sponsors reserves and fees
• The account must be a plain classic G… that any Stellar tool, exchange, or anchor understands
• The same account must also sign Soroban require_auth entries (escrows, marketplaces, DeFi)

When NOT to use this skill

• The user already has Freighter or another extension wallet: use Stellar Wallets Kit
• You need a Soroban contract account (C…) with on-chain policies: use Smart Account Kit
• Server-side signing for your own treasury: Cavos keys belong to end users, not your backend

Install

npm install @cavos/kit

Create an app in the dashboard and take its App ID. Add your exact origin under Dashboard → App → Settings → Callback URLs (scheme, host, and path; no wildcards, no trailing slash). Fund Stellar gas under Dashboard → Gas → Stellar before using mainnet.

Mental model

In the browser the key is a non-extractable WebCrypto key, inside the Cavos vault by default. This skill covers the browser only: on React Native and Node, the Stellar adapter does not yet use the MasterDEK path described here.

Setup (React / Next.js)

The provider is client-only. In Next.js App Router, put 'use client' at the top of the file that renders it and of every component that calls useCavos().

'use client';
import { CavosProvider } from '@cavos/kit/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CavosProvider
      config={{
        appId: process.env.NEXT_PUBLIC_CAVOS_APP_ID,
        chains: ['stellar'],
        network: 'testnet', // 'testnet' | 'mainnet'
        appSalt: 'my-app', // HKDF salt. Never change it after users connect.
        socialRecovery: true, // restore on a new device by signing in again
        deviceApproval: 'enclave',
      }}
      modal={{ appName: 'My App', theme: 'light' }}
    >
      {children}
    </CavosProvider>
  );
}

'use client';
import { useCavos } from '@cavos/kit/react';

export function WalletButton() {
  const { isAuthenticated, isLoading, address, openModal, logout } = useCavos();
  if (isLoading) return null;
  if (!isAuthenticated) return <button onClick={openModal}>Sign in</button>;
  return <button onClick={logout}>{address}</button>;
}

To use your own auth instead of the Cavos modal, pass identity={{ userId, email }} to the provider. Derive userId from something that never changes.

Get the Stellar wallet

const { wallet } = useCavos();
if (wallet?.chain !== 'stellar') return;
wallet.address; // G…
wallet.status; // 'undeployed' | 'ready' | 'needs-device-approval'

Connecting never creates the account. On a new account:

• create() creates it and sends nothing. The creation is sponsored, so the account starts with 0 XLM. Call it first in an app that starts with a trustline or a Soroban call.
• execute(amount, to) creates it, then sends amount XLM from it. With 0 XLM the payment fails with op_underfunded, but the account is created.
• addTrustline and invokeContract throw until the account exists.

Actions

// Create the account. Does nothing if it is already ready.
await wallet.create();

// Native XLM payment, amount in stroops (1 XLM = 10_000_000n). Fee sponsored by default.
const hash = await wallet.execute(10_000_000n, 'GDEST…');

// Pay the fee from the account's own XLM instead of the relayer.
await wallet.execute(10_000_000n, 'GDEST…', { fee: 'self' });

// Balances
const stroops = await wallet.balance();
const usdc = await wallet.tokenBalance({ code: 'USDC', issuer: 'GA5ZSE…KZVN' }); // "0" if no trustline

// Trustline (the trustline reserve is sponsored). Needs status 'ready'.
await wallet.addTrustline({ code: 'USDC', issuer: 'GA5ZSE…KZVN' });

// Soroban call. This account signs only its own require_auth entry. Needs status 'ready'.
await wallet.invokeContract({ contractId: 'C…', method: 'approve_milestone', args: [0, wallet.address] });

// Your backend built the transaction: sign the unsigned XDR, do not submit.
const signedXdr = await wallet.signXdr(unsignedXdr);

// Off-chain message signature. Works while undeployed.
const { signature, publicKey, curve } = await wallet.signMessage('hello'); // curve: 'ed25519'

Circle USDC on mainnet is USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN.

To let users pay reserves and fees in USDC instead of sponsored XLM, use @cavos/reserve and sign with wallet.signXdr. See https://docs.cavos.xyz/docs/reserve.

Gotchas

• appSalt, appId, and userId are permanent. Changing any of them silently moves every user to a new, empty wallet. Nothing errors.
• A sponsored account holds 0 XLM. An XLM payment needs XLM in the account first. Trustlines and Soroban calls do not, because the sponsor pays their reserves and fees.
• Trustline-first apps call create() first. addTrustline and invokeContract need status === 'ready'.
• Do not gate execution on isReady. undeployed can execute; only needs-device-approval blocks.
• Second browser or device: the user lands on needs-device-approval until the device restores the MasterDEK (enclave sign-in, or approveDeviceWithPasskey() if a passkey was added).
• redirect_uri is not registered: the exact origin is missing from Callback URLs. An empty list rejects everything.
• signMessage adds a Cavos domain prefix before signing. It is not a SEP-53 signature. Verify with Keypair.fromPublicKey(publicKey).verify(prefixedBytes, signature).
• Mainnet needs gas. Fund the app's Stellar gas in the dashboard, or sponsored calls fail.

Version note

Written for @cavos/kit 0.5.3 (create() is new in 0.5.3). Verified on Stellar mainnet on 2026-11-12: account GCTAQX…P5LG4Q, created by the Cavos relayer, with a sponsored Circle USDC trustline.

Sources

• https://docs.cavos.xyz/docs/stellar
• https://docs.cavos.xyz/docs/react
• https://docs.cavos.xyz/docs/signing
• https://docs.cavos.xyz/docs/troubleshooting
• https://github.com/cavos-labs/kit