Skip to main content
GasConfig controls who covers the Stellar transaction fee. The type is a discriminated union with exactly two members - any other value fails to type-check: 
type GasConfig =
  | { mode: "sponsored" }
  | { mode: "token"; token: string; maxFee?: string };
The facilitator’s sponsor account pays the XLM fee on behalf of the payer. The payer signs only the SorobanAuthorizationEntry off-chain; the facilitator wraps it in a fee-bump transaction, supplies the XLM, and submits to the network. The payer needs zero XLM - not to transact, and not even to exist on-chain. This is the default for most applications. See Onboarding to understand how an account with no XLM balance is materialized in the first place. 
// Gasless modes - v1 ships exactly one: sponsored. The facilitator's sponsor account
// pays the XLM fee; the payer needs zero XLM.
import type { GasConfig } from "@buckspay/core";

export const sponsored: GasConfig = { mode: "sponsored" };

// Roadmap (NOT available in v1 - do not pass these):
//   { mode: "token", token: "USDC:GA5..." }  // pay gas in USDC via FeeForwarder
//   { mode: "self" }                          // payer pays their own fee
// The GasConfig type only admits `{ mode: "sponsored" }` today, so an unimplemented
// mode fails to type-check - the docs can't drift into an unsupported config.

​
Token-fee mode

{ mode: "token", token } lets the payer cover the fee in USDC instead of XLM. The facilitator still fronts the XLM gas; the FeeForwarder contract collects reimbursement from the payer’s stablecoin balance in a single authorization entry - the payer signs once. Use token-fee when you want the user, not your sponsor, to bear the gas cost in the asset they already hold. See Gas in token for the full details: the FeeQuote fields, the maxFee ceiling, and the TOKEN_GAS_REJECTED error code.

​
Choosing a mode

ScenarioRecommended mode
Your app subsidizes fees (UX priority)sponsored
User holds USDC, no sponsor budgettoken
Any other tokennot yet supported - use sponsored
The GasConfig type only admits these two members. Passing an undeclared mode is a compile-time error - you cannot accidentally configure something unsupported.

​
Next

Gas in token

Full reference for the USDC fee-forwarding mode: FeeQuote, maxFee, and error codes.

Onboarding

How a payer with zero XLM gets a payment-ready account, sponsored end-to-end.