Wallet Solana API Reference

Table of Contents

WalletManagerSolana

The main class for managing Solana wallets. Extends WalletManager from @tetherto/wdk-wallet.

Constructor

new WalletManagerSolana(seed, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• config (object): Configuration object
  • provider (string | string[], optional): Solana RPC endpoint URL or an ordered list of endpoints for failover
  • rpcUrl (string | string[], optional): Deprecated alias for provider. If both are set, provider takes precedence
  • commitment (string, optional): Commitment level ('processed', 'confirmed', or 'finalized')
  • retries (number, optional): Additional retry attempts for ordered provider failover (default: 3)
  • transferMaxFee (number | bigint, optional): Maximum fee amount for SPL token transfer operations (in lamports)
  • transactionMaxFee (number | bigint, optional): Maximum fee amount for native SOL send/sign operations (in lamports)

Example:

const wallet = new WalletManagerSolana(seedPhrase, {
  provider: 'https://api.mainnet-beta.solana.com',
  commitment: 'confirmed',
  transferMaxFee: 5000, // Maximum SPL transfer fee in lamports
  transactionMaxFee: 5000 // Maximum native send/sign fee in lamports
})

Methods

getAccount(index)

Returns a wallet account at the specified index.

Parameters:

• index (number, optional): The index of the account to get (default: 0)

Returns: Promise<WalletAccountSolana> - The wallet account

Example:

const account = await wallet.getAccount(0)

getAccountByPath(path)

Returns a wallet account at the specified SLIP-0010 derivation path.

Parameters:

• path (string): The derivation path (e.g., "0'/0'/0'"). On Solana, every child segment must be hardened.

Returns: Promise<WalletAccountSolana> - The wallet account

Example:

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

getFeeRates()

Returns current fee rates for transactions based on recent prioritization fees.

Returns: Promise<{normal: bigint, fast: bigint}> - Object containing fee rates in lamports

Throws: Error if wallet is not connected to a provider

Example:

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'lamports')
console.log('Fast fee rate:', feeRates.fast, 'lamports')

dispose()

Disposes all wallet accounts, clearing private keys from memory.

Example:

wallet.dispose()

WalletAccountSolana

Represents an individual Solana wallet account. Extends WalletAccountReadOnlySolana and implements IWalletAccount.

Constructor

