> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buckspay.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Gasless modes

> Sponsored vs. token-fee gas abstraction - choose who pays for the transaction fee.

`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:

```ts theme={null}
type GasConfig =
  | { mode: "sponsored" }
  | { mode: "token"; token: string; maxFee?: string };
```

## Sponsored mode

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](/features/onboarding) to understand how an
account with no XLM balance is materialized in the first place.

```ts theme={null}
// 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](/features/gas-in-token) for the full details: the `FeeQuote` fields,
the `maxFee` ceiling, and the `TOKEN_GAS_REJECTED` error code.

## Choosing a mode

| Scenario                               | Recommended mode                    |
| -------------------------------------- | ----------------------------------- |
| Your app subsidizes fees (UX priority) | `sponsored`                         |
| User holds USDC, no sponsor budget     | `token`                             |
| Any other token                        | not yet supported - use `sponsored` |

<Note>
  The `GasConfig` type only admits these two members. Passing an undeclared mode is a
  compile-time error - you cannot accidentally configure something unsupported.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Gas in token" href="/features/gas-in-token">
    Full reference for the USDC fee-forwarding mode: FeeQuote, maxFee, and error codes.
  </Card>

  <Card title="Onboarding" href="/features/onboarding">
    How a payer with zero XLM gets a payment-ready account, sponsored end-to-end.
  </Card>
</CardGroup>