Swap Quoting - Mobula API

Get swap quote with transaction details

curl --request GET \
  --url https://demo-api.mobula.io/api/2/swap/quoting

{
  "data": {
    "requestId": "<string>",
    "solana": {
      "transaction": {
        "serialized": "AQABAuObQ8Adqk1eqZxRMJg4r6vGtXq9k0...base64...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 269450123
    },
    "amountOutTokens": "245.123",
    "slippagePercentage": 1,
    "amountInUSD": 200.45,
    "amountOutUSD": 199.87,
    "marketImpactPercentage": 0.04,
    "poolFeesPercentage": 0.25,
    "tokenIn": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "name": "USD Coin",
      "symbol": "USDC",
      "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
    },
    "tokenOut": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "name": "USD Coin",
      "symbol": "USDC",
      "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
    },
    "details": {
      "route": {
        "hops": [
          {
            "poolAddress": "<string>",
            "tokenIn": {
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "decimals": 6,
              "name": "USD Coin",
              "symbol": "USDC",
              "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
            },
            "tokenOut": {
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "decimals": 6,
              "name": "USD Coin",
              "symbol": "USDC",
              "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
            },
            "amountInTokens": "1.0",
            "amountOutTokens": "245.1",
            "exchange": "Raydium",
            "poolType": "CLMM",
            "feePercentage": 0.25,
            "feeBps": 25
          }
        ],
        "totalFeePercentage": 0.25,
        "aggregator": "jupiter"
      },
      "aggregator": "<string>",
      "raw": {}
    },
    "fee": {
      "amount": "0.001",
      "percentage": 0.5,
      "wallet": "0xCALLER…",
      "deductedFrom": "input"
    },
    "evm": null,
    "ton": null
  },
  "error": "<string>"
}

GET

swap

quoting

Get swap quote with transaction details

curl --request GET \
  --url https://demo-api.mobula.io/api/2/swap/quoting

{
  "data": {
    "requestId": "<string>",
    "solana": {
      "transaction": {
        "serialized": "AQABAuObQ8Adqk1eqZxRMJg4r6vGtXq9k0...base64...",
        "variant": "versioned"
      },
      "lastValidBlockHeight": 269450123
    },
    "amountOutTokens": "245.123",
    "slippagePercentage": 1,
    "amountInUSD": 200.45,
    "amountOutUSD": 199.87,
    "marketImpactPercentage": 0.04,
    "poolFeesPercentage": 0.25,
    "tokenIn": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "name": "USD Coin",
      "symbol": "USDC",
      "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
    },
    "tokenOut": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "name": "USD Coin",
      "symbol": "USDC",
      "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
    },
    "details": {
      "route": {
        "hops": [
          {
            "poolAddress": "<string>",
            "tokenIn": {
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "decimals": 6,
              "name": "USD Coin",
              "symbol": "USDC",
              "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
            },
            "tokenOut": {
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "decimals": 6,
              "name": "USD Coin",
              "symbol": "USDC",
              "logo": "https://metadata.mobula.io/assets/logos/evm_8453_0x8335…"
            },
            "amountInTokens": "1.0",
            "amountOutTokens": "245.1",
            "exchange": "Raydium",
            "poolType": "CLMM",
            "feePercentage": 0.25,
            "feeBps": 25
          }
        ],
        "totalFeePercentage": 0.25,
        "aggregator": "jupiter"
      },
      "aggregator": "<string>",
      "raw": {}
    },
    "fee": {
      "amount": "0.001",
      "percentage": 0.5,
      "wallet": "0xCALLER…",
      "deductedFrom": "input"
    },
    "evm": null,
    "ton": null
  },
  "error": "<string>"
}

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

Param	Type	Description
`chainId`	string	`evm:<N>` (e.g. `evm:8453`), `solana:solana`, or `ton:mainnet`
`tokenIn`	string	Sell token address. Native sentinel varies per chain (see below).
`tokenOut`	string	Buy token address
`amount` or `amountRaw`	string	Either the human amount (`"1.5"`) or the raw amount (`"1500000"`). Exactly one.
`walletAddress`	string	The user’s address (used as recipient + fee context)

Common optional

Param	Type	Default	Description
`slippage`	string %	`1`	0-100
`feePercentage`	string %	–	Caller referral fee 0-99% (Mobula skims 20% off the top)
`feeWallet`	string	–	Required when `feePercentage > 0`
`minFeesNative`	string	–	Minimum caller referral fee in the chain’s native token. Currently honored on TON native-input swaps.
`excludedProtocols`	csv string	–	DEX-level deny list (e.g. `pump-amm,raydium`)
`onlyProtocols`	csv string	–	DEX-level allow list
`onlyRouters`	csv string	–	Aggregator filter — `jupiter`, `kyberswap`, `lifi`, `naos`
`poolAddress`	string	–	Pin routing to a single pool