new WalletAccountSolana(seed, path, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• path (string): SLIP-0010 derivation path (e.g., "0'/0'/0'")
• config (SolanaWalletConfig, optional): Configuration object

Methods

getAddress()

Returns the account's Solana address.

Returns: Promise<string> - The account's base58-encoded Solana address

Example:

const address = await account.getAddress()
console.log('Account address:', address)

sign(message)

Signs a message using the account's private key.

Parameters:

• message (string): The message to sign

Returns: Promise<string> - The message signature (hex-encoded)

Example:

const signature = await account.sign('Hello, Solana!')
console.log('Signature:', signature)

signTransaction(tx)

Signs a Solana transaction without broadcasting it. Use this method when a relay, review flow, or separate submission path needs a fully signed transaction.

Parameters:

• tx (SolanaTransaction): A simple transfer object or a prebuilt TransactionMessage

When tx is a TransactionMessage, WDK preserves an existing recent blockhash or durable nonce lifetime. If no lifetime is present, WDK fetches the latest blockhash before signing. If you set an explicit feePayer, it must match the wallet address.

Returns: Promise<FullySignedTransaction> - The signed transaction

Throws: Error if wallet is not connected to a provider or if the estimated fee is greater than transactionMaxFee

Example:

const signedTransaction = await account.signTransaction({
  to: '11111111111111111111111111111112',
  value: 1000000000 // 1 SOL in lamports
})
console.log('Signed transaction:', signedTransaction)

verify(message, signature)

Verifies a message signature against the account's address.

Parameters:

• message (string): The original message
• signature (string): The signature to verify (hex-encoded)

Returns: Promise<boolean> - True if the signature is valid

Example:

const isValid = await account.verify('Hello, Solana!', signature)
console.log('Signature valid:', isValid)

sendTransaction(tx)

Sends a Solana transaction.

Parameters:

• tx (SolanaTransaction | FullySignedTransaction): A simple transfer object, prebuilt TransactionMessage, or fully signed transaction
  • to (string): Recipient's Solana address (base58-encoded)
  • value (number | bigint): Amount in lamports

When tx is a TransactionMessage, WDK preserves an existing recent blockhash or durable nonce lifetime. If no lifetime is present, WDK fetches the latest blockhash before quoting or sending. If you set an explicit feePayer, it must match the wallet address.

When tx is a FullySignedTransaction, WDK quotes it again, enforces transactionMaxFee, and broadcasts its exact wire bytes. It does not refresh the recent blockhash or durable nonce and does not re-sign the transaction.

Returns: Promise<{hash: string, fee: bigint}> - Object containing transaction hash and fee (in lamports)

Throws: Error if wallet is not connected to a provider or if the estimated fee is greater than transactionMaxFee

Example:

const result = await account.sendTransaction({
  to: '11111111111111111111111111111112',
  value: 1000000000 // 1 SOL in lamports
})
console.log('Transaction hash:', result.hash)
console.log('Transaction fee:', result.fee, 'lamports')

quoteSendTransaction(tx)

Estimates the fee for a Solana transaction.

Parameters:

• tx (SolanaTransaction | FullySignedTransaction): A transaction input or fully signed transaction (same forms as sendTransaction)

Returns: Promise<{fee: bigint}> - Object containing fee estimate (in lamports)

Example:

const quote = await account.quoteSendTransaction({
  to: '11111111111111111111111111111112',
  value: 1000000000
})
console.log('Estimated fee:', quote.fee, 'lamports')

transfer(options)

Transfers SPL tokens to another address.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token mint address (base58-encoded)
  • recipient (string): Recipient's Solana address (base58-encoded)
  • amount (number | bigint): Amount in token's base units

Returns: Promise<{hash: string, fee: bigint}> - Object containing transaction hash and fee (in lamports)

Throws: Error if wallet is not connected to a provider or if fee exceeds maximum

Example:

const result = await account.transfer({
  token: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT mint
  recipient: '11111111111111111111111111111112',
  amount: 1000000 // 1 USDT (6 decimals)
})
console.log('Transfer hash:', result.hash)
console.log('Transfer fee:', result.fee, 'lamports')

quoteTransfer(options)

Estimates the fee for an SPL token transfer.

Parameters:

• options (TransferOptions): Transfer options (same as transfer)

Returns: Promise<{fee: bigint}> - Object containing fee estimate (in lamports)

Example:

const quote = await account.quoteTransfer({
  token: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
  recipient: '11111111111111111111111111111112',
  amount: 1000000
})
console.log('Transfer fee estimate:', quote.fee, 'lamports')

getBalance()

Returns the native SOL balance (in lamports).

Returns: Promise<bigint> - Balance in lamports

Example:

const balance = await account.getBalance()
console.log('SOL balance:', balance, 'lamports')

getTokenBalance(tokenMint)

Returns the balance of a specific SPL token.

Parameters:

• tokenMint (string): Token mint address (base58-encoded)

Returns: Promise<bigint> - Token balance in base units

Example:

const tokenBalance = await account.getTokenBalance('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB')
console.log('USDT balance:', tokenBalance)

getTokenBalances(tokenAddresses)

Returns balances for multiple SPL tokens. The wallet batches associated token account lookups with getMultipleAccounts, returns balances in base units, and reports 0n for token accounts that do not exist.

Parameters:

• tokenAddresses (string[]): Token mint addresses (base58-encoded)

Returns: Promise<Record<string, bigint>> - Mapping of token mint address to token balance in base units

Example:

const tokenBalances = await account.getTokenBalances([
  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
  'So11111111111111111111111111111111111111112'
])
console.log('Token balances:', tokenBalances)

getTransactionReceipt(hash)

Gets the native transaction object for a signature. This method is deprecated; use getTransaction() and read its transaction field when native data is needed.

Parameters:

• hash (string): Transaction hash

Returns: Promise<SolanaTransactionReceipt \| null> - Transaction receipt details, or null if not found

Example:

const receipt = await account.getTransactionReceipt('5....')
console.log('Transaction receipt:', receipt)

getTransaction(hash)

Returns normalized status for a valid base58 Solana transaction signature. The method queries signature status with transaction-history search enabled.

const receipt = await account.getTransaction(signature)

console.log(receipt.finality)      // pending, confirmed, or final
console.log(receipt.success)       // Set after confirmed or finalized processing
console.log(receipt.confirmations) // Number, or null after finalization
console.log(receipt.transaction)   // Native transaction object, or null

Solana processed maps to pending, confirmed maps to confirmed, and finalized maps to final. The block field is the slot and fee is the native transaction fee when available. A settled transaction reports success: false when its status contains an error. The native transaction can still be null when the RPC does not return it at the configured commitment.

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

waitForTransaction(hash, options?)

Polls until the target is reached. The default target is confirmed, interval is four seconds, and timeout is 60 seconds.

const receipt = await account.waitForTransaction(signature, {
  target: 'final',
  timeout: 60000,
  interval: 4000,
  maxPollErrors: 3
})

The Solana implementation does not currently classify an evicted or never-landed signature as dropped; that case eventually throws TimeoutError. Reaching a finality target does not guarantee execution success, so inspect success.

toReadOnlyAccount()

Returns a read-only copy of the account. After the first call, subsequent calls reuse the same read-only account instance.

Returns: Promise<WalletAccountReadOnlySolana> - The read-only account

Example:

const readOnlyAccount = await account.toReadOnlyAccount()

dispose()

Disposes the wallet account, clearing private keys from memory.

Example:

account.dispose()

Properties

⚠️ Security Note: The keyPair property contains sensitive cryptographic material. Never log, display, mutate, or expose the private key.

WalletAccountReadOnlySolana

Represents a read-only Solana wallet account.

Constructor

new WalletAccountReadOnlySolana(publicKey, config)

Parameters:

• publicKey (string): The account's public key (base58-encoded)
• config (SolanaWalletConfig, optional): Configuration object

Methods

getAddress()

Returns the account's Solana address.

Returns: Promise<string> - The account's base58-encoded Solana address

Example:

const address = await readOnlyAccount.getAddress()
console.log('Account address:', address)

getBalance()

Returns the native SOL balance (in lamports).

Returns: Promise<bigint> - Balance in lamports

Example:

const balance = await readOnlyAccount.getBalance()
console.log('SOL balance:', balance, 'lamports')

getTokenBalance(tokenMint)

Returns the balance of a specific SPL token.

Parameters:

• tokenMint (string): Token mint address (base58-encoded)

Returns: Promise<bigint> - Token balance in base units

Example:

const tokenBalance = await readOnlyAccount.getTokenBalance('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB')
console.log('USDT balance:', tokenBalance)

getTokenBalances(tokenAddresses)

Returns balances for multiple SPL tokens from the read-only account address.

Parameters:

• tokenAddresses (string[]): Token mint addresses (base58-encoded)

Returns: Promise<Record<string, bigint>> - Mapping of token mint address to token balance in base units

Example:

const tokenBalances = await readOnlyAccount.getTokenBalances([
  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
  'So11111111111111111111111111111111111111112'
])
console.log('Read-only token balances:', tokenBalances)

verify(message, signature)

Verifies a message signature.

Parameters:

• message (string): The original message
• signature (string): The signature to verify (hex-encoded)

Returns: Promise<boolean> - True if the signature is valid

Example:

const isValid = await readOnlyAccount.verify('Hello, Solana!', signature)
console.log('Signature valid:', isValid)

quoteSendTransaction(tx)

Estimates the fee for a transaction.

Parameters:

• tx (SolanaTransaction): The transaction object
  • to (string): Recipient's Solana address (base58-encoded)
  • value (number): Amount in lamports

Returns: Promise<{fee: bigint}> - Object containing fee estimate (in lamports)

Example:

const quote = await readOnlyAccount.quoteSendTransaction({
  to: '11111111111111111111111111111112',
  value: 1000000000
})
console.log('Estimated fee:', quote.fee, 'lamports')

quoteTransfer(options)

Estimates the fee for an SPL token transfer.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token mint address (base58-encoded)
  • recipient (string): Recipient's Solana address (base58-encoded)
  • amount (number): Amount in token's base units

Returns: Promise<{fee: bigint}> - Object containing fee estimate (in lamports)

Example:

const quote = await readOnlyAccount.quoteTransfer({
  token: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
  recipient: '11111111111111111111111111111112',
  amount: 1000000
})
console.log('Transfer fee estimate:', quote.fee, 'lamports')

getTransaction(hash) and waitForTransaction(hash, options?)

Read-only accounts expose the same normalized signature-status methods as owned accounts. getTransaction() maps processed, confirmed, and finalized to pending, confirmed, and final; waitForTransaction() defaults to a four-second interval and 60-second timeout. Inspect success after settlement. getTransactionReceipt() remains available for the native object but is deprecated.

Types

Normalized Transaction Types

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

interface TransactionReceipt {
  hash: string
  finality: Finality
  success?: boolean
  block?: number
  fee?: bigint
}

interface WaitForTransactionOptions {
  target?: WaitForTransactionTarget // Default: 'confirmed'
  timeout?: number                  // Milliseconds; Solana default: 60,000
  interval?: number                 // Milliseconds; default: 4,000
  maxPollErrors?: number            // Default: 3
}

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

The package re-exports these types. dropped is part of the shared union, but the Solana implementation does not currently emit it.

SolanaWalletConfig

interface SolanaWalletConfig {
  provider?: string | string[];
  /** Deprecated alias for provider. provider takes precedence when both are set. */
  rpcUrl?: string | string[];
  commitment?: 'processed' | 'confirmed' | 'finalized';
  retries?: number;
  transferMaxFee?: number | bigint;
  transactionMaxFee?: number | bigint;
}

FullySignedTransaction

signTransaction() returns the FullySignedTransaction type defined by @solana/transactions. The WDK package does not re-export this type; import it from the Solana package when an explicit annotation is needed.

import type { FullySignedTransaction } from '@solana/transactions'

The signed value contains the compiled message bytes and all required signatures. Its transaction lifetime is sealed at signing time.

TransferOptions

interface TransferOptions {
  token: string;
  recipient: string;
  amount: number | bigint;
}

KeyPair

interface KeyPair {
  publicKey: Uint8Array
  privateKey: Uint8Array | null
}

Need Help?