Token Swaps - Monei API

Overview

Monei integrates with leading DEX aggregators to provide the best swap rates across multiple decentralized exchanges. This guide covers token swaps on EVM networks. What you’ll learn:

Get swap quotes and rates
Swap native tokens to ERC-20 tokens
Swap ERC-20 to ERC-20 tokens
Swap ERC-20 tokens back to native
Price impact and slippage
Gas optimization for swaps

Swap Types

Native → Token

Swap ETH/BNB/MATIC to any ERC-20 token

Token → Token

Swap between any two ERC-20 tokens

Token → Native

Swap ERC-20 tokens back to native currency

Get Swap Quote

Always get a quote before executing a swap to see the exchange rate and estimated output.

Native to Token Quote

import MoneiSDK from 'monei-sdk';

const monei = new MoneiSDK({
  apiKey: process.env.MONEI_API_KEY,
});

// Get quote for swapping 0.1 BNB to USDT on BSC
const quote = await monei.evmExchange.getNativeToTokenPrice({
  outputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT on BSC
  amount: '0.1', // 0.1 BNB
  chainId: 56
});

console.log('Quote ID:', quote.quoteId);
console.log('From:', quote.fromToken.symbol, '(Native)');
console.log('To:', quote.toToken.symbol);
console.log('Input Amount:', quote.fromAmount);
console.log('Output Amount:', quote.toAmount);
console.log('Exchange Rate:', quote.rate);
console.log('Minimum Output:', quote.minToAmount, '(with slippage)');
console.log('Price Impact:', quote.priceImpact + '%');
console.log('Gas Cost:', quote.estimatedGasUsd, 'USD');
console.log('Expires At:', new Date(quote.expiryTimestamp * 1000));

from monei import MoneiClient

monei = MoneiClient(
    api_key=os.getenv('MONEI_API_KEY')
)

# Get quote
quote = monei.evm_exchange.get_native_to_token_price(
    output_mint='0x55d398326f99059fF775485246999027B3197955',
    amount='0.1',
    chain_id=56
)

print(f'Quote ID: {quote.quote_id}')
print(f'From: {quote.from_token.symbol} (Native)')
print(f'To: {quote.to_token.symbol}')
print(f'Input: {quote.from_amount}')
print(f'Output: {quote.to_amount}')
print(f'Rate: {quote.rate}')
print(f'Min Output: {quote.min_to_amount}')
print(f'Price Impact: {quote.price_impact}%')
print(f'Gas Cost: ${quote.estimated_gas_usd}')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/price/native-to-token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outputMint": "0x55d398326f99059fF775485246999027B3197955",
    "amount": "0.1",
    "chainId": 56
  }'

Response:

{
  "statusCode": 200,
  "message": "Quote retrieved successfully",
  "data": {
    "quoteId": "0x592dbadfad19da6808b637c2",
    "fromToken": {
      "address": null,
      "symbol": "BNB",
      "decimals": 18
    },
    "toToken": {
      "address": "0x55d398326f99059fF775485246999027B3197955",
      "symbol": "USDT",
      "decimals": 18
    },
    "fromAmount": "100000000000000000",
    "toAmount": "28700000000000000000",
    "rate": "287.0",
    "reverseRate": "0.003484",
    "minToAmount": "28413000000000000000",
    "protocolFee": "100000000000000",
    "protocolFeeToken": {
      "address": null,
      "symbol": "BNB",
      "decimals": 18
    },
    "estimatedGas": "150000",
    "estimatedGasUsd": "1.25",
    "priceImpact": "0.15",
    "liquidityAvailable": true,
    "totalValueUsd": "28.70",
    "expiryTimestamp": 1698765432,
    "blockNumber": "24161093",
    "chainId": 56
  }
}

Token to Token Quote

// Get quote for USDT → USDC swap on BSC
const quote = await monei.evmExchange.getTokenToTokenPrice({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  outputMint: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', // USDC
  amount: '100', // 100 USDT
  chainId: 56
});

console.log('Swap 100 USDT → USDC');
console.log('Rate:', quote.rate);
console.log('Output:', quote.toAmount, 'USDC');
console.log('Min Output:', quote.minToAmount, 'USDC');
console.log('Price Impact:', quote.priceImpact + '%');

# Get token-to-token quote
quote = monei.evm_exchange.get_token_to_token_price(
    input_mint='0x55d398326f99059fF775485246999027B3197955',
    output_mint='0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
    amount='100',
    chain_id=56
)

print(f'Swap 100 USDT → USDC')
print(f'Rate: {quote.rate}')
print(f'Output: {quote.to_amount} USDC')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/price/token-to-token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputMint": "0x55d398326f99059fF775485246999027B3197955",
    "outputMint": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
    "amount": "100",
    "chainId": 56
  }'

