Get Swap Quoting - Mobula API

Overview

The Swap Quoting endpoint provides swap quotes with optimized routing across multiple DEXs and liquidity sources. It returns the estimated output amount, slippage, and a serialized transaction ready to be signed.

Query Parameters

chainId (required) — The blockchain identifier (e.g., evm:1, solana, ethereum)
tokenIn (required) — Address of the token to swap from (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens)
tokenOut (required) — Address of the token to swap to (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens)
amount (required if amountRaw not provided) — Human-readable amount of tokenIn to swap (e.g., "1.5" for 1.5 tokens). This will be converted to raw amount by multiplying by 10^decimals.
amountRaw (required if amount not provided) — Raw amount as a string (e.g., "1500000" for 1.5 USDC with 6 decimals). This is the exact amount that will be used in the swap without conversion. Must be a positive integer string.
walletAddress (required) — Wallet address that will execute the swap
slippage (optional) — Maximum acceptable slippage percentage (0-100). Default: 1
excludedProtocols (optional) — Comma-separated list of factory addresses to exclude from routing. Can be any factory address.
onlyProtocols (optional) — Comma-separated list of tradable pool types to restrict routing to (e.g., uniswap-v2, uniswap-v3, raydium-amm). Only valid tradable pool types will be considered; non-tradable types will be filtered out.
poolAddress (optional) — Specific pool address to use for the swap
onlyRouters (optional) — Comma-separated list of routers to use for routing (e.g., jupiter, kyberswap, lifi). Only the specified routers will be used for the swap. Supported values: jupiter (Solana), kyberswap (EVM), lifi (EVM)
feePercentage (optional) — Fee percentage to charge on the swap (0.01 to 99). Default: 0 (no fee).
- On EVM chains: Fee is applied to the swap via MobulaRouter. No feeWallet required - fees go to the protocol.
- On Solana: Fee is taken from SOL/WSOL (the native token). Must be provided together with feeWallet.
feeWallet (optional, Solana only) — Wallet address to receive fees. Must be a valid Solana wallet address. Only required on Solana when feePercentage is set.

Amount Specification

Either amount OR amountRaw must be provided (but not both).

Understanding Token Decimals

Tokens have a decimals property that determines how many decimal places they support:

ETH/WETH: 18 decimals
USDC: 6 decimals
USDT: 6 decimals
BTC: 8 decimals

The relationship between human-readable amount and raw amount is:

raw amount = human-readable amount × 10^decimals

Examples:

For USDC (6 decimals): amount="1.5" becomes 1500000 raw units
For ETH (18 decimals): amount="0.0001" becomes 100000000000000 raw units (1e14)
For USDC (6 decimals): amountRaw="1500000" represents 1.5 USDC

When to use amount:

You have a human-readable amount (e.g., “1.5” tokens)
You want the API to handle the conversion automatically
Simpler for most use cases

When to use amountRaw:

You already have the raw amount from another source
You want to avoid precision loss from floating-point conversion
You need exact control over the amount being swapped

Fees

Fees allow you to charge a percentage fee on swaps. This is useful for monetizing your integration. How it works:

On EVM chains: Fee is applied via MobulaRouter. Default is 0% (no fee).
On Solana: Fee is taken from SOL/WSOL and sent to your designated feeWallet.

Requirements:

Fee percentage must be between 0.01% and 99%

Usage Examples

