Paymaster

Introduction

A paymaster pays a transaction’s Solana fee on behalf of your user. Use it when your application should cover fees so the user can transact without holding SOL for gas. Your user still authorizes the wallet operation.

SDK examples

Use the clients from Client setup. Rust uses separate WalletClient and PaymasterClient instances on the same network.

Check paymaster funding

const balance = await swig.paymaster.getBalance({
  network: 'mainnet',
  kind: 'api',
});
if (!balance.configured) throw new Error('API paymaster is not configured');
// balance.configured, balance.address, balance.balanceLamports, balance.balanceSol

balance = await swig.paymaster.get_balance(network="mainnet", kind="api")
if not balance.configured:
    raise RuntimeError("API paymaster is not configured")
# balance.configured, balance.address, balance.balance_lamports, balance.balance_sol

let balance = paymaster.get_balance().await?;

Use getIdpBalance() / get_idp_balance() for IdP funding. TypeScript/Python resolve network from the call, then client, then mainnet for paymaster calls. Rust always uses its configured network. For TypeScript/Python, signedBase64Transaction / signed_base64_transaction is your already-signed preparation. Rust’s sign_transaction is an application-owned async helper following Signing.

const submitted = await swig.transactions.sponsor({
  transaction: signedBase64Transaction,
  network: 'mainnet',
  idempotencyKey,
});

// submitted.requestId
// submitted.signature
// submitted.spentByPaymaster

from swig_developer_sdk import SponsorSignedTransactionArgs

submitted = await swig.transactions.sponsor(
    SponsorSignedTransactionArgs(
        transaction=signed_base64_transaction,
        network="mainnet",
        idempotency_key=idempotency_key,
    )
)

# submitted.request_id
# submitted.signature
# submitted.spent_by_paymaster

use swig_developer_sdk::{PrepareTransferSolArgs, SponsorSignedTransactionArgs};

let funding = paymaster.get_balance().await?;
let prepared = wallet
    .prepare_transfer_sol(PrepareTransferSolArgs {
        swig_config_address,
        fee_payer: funding.address,
        destination,
        amount: lamports,
        requester_authority,
    })
    .await?;

let signed_transaction = sign_transaction(&prepared).await?;

let submitted = paymaster
    .sponsor(SponsorSignedTransactionArgs {
        transaction: signed_transaction,
        idempotency_key,
    })
    .await?;

The result contains the request ID, submitted signature, and paymaster spend. RPC acceptance is not confirmation; track confirmation or finality separately. Rust returns a native Signature; spent_by_paymaster is an i64 and may be negative. Use an ordered bundle for one to five signed transactions that must land together. Bundles are mainnet-only. Before collecting signatures:

Include transfers totaling at least 1,000 lamports from the API paymaster to backend-recognized Jito tip accounts.
Keep tip destinations in static account keys, outside lookup tables.
Keep the paymaster out of every other instruction’s account list, including read-only accounts. The SDK does not add the tip for you.

const bundle = await swig.transactions.sponsorBundle({
  transactions: [signedFirstBase64, signedSecondBase64],
  network: 'mainnet',
  idempotencyKey,
});

// bundle.requestId
// bundle.bundleId
// bundle.signatures
// bundle.estimatedSpentByPaymaster

from swig_developer_sdk import SponsorSignedTransactionBundleArgs

bundle = await swig.transactions.sponsor_bundle(
    SponsorSignedTransactionBundleArgs(
        transactions=(signed_first_base64, signed_second_base64),
        network="mainnet",
        idempotency_key=idempotency_key,
    )
)

# bundle.request_id
# bundle.bundle_id
# bundle.signatures
# bundle.estimated_spent_by_paymaster

use swig_developer_sdk::SponsorSignedTransactionBundleArgs;

let bundle = paymaster
    .sponsor_bundle(SponsorSignedTransactionBundleArgs {
        transactions: signed_transactions,
        idempotency_key,
    })
    .await?;

The response preserves signature order. A bundleId means acceptance by Jito, not confirmation; estimatedSpentByPaymaster is an estimate, not a settled charge. The same transaction-and-key retry rules apply.

Check IdP funding

Query the separate IdP paymaster when your integration sponsors IdP operations.

const idpBalance = await swig.paymaster.getIdpBalance({ network: 'mainnet' });
if (!idpBalance.configured) throw new Error('IdP paymaster is not configured');

idp_balance = await swig.paymaster.get_idp_balance(network="mainnet")
if not idp_balance.configured:
    raise RuntimeError("IdP paymaster is not configured")

let idp_balance = paymaster.get_idp_balance().await?;

Flow

Prepare with paymaster
  └─ User signs
      └─ Sponsor fees
          └─ Confirm

Input

Operation	Parameter	Description
Both	`network`	`mainnet` or `devnet`; use the same network for wallet and paymaster clients
Balance	`kind`	`api` for transaction sponsorship; `idp` for IdP funding
Sponsor	`transaction`	Signed base64 transaction in TypeScript/Python; native `VersionedTransaction` in Rust
Sponsor	`idempotencyKey` / `idempotency_key`	Stable key for this exact transaction; reuse it for retries

Use the API paymaster’s returned address as feePayer / fee_payer during preparation. Complete participant approval and embedded signatures, then every required application-owned Solana signature. Sponsorship adds the paymaster’s signature; it does not replace the other signers. Keep the same signed transaction and key on retry. A matching retry returns the original result without another spend. Resolve an uncertain attempt before starting another. In Rust, Some(nonempty_key) enables eligible retries; None or an empty key disables them.

Output

The balance read returns the following fields. Python uses snake_case attributes.

Field	TypeScript/Python type	Meaning
`configured`	boolean	Distinguishes an absent paymaster from one with zero SOL
`kind`	string	`api`, `idp`, or `unspecified`
`id`, `address`, `label`	string	Identifier, public key, and display label
`balanceLamports` / `balance_lamports`	string	Exact balance in lamports
`balanceSol` / `balance_sol`	number	SOL balance for display

Rust returns PaymasterBalance with a Pubkey address and u64 lamport balance. It has no configured field. Each admitted balance call consumes one API request, including retries and admitted errors. Reading funding does not spend the sponsorship budget.

Errors

Error	Meaning
API paymaster not configured	TypeScript/Python return configured=false; Rust returns GetPaymasterBalanceError::NotConfigured. Create an API paymaster for this network. IdP funding is a separate balance.
Insufficient funding or spending limit reached	The paymaster cannot cover this request within its configured limits. Check its balance and limits in the Developer Portal.
Missing signature or incorrect fee payer	The transaction is not ready for this paymaster to sponsor. Prepare with the API paymaster address and complete all other required signatures.
Idempotency conflict or lost response	The outcome of this attempt needs reconciliation. Keep the original transaction and key; resolve the attempt before starting a replacement.

Getting started

Wallet

Query

Finance

AI

Additional resources

Introduction

SDK examples

Check paymaster funding

Check IdP funding

Flow

Input

Output

Errors

Introduction

SDK examples

Check paymaster funding

Sponsor one transaction

Sponsor a bundle

Check IdP funding

Flow

Input

Output

Errors