Swap Instructions
Get swap instructions for Solana that allow you to build custom transactions with your own instructions (e.g., Jito tips, fee transfers).
Overview
The Swap Instructions endpoint returns individual Solana instructions instead of a serialized transaction. This allows you to:- Add your own instructions (e.g., Jito tips, custom fee transfers)
- Combine multiple swaps in a single transaction
- Have full control over transaction construction
- Avoid deserializing/re-serializing transactions which adds latency
Query Parameters
chainId(required) — The blockchain identifier. Must besolanaorsolana:solanatokenIn(required) — Address of the token to swap from (useSo11111111111111111111111111111111111111111for native SOL)tokenOut(required) — Address of the token to swap to (useSo11111111111111111111111111111111111111111for native SOL)amount(required ifamountRawnot provided) — Human-readable amount of tokenIn to swap (e.g.,"1.5"for 1.5 tokens)amountRaw(required ifamountnot provided) — Raw amount as a string (e.g.,"1500000000"for 1.5 SOL with 9 decimals)walletAddress(required) — Wallet address that will execute the swapslippage(optional) — Maximum acceptable slippage percentage (0-100). Default:1excludedProtocols(optional) — Comma-separated list of factory addresses to exclude from routingonlyProtocols(optional) — Comma-separated list of tradable pool types to restrict routingpoolAddress(optional) — Specific pool address to use for the swaponlyVerifiedTokens(optional) — When set to"true", rejects quotes wheretokenOutis an unverified launchpad token (e.g., Pump.fun, Pumpswap, Raydium Launchlab). Default:"false".prioritizationFeeLamports(optional) — Jupiter-compatible priority fee budget. Can beauto, a fixed lamport amount, or{"priorityLevelWithMaxLamports":{"priorityLevel":"medium"|"high"|"veryHigh","maxLamports":1000000,"global":false}}dynamicComputeUnitLimit(optional) — Solana only. Dynamically sizes the compute unit limit from the built swap instructions. Default:true.jitoTipLamports(optional) — Jito tip amount in lamports for block engine prioritypayerAddress(optional) — Separate Solana fee payer. When provided and different fromwalletAddress, both wallets must sign. The payer covers transaction fees, priority/Jito tips, and ATA rent for accounts Mobula creates.closeAuthority(optional) — Close authority for non-WSOL ATAs Mobula creates during the swap whenpayerAddressis used. Usually set this to the central payer wallet to reclaim rent later.swapRecipientAddress(optional) — Wallet that receives the exact final swap output after router fee/slippage checks. The swap still useswalletAddressas taker, then MobulaRouter transfers the final output. Cannot be combined withdestinationWallet. Legacy alias:finalRecipientWallet.feePercentage(optional) — Fee percentage to charge on the swap (0.01 to 99). Fee is always taken from native SOL (deducted from the swap amount). At least one side of the swap must be native SOL. Must be used together withfeeWallet.feeWallet(optional) — Wallet address to receive fees. Required whenfeePercentageis set.
Usage Examples
Basic Swap Instructions
With Priority Fee
With Jito Tip
With Integration Fee
feeWallet via a SystemProgram.transfer instruction.
With Central Fee Payer, Close Authority, and Recipient
payerAddress pays transaction fees and ATA rent. closeAuthority lets that payer close non-WSOL ATAs Mobula created during the swap if they are left open later. swapRecipientAddress receives the final output while walletAddress remains the swap taker and token-transfer authority.
Response Format
Response Fields
Data Object
amountOutTokens(string, optional) — Estimated output amount in tokensslippagePercentage(number, optional) — Slippage percentagetokenIn(object, optional) — Input token metadataaddress(string) — Token contract addressname(string, optional) — Token namesymbol(string, optional) — Token symboldecimals(number) — Token decimalslogo(string | null, optional) — Token logo URL
tokenOut(object, optional) — Output token metadatarequestId(string) — Unique identifier for tracking this requestsolana(object) — Solana instructions containerinstructions(object) — All instructions needed for the swapcomputeBudgetInstructions(array, optional) — Instructions to set compute budgetsetupInstructions(array, optional) — Setup instructions (e.g., create token accounts)swapInstructions(array) — The swap instructions (can be multiple for multi-hop routes)cleanupInstructions(array, optional) — Cleanup instructions (e.g., close token accounts)addressLookupTableAddresses(array, optional) — ALT addresses for versioned transactions
lastValidBlockHeight(number) — The last block height at which the blockhash is validrecentBlockhash(string) — Recent blockhash to use when building the transaction
Instruction Format
Each instruction contains:programId(string) — The program that will process this instructionaccounts(array) — Account keys involved in the instructionpubkey(string) — Account public keyisSigner(boolean) — Whether the account must signisWritable(boolean) — Whether the account is writable
data(string) — Instruction data as base64 encoded string
Building a Transaction
After receiving instructions, you need to build and sign the transaction yourself:Important Notes
- Solana Only: This endpoint only works with Solana chains
- Mobula Execution Engine: Instructions are generated by Mobula’s internal execution engine, which routes through multiple DEXs (Raydium, Orca, Pumpfun, etc.) for optimal pricing
- Blockhash Expiry: The
recentBlockhashandlastValidBlockHeighthave a limited validity window (~150 blocks / ~1 minute). Build and send your transaction quickly. - ALT Required: For complex swaps, Address Lookup Tables are required. Always fetch and include them if
addressLookupTableAddressesis provided. - Request ID: Keep the
requestIdfor troubleshooting with Mobula support
Comparison with /swap/quoting
Query Parameters
Mobula chain id. EVM: evm:<integer> (e.g. evm:1, evm:8453, evm:42161). Solana: solana:solana. TON: ton:mainnet or ton:testnet.
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.
1Buy token address. Same native identifier rules as tokenIn.
1Human-readable amount (e.g. "1.5" for 1.5 tokens). Converted server-side: raw = amount × 10^decimals. Mutually exclusive with amountRaw.
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.
USD value of tokenIn to spend. Resolved server-side from the live weighted token price. Mutually exclusive with amount and amountRaw.
auto (default) lets the router choose adaptive slippage. A number is a fixed slippage tolerance in % (0-100).
Optional market impact guard in %. If the computed marketImpactPercentage is greater than this value, the quote is rejected with HTTP 400.
User wallet address — signer/source wallet for the swap.
1Solana only. Optional wallet that receives tokenOut. Defaults to walletAddress. Native SOL output is not supported yet with a separate destination wallet.
Deprecated Solana alias for swapRecipientAddress; kept for backward compatibility.
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.
DEX-level deny list (CSV). Example: pump-amm,raydium.
DEX-level allow list (CSV). Example: uniswap-v3,uniswap-v4.
Pin routing to a single pool (e.g. when you want a specific Uniswap V3 fee tier).
Aggregator filter (CSV) — jupiter, kyberswap, lifi, naos. Omit to let the API pick.
Solana only. Jupiter-compatible priority fee budget. Use auto, a fixed lamport amount, or { "priorityLevelWithMaxLamports": { "priorityLevel": "medium" | "high" | "veryHigh", "maxLamports": 1000000, "global": false } }.
Solana only. Dynamically sizes the compute unit limit from the assembled swap instructions. Default: true.
Solana only. Jito tip in lamports — adds a transfer to one of the Jito tip accounts for fast landing.
Caller referral fee in % (0-99). Mobula skims a 20% platform cut off the top. Requires feeWallet.
Wallet that receives the caller referral fee. Required when feePercentage > 0.
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.
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.
Solana only. Raw amount (smallest unit) of feeToken to charge as a flat minimum fee. The swap reverts if the user lacks balance.
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.
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.
Solana only. true returns N candidate transactions over a durable nonce — race them across landers (Jito, Nozomi, 0slot). Only one commits.
Per-lander tip when multiLander=true. Defaults to each lander's minimum.
When true, reject quotes involving unverified launchpad tokens.