Token to Native Quote

// Get quote for USDT → BNB swap
const quote = await monei.evmExchange.getTokenToNativePrice({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  amount: '100', // 100 USDT
  chainId: 56
});

console.log('Swap 100 USDT → BNB');
console.log('Rate:', quote.rate);
console.log('Output:', quote.toAmount, 'BNB');
console.log('Min Output:', quote.minToAmount, 'BNB');

# Get token-to-native quote
quote = monei.evm_exchange.get_token_to_native_price(
    input_mint='0x55d398326f99059fF775485246999027B3197955',
    amount='100',
    chain_id=56
)

print(f'Swap 100 USDT → BNB')
print(f'Rate: {quote.rate}')
print(f'Output: {quote.to_amount} BNB')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/price/token-to-native \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputMint": "0x55d398326f99059fF775485246999027B3197955",
    "amount": "100",
    "chainId": 56
  }'

Execute Swap

Swap Native to Token

// Swap 0.1 BNB to USDT on BSC
const swap = await monei.evmExchange.swapNativeToToken({
  outputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  amount: '0.1', // 0.1 BNB
  amountOut: '28', // Expected minimum USDT output
  chainId: 56
});

console.log('Transaction Hash:', swap.txHash);
console.log('View on BscScan:', `https://bscscan.com/tx/${swap.txHash}`);

// Wait for confirmation
await monei.evm.waitForTransaction(swap.txHash, 56);
console.log('Swap completed!');

# Execute swap
swap = monei.evm_exchange.swap_native_to_token(
    output_mint='0x55d398326f99059fF775485246999027B3197955',
    amount='0.1',
    amount_out='28',
    chain_id=56
)

print(f'Transaction Hash: {swap.tx_hash}')
print(f'Explorer: https://bscscan.com/tx/{swap.tx_hash}')

# Wait for confirmation
monei.evm.wait_for_transaction(swap.tx_hash, 56)
print('Swap completed!')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/native-to-token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outputMint": "0x55d398326f99059fF775485246999027B3197955",
    "amount": "0.1",
    "amountOut": "28",
    "chainId": 56
  }'

Response:

{
  "statusCode": 200,
  "message": "Swap executed successfully",
  "data": {
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
}

Swap Token to Token

// Swap 100 USDT to USDC on BSC
const swap = await monei.evmExchange.swapTokenToToken({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  outputMint: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', // USDC
  amount: '100',
  chainId: 56
});

console.log('Transaction Hash:', swap.txHash);
console.log('View on BscScan:', `https://bscscan.com/tx/${swap.txHash}`);

# Execute token-to-token swap
swap = monei.evm_exchange.swap_token_to_token(
    input_mint='0x55d398326f99059fF775485246999027B3197955',
    output_mint='0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
    amount='100',
    chain_id=56
)

print(f'Transaction Hash: {swap.tx_hash}')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/token-to-token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputMint": "0x55d398326f99059fF775485246999027B3197955",
    "outputMint": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
    "amount": "100",
    "chainId": 56
  }'

Swap Token to Native

// Swap 100 USDT to BNB on BSC
const swap = await monei.evmExchange.swapTokenToNative({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  amount: '100',
  chainId: 56
});

console.log('Transaction Hash:', swap.txHash);
console.log('View on BscScan:', `https://bscscan.com/tx/${swap.txHash}`);

# Execute token-to-native swap
swap = monei.evm_exchange.swap_token_to_native(
    input_mint='0x55d398326f99059fF775485246999027B3197955',
    amount='100',
    chain_id=56
)

print(f'Transaction Hash: {swap.tx_hash}')

curl -X POST https://api.monei.cc/api/v1/evm-exchange/token-to-native \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputMint": "0x55d398326f99059fF775485246999027B3197955",
    "amount": "100",
    "chainId": 56
  }'

Understanding Quote Details

Key Quote Fields

Field	Description
`quoteId`	Unique identifier for this quote (valid for ~5 minutes)
`rate`	Exchange rate (1 input token = X output tokens)
`reverseRate`	Reverse rate (1 output token = Y input tokens)
`toAmount`	Expected output amount
`minToAmount`	Minimum output after slippage (usually 0.5%)
`priceImpact`	How much this trade affects the market price
`estimatedGas`	Estimated gas cost in native token
`estimatedGasUsd`	Estimated gas cost in USD
`liquidityAvailable`	Whether sufficient liquidity exists
`expiryTimestamp`	When this quote expires (Unix timestamp)

Price Impact

Price impact shows how much your trade will move the market price:

