Using Paymaster SDK

This guide covers how to use the Swig Paymaster SDK to sponsor transaction fees for your users, enabling gasless transactions.

What is a Paymaster?

A paymaster is a service that pays transaction fees on behalf of users, so they can begin using your application before acquiring SOL. Benefits:

Users can transact before acquiring SOL
Lower barrier to entry for new users
Better user experience for dApps

Prerequisites

Before using the paymaster SDK:

Create a paymaster in the Developer Portal
Fund your paymaster with SOL
Get your API key from the Developer Portal

Paymasters require a paid subscription (PRO, ULTRA, or ENTERPRISE). See Subscriptions & Billing for details.

Installation

Choose the package that matches your Solana SDK version:

Classic (web3.js 1.x)
Kit (web3.js 2.0)

npm install @swig-wallet/paymaster-classic

For applications using @solana/web3.js version 1.x (the traditional Solana SDK).

npm install @swig-wallet/paymaster-kit

For applications using @solana/kit (the new modular Solana SDK 2.0).

Configuration

Create a paymaster client with your credentials:

Classic (web3.js 1.x)
Kit (web3.js 2.0)

import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

import { createPaymasterClient } from '@swig-wallet/paymaster-kit';
import { address } from '@solana/kit';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

Configuration Options

Option	Type	Required	Description
`apiKey`	string	Yes	API key from Developer Portal
`paymasterPubkey`	string	Yes	Paymaster public key
`baseUrl`	string	Yes	Paymaster API URL (`https://api.onswig.com`)
`network`	`'mainnet'` \| `'devnet'`	Yes	Solana network
`customRpcUrl`	string	No	Custom RPC endpoint (overrides default)
`retryOptions`	object	No	Retry configuration for failed requests

Retry Options

Configure automatic retries for transient failures:

const paymaster = createPaymasterClient({
  apiKey: 'sk_your_api_key',
  paymasterPubkey: '...',
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
  retryOptions: {
    maxRetries: 3,        // Number of retry attempts
    retryDelay: 1000,     // Initial delay in milliseconds
    backoffMultiplier: 2, // Exponential backoff multiplier
  },
});

Quick Start

Here’s a minimal example to sponsor a transaction:

Classic (web3.js 1.x)
Kit (web3.js 2.0)

import { Keypair, PublicKey, TransactionInstruction } from '@solana/web3.js';
import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

// Initialize client
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

// User's keypair
const userKeypair = Keypair.generate();

// Create an instruction (memo example)
const instruction = new TransactionInstruction({
  keys: [{ pubkey: userKeypair.publicKey, isSigner: true, isWritable: false }],
  programId: new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'),
  data: Buffer.from('Hello, gasless world!'),
});

// Create transaction - paymaster is set as fee payer
const transaction = await paymaster.createLegacyTransaction(
  [instruction],
  [userKeypair], // User signs here
);

// Paymaster signs and sends
const signature = await paymaster.signAndSend(transaction);
console.log(`https://explorer.solana.com/tx/${signature}?cluster=devnet`);

import { getAddMemoInstruction } from '@solana-program/memo';
import {
  address,
  generateKeyPairSigner,
  getSignatureFromTransaction,
  partiallySignTransaction,
} from '@solana/kit';
import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

// Initialize client
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

// User's keypair
const userKeypair = await generateKeyPairSigner();

// Create an instruction
const instruction = getAddMemoInstruction({
  memo: 'Hello, gasless world!',
  signers: [userKeypair],
});

// Create transaction - paymaster is set as fee payer
const unsignedTx = await paymaster.createTransaction([instruction]);

// User signs
const partiallySignedTx = await partiallySignTransaction(
  [userKeypair.keyPair],
  unsignedTx,
);

// Paymaster signs and validates
const signedTx = await paymaster.fullySign(partiallySignedTx);

// Get signature
const signature = getSignatureFromTransaction(signedTx).toString();
console.log(`https://explorer.solana.com/tx/${signature}?cluster=devnet`);

Transaction Flow

The paymaster transaction flow works as follows:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Create    │───▶│    User     │───▶│  Paymaster  │───▶│   Submit    │
│ Transaction │    │    Signs    │    │    Signs    │    │  to Network │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │                  │
       ▼                  ▼                  ▼                  ▼
   Paymaster         User proves       Fee covered        Transaction
   as fee payer     authorization      by paymaster        confirmed

Create Transaction: Build the transaction with the paymaster set as the fee payer
User Signs: User signs to authorize the transaction
Paymaster Signs: Paymaster validates and signs (covering the fee)
Submit: Transaction is sent to the Solana network

Next Steps

Sponsoring Transactions - Detailed examples and methods
Advanced Usage - Error handling, retries, versioned transactions
Create a Paymaster - Set up your paymaster in the Developer Portal

Overview

Quickstarts

TypeScript Packages

Rust Packages

AI & MCP

Examples & Recipes

Error Types

Migration & Releases

Using Paymaster SDK

What is a Paymaster?

Prerequisites

Installation

Configuration

Configuration Options

Retry Options

Quick Start

Transaction Flow

Next Steps

​What is a Paymaster?

​Prerequisites

​Installation

​Configuration

​Configuration Options

​Retry Options

​Quick Start

​Transaction Flow

​Next Steps

What is a Paymaster?

Prerequisites

Installation

Configuration

Configuration Options

Retry Options

Quick Start

Transaction Flow

Next Steps