API Reference

Imports

import WalletManagerSolanaGasless from '@tetherto/wdk-wallet-solana-gasless'

import {
  WalletAccountReadOnlySolanaGasless,
  WalletAccountSolanaGasless
} from '@tetherto/wdk-wallet-solana-gasless'

Exports

WalletManagerSolanaGasless

Derives and returns owned Solana gasless accounts from a BIP-39 mnemonic or raw 16–64-byte seed for SLIP-0010 derivation. Extends WalletManager from @tetherto/wdk-wallet. The manager shares one Solana RPC client and one Kora paymaster client across derived accounts and their read-only conversions.

Constructor

new WalletManagerSolanaGasless(
  seed: string | Uint8Array,
  config?: SolanaGaslessWalletConfig
)

Parameters:

• seed: BIP-39 mnemonic seed phrase or raw 16–64-byte seed for SLIP-0010 derivation.
• config: Solana RPC and Kora-compatible paymaster configuration.

Methods

getAccount

getAccount(index?: number): Promise<WalletAccountSolanaGasless>

Returns the account for m/44'/501'/index'/0'. If index is omitted, the module uses 0.

const wallet = new WalletManagerSolanaGasless(seedPhrase, config)
const account = await wallet.getAccount(0)

getAccountByPath

getAccountByPath(path: string): Promise<WalletAccountSolanaGasless>

Returns the account at a specific Solana SLIP-0010 derivation path.

const account = await wallet.getAccountByPath("0'/0'/1'")

WalletAccountSolanaGasless

Owned Solana gasless account. Extends WalletAccountReadOnlySolanaGasless and implements IWalletAccount from @tetherto/wdk-wallet.

Constructor

new WalletAccountSolanaGasless(
  seed: string | Uint8Array,
  path: string,
  config: SolanaGaslessWalletConfig
)

Parameters:

• seed: BIP-39 mnemonic seed phrase or raw 16–64-byte seed for SLIP-0010 derivation.
• path: SLIP-0010 derivation path, for example "0'/0'/0'".
• config: Solana RPC and Kora-compatible paymaster configuration.

Properties

Methods

getAddress

getAddress(): Promise<string>

Returns the account's base58-encoded Solana address.

sign

sign(message: string): Promise<string>

Signs a message and returns its signature.

signTransaction

