Skip to main content
The Wallets Kit signer wraps Stellar Wallets Kit and gives users their preferred browser wallet - Freighter, xBull, or LOBSTR - without any wallet-specific branching in your application code.

​
When to use

Choose walletsKit when your users already have a Stellar wallet installed. It suits classic G... accounts backed by an existing keypair. For new users who have no wallet, consider the passkey signer instead.

​
Factory

import { walletsKit } from "@buckspay/signers/wallets-kit";

const signer = walletsKit({ network: "testnet" });
//                          network: "pubnet" - for production
walletsKit(opts) accepts a KitOptions object:
OptionTypeRequiredDescription
network"testnet" | "pubnet"YesWhich Stellar network to target
selectedWalletIdstringNoPre-select a wallet (default: Freighter)
The factory returns a BuckspaySigner. The browser wallet library is loaded lazily on first use so it never runs during server-side rendering.

​
Example

The snippet below shows a complete classic gasless transfer using walletsKit paired with classicAccount. This is the canonical starting point for users who already have a wallet. 
// Quickstart - classic gasless USDC transfer (browser; NO apiKey).
import { createBuckspayClient, createRpcSimContext } from "@buckspay/core";
import { classicAccount } from "@buckspay/accounts/classic";
import { walletsKit } from "@buckspay/signers/wallets-kit";
import { buckspayFacilitator } from "@buckspay/relayer/buckspay-facilitator";

const USDC_SAC: string = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
const MERCHANT: string = "GA6HCMBLTZS5VYYBCATRBR5VBZJEH5C2OON6XQGB3RNYDDAQ7JZ65YQH";

export async function quickstart(): Promise<void> {
  const buckspay = createBuckspayClient(
    {
      network: "testnet",
      account: classicAccount(),
      signer: walletsKit({ network: "testnet" }),
      // url points at YOUR backend, which forwards to the facilitator with the key server-side.
      relayer: buckspayFacilitator({ url: "/api/gasless", network: "testnet" }),
      gas: { mode: "sponsored" }
    },
    // prepare() simulates against the Soroban RPC.
    createRpcSimContext("https://soroban-testnet.stellar.org")
  );

  await buckspay.connect(); // wallet + ensureReady
  const call = buckspay.transfer({ token: USDC_SAC, to: MERCHANT, amount: "1.50" });
  const receipt = await buckspay.pay([call]); // prepare -> sign -> send
  console.log(receipt.transferTx); // settled on testnet
}

​
How signatures work

Freighter historically returned a double-encoded auth entry in some versions. The Wallets Kit signer applies normalizeSignature internally before returning, so your code always receives a clean 64-byte signature regardless of which wallet or version the user has installed.

​
Next

Passkey

Passwordless flow for new users - no wallet required.

Account models

Pair walletsKit with classicAccount or ozContractAccount.