Price Impact	Interpretation	Action
< 1%	Low impact	Safe to proceed
1% - 3%	Moderate impact	Consider splitting trade
3% - 5%	High impact	Warning recommended
> 5%	Very high impact	Split into smaller trades

// Check price impact before swapping
const quote = await monei.evmExchange.getNativeToTokenPrice({
  outputMint: tokenAddress,
  amount: '1.0',
  chainId: 56
});

const priceImpact = parseFloat(quote.priceImpact);

if (priceImpact > 5) {
  console.log('⚠️ WARNING: Very high price impact!');
  console.log('Consider splitting into smaller trades');
} else if (priceImpact > 3) {
  console.log('⚠️ High price impact:', priceImpact + '%');
} else if (priceImpact > 1) {
  console.log('ℹ️ Moderate price impact:', priceImpact + '%');
} else {
  console.log('✓ Low price impact:', priceImpact + '%');
}

# Check price impact
quote = monei.evm_exchange.get_native_to_token_price(
    output_mint=token_address,
    amount='1.0',
    chain_id=56
)

price_impact = float(quote.price_impact)

if price_impact > 5:
    print('⚠️ WARNING: Very high price impact!')
    print('Consider splitting into smaller trades')
elif price_impact > 3:
    print(f'⚠️ High price impact: {price_impact}%')
elif price_impact > 1:
    print(f'ℹ️ Moderate price impact: {price_impact}%')
else:
    print(f'✓ Low price impact: {price_impact}%')

Slippage Protection

Slippage is the difference between expected and actual output amounts. Default Slippage: 0.5% (configurable)

// Calculate minimum output with custom slippage
function calculateMinOutput(expectedOutput, slippagePercent = 0.5) {
  const slippage = 1 - (slippagePercent / 100);
  return (parseFloat(expectedOutput) * slippage).toFixed(6);
}

// Get price
const quote = await monei.evmExchange.getNativeToTokenPrice({
  outputMint: tokenAddress,
  amount: '0.1',
  chainId: 56
});

// Calculate min output with 1% slippage
const minOutput = calculateMinOutput(quote.toAmount, 1.0);

console.log('Expected Output:', quote.toAmount);
console.log('Min Output (1% slippage):', minOutput);
console.log('Default Min Output (0.5%):', quote.minToAmount);

// Execute with custom slippage
const swap = await monei.evmExchange.swapNativeToToken({
  outputMint: tokenAddress,
  amount: '0.1',
  amountOut: minOutput, // Custom min output
  chainId: 56
});

# Calculate min output with slippage
def calculate_min_output(expected_output, slippage_percent=0.5):
    slippage = 1 - (slippage_percent / 100)
    return float(expected_output) * slippage

# Get price
quote = monei.evm_exchange.get_native_to_token_price(
    output_mint=token_address,
    amount='0.1',
    chain_id=56
)

# Calculate with 1% slippage
min_output = calculate_min_output(quote.to_amount, 1.0)

print(f'Expected: {quote.to_amount}')
print(f'Min (1% slippage): {min_output}')
print(f'Default Min (0.5%): {quote.min_to_amount}')

Recommended Slippage:

Market Condition	Recommended Slippage
Stablecoin swaps	0.1% - 0.3%
Normal volatility	0.5% - 1.0%
High volatility	1.0% - 3.0%
Very low liquidity	3.0% - 5.0%

Gas Optimization

Network Comparison for Swaps

Network	Typical Swap Gas	USD Cost	Best For
Polygon	~200,000 gas	$0.05 -$ 0.20	Small/frequent swaps
BSC	~180,000 gas	$0.50 -$ 2.00	Medium swaps
Base	~150,000 gas	$1.00 -$ 3.00	Fast execution
Arbitrum	~200,000 gas	$1.00 -$ 5.00	Balanced cost/speed
Optimism	~200,000 gas	$0.50 -$ 3.00	L2 efficiency
Ethereum	~150,000 gas	$30 -$ 100	Large swaps only

Optimize Swap Costs