signTransaction(
  tx: SolanaTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<FullySignedTransaction>

Signs a paymaster-funded transaction without broadcasting it. The module adds the paymaster payment instruction, checks the quoted payment against transactionMaxFee, signs with the account owner, asks the paymaster to sign, and returns the fully signed transaction.

The method throws when the quoted paymaster fee is greater than transactionMaxFee.

sendTransaction

sendTransaction(
  tx: SolanaTransaction | FullySignedTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<TransactionResult>

For an unsigned input, sends a paymaster-funded native transfer or prebuilt transaction message. For the exact FullySignedTransaction returned by signTransaction(), the module does not contact the paymaster: it searches for the embedded payment fee, applies transactionMaxFee, base64-encodes the signed wire transaction, and sends it through the configured Solana RPC with encoding: 'base64'.

const result = await account.sendTransaction({
  to: 'Recipient1111111111111111111111111111111',
  value: 1000000n
}, {
  transactionMaxFee: 500000n
})

console.log(result.hash)
console.log(result.fee)

The method throws when the payment fee is greater than transactionMaxFee; a fee equal to the cap is allowed. An unsigned-flow payment above Number.MAX_SAFE_INTEGER can be rounded internally before this comparison. A signed transaction retains its existing blockhash or durable nonce lifetime, payment instruction, and signatures. The method does not refresh or re-sign it.

transfer

transfer(
  options: TransferOptions,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<TransferResult>

Transfers SPL tokens through the paymaster. Native SOL transfers are handled by sendTransaction() instead. The second argument contains paymaster overrides, not standard Solana memo options. Transfer memos and Token-2022 mints remain unsupported.

const result = await account.transfer({
  token: 'TokenMint111111111111111111111111111111111',
  recipient: 'Recipient1111111111111111111111111111111',
  amount: 1000000n
}, {
  transferMaxFee: 500000n
})

The method throws when the quoted paymaster fee is greater than transferMaxFee.

quoteSendTransaction

quoteSendTransaction(
  tx: SolanaTransaction | FullySignedTransaction,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<Omit<TransactionResult, 'hash'>>

For an unsigned input, requests a paymaster fee quote for sendTransaction() or signTransaction() inputs. Beta.5 validates the returned SPL payment instruction but converts its u64 amount through Number; values above Number.MAX_SAFE_INTEGER can round before being returned as bigint. For a FullySignedTransaction, it does not call the paymaster or broadcast: it searches for a signed SPL token payment to the configured paymaster token account and decodes a matching u64 exactly. The effective paymasterToken, including a per-call override, selects the payment to decode. If there is no match, the method throws NoSuchElementError. Neither form enforces transactionMaxFee during the quote.

quoteTransfer

quoteTransfer(
  options: TransferOptions,
  config?: SolanaGaslessWalletPaymasterConfigOverrides
): Promise<Omit<TransferResult, 'hash'>>

Quotes the paymaster fee for transfer() inputs. Quote methods return estimates and do not enforce transferMaxFee.

getTransactionReceipt

getTransactionReceipt(hash: string): Promise<SolanaTransactionReceipt | null>

Returns the native Solana transaction for a submitted signature, or null if it has not been included yet. This method is deprecated; use getTransaction() and read its transaction field for native data.

getTransaction

getTransaction(hash: string): Promise<TransactionReceipt & SolanaTransactionDetails>

Returns normalized status for a valid base58 Solana signature. processed maps to pending, confirmed maps to confirmed, and finalized maps to final. Settled receipts expose success, the slot in block, the fee when available, confirmation count, and the native transaction when returned by the configured RPC commitment.

An invalid signature throws ValueError; a well-formed signature absent from transaction history throws NoSuchElementError.

waitForTransaction

waitForTransaction(
  hash: string,
  options?: WaitForTransactionOptions
): Promise<TransactionReceipt & SolanaTransactionDetails>

Waits for the default confirmed target or for final when requested. The default polling interval is four seconds and timeout is 60 seconds. The Solana implementation does not currently emit dropped; a never-landed or evicted signature times out. Reaching the target does not prove successful execution, so inspect success.

toReadOnlyAccount

toReadOnlyAccount(): Promise<WalletAccountReadOnlySolanaGasless>

Returns a read-only account for the same address.

WalletAccountReadOnlySolanaGasless

Read-only Solana gasless account for an address. Extends WalletAccountReadOnly from @tetherto/wdk-wallet.

Constructor

new WalletAccountReadOnlySolanaGasless(
  addr: string,
  config: Omit<SolanaGaslessWalletConfig, 'transferMaxFee' | 'transactionMaxFee'>
)

Parameters:

• addr: Solana account address.
• config: Solana RPC and paymaster configuration. Read-only accounts do not accept transferMaxFee or transactionMaxFee.

Methods

Read-only and owned accounts have the same normalized transaction semantics. The package delegates these calls to the wrapped standard Solana read-only account.

Configuration Types

Normalized Transaction Types

type Finality = 'pending' | 'confirmed' | 'final' | 'dropped'
type WaitForTransactionTarget = 'confirmed' | 'final'

interface WaitForTransactionOptions {
  target?: WaitForTransactionTarget
  timeout?: number
  interval?: number
  maxPollErrors?: number
}

interface SolanaTransactionDetails {
  confirmations: number | null
  transaction: SolanaTransactionReceipt | null
}

TransactionReceipt adds hash, finality, and optional success, block, and fee fields. These types are re-exported from the package root.

SolanaGaslessWalletConfig

type SolanaGaslessWalletConfig =
  SolanaWalletConfig & SolanaGaslessWalletPaymasterConfig

Combines the base Solana wallet configuration with the required paymaster configuration.

SolanaGaslessWalletPaymasterConfig

type SolanaGaslessWalletPaymasterConfig = {
  paymasterUrl: string | KoraClientOptions | KoraClient | (string | KoraClientOptions | KoraClient)[]
  paymasterAddress: string
  paymasterToken: PaymasterTokenConfig
}

PaymasterTokenConfig

type PaymasterTokenConfig = {
  address: string
}

SolanaGaslessWalletPaymasterConfigOverrides

type SolanaGaslessWalletPaymasterConfigOverrides = Partial<
  Pick<SolanaGaslessWalletPaymasterConfig, 'paymasterToken'> &
  Pick<SolanaWalletConfig, 'transferMaxFee' | 'transactionMaxFee'>
>

Pass overrides as the second argument to quote, sign, send, or transfer methods. Fields set to undefined retain their configured values; this is a shallow merge. For a signed transaction, retain the paymasterToken used at signing.

Errors

Import runtime error classes from the package root:

import {
  AssertionError,
  MaximumFeeExceededError,
  NoSuchElementError,
  ProviderRequiredError,
  TimeoutError,
  ValueError
} from '@tetherto/wdk-wallet-solana-gasless'

• ValueError: missing required paymaster fields, an empty paymaster endpoint list, a mismatched fee payer, or an invalid returned payment instruction. ConfigurationError was removed in beta.5.
• MaximumFeeExceededError: a sign, send, or transfer fee exceeds its applicable cap.
• NoSuchElementError: a signed quote/send cannot find a payment for the effective fee token, or transaction status lookup finds no matching transaction.
• ProviderRequiredError: an operation requiring Solana RPC has no configured provider.
• TimeoutError: the requested transaction finality is not reached in time.
• AssertionError: an inherited account precondition fails, such as using a disposed signing account.

Provider and Solana libraries may throw other errors; rethrow unfamiliar failures rather than treating every exception as a WDK error.

Next Steps

Need Help?