Swap Instructions - Mobula API

Get swap quote instructions with transaction details

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

{
  "data": {
    "requestId": "<string>",
    "solana": {
      "instructions": {
        "swapInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "computeBudgetInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "setupInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "cleanupInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "addressLookupTableAddresses": [
          "<string>"
        ]
      },
      "lastValidBlockHeight": 123,
      "recentBlockhash": "<string>"
    },
    "amountOutTokens": "<string>",
    "slippagePercentage": 123,
    "amountInUSD": 123,
    "amountOutUSD": 123,
    "marketImpactPercentage": 123,
    "poolFeesPercentage": 123,
    "tokenIn": {
      "address": "<string>",
      "decimals": 123,
      "name": "<string>",
      "symbol": "<string>",
      "logo": "<string>"
    },
    "tokenOut": {
      "address": "<string>",
      "decimals": 123,
      "name": "<string>",
      "symbol": "<string>",
      "logo": "<string>"
    },
    "details": {
      "route": {
        "hops": [
          {
            "poolAddress": "<string>",
            "tokenIn": {
              "address": "<string>",
              "decimals": 123,
              "name": "<string>",
              "symbol": "<string>",
              "logo": "<string>"
            },
            "tokenOut": {
              "address": "<string>",
              "decimals": 123,
              "name": "<string>",
              "symbol": "<string>",
              "logo": "<string>"
            },
            "amountInTokens": "<string>",
            "amountOutTokens": "<string>",
            "exchange": "<string>",
            "poolType": "<string>",
            "feePercentage": 123,
            "feeBps": 123
          }
        ],
        "totalFeePercentage": 123,
        "aggregator": "<string>"
      },
      "aggregator": "<string>",
      "raw": {}
    },
    "fee": {
      "amount": "<string>",
      "percentage": 123,
      "wallet": "<string>"
    }
  },
  "error": "<string>"
}

GET

swap

quoting-instructions

Get swap quote instructions with transaction details

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

