Skip to main content
GET
Get swap quote with transaction details
GET /api/2/swap/quoting returns the cheapest route for a token-in → token-out trade plus the calldata to execute it. Same envelope across chains; per-chain extension under data.evm / data.solana / data.ton.

EVM

Ethereum, Base, Arbitrum, BNB Chain, Polygon + 25 chains

Solana

Jupiter, Raydium, Orca, Meteora, Pump.fun + multi-lander

TON

Stonfi v2, DeDust v2, pTON v2 — multi-message envelope

Arguments

Required

ParamTypeDescription
chainIdstringevm:<N> (e.g. evm:8453), solana:solana, or ton:mainnet
tokenInstringSell token address. Native sentinel varies per chain (see below).
tokenOutstringBuy token address
amount or amountRawstringEither the human amount ("1.5") or the raw amount ("1500000"). Exactly one.
walletAddressstringThe user’s address (used as recipient + fee context)

Common optional

ParamTypeDefaultDescription
slippagestringauto% value (0-100) or auto
feePercentagestring %Caller referral fee 0-99% (Mobula skims 20% off the top)
feeWalletstringRequired when feePercentage > 0
minFeesNativestringMinimum caller referral fee in the chain’s native token. Honored on TON native-input swaps and on Solana when the fee asset is native SOL (enforced on-chain by MobulaRouter).
feeTokenstringSolana only. Mint of a token to charge a flat minimum fee in (with minFeesTokenRaw), via a dedicated transfer to feeWallet, independent of the route.
minFeesTokenRawstringSolana only. Raw amount (smallest unit) of feeToken to charge. Tx reverts if balance is insufficient.
excludedProtocolscsv stringDEX-level deny list (e.g. pump-amm,raydium)
onlyProtocolscsv stringDEX-level allow list
onlyRouterscsv stringAggregator filter — jupiter, kyberswap, lifi, naos
poolAddressstringPin routing to a single pool

Solana-only

ParamDescription
prioritizationFeeLamportsJupiter-compatible priority fee budget: auto, fixed lamports, or {"priorityLevelWithMaxLamports":{"priorityLevel":"medium" | "high" | "veryHigh","maxLamports":1000000,"global":false}}
dynamicComputeUnitLimitSolana only. true by default; dynamically sizes the compute limit from the built swap instructions
jitoTipLamportsAdds a Jito tip transfer for fast landing
multiLandertrue returns N candidates over a durable nonce
landerTipLamportsPer-lander tip when multiLander=true
payerAddressFee abstraction — separate fee payer from walletAddress. The payer signs and pays Solana fees / ATA rent; swap funds still come from walletAddress.
closeAuthorityClose authority for non-WSOL ATAs Mobula creates during the swap when payerAddress is used. Usually set it to the central payer wallet to reclaim rent later.
destinationWalletOptional Solana tokenOut recipient. Do not combine with finalRecipientWallet.
swapRecipientAddressRouter-enforced final output recipient. MobulaRouter transfers the exact final swap output to this wallet after swap execution and fee/slippage checks. Legacy alias: finalRecipientWallet.

Native sentinel addresses

ChainSentinel
EVM0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
Solana native SOLSo11111111111111111111111111111111111111111
Solana WSOL SPL mintSo11111111111111111111111111111111111111112
TONEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c

Response

Exactly one of evm / solana / ton is populated, the others are null. See the per-chain pages above for the calldata shape.

Common fields (every chain)

FieldTypeDescription
amountOutTokensstringEstimated output, human-readable
amountInUSD / amountOutUSDnumberUSD value at quote time
slippagePercentagenumberEcho of the input parameter
marketImpactPercentagenumberEstimated price impact at this trade size
poolFeesPercentagenumberSum of LP fees paid across the route
tokenIn / tokenOutobject{address, symbol?, name?, decimals, logo?}
requestIdstringUnique per quote — pass to support / analytics
details.route.hops[]arrayOne entry per pool used (multi-hop)
details.route.aggregatorstringWhich aggregator picked the route
feeobject?Echoed when feePercentage was set: {amount, percentage, wallet, deductedFrom: 'input'|'output'}

Chain-specific calldata

The data.evm, data.solana, data.ton blocks carry the chain-specific transaction shape:
ChainBlockShape
EVMdata.evm.transaction{ to, from, data, value, gasLimit?, chainId, approvalAddress?, approvals[]? } — see EVM Quoting
Solanadata.solana.transaction + lastValidBlockHeight{ serialized: base64, variant: 'versioned' | 'legacy' } — see Solana Quoting
TONdata.ton.transactions[1..4] + data.ton.fees{ to, value, body, bounce, stateInit? }[] — see TON Quoting
When multiLander=true (Solana only), data.candidates[] replaces data.solana.transaction — see the Solana page.

Quick example

Sign + broadcast via the /swap/send endpoint, or — for EVM — directly from your wallet.

Errors