Basic Swap Quote with Native SOL (Human-readable Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=So11111111111111111111111111111111111111111&tokenOut=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1&walletAddress=YourWalletAddress&slippage=1"

Basic Swap Quote with Native SOL (Raw Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=So11111111111111111111111111111111111111111&tokenOut=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amountRaw=1000000000&walletAddress=YourWalletAddress&slippage=1"

Swap with Excluded Protocols (Human-readable Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=ethereum&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amount=1&walletAddress=0xYourWalletAddress&slippage=2&excludedProtocols=uniswap-v2,sushiswap"

Swap with Excluded Protocols (Raw Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=ethereum&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amountRaw=1000000000000000000&walletAddress=0xYourWalletAddress&slippage=2&excludedProtocols=uniswap-v2,sushiswap"

Swap with Specific Pool Type (Human-readable Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=evm:1&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xdAC17F958D2ee523a2206206994597C13D831ec7&amount=0.5&walletAddress=0xYourWalletAddress&onlyProtocols=uniswap-v3"

Swap with Specific Pool Type (Raw Amount)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=evm:1&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xdAC17F958D2ee523a2206206994597C13D831ec7&amountRaw=500000000000000000&walletAddress=0xYourWalletAddress&onlyProtocols=uniswap-v3"

Swap with Specific Router (Solana - Jupiter)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=So11111111111111111111111111111111111111111&tokenOut=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1&walletAddress=YourWalletAddress&onlyRouters=jupiter"

Swap with Specific Router (EVM - KyberSwap)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=evm:1&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amount=1&walletAddress=0xYourWalletAddress&onlyRouters=kyberswap"

Swap with Multiple Routers (EVM - KyberSwap and LiFi)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=evm:1&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amount=1&walletAddress=0xYourWalletAddress&onlyRouters=kyberswap,lifi"

Swap with Fee (EVM)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=evm:1&tokenIn=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amount=1&walletAddress=0xYourWalletAddress&feePercentage=0.5"

This example charges a 0.5% fee on an EVM swap:

Fee is applied via MobulaRouter

Swap with Fee (Buy - SOL to Token)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=So11111111111111111111111111111111111111111&tokenOut=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1&walletAddress=YourWalletAddress&slippage=1&feePercentage=1&feeWallet=FeeWalletAddressHere"

This example charges a 1% fee on SOL (quote token) for a buy order:

User inputs: 1 SOL (SOL is the quote token)
Fee sent to fee wallet: 0.01 SOL
Amount used for swap: 0.99 SOL
User receives: full swap output in USDC

Swap with Fee (Sell - Token to SOL)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&tokenOut=So11111111111111111111111111111111111111111&amount=100&walletAddress=YourWalletAddress&slippage=1&feePercentage=0.5&feeWallet=FeeWalletAddressHere"

This example charges a 0.5% fee on SOL (quote token) after the swap:

User inputs: 100 USDC (USDC is a stablecoin, but SOL is also a quote token)
If USDC is detected as the quote → Fee on input: 0.5 USDC → 99.5 USDC swapped
If SOL is detected as the quote → Fee on output: 0.5% of output SOL goes to fee wallet

Swap with Fee (Meme Token to SOL)

curl -X GET "https://api.mobula.io/api/2/swap/quoting?chainId=solana&tokenIn=MemeTokenAddress&tokenOut=So11111111111111111111111111111111111111111&amount=1000000&walletAddress=YourWalletAddress&slippage=5&feePercentage=1&feeWallet=FeeWalletAddressHere"

This example charges a 1% fee on SOL (quote token) after the swap:

User inputs: 1,000,000 MEME tokens (MEME is base token)
Full amount used for swap
Fee on output: 1% of output SOL (weighted by slippage) sent to fee wallet
User receives: remaining SOL after fee

Response Format

Supports both Solana and EVM chains (Ethereum, Arbitrum, Base, etc.).

Solana Response

{
  "data": {
    "solana": {
      "transaction": {
        "serialized": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDMzMzMzMzMzMzMzMzMzMzMzMzMzMz...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 305123456
    },
    "estimatedAmountOut": "99500000",
    "estimatedSlippage": 0.5,
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response Fields

Data Object

For Solana:

solana (object, optional) — Solana transaction container
- transaction (object) — Transaction details
  - serialized (string) — Base64 encoded serialized transaction
  - variant (enum: legacy | versioned) — Transaction variant
- lastValidBlockHeight (number) — The last block height at which the blockhash used in this transaction is valid. Use this to check if the transaction has expired before sending.

Common Fields:

estimatedAmountOut (string, optional) — Estimated output amount in tokenOut’s base units
estimatedSlippage (number, optional) — Estimated slippage percentage
requestId (string) — Unique identifier for tracking this request. Keep this ID and provide it to the Mobula team if you encounter any issues.
fee (object, optional) — Fee details (only present if fee was applied)
- amount (string) — Fee amount in human-readable format
- percentage (number) — Fee percentage that was applied
- wallet (string) — Wallet address receiving the fee
- deductedFrom (enum: input | output) — Whether fee was deducted from input (buy) or output (sell)

Error Field

error (string, optional) — Error message if the quote failed. If you receive an error, please report it to the Mobula team along with the requestId for faster resolution.

Example Responses

Successful Solana Swap Quote

{
  "data": {
    "solana": {
      "transaction": {
        "serialized": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDMzMzMzMzMzMzMzMzMzMzMzMzMzMz...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 305123456
    },
    "estimatedAmountOut": "99750000",
    "estimatedSlippage": 0.25,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Successful Swap Quote with Fee (Buy)

{
  "data": {
    "solana": {
      "transaction": {
        "serialized": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDMzMzMzMzMzMzMzMzMzMzMzMzMzMz...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 305123456
    },
    "estimatedAmountOut": "148500000",
    "estimatedSlippage": 1.0,
    "requestId": "880e8400-e29b-41d4-a716-446655440003",
    "fee": {
      "amount": "0.01",
      "percentage": 1,
      "wallet": "FeeWalletAddress111111111111111111111111111",
      "deductedFrom": "input"
    }
  }
}

Successful Swap Quote with Fee (Sell)

{
  "data": {
    "solana": {
      "transaction": {
        "serialized": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDMzMzMzMzMzMzMzMzMzMzMzMzMzMz...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 305123456
    },
    "estimatedAmountOut": "985050000",
    "estimatedSlippage": 1.0,
    "requestId": "990e8400-e29b-41d4-a716-446655440004",
    "fee": {
      "amount": "0.0049005",
      "percentage": 0.5,
      "wallet": "FeeWalletAddress111111111111111111111111111",
      "deductedFrom": "output"
    }
  }
}

Quote with Error

{
  "data": {
    "estimatedAmountOut": "0",
    "estimatedSlippage": 5.0,
    "requestId": "770e8400-e29b-41d4-a716-446655440002"
  },
  "error": "Insufficient liquidity for the requested swap amount"
}

Important Notes

Native Token Address:
- EVM chains: Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens (ETH, BNB, MATIC, etc.)
- Solana:
  - Use So11111111111111111111111111111111111111111 for native SOL (ends with 1) - this is what users typically hold in their wallet
  - So11111111111111111111111111111111111111112 (ends with 2) is Wrapped SOL (WSOL) - only use this if you specifically hold WSOL tokens
  - Automatic wrap/unwrap: If you use the native SOL address, we automatically handle the wrapping and unwrapping internally. You don’t need to manage WSOL yourself
Amount Format:
- Use amount for human-readable amounts (e.g., "1.5" for 1.5 tokens). The API will automatically convert to raw units using the token’s decimals.
- Use amountRaw for raw amounts as a string (e.g., "1500000" for 1.5 USDC with 6 decimals). This avoids precision loss and is useful when you already have the raw amount.
- Either amount OR amountRaw must be provided, but not both.
Token Decimals: Each token has a decimals property (typically 18 for ETH, 6 for USDC, 8 for BTC). Raw amount = human-readable amount × 10^decimals. For example, 1.5 USDC (6 decimals) = 1,500,000 raw units.
Blockchain Support: Supports both Solana and EVM chains (Ethereum, Arbitrum, Base, Optimism, etc.).
Solana Transactions: Base64 encoded and ready to be deserialized, signed, and sent
Slippage: Higher slippage increases success rate but may result in worse execution prices
Request ID: Always keep the requestId from the response. In case of any issues or errors, provide this ID to the Mobula team for faster troubleshooting and resolution.
onlyProtocols Behavior: This parameter only restricts routing to a subset of tradable pool types. Non-tradable pool types will be automatically filtered out. You cannot extend beyond the base set of tradable protocols.
excludedProtocols Behavior: You can specify any factory address to exclude from routing, regardless of whether it’s tradable or not.
onlyRouters Behavior: Restricts the swap routing to specific providers. Supported routers are: jupiter (Solana only), kyberswap (EVM chains), and lifi (EVM chains). You can specify multiple routers by separating them with commas. If not specified, all available routers for the chain will be used.
Fee Behavior:
- Fee percentage must be between 0.01% and 99%. Default is 0% (no fee).
- On EVM chains: Fee is applied via MobulaRouter
- On Solana: Both feePercentage and feeWallet must be provided together:
  - Fee is ALWAYS deducted from SOL/WSOL (the native token) for maximum extraction
  - If tokenIn is SOL/WSOL → Fee is deducted from input before the swap
  - If tokenOut is SOL/WSOL → Fee is deducted from output after the swap (weighted by slippage)
  - If neither token is SOL → Fallback to quote token logic (stablecoins first)
  - The fee transfer is included in the same transaction as the swap, so it’s atomic

Next Steps

For Solana Transactions

After receiving a quote:

Save the requestId for troubleshooting purposes
Decode the base64 serialized transaction
Deserialize based on the variant field (legacy or versioned)
Sign it with your Solana wallet
Send to the network using your preferred RPC

Example:

const { solana, requestId } = response.data;

// Save requestId for support
console.log('Request ID:', requestId);

const txBuffer = Buffer.from(solana.transaction.serialized, 'base64');
const { lastValidBlockHeight } = solana;

if (solana.transaction.variant === 'versioned') {
  const tx = VersionedTransaction.deserialize(txBuffer);
  tx.sign([wallet]);
  
  // Send with confirmation using lastValidBlockHeight
  const signature = await connection.sendTransaction(tx);
  await connection.confirmTransaction({
    signature,
    blockhash: tx.message.recentBlockhash,
    lastValidBlockHeight,
  });
  console.log('Transaction confirmed:', signature);
} else {
  const tx = Transaction.from(txBuffer);
  tx.partialSign(wallet);
  
  // Send with confirmation using lastValidBlockHeight
  const signature = await connection.sendTransaction(tx);
  await connection.confirmTransaction({
    signature,
    blockhash: tx.recentBlockhash,
    lastValidBlockHeight,
  });
  console.log('Transaction confirmed:', signature);
}

For EVM Transactions

After receiving a quote:

Save the requestId for troubleshooting purposes
The response contains a ready-to-sign transaction in evm field
Sign and send it using your preferred web3 library (ethers.js, viem, web3.js)

Example:

const { evm, requestId } = response.data;

// Save requestId for support
console.log('Request ID:', requestId);

// Using ethers.js
const tx = await signer.sendTransaction({
  to: evm.to,
  from: evm.from,
  data: evm.data,
  value: evm.value,
  chainId: evm.chainId,
});

await tx.wait();
console.log('Transaction confirmed:', tx.hash);

Use Cases

DEX Aggregation: Get the best swap rates across multiple DEXs
Trading Bots: Automated trading with optimal routing
DeFi Applications: Integrate swap functionality into your dApp
Price Comparison: Compare swap rates before execution

Query Parameters

chainId

string

required

The blockchain identifier (e.g., evm:1, solana, ethereum)

tokenIn

string

required

Address of the token to swap from (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens)

tokenOut

string

required

Address of the token to swap to (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens)

amount

string

Human-readable amount of tokenIn to swap (e.g., "1.5" for 1.5 tokens). Will be converted to raw amount by multiplying by 10^decimals. Either amount or amountRaw must be provided (but not both).

amountRaw

string

Raw amount as a string (e.g., "1500000" for 1.5 USDC with 6 decimals). This is the exact amount that will be used in the swap without conversion. Must be a positive integer string. Either amount or amountRaw must be provided (but not both).

walletAddress

string

required

Wallet address that will execute the swap

slippage

string

default:1

Maximum acceptable slippage percentage (0-100)

excludedProtocols

string

Comma-separated list of factory addresses to exclude from routing. Can be any factory address.

onlyProtocols

string

Comma-separated list of tradable pool types to restrict routing to (e.g., uniswap-v2, uniswap-v3, raydium-amm). Only valid tradable pool types will be considered; non-tradable types will be filtered out.

poolAddress

string

Specific pool address to use for the swap

Response

200 - application/json

Swap quote response

data

object

required

Show child attributes

data.requestId

string

required

Unique identifier for the request

data.transaction

object

Show child attributes

data.transaction.serialized

string

required

Base64 encoded serialized transaction

data.transaction.type

enum<string>

required

Transaction type

Available options:

legacy,

versioned

data.estimatedAmountOut

string | null

Estimated output amount in tokenOut's base units

data.estimatedSlippage

number | null

Estimated slippage percentage

error

string | null

Error message if the quote failed

Introduction

Market & Token Data

History - Prices & OHLCV Candles

Trades Data

Holders Data

Pulse API

Wallet Explorer API

Swap API

Metacore

Webhook

Misc

​Overview

​Query Parameters

​Amount Specification

​Understanding Token Decimals

​Fees

​Usage Examples

​Basic Swap Quote with Native SOL (Human-readable Amount)

​Basic Swap Quote with Native SOL (Raw Amount)

​Swap with Excluded Protocols (Human-readable Amount)

​Swap with Excluded Protocols (Raw Amount)

​Swap with Specific Pool Type (Human-readable Amount)

​Swap with Specific Pool Type (Raw Amount)

​Swap with Specific Router (Solana - Jupiter)

​Swap with Specific Router (EVM - KyberSwap)

​Swap with Multiple Routers (EVM - KyberSwap and LiFi)

​Swap with Fee (EVM)

​Swap with Fee (Buy - SOL to Token)

​Swap with Fee (Sell - Token to SOL)

​Swap with Fee (Meme Token to SOL)

​Response Format

​Solana Response

​Response Fields

​Data Object

​Error Field

​Example Responses

​Successful Solana Swap Quote

​Successful Swap Quote with Fee (Buy)

​Successful Swap Quote with Fee (Sell)

​Quote with Error

​Important Notes

​Next Steps

​For Solana Transactions

​For EVM Transactions

​Use Cases

Query Parameters

Response

Overview

Query Parameters

Amount Specification

Understanding Token Decimals

Fees

Usage Examples

Basic Swap Quote with Native SOL (Human-readable Amount)

Basic Swap Quote with Native SOL (Raw Amount)

Swap with Excluded Protocols (Human-readable Amount)

Swap with Excluded Protocols (Raw Amount)

Swap with Specific Pool Type (Human-readable Amount)

Swap with Specific Pool Type (Raw Amount)

Swap with Specific Router (Solana - Jupiter)

Swap with Specific Router (EVM - KyberSwap)

Swap with Multiple Routers (EVM - KyberSwap and LiFi)

Swap with Fee (EVM)

Swap with Fee (Buy - SOL to Token)

Swap with Fee (Sell - Token to SOL)

Swap with Fee (Meme Token to SOL)

Response Format

Solana Response

Response Fields

Data Object

Error Field

Example Responses

Successful Solana Swap Quote

Successful Swap Quote with Fee (Buy)

Successful Swap Quote with Fee (Sell)

Quote with Error

Important Notes

Next Steps

For Solana Transactions

For EVM Transactions

Use Cases