> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Swap Quoting
> Single endpoint to quote swaps across EVM, Solana and TON — same shape, chain-specific calldata block. Best-route aggregation, slippage protection, integrated fee accounting.
`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`.
Ethereum, Base, Arbitrum, BNB Chain, Polygon + 25 chains
Jupiter, Raydium, Orca, Meteora, Pump.fun + multi-lander
Stonfi v2, DeDust v2, pTON v2 — multi-message envelope
## Arguments
### Required
| Param | Type | Description |
| ------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `chainId` | string | `evm:` (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 | `auto` | `%` value (`0`-`100`) or `auto` |
| `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. Honored on TON native-input swaps and on Solana when the fee asset is native SOL (enforced on-chain by MobulaRouter). |
| `feeToken` | string | – | Solana only. Mint of a token to charge a flat **minimum** fee in (with `minFeesTokenRaw`), via a dedicated transfer to `feeWallet`, independent of the route. |
| `minFeesTokenRaw` | string | – | Solana only. Raw amount (smallest unit) of `feeToken` to charge. Tx reverts if balance is insufficient. |
| `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 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prioritizationFeeLamports` | Jupiter-compatible priority fee budget: `auto`, fixed lamports, or `{"priorityLevelWithMaxLamports":{"priorityLevel":"medium" \| "high" \| "veryHigh","maxLamports":1000000,"global":false}}` |
| `dynamicComputeUnitLimit` | Solana only. `true` by default; dynamically sizes the compute limit from the built swap instructions |
| `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`. The payer signs and pays Solana fees / ATA rent; swap funds still come from `walletAddress`. |
| `destinationWallet` | Optional Solana tokenOut recipient. Do not combine with `finalRecipientWallet`. |
| `finalRecipientWallet` | Router-enforced final output recipient. The Mobula router transfers the exact final swap output to this wallet after swap execution and fee/slippage checks. |
### Native sentinel addresses
| Chain | Sentinel |
| -------------------- | -------------------------------------------------- |
| EVM | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` |
| Solana native SOL | `So11111111111111111111111111111111111111111` |
| Solana WSOL SPL mint | `So11111111111111111111111111111111111111112` |
| TON | `EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c` |
## Response
```json theme={null}
{
"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](./evm-quoting) |
| Solana | `data.solana.transaction` + `lastValidBlockHeight` | `{ serialized: base64, variant: 'versioned' \| 'legacy' }` — see [Solana Quoting](./solana-quoting) |
| TON | `data.ton.transactions[1..4]` + `data.ton.fees` | `{ to, value, body, bounce, stateInit? }[]` — see [TON Quoting](./ton-quoting) |
When `multiLander=true` (Solana only), `data.candidates[]` replaces `data.solana.transaction` — see the [Solana page](./solana-quoting#multi-lander).
## Quick example
```ts theme={null}
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`](./swap-send) endpoint, or — for EVM — directly from your wallet.
## Errors
`200` with `data: null, error: ""` 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.
## OpenAPI
````yaml get /2/swap/quoting
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, trendings, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/swap/quoting:
get:
tags:
- V2 - Swap
summary: Get swap quote with transaction details
description: >-
Get a swap quote with optimized routing across multiple DEXs and
liquidity sources. Returns estimated output amount, slippage, and a
serialized transaction ready to be signed. Either `amount`
(human-readable) or `amountRaw` (raw amount as string) must be provided,
but not both.
parameters:
- schema:
type: string
description: >-
Mobula chain id. EVM: `evm:` (e.g. `evm:1`, `evm:8453`,
`evm:42161`). Solana: `solana:solana`. TON: `ton:mainnet` or
`ton:testnet`.
required: false
description: >-
Mobula chain id. EVM: `evm:` (e.g. `evm:1`, `evm:8453`,
`evm:42161`). Solana: `solana:solana`. TON: `ton:mainnet` or
`ton:testnet`.
name: chainId
in: query
- schema:
type: string
minLength: 1
description: >-
Sell token address. Native sentinels — EVM:
`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (EIP-7528). Solana:
`So11111111111111111111111111111111111111112` (wSOL). TON:
`EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c`.
required: true
description: >-
Sell token address. Native sentinels — EVM:
`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (EIP-7528). Solana:
`So11111111111111111111111111111111111111112` (wSOL). TON:
`EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c`.
name: tokenIn
in: query
- schema:
type: string
minLength: 1
description: Buy token address. Same sentinel rules as `tokenIn`.
required: true
description: Buy token address. Same sentinel rules as `tokenIn`.
name: tokenOut
in: query
- schema:
type: string
description: >-
Human-readable amount (e.g. `"1.5"` for 1.5 tokens). Converted
server-side: raw = amount × 10^decimals. Mutually exclusive with
`amountRaw`.
required: false
description: >-
Human-readable amount (e.g. `"1.5"` for 1.5 tokens). Converted
server-side: raw = amount × 10^decimals. Mutually exclusive with
`amountRaw`.
name: amount
in: query
- schema:
type: string
description: >-
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`.
required: false
description: >-
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`.
name: amountRaw
in: query
- schema:
type: string
description: >-
Slippage tolerance in % (0-100, default 1). Quote rejects if
expected output drops below this threshold.
required: false
description: >-
Slippage tolerance in % (0-100, default 1). Quote rejects if
expected output drops below this threshold.
name: slippage
in: query
- schema:
type: string
minLength: 1
description: >-
User wallet address — recipient of `tokenOut`, signer for the
broadcast tx, fee context.
required: true
description: >-
User wallet address — recipient of `tokenOut`, signer for the
broadcast tx, fee context.
name: walletAddress
in: query
- schema:
anyOf:
- type: string
- type: array
items:
type: string
description: 'DEX-level deny list (CSV). Example: `pump-amm,raydium`.'
required: false
description: 'DEX-level deny list (CSV). Example: `pump-amm,raydium`.'
name: excludedProtocols
in: query
- schema:
anyOf:
- type: string
- type: array
items:
type: string
description: 'DEX-level allow list (CSV). Example: `uniswap-v3,uniswap-v4`.'
required: false
description: 'DEX-level allow list (CSV). Example: `uniswap-v3,uniswap-v4`.'
name: onlyProtocols
in: query
- schema:
type: string
description: >-
Pin routing to a single pool (e.g. when you want a specific
Uniswap V3 fee tier).
required: false
description: >-
Pin routing to a single pool (e.g. when you want a specific Uniswap
V3 fee tier).
name: poolAddress
in: query
- schema:
type: string
description: >-
Aggregator filter (CSV) — `jupiter`, `kyberswap`, `lifi`, `naos`.
Omit to let the API pick.
required: false
description: >-
Aggregator filter (CSV) — `jupiter`, `kyberswap`, `lifi`, `naos`.
Omit to let the API pick.
name: onlyRouters
in: query
- schema:
type: string
description: >-
Solana only. Jupiter-compatible priority fee budget. Use `auto`, a
fixed lamport amount, or a JSON priority object with
`priorityLevelWithMaxLamports`.
required: false
description: >-
Solana only. Jupiter-compatible priority fee budget. Use `auto`, a
fixed lamport amount, or a JSON priority object with
`priorityLevelWithMaxLamports`.
name: prioritizationFeeLamports
in: query
- schema:
type: string
description: >-
Solana only. Dynamically sizes the compute unit limit from the
built swap instructions. Default `true`.
required: false
description: >-
Solana only. Dynamically sizes the compute unit limit from the built
swap instructions. Default `true`.
name: dynamicComputeUnitLimit
in: query
- schema:
type: string
description: >-
Solana only. Jito tip in lamports — adds a transfer to one of the
Jito tip accounts for fast landing.
required: false
description: >-
Solana only. Jito tip in lamports — adds a transfer to one of the
Jito tip accounts for fast landing.
name: jitoTipLamports
in: query
- schema:
anyOf:
- type: string
- type: number
description: >-
Caller referral fee in % (0-99). Mobula skims a 20% platform cut
off the top. Requires `feeWallet`.
required: false
description: >-
Caller referral fee in % (0-99). Mobula skims a 20% platform cut off
the top. Requires `feeWallet`.
name: feePercentage
in: query
- schema:
type: string
description: >-
Wallet that receives the caller referral fee. Required when
`feePercentage > 0`.
required: false
description: >-
Wallet that receives the caller referral fee. Required when
`feePercentage > 0`.
name: feeWallet
in: query
- schema:
anyOf:
- type: string
- type: number
description: >-
Minimum caller referral fee in native-token units. Currently
honored on TON native-input swaps; requires `feeWallet`.
required: false
description: >-
Minimum caller referral fee in native-token units. Currently honored
on TON native-input swaps; requires `feeWallet`.
name: minFeesNative
in: query
- schema:
type: string
description: >-
Solana only. Fee abstraction — wallet that signs/pays for the tx
(separate from `walletAddress`).
required: false
description: >-
Solana only. Fee abstraction — wallet that signs/pays for the tx
(separate from `walletAddress`).
name: payerAddress
in: query
- schema:
type: string
description: >-
Solana only. `true` returns N candidate transactions over a
durable nonce — race them across landers (Jito, Nozomi, 0slot).
Only one commits.
required: false
description: >-
Solana only. `true` returns N candidate transactions over a durable
nonce — race them across landers (Jito, Nozomi, 0slot). Only one
commits.
name: multiLander
in: query
- schema:
type: string
description: >-
Per-lander tip when `multiLander=true`. Defaults to each lander's
minimum.
required: false
description: >-
Per-lander tip when `multiLander=true`. Defaults to each lander's
minimum.
name: landerTipLamports
in: query
responses:
'200':
description: Swap quoting response
content:
application/json:
schema:
$ref: '#/components/schemas/SwapQuotingResponse'
'400':
description: Bad request - validation error
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: array
items:
type: object
properties:
path:
type: string
message:
type: string
code:
type: string
required:
- path
- message
- code
requestId:
type: string
required:
- message
- errors
- requestId
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
message:
type: string
requestId:
type: string
required:
- message
- requestId
components:
schemas:
SwapQuotingResponse:
type: object
properties:
data:
$ref: '#/components/schemas/SwapQuotingData'
error:
type: string
description: >-
Set on routing failures (no route, slippage too tight, upstream
timeout). The `data` block still carries `requestId` for support.
required:
- data
SwapQuotingData:
anyOf:
- $ref: '#/components/schemas/SwapQuoteSolana'
- $ref: '#/components/schemas/SwapQuoteEVM'
- $ref: '#/components/schemas/SwapQuoteTON'
- $ref: '#/components/schemas/SwapQuoteSolanaMultiLander'
- $ref: '#/components/schemas/SwapQuoteError'
SwapQuoteSolana:
type: object
properties:
amountOutTokens:
type: string
description: Estimated output, human-readable.
example: '245.123'
slippagePercentage:
type: number
description: Echo of the request `slippage` param.
example: 1
amountInUSD:
type: number
description: Input value in USD at quote time.
example: 200.45
amountOutUSD:
type: number
description: Output value in USD at quote time.
example: 199.87
marketImpactPercentage:
type: number
description: Estimated price impact at this trade size.
example: 0.04
poolFeesPercentage:
type: number
description: Sum of LP fees paid across the route, in %.
example: 0.25
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
requestId:
type: string
description: Unique per quote — pass to support / analytics.
details:
$ref: '#/components/schemas/SwapDetails'
fee:
$ref: '#/components/schemas/IntegrationFee'
solana:
$ref: '#/components/schemas/SolanaCalldata'
evm:
nullable: true
ton:
nullable: true
required:
- requestId
- solana
SwapQuoteEVM:
type: object
properties:
amountOutTokens:
type: string
description: Estimated output, human-readable.
example: '245.123'
slippagePercentage:
type: number
description: Echo of the request `slippage` param.
example: 1
amountInUSD:
type: number
description: Input value in USD at quote time.
example: 200.45
amountOutUSD:
type: number
description: Output value in USD at quote time.
example: 199.87
marketImpactPercentage:
type: number
description: Estimated price impact at this trade size.
example: 0.04
poolFeesPercentage:
type: number
description: Sum of LP fees paid across the route, in %.
example: 0.25
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
requestId:
type: string
description: Unique per quote — pass to support / analytics.
details:
$ref: '#/components/schemas/SwapDetails'
fee:
$ref: '#/components/schemas/IntegrationFee'
evm:
$ref: '#/components/schemas/EVMCalldata'
solana:
nullable: true
ton:
nullable: true
required:
- requestId
- evm
SwapQuoteTON:
type: object
properties:
amountOutTokens:
type: string
description: Estimated output, human-readable.
example: '245.123'
slippagePercentage:
type: number
description: Echo of the request `slippage` param.
example: 1
amountInUSD:
type: number
description: Input value in USD at quote time.
example: 200.45
amountOutUSD:
type: number
description: Output value in USD at quote time.
example: 199.87
marketImpactPercentage:
type: number
description: Estimated price impact at this trade size.
example: 0.04
poolFeesPercentage:
type: number
description: Sum of LP fees paid across the route, in %.
example: 0.25
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
requestId:
type: string
description: Unique per quote — pass to support / analytics.
details:
$ref: '#/components/schemas/SwapDetails'
fee:
$ref: '#/components/schemas/IntegrationFee'
ton:
$ref: '#/components/schemas/TonCalldata'
solana:
nullable: true
evm:
nullable: true
required:
- requestId
- ton
SwapQuoteSolanaMultiLander:
type: object
properties:
amountOutTokens:
type: string
description: Estimated output, human-readable.
example: '245.123'
slippagePercentage:
type: number
description: Echo of the request `slippage` param.
example: 1
amountInUSD:
type: number
description: Input value in USD at quote time.
example: 200.45
amountOutUSD:
type: number
description: Output value in USD at quote time.
example: 199.87
marketImpactPercentage:
type: number
description: Estimated price impact at this trade size.
example: 0.04
poolFeesPercentage:
type: number
description: Sum of LP fees paid across the route, in %.
example: 0.25
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
requestId:
type: string
description: Unique per quote — pass to support / analytics.
details:
$ref: '#/components/schemas/SwapDetails'
fee:
$ref: '#/components/schemas/IntegrationFee'
candidates:
type: array
items:
$ref: '#/components/schemas/SwapQuoteCandidate'
minItems: 1
description: >-
Multi-lander candidate transactions (Solana only). Sign every
candidate, broadcast all of them in batch — only one will land.
nonceAccount:
type: string
description: Durable nonce account public key.
nonceAuthority:
type: string
description: Nonce authority public key (must co-sign).
solana:
nullable: true
evm:
nullable: true
ton:
nullable: true
required:
- requestId
- candidates
- nonceAccount
- nonceAuthority
SwapQuoteError:
type: object
properties:
amountOutTokens:
type: string
description: Estimated output, human-readable.
example: '245.123'
slippagePercentage:
type: number
description: Echo of the request `slippage` param.
example: 1
amountInUSD:
type: number
description: Input value in USD at quote time.
example: 200.45
amountOutUSD:
type: number
description: Output value in USD at quote time.
example: 199.87
marketImpactPercentage:
type: number
description: Estimated price impact at this trade size.
example: 0.04
poolFeesPercentage:
type: number
description: Sum of LP fees paid across the route, in %.
example: 0.25
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
requestId:
type: string
description: Unique per quote — pass to support / analytics.
details:
$ref: '#/components/schemas/SwapDetails'
fee:
$ref: '#/components/schemas/IntegrationFee'
solana:
nullable: true
evm:
nullable: true
ton:
nullable: true
required:
- requestId
TokenInfo:
type: object
properties:
address:
type: string
description: Token contract address (chain-specific format).
example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
name:
type: string
example: USD Coin
symbol:
type: string
example: USDC
decimals:
type: number
example: 6
logo:
type: string
nullable: true
description: Logo URL (null when unavailable).
example: https://metadata.mobula.io/assets/logos/evm_8453_0x8335…
required:
- address
- decimals
SwapDetails:
type: object
properties:
route:
$ref: '#/components/schemas/RouteDetails'
aggregator:
type: string
raw:
type: object
additionalProperties:
nullable: true
description: >-
Aggregator-specific raw payload (provided for debugging — schema may
vary).
IntegrationFee:
type: object
properties:
amount:
type: string
description: Fee amount in human-readable format.
example: '0.001'
percentage:
type: number
description: Fee percentage applied (0.01 to 99).
example: 0.5
wallet:
type: string
description: Wallet address receiving the fee.
example: 0xCALLER…
deductedFrom:
type: string
enum:
- input
- output
description: '`input` for native-in swaps, `output` for native-out swaps.'
example: input
required:
- amount
- percentage
- wallet
- deductedFrom
description: >-
Echoed when `feePercentage` and `feeWallet` were provided in the
request.
SolanaCalldata:
type: object
properties:
transaction:
$ref: '#/components/schemas/SolanaTransaction'
lastValidBlockHeight:
type: number
description: Blockhash expiry — broadcast before the chain ticks past this slot.
example: 269450123
required:
- transaction
- lastValidBlockHeight
EVMCalldata:
type: object
properties:
transaction:
$ref: '#/components/schemas/EVMTransaction'
required:
- transaction
TonCalldata:
type: object
properties:
transaction:
$ref: '#/components/schemas/TonInternalMessage'
transactions:
type: array
items:
$ref: '#/components/schemas/TonInternalMessage'
minItems: 1
maxItems: 4
description: >-
Full message envelope. `[0]` = swap, `[1]` = Mobula 0.1% protocol
fee, `[2]` = caller referral fee. v4r2 wallet contract supports up
to 4 per signature. TonConnect wallets accept this verbatim as
`messages: []`.
fees:
$ref: '#/components/schemas/TonFeeBreakdown'
required:
- transaction
- transactions
- fees
SwapQuoteCandidate:
type: object
properties:
lander:
type: string
description: Lander id — `jito`, `nozomi`, `zeroslot`, …
example: jito
serialized:
type: string
description: Base64-encoded serialized VersionedTransaction (unsigned).
tipAccount:
type: string
description: Tip account used for this candidate.
example: Cw8C…
tipLamports:
type: number
description: Tip amount in lamports.
example: 1000
required:
- lander
- serialized
- tipAccount
- tipLamports
RouteDetails:
type: object
properties:
hops:
type: array
items:
$ref: '#/components/schemas/RouteHop'
description: Ordered list of pools used (multi-hop).
totalFeePercentage:
type: number
description: Sum of LP fees across the route, in %.
example: 0.25
aggregator:
type: string
description: Aggregator that picked the route.
example: jupiter
required:
- hops
SolanaTransaction:
type: object
properties:
serialized:
type: string
description: >-
Base64-encoded serialized Solana transaction (typically a
VersionedTransaction).
example: AQABAuObQ8Adqk1eqZxRMJg4r6vGtXq9k0...base64...
variant:
type: string
enum:
- legacy
- versioned
description: Transaction variant — almost always `versioned` in production.
example: versioned
required:
- serialized
- variant
EVMTransaction:
type: object
properties:
to:
type: string
description: Target contract — always MobulaRouter on the chain.
example: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
from:
type: string
description: Echo of the input `walletAddress`.
example: 0xUSER…
data:
type: string
description: ABI-encoded calldata for MobulaRouter — pass through verbatim.
example: 0x4585e33b…
value:
type: string
description: >-
Native token to attach, in wei. Equals `amountIn` for native-in
swaps, else `0`.
example: '100000000000000000'
gasLimit:
type: string
description: Suggested gas limit (wallet may simulate to refine).
example: '350000'
gasPrice:
type: string
description: Legacy gas price in wei (chains without EIP-1559).
example: '5000000000'
maxFeePerGas:
type: string
description: EIP-1559 max fee per gas in wei.
example: '20000000000'
maxPriorityFeePerGas:
type: string
description: EIP-1559 priority fee in wei.
example: '1500000000'
nonce:
type: number
description: Optional nonce — wallet picks if omitted.
chainId:
type: number
description: >-
EIP-155 chain id, matches the integer suffix of the request
`chainId` param.
example: 8453
approvalAddress:
type: string
description: >-
Address to grant the ERC-20 allowance to. Defaults to `to`
(MobulaRouter).
example: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
approvals:
type: array
items:
$ref: '#/components/schemas/EVMApproval'
description: >-
Pre-flight ERC-20 approvals to execute before the swap. Empty/absent
means no approval needed.
required:
- to
- from
- data
- value
- chainId
TonInternalMessage:
type: object
properties:
to:
type: string
description: >-
Recipient. Friendly `EQ…`/`UQ…` form preferred, raw `0:hex`
accepted.
example: EQBL58cH_GfHhfdopPfcAW59dJmQPiZG-qokeJmL3V4cioTX
value:
type: string
description: >-
Amount to attach in nanoTon (digit-only string, bigint-safe). 1 TON
= 10^9 nanoTon.
example: '299700000'
body:
type: string
description: Inner message body BoC, base64. Empty string for plain transfers.
example: te6cckECBQEAAS4AAUWIAY9DQE...base64...
bounce:
type: boolean
description: >-
`true` for jetton transfers (refund on failure). `false` only for
trusted receive-only wallets.
example: true
stateInit:
type: string
description: >-
Optional StateInit BoC base64 — set on first deploy of a recipient
jetton wallet.
validUntilSeconds:
type: integer
minimum: 0
exclusiveMinimum: true
description: >-
Optional TonConnect-style ttl hint (seconds). Backend does not
enforce.
example: 600
required:
- to
- value
- body
- bounce
description: Primary swap message (back-compat). Always equal to `transactions[0]`.
TonFeeBreakdown:
type: object
properties:
mobulaFeeAmount:
type: string
description: >-
Mobula's slice (always-on protocol fee + 20% cut of the referral).
nanoTon string.
example: '30000'
referralFeeAmount:
type: string
description: >-
Caller's net fee (referral total − Mobula's cut). 0 when no
referral. nanoTon string.
example: '200000'
swapAmount:
type: string
description: >-
What enters the swap after both fees are deducted. `mobulaFeeAmount
+ referralFeeAmount + swapAmount = amountIn`. nanoTon string.
example: '49770000'
mobulaFeeBps:
type: integer
minimum: 0
description: >-
Mobula protocol fee in basis points. Always 10 (= 0.1%) in
production.
example: 10
userFeeBps:
type: integer
minimum: 0
description: >-
Caller-set referral fee in bps (`feePercentage × 100`). 0 when
unset.
example: 50
platformCutBps:
type: integer
minimum: 0
description: >-
Mobula's percentage cut of the referral, in bps. Always 2000 (= 20%)
in production.
example: 2000
required:
- mobulaFeeAmount
- referralFeeAmount
- swapAmount
- mobulaFeeBps
- userFeeBps
- platformCutBps
RouteHop:
type: object
properties:
poolAddress:
type: string
description: Pool / pair address used for this hop.
tokenIn:
$ref: '#/components/schemas/TokenInfo'
tokenOut:
$ref: '#/components/schemas/TokenInfo'
amountInTokens:
type: string
description: Hop input amount, human-readable.
example: '1.0'
amountOutTokens:
type: string
description: Hop output amount, human-readable.
example: '245.1'
exchange:
type: string
description: DEX name (e.g. `Uniswap V3`, `Raydium`, `DeDust`).
example: Raydium
poolType:
type: string
description: Pool type within the DEX (e.g. `CLMM`, `v3`, `VOLATILE`).
example: CLMM
feePercentage:
type: number
description: Hop LP fee in %.
example: 0.25
feeBps:
type: number
description: Hop LP fee in basis points.
example: 25
required:
- poolAddress
- tokenIn
- tokenOut
- amountInTokens
- amountOutTokens
EVMApproval:
type: object
properties:
token:
type: string
spender:
type: string
required:
- token
- spender
````