// Compare costs across networks
async function findBestNetwork(tokenInAddress, tokenOutAddress, amount) {
  const networks = [
    { chainId: 56, name: 'BSC' },
    { chainId: 137, name: 'Polygon' },
    { chainId: 8453, name: 'Base' },
    { chainId: 42161, name: 'Arbitrum' }
  ];
  
  const quotes = [];
  
  for (const network of networks) {
    try {
      const quote = await monei.evmExchange.getTokenToTokenPrice({
        inputMint: tokenInAddress,
        outputMint: tokenOutAddress,
        amount: amount,
        chainId: network.chainId
      });
      
      quotes.push({
        network: network.name,
        chainId: network.chainId,
        output: quote.toAmount,
        gasCostUsd: parseFloat(quote.estimatedGasUsd),
        netOutput: parseFloat(quote.toAmount) - parseFloat(quote.estimatedGasUsd)
      });
    } catch (error) {
      console.log(`${network.name}: Token not available`);
    }
  }
  
  // Sort by net output (after gas)
  quotes.sort((a, b) => b.netOutput - a.netOutput);
  
  console.log('\nNetwork Comparison:');
  quotes.forEach(q => {
    console.log(`${q.network}:`);
    console.log(`  Output: ${q.output}`);
    console.log(`  Gas Cost: $${q.gasCostUsd}`);
    console.log(`  Net: ${q.netOutput}`);
  });
  
  return quotes[0]; // Best network
}

// Find best network for swap
const best = await findBestNetwork(usdtAddress, usdcAddress, '100');
console.log(`\nBest Network: ${best.network}`);

# Compare networks
async def find_best_network(token_in, token_out, amount):
    networks = [
        {'chain_id': 56, 'name': 'BSC'},
        {'chain_id': 137, 'name': 'Polygon'},
        {'chain_id': 8453, 'name': 'Base'},
        {'chain_id': 42161, 'name': 'Arbitrum'}
    ]
    
    quotes = []
    
    for network in networks:
        try:
            quote = monei.evm_exchange.get_token_to_token_price(
                input_mint=token_in,
                output_mint=token_out,
                amount=amount,
                chain_id=network['chain_id']
            )
            
            quotes.append({
                'network': network['name'],
                'chain_id': network['chain_id'],
                'output': float(quote.to_amount),
                'gas_cost_usd': float(quote.estimated_gas_usd),
                'net_output': float(quote.to_amount) - float(quote.estimated_gas_usd)
            })
        except Exception as e:
            print(f"{network['name']}: Not available")
    
    # Sort by net output
    quotes.sort(key=lambda x: x['net_output'], reverse=True)
    
    return quotes[0]

Common Token Pairs

Stablecoin Swaps (BSC)

USDT ↔ USDC
BNB ↔ USDT
USDT ↔ BNB

// USDT to USDC
const swap = await monei.evmExchange.swapTokenToToken({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  outputMint: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', // USDC
  amount: '1000',
  chainId: 56
});

// BNB to USDT
const swap = await monei.evmExchange.swapNativeToToken({
  outputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  amount: '1.0', // 1 BNB
  amountOut: '287', // Expected USDT
  chainId: 56
});

// USDT to BNB
const swap = await monei.evmExchange.swapTokenToNative({
  inputMint: '0x55d398326f99059fF775485246999027B3197955', // USDT
  amount: '287', // 287 USDT
  chainId: 56
});

Best Practices

Always Get Quote

Get fresh quote before each swap (quotes expire in ~5 min)

Check Price Impact

Avoid swaps with high price impact (>5%)

Set Slippage

Use appropriate slippage for market conditions

Monitor Gas

Factor gas costs into swap profitability

Use Cheap Networks

Polygon/BSC for small swaps, Ethereum for large

Test Small First

Test with small amount before large swaps

Troubleshooting

Swap Failed - Slippage Exceeded

Error: Transaction reverted due to slippageCause: Actual output fell below minimum due to price movementSolution:

Increase slippage tolerance
Get fresh quote
Split into smaller trades
Try during less volatile periods

Insufficient Liquidity

Error: Not enough liquidity for swapSolutions:

Reduce swap amount
Try different network
Use more liquid token pairs (USDT/USDC)
Check DEX liquidity on explorer

Quote Expired

Error: Quote ID expired or invalidCause: Quotes are valid for ~5 minutesSolution:

Get fresh quote before swapping
Execute swap immediately after quote
Don’t reuse old quotes

High Price Impact

Warning: Price impact > 5%Recommendations:

Split into multiple smaller swaps
Use different network with more liquidity
Wait for better liquidity
Consider limit orders (if available)

Next Steps

Wallet Operations

Manage your EVM wallet

Transactions

Learn about EVM transactions

Solana Swaps

Swap tokens on Solana

Networks

Explore supported networks

​Overview

​Swap Types

Native → Token

Token → Token

Token → Native

​Get Swap Quote

​Native to Token Quote

​Token to Token Quote

​Token to Native Quote

​Execute Swap

​Swap Native to Token

​Swap Token to Token

​Swap Token to Native

​Understanding Quote Details

​Key Quote Fields

​Price Impact

​Slippage Protection

​Gas Optimization

​Network Comparison for Swaps

​Optimize Swap Costs

​Common Token Pairs

​Stablecoin Swaps (BSC)

​Best Practices