Solana-only

Param	Description
`priorityFee`	`auto` / `low` / `medium` / `high` / `veryHigh` / microLamports number
`computeUnitLimit`	`true` (dynamic) or fixed CU (default 400 000)
`jitoTipLamports`	Adds a Jito tip transfer for fast landing
`multiLander`	`true` returns N candidates over a durable nonce
`landerTipLamports`	Per-lander tip when `multiLander=true`
`payerAddress`	Fee abstraction — separate fee payer from `walletAddress`

Native sentinel addresses

Chain	Sentinel
EVM	`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`
Solana	`So11111111111111111111111111111111111111112`
TON	`EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c`

Response

{
  "data": {
    "amountOutTokens": "245.123",
    "amountInUSD": 200.45,
    "amountOutUSD": 199.87,
    "slippagePercentage": 1,
    "marketImpactPercentage": 0.04,
    "poolFeesPercentage": 0.25,
    "tokenIn":  { "address": "…", "symbol": "…", "decimals": 9, "logo": "…" },
    "tokenOut": { "address": "…", "symbol": "…", "decimals": 6, "logo": "…" },
    "requestId": "f8b2…",
    "details": {
      "route": {
        "hops": [
          { "poolAddress": "…", "tokenIn": { /* … */ }, "tokenOut": { /* … */ }, "amountInTokens": "1.0", "amountOutTokens": "245.1", "exchange": "Raydium", "poolType": "CLMM", "feeBps": 25 }
        ],
        "totalFeePercentage": 0.25,
        "aggregator": "jupiter"
      }
    },
    "fee": { "amount": "0.001", "percentage": 0.5, "wallet": "…", "deductedFrom": "input" },
    "evm":    null,
    "solana": { /* … */ },
    "ton":    null
  }
}

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)

Field	Type	Description
`amountOutTokens`	string	Estimated output, human-readable
`amountInUSD` / `amountOutUSD`	number	USD value at quote time
`slippagePercentage`	number	Echo of the input parameter
`marketImpactPercentage`	number	Estimated price impact at this trade size
`poolFeesPercentage`	number	Sum of LP fees paid across the route
`tokenIn` / `tokenOut`	object	`{address, symbol?, name?, decimals, logo?}`
`requestId`	string	Unique per quote — pass to support / analytics
`details.route.hops[]`	array	One entry per pool used (multi-hop)
`details.route.aggregator`	string	Which aggregator picked the route
`fee`	object?	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:

Chain	Block	Shape
EVM	`data.evm.transaction`	`{ to, from, data, value, gasLimit?, chainId, approvalAddress?, approvals[]? }` — see EVM Quoting
Solana	`data.solana.transaction` + `lastValidBlockHeight`	`{ serialized: base64, variant: 'versioned' \| 'legacy' }` — see Solana Quoting
TON	`data.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

const r = await fetch(
  `https://api.mobula.io/api/2/swap/quoting?` + new URLSearchParams({
    chainId: 'evm:8453',
    tokenIn:  '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
    tokenOut: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    amount:   '0.1',
    walletAddress: '0xUSER…',
    slippage: '1',
  }),
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } },
);
const quote = await r.json();

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 sentinels — EVM: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (EIP-7528). Solana: So11111111111111111111111111111111111111112 (wSOL). TON: EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c.

Minimum string length: 1

tokenOut

string

required

Buy token address. Same sentinel 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.

slippage

string

Slippage tolerance in % (0-100, default 1). Quote rejects if expected output drops below this threshold.

walletAddress

string

required

User wallet address — recipient of tokenOut, signer for the broadcast tx, fee context.

Minimum string length: 1

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.

priorityFee

string

Solana only. auto, low, medium, high, veryHigh, or microLamports per CU as a number string.

computeUnitLimit

string

Solana only. true for dynamic CU limit, or a fixed integer (default 400 000).

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. Currently honored on TON native-input swaps; requires feeWallet.

payerAddress

string

Solana only. Fee abstraction — wallet that signs/pays for the tx (separate from walletAddress).

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.

Response

Swap quoting response

data

object

required

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

error

string

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

Get first buyers for a token EVM Swap Quoting

⌘I

Documentation Index

EVM

Solana

TON

​Arguments

​Required

​Common optional

​Solana-only

​Native sentinel addresses

​Response

​Common fields (every chain)

​Chain-specific calldata

​Quick example

​Errors

Query Parameters

Response

Arguments

Required

Common optional

Solana-only

Native sentinel addresses

Response

Common fields (every chain)

Chain-specific calldata

Quick example

Errors