200 with data: null, error: "<message>" for routing failures (no route, slippage too tight, …). 4xx for validation, 5xx for upstream RPC issues. The requestId field always survives — include it when reporting issues.

Query Parameters

chainId
string

Mobula chain id. EVM: evm:<integer> (e.g. evm:1, evm:8453, evm:42161). Solana: solana:solana. TON: ton:mainnet or ton:testnet.

tokenIn
string
required

Sell token address. Native identifiers — EVM: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (EIP-7528). Solana native SOL: So11111111111111111111111111111111111111111. Use wrapped SOL / WSOL mint So11111111111111111111111111111111111111112 only when swapping WSOL token-account balance. TON: EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c.

Minimum string length: 1
tokenOut
string
required

Buy token address. Same native identifier rules as tokenIn.

Minimum string length: 1
amount
string

Human-readable amount (e.g. "1.5" for 1.5 tokens). Converted server-side: raw = amount × 10^decimals. Mutually exclusive with amountRaw.

amountRaw
string

Raw amount as a digit-only string (e.g. "1500000" for 1.5 USDC at 6 decimals). Use this when you already have the bigint to avoid float precision loss. Mutually exclusive with amount.

amountUSD

USD value of tokenIn to spend. Resolved server-side from the live weighted token price. Mutually exclusive with amount and amountRaw.

slippage

auto (default) lets the router choose adaptive slippage. A number is a fixed slippage tolerance in % (0-100).

maxMarketImpactPercentage

Optional market impact guard in %. If the computed marketImpactPercentage is greater than this value, the quote is rejected with HTTP 400.

walletAddress
string
required

User wallet address — signer/source wallet for the swap.

Minimum string length: 1
destinationWallet
string

Solana only. Optional wallet that receives tokenOut. Defaults to walletAddress. Native SOL output is not supported yet with a separate destination wallet.

finalRecipientWallet
string

Deprecated Solana alias for swapRecipientAddress; kept for backward compatibility.

swapRecipientAddress
string

Solana only. Optional wallet that receives the exact final output after the Mobula on-chain router executes the swap and fee/slippage checks. For SPL outputs, Mobula creates the recipient ATA idempotently and closes router-created temporary output accounts when empty. Cannot be combined with destinationWallet.

excludedProtocols

DEX-level deny list (CSV). Example: pump-amm,raydium.

onlyProtocols

DEX-level allow list (CSV). Example: uniswap-v3,uniswap-v4.

poolAddress
string

Pin routing to a single pool (e.g. when you want a specific Uniswap V3 fee tier).

onlyRouters
string

Aggregator filter (CSV) — jupiter, kyberswap, lifi, naos. Omit to let the API pick.

prioritizationFeeLamports
any | null

Solana only. Jupiter-compatible priority fee budget. Use auto, a fixed lamport amount, or { "priorityLevelWithMaxLamports": { "priorityLevel": "medium" | "high" | "veryHigh", "maxLamports": 1000000, "global": false } }.

dynamicComputeUnitLimit
string

Solana only. Dynamically sizes the compute unit limit from the assembled swap instructions. Default: true.

jitoTipLamports
string

Solana only. Jito tip in lamports — adds a transfer to one of the Jito tip accounts for fast landing.

feePercentage

Caller referral fee in % (0-99). Mobula skims a 20% platform cut off the top. Requires feeWallet.

feeWallet
string

Wallet that receives the caller referral fee. Required when feePercentage > 0.

minFeesNative

Minimum caller referral fee in native-token units (TON, or SOL on Solana). Floors the referral fee; honored when the fee asset is the native token. Currently honored on TON native-input swaps; requires feeWallet.

feeToken
string

Solana only. Mint of a token in which to charge a flat MINIMUM fee (paired with minFeesTokenRaw). Charged via a separate transfer to feeWallet, independent of the swap route. Requires feeWallet.

minFeesTokenRaw

Solana only. Raw amount (smallest unit) of feeToken to charge as a flat minimum fee. The swap reverts if the user lacks balance.

payerAddress
string

Solana only. Fee abstraction — separate fee payer from walletAddress. When different, both wallets sign; payerAddress pays transaction fees, priority/Jito tips, and ATA rent for accounts Mobula creates.

closeAuthority
string

Solana only. Optional close authority for non-WSOL ATAs Mobula creates during the swap when payerAddress is used. If omitted, walletAddress remains the close authority. Ignored when no separate payerAddress is provided.

multiLander
string

Solana only. true returns N candidate transactions over a durable nonce — race them across landers (Jito, Nozomi, 0slot). Only one commits.

landerTipLamports
string

Per-lander tip when multiLander=true. Defaults to each lander's minimum.

onlyVerifiedTokens
string

When true, reject quotes involving unverified launchpad tokens.

Response

Swap quoting response

data
object
required
error
string

Set on routing failures (no route, slippage too tight, upstream timeout). The data block still carries requestId for support.