Skip to main content
Buckspay makes a gasless Stellar USDC payment a three-call affair. The user signs with a wallet they already have (Freighter, xBull, LOBSTR); Buckspay’s facilitator pays the XLM fee. No private keys ever touch your app.
1
Install the packages
2
Add the core client plus the account, signer, and relayer packages you need for a classic Stellar address flow.
3
pnpm add @buckspay/core @buckspay/accounts @buckspay/signers @buckspay/relayer
4
Run the full example
5
The snippet below is the complete, runnable file - compiled and type-checked in CI. It:
6
  • Creates a client with a classic G-address account, a Wallets Kit browser signer, and your backend BFF route as the relayer. createRpcSimContext gives prepare() a recording simulator over the Soroban RPC.
  • Connects the user’s wallet and ensures the account is ready on-chain.
  • Calls transfer to build the payment intent.
  • Calls pay - which runs prepare -> sign -> send in one call.
  • Logs the settled receipt (receipt.transferTx).
    • 7
    // 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
}
    8
    No API key in the browser. url: "/api/gasless" points at your backend route, which forwards the request to the facilitator with the secret key server-side. See BFF / backend integration for the route implementation.
    9
    Confirm on-chain
    10
    receipt is the facilitator’s settlement response:
    11
    {
  ok: true,
  via: "buckspay_self",
  token: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
  chain: "stellar-testnet",
  transferTx: "a1b2c3...",   // transaction hash - verify on Stellar Expert
  ledger: 54321,
  status: "SUCCESS"
}
    12
    Paste transferTx into Stellar Expert (testnet) to confirm the payment landed.

    ​
    Next steps

    Account models

    Classic G-addresses vs. smart-contract accounts (passkey and multi-sig).

    Gasless modes

    Sponsored, fee-forwarding, and session-based gas strategies.

    React hooks

    Drop-in hooks for React apps - useWallet, useStellarPay, and BuckspayProvider.