{
  "data": {
    "requestId": "<string>",
    "solana": {
      "instructions": {
        "swapInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "computeBudgetInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "setupInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "cleanupInstructions": [
          {
            "programId": "<string>",
            "accounts": [
              {
                "pubkey": "<string>",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "<string>"
          }
        ],
        "addressLookupTableAddresses": [
          "<string>"
        ]
      },
      "lastValidBlockHeight": 123,
      "recentBlockhash": "<string>"
    },
    "amountOutTokens": "<string>",
    "slippagePercentage": 123,
    "amountInUSD": 123,
    "amountOutUSD": 123,
    "marketImpactPercentage": 123,
    "poolFeesPercentage": 123,
    "tokenIn": {
      "address": "<string>",
      "decimals": 123,
      "name": "<string>",
      "symbol": "<string>",
      "logo": "<string>"
    },
    "tokenOut": {
      "address": "<string>",
      "decimals": 123,
      "name": "<string>",
      "symbol": "<string>",
      "logo": "<string>"
    },
    "details": {
      "route": {
        "hops": [
          {
            "poolAddress": "<string>",
            "tokenIn": {
              "address": "<string>",
              "decimals": 123,
              "name": "<string>",
              "symbol": "<string>",
              "logo": "<string>"
            },
            "tokenOut": {
              "address": "<string>",
              "decimals": 123,
              "name": "<string>",
              "symbol": "<string>",
              "logo": "<string>"
            },
            "amountInTokens": "<string>",
            "amountOutTokens": "<string>",
            "exchange": "<string>",
            "poolType": "<string>",
            "feePercentage": 123,
            "feeBps": 123
          }
        ],
        "totalFeePercentage": 123,
        "aggregator": "<string>"
      },
      "aggregator": "<string>",
      "raw": {}
    },
    "fee": {
      "amount": "<string>",
      "percentage": 123,
      "wallet": "<string>"
    }
  },
  "error": "<string>"
}

Overview

Solana Swap Execution - Alpha ModeThis endpoint is currently in alpha mode. This means:

The feature is functional but may have limitations or unexpected behavior
Performance and reliability improvements are ongoing
We recommend testing thoroughly before production use
Please report any issues to the Mobula team for faster resolution

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

Note: This endpoint is only available for Solana chains. Mobula’s execution engine handles the instruction generation internally, supporting multiple DEXs and liquidity sources (Raydium, Orca, Pumpfun, etc.).

Query Parameters

chainId (required) — The blockchain identifier. Must be solana or solana:solana
tokenIn (required) — Address of the token to swap from (use So11111111111111111111111111111111111111111 for native SOL)
tokenOut (required) — Address of the token to swap to (use So11111111111111111111111111111111111111111 for native SOL)
amount (required if amountRaw not provided) — Human-readable amount of tokenIn to swap (e.g., "1.5" for 1.5 tokens)
amountRaw (required if amount not provided) — Raw amount as a string (e.g., "1500000000" for 1.5 SOL with 9 decimals)
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
onlyProtocols (optional) — Comma-separated list of tradable pool types to restrict routing
poolAddress (optional) — Specific pool address to use for the swap
onlyVerifiedTokens (optional) — When set to "true", rejects quotes where tokenOut is an unverified launchpad token (e.g., Pump.fun, Pumpswap, Raydium Launchlab). Default: "false".
prioritizationFeeLamports (optional) — Jupiter-compatible priority fee budget. Can be auto, 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 priority
payerAddress (optional) — Separate Solana fee payer. When provided and different from walletAddress, 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 when payerAddress is 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 uses walletAddress as taker, then MobulaRouter transfers the final output. Cannot be combined with destinationWallet. 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 with feeWallet.
feeWallet (optional) — Wallet address to receive fees. Required when feePercentage is set.

Usage Examples

Basic Swap Instructions

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

With Priority Fee

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

With Jito Tip

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

With Integration Fee

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

This example charges a 1% fee on the swap. The fee is deducted from native SOL and sent to your feeWallet via a SystemProgram.transfer instruction.

With Central Fee Payer, Close Authority, and Recipient

curl -X GET "https://api.mobula.io/api/2/swap/quoting-instructions?chainId=solana&tokenIn=So11111111111111111111111111111111111111111&tokenOut=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1&walletAddress=UserWalletAddressHere&payerAddress=CentralFeePayerAddressHere&closeAuthority=CentralFeePayerAddressHere&swapRecipientAddress=RecipientWalletAddressHere"

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

{
  "data": {
    "amountOutTokens": "150.123456",
    "slippagePercentage": 1,
    "tokenIn": {
      "address": "So11111111111111111111111111111111111111111",
      "name": "Wrapped SOL",
      "symbol": "SOL",
      "decimals": 9,
      "logo": "https://metadata.mobula.io/assets/logos/solana_solana_So11111111111111111111111111111111111111111.webp"
    },
    "tokenOut": {
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "logo": "https://metadata.mobula.io/assets/logos/solana_solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.webp"
    },
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "solana": {
      "instructions": {
        "computeBudgetInstructions": [
          {
            "programId": "ComputeBudget111111111111111111111111111111",
            "accounts": [],
            "data": "AgAAABAnAAAAAAAA"
          }
        ],
        "setupInstructions": [
          {
            "programId": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
            "accounts": [
              {
                "pubkey": "YourWalletAddress",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "..."
          }
        ],
        "swapInstructions": [
          {
            "programId": "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
            "accounts": [
              {
                "pubkey": "YourWalletAddress",
                "isSigner": true,
                "isWritable": true
              }
            ],
            "data": "..."
          }
        ],
        "cleanupInstructions": [
          {
            "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
            "accounts": [
              {
                "pubkey": "YourWalletAddress",
                "isSigner": false,
                "isWritable": true
              }
            ],
            "data": "..."
          }
        ],
        "addressLookupTableAddresses": [
          "GxS6FiQ3mNnAar9HGQ6mxP7t6FcwmHkU7peSeQDUHmpN"
        ]
      },
      "lastValidBlockHeight": 305123456,
      "recentBlockhash": "EkSnNWid2cvwEVnVx9aBqawnmiCNiDgp3gUdkDPTKN1N"
    }
  }
}

Response Fields

Data Object

amountOutTokens (string, optional) — Estimated output amount in tokens
slippagePercentage (number, optional) — Slippage percentage
tokenIn (object, optional) — Input token metadata
- address (string) — Token contract address
- name (string, optional) — Token name
- symbol (string, optional) — Token symbol
- decimals (number) — Token decimals
- logo (string | null, optional) — Token logo URL
tokenOut (object, optional) — Output token metadata
requestId (string) — Unique identifier for tracking this request
solana (object) — Solana instructions container
- instructions (object) — All instructions needed for the swap
  - computeBudgetInstructions (array, optional) — Instructions to set compute budget
  - setupInstructions (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 valid
- recentBlockhash (string) — Recent blockhash to use when building the transaction

Instruction Format

Each instruction contains:

programId (string) — The program that will process this instruction
accounts (array) — Account keys involved in the instruction
- pubkey (string) — Account public key
- isSigner (boolean) — Whether the account must sign
- isWritable (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:

import {
  Connection,
  TransactionMessage,
  VersionedTransaction,
  PublicKey,
  TransactionInstruction,
  AddressLookupTableAccount,
} from '@solana/web3.js';

const { solana, requestId } = response.data;

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

// Helper to convert instruction format
function toTransactionInstruction(ix) {
  return new TransactionInstruction({
    programId: new PublicKey(ix.programId),
    keys: ix.accounts.map(acc => ({
      pubkey: new PublicKey(acc.pubkey),
      isSigner: acc.isSigner,
      isWritable: acc.isWritable,
    })),
    data: Buffer.from(ix.data, 'base64'),
  });
}

// Build all instructions
const instructions = [];

// 1. Add compute budget instructions (if any)
if (solana.instructions.computeBudgetInstructions) {
  for (const ix of solana.instructions.computeBudgetInstructions) {
    instructions.push(toTransactionInstruction(ix));
  }
}

// 2. Add setup instructions (if any)
if (solana.instructions.setupInstructions) {
  for (const ix of solana.instructions.setupInstructions) {
    instructions.push(toTransactionInstruction(ix));
  }
}

// 3. Add YOUR custom instructions here (e.g., Jito tip, fee transfer)
// Example: Add a Jito tip
const JITO_TIP_ACCOUNTS = [
  '96gYZGLnJYVFmbjzopPSU6QiEV5fGqZNyN9nmNhvrZU5',
  'HFqU5x63VTqvQss8hp11i4wVV8bD44PvwucfZ2bU7gRe',
  // ... more tip accounts
];
const tipAccount = JITO_TIP_ACCOUNTS[Math.floor(Math.random() * JITO_TIP_ACCOUNTS.length)];
const tipInstruction = SystemProgram.transfer({
  fromPubkey: wallet.publicKey,
  toPubkey: new PublicKey(tipAccount),
  lamports: 10000, // 0.00001 SOL
});
instructions.push(tipInstruction);

// 4. Add the swap instructions (can be multiple for multi-hop routes)
if (solana.instructions.swapInstructions) {
  for (const ix of solana.instructions.swapInstructions) {
    instructions.push(toTransactionInstruction(ix));
  }
}

// 5. Add cleanup instructions (if any)
if (solana.instructions.cleanupInstructions) {
  for (const ix of solana.instructions.cleanupInstructions) {
    instructions.push(toTransactionInstruction(ix));
  }
}

// Fetch Address Lookup Tables (if any)
const addressLookupTables = [];
if (solana.instructions.addressLookupTableAddresses?.length > 0) {
  const connection = new Connection('YOUR_RPC_URL');
  for (const address of solana.instructions.addressLookupTableAddresses) {
    const result = await connection.getAddressLookupTable(new PublicKey(address));
    if (result.value) {
      addressLookupTables.push(result.value);
    }
  }
}

// Build the versioned transaction
const messageV0 = new TransactionMessage({
  payerKey: wallet.publicKey,
  recentBlockhash: solana.recentBlockhash,
  instructions,
}).compileToV0Message(addressLookupTables);

const transaction = new VersionedTransaction(messageV0);

// Sign the transaction
transaction.sign([wallet]);

// Send the transaction
const signature = await connection.sendTransaction(transaction);

// Confirm with lastValidBlockHeight
await connection.confirmTransaction({
  signature,
  blockhash: solana.recentBlockhash,
  lastValidBlockHeight: solana.lastValidBlockHeight,
});

console.log('Transaction confirmed:', signature);

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 recentBlockhash and lastValidBlockHeight have 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 addressLookupTableAddresses is provided.
Request ID: Keep the requestId for troubleshooting with Mobula support

Comparison with /swap/quoting

Feature	/swap/quoting	/swap/quoting-instructions
Returns	Serialized transaction	Individual instructions
Custom instructions	Need to deserialize	Direct insertion
Latency	Lower (ready to sign)	Slightly higher (need to build)
Flexibility	Limited	Full control
Chain support	Solana + EVM	Solana only
Use case	Simple swaps	Advanced integrations

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.

prioritizationFeeLamports

string

Solana only. Jupiter-compatible priority fee budget. Use auto, a fixed lamport amount, or a JSON priority object with priorityLevelWithMaxLamports.

dynamicComputeUnitLimit

string

Solana only. Dynamically sizes the compute unit limit from the built 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. 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

200 - application/json

Swap quoting instructions response

data

object

required

Show child attributes

error

string

TON Swap Quoting Send Swap Transaction

⌘I

​Overview

​Query Parameters

​Usage Examples

​Basic Swap Instructions

​With Priority Fee

​With Jito Tip

​With Integration Fee

​With Central Fee Payer, Close Authority, and Recipient

​Response Format

​Response Fields

​Data Object

​Instruction Format

​Building a Transaction

​Important Notes

​Comparison with /swap/quoting

Query Parameters

Response

Overview

Query Parameters

Usage Examples

Basic Swap Instructions

With Priority Fee

With Jito Tip

With Integration Fee

With Central Fee Payer, Close Authority, and Recipient

Response Format

Response Fields

Data Object

Instruction Format

Building a Transaction

Important Notes

Comparison with /swap/quoting