Amount Formats

The SDK supports multiple amount formats for intuitive trading. Instead of always specifying exact token amounts, you can use USD values, percentages, or max/all keywords.

Overview

Decimal Amounts

The most precise format - specify exactly how many tokens to use.

// Swap exactly 1.5 SOL
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '1.5',
});
 
// Transfer exactly 0.01 ETH
await wallet.trading.transfer({
  to: '0x...',
  token: 'ETH',
  amount: '0.01',
  chain: 'ethereum',
});

Precision Notes

• Respects token decimals (SOL: 9, USDC: 6, ETH: 18)
• Excess precision is truncated, not rounded
• Always use strings to avoid floating-point issues

// Good - use strings
amount: '0.123456789'
 
// Avoid - numbers may lose precision
amount: 0.123456789

USD Amounts

Specify value in US dollars - automatically converted at the current market price.

// Swap $100 worth of SOL
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100',
});
 
// Alternative suffix format
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '100usd',
});

How USD Conversion Works

1. Fetch current token price from market data
2. Calculate token amount: tokenAmount = usdAmount / price
3. Execute with the calculated token amount

User request: "$100 of SOL"
SOL price: $150
Calculation: $100 / $150 = 0.667 SOL
Executed: Swap 0.667 SOL

USD Format Variants

All of these are equivalent:

• "$100" - Dollar sign prefix
• "$100.00" - With cents
• "100usd" - Lowercase suffix
• "100USD" - Uppercase suffix

Percentage Amounts

Swap or transfer a percentage of your current balance.

// Swap half of SOL balance
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '50%',
});
 
// Transfer 25% of USDC holdings
await wallet.trading.transfer({
  to: 'recipient_address',
  token: 'USDC',
  amount: '25%',
  chain: 'solana',
});

How Percentage Works

1. Fetch current balance of the input token
2. Calculate amount: amount = balance * (percentage / 100)
3. Execute with the calculated amount

User request: "50% of SOL"
SOL balance: 10 SOL
Calculation: 10 x 0.5 = 5 SOL
Executed: Swap 5 SOL

Percentage Considerations

• Based on balance at execution time
• For native tokens (SOL/ETH), a gas buffer is reserved
• "100%" is equivalent to "max"

Max/All Amounts

Swap or transfer your entire balance of a token.

// Swap all SOL
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: 'max',
});
 
// Alternative keyword
await wallet.trading.swap({
  inputToken: 'BONK',
  outputToken: 'SOL',
  amount: 'all',
});

Gas Buffer for Native Tokens

When using "max" with native tokens (SOL, ETH), a small buffer is reserved for transaction fees:

For non-native tokens (USDC, BONK, etc.), "max" uses the full balance with no buffer.

Max Format Variants

All of these are equivalent:

• "max" - Lowercase
• "MAX" - Uppercase
• "all" - Alternative keyword
• "ALL" - Uppercase alternative

Endpoint Support

All trading operations support all amount formats.

Edge Cases and Considerations

Dust Amounts

Very small amounts may fail due to minimum transaction requirements:

// May fail - amount too small
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '0.000001', // Dust amount
});

Rounding Behavior

• Amounts are truncated to the token's decimal precision, not rounded
• For example, "1.123456789123" SOL becomes "1.123456789" (9 decimals)
• USD conversions may result in slight differences from the requested dollar amount

Insufficient Balance

If the calculated amount exceeds your balance:

// Balance: 5 SOL, requesting $1000 worth
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$1000', // More than balance
});
// Throws InsufficientFundsError

Format Selection Guide

Best Practices

Always Preview with Quotes

Get a quote first to see the actual amounts before executing:

// Preview the swap
const quote = await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100',
  quoteOnly: true,
});
 
console.log(`Will swap ${quote.inputAmount} SOL for ~${quote.outputAmount} USDC`);
 
// Then execute
const result = await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100',
});

Confirm Large Operations

For max or high percentage amounts, always confirm with the user:

const info = await wallet.wallet.get();
const solBalance = info.balances.solana.native;
 
// Show user what "max" means
console.log(`This will swap your entire balance of ${solBalance} SOL`);
 
// Then execute after confirmation
await wallet.trading.swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: 'max',
});

Use Strings for Precision

Always pass amounts as strings to avoid JavaScript floating-point issues:

// Correct
amount: '0.1'
 
// Avoid - may have precision issues
amount: 0.1
amount: String(0.1)

Error Cases

Type Definition

type FlexibleAmount = string;
 
// Valid patterns:
// /^\d+\.?\d*$/           - Decimal (1.5, 100)
// /^\$\d+\.?\d*$/         - USD prefix ($100, $100.50)
// /^\d+\.?\d*usd$/i       - USD suffix (100usd, 100USD)
// /^\d+\.?\d*%$/          - Percentage (50%, 100%)
// /^(max|all)$/i          - Max (max, MAX, all, ALL)