Quote Endpoint

The quote endpoint finds the optimal swap route between two tokens and returns detailed execution information.

Endpoint

GET /api/v1/quote

Request Parameters

Required Parameters

Parameter	Type	Description
from	string	Input token identifier (e.g., WEGLD-bd4d79)
to	string	Output token identifier (e.g., USDC-c76f1f)

Amount Parameters

You must provide exactly one of:

Parameter	Type	Description
amountIn	string	Amount to swap (in smallest units). Returns maximum output.
amountOut	string	Desired output amount (in smallest units). Returns required input.

Optional Parameters

Parameter	Type	Default	Description
slippage	number	0.01	Slippage tolerance (0.01 = 1%)
maxSplits	number	5	Maximum number of route splits
maxHops	number	10	Maximum swaps per route
includePaths	boolean	true	Include detailed path breakdown
referralId	number	0	Referral ID for fee sharing
algorithm	string	hybrid	Routing algorithm: greedy, lagrangian, or hybrid
maxBuiltinCalls	number	-	Limit smart contract calls (gas optimization)
includeLpRoutes	boolean	false	Enable LP token mint/burn routing

Arbitrage Parameters

When from equals to, the API detects arbitrage opportunities:

Parameter	Type	Default	Description
minProfitBps	number	10	Minimum profit in basis points
maxCycles	number	5	Maximum arbitrage cycles to find
fastMode	boolean	false	Use faster but less optimal search

Response Format

Successful Response

{
  "from": "WEGLD-bd4d79",
  "to": "USDC-c76f1f",
  "amountIn": "1000000000000000000",
  "amountOut": "42500000",
  "amountInShort": 1.0,
  "amountOutShort": 42.5,
  "amountOutMin": "42075000",
  "amountOutMinShort": 42.075,
  "slippage": 0.01,
  "priceImpact": 0.0012,
  "rate": 42.5,
  "rateInverse": 0.0235,
  "paths": [...],
  "instructions": [...],
  "txData": "c3dhcEV4YWN0QW1...",
  "estimatedBuiltinCalls": 3,
  "feeBps": 30,
  "feeAmount": "127500",
  "feeAmountShort": 0.1275
}

Response Fields

Field	Type	Description
from	string	Input token identifier
to	string	Output token identifier
amountIn	string	Input amount in smallest units
amountOut	string	Output amount in smallest units
amountInShort	number	Human-readable input amount
amountOutShort	number	Human-readable output amount
amountOutMin	string	Minimum output after slippage
amountOutMinShort	number	Human-readable minimum output
amountInMax	string	Maximum input (reverse quotes only)
amountInMaxShort	number	Human-readable max input
slippage	number	Applied slippage tolerance
priceImpact	number	Estimated price impact (0.01 = 1%)
rate	number	Exchange rate (output per input)
rateInverse	number	Inverse rate (input per output)
paths	array	Detailed route breakdown
instructions	array	Smart contract instructions
txData	string	Base64-encoded transaction data
estimatedBuiltinCalls	number	Estimated SC calls
feeBps	number	Protocol fee in basis points
feeAmount	string	Fee amount in output token
feeAmountShort	number	Human-readable fee

Path Object

When includePaths=true, each path in the paths array contains:

{
  "amountIn": "500000000000000000",
  "amountOut": "21250000",
  "amountInShort": 0.5,
  "amountOutShort": 21.25,
  "splitPpm": 500000,
  "swaps": [
    {
      "dex": "xExchange",
      "pairId": 42,
      "address": "erd1qqq...",
      "from": "WEGLD-bd4d79",
      "to": "USDC-c76f1f",
      "amountIn": "500000000000000000",
      "amountOut": "21250000",
      "amountInShort": 0.5,
      "amountOutShort": 21.25
    }
  ]
}

Field	Type	Description
splitPpm	number	Path allocation in parts per million
swaps	array	Individual swaps in this path
swaps[].dex	string	DEX name (xExchange, AshSwap, JEX, OneDex)
swaps[].address	string	Pool smart contract address

Examples

Forward Quote

Get the best rate for swapping 1 EGLD to USDC:

curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountIn=1000000000000000000&\
slippage=0.005"

Reverse Quote

Calculate how much EGLD needed to receive exactly 100 USDC:

curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountOut=100000000&\
slippage=0.01"

Arbitrage Detection

Find profitable arbitrage cycles for WEGLD:

curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=WEGLD-bd4d79&\
amountIn=10000000000000000000&\
minProfitBps=50"

Large Trade with Splits

Optimize a large trade with multiple route splits:

curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountIn=100000000000000000000&\
maxSplits=8&\
algorithm=hybrid"

Minimal Response

Get quote without path details for faster response:

curl "https://swap.xoxno.com/api/v1/quote?\
from=WEGLD-bd4d79&\
to=USDC-c76f1f&\
amountIn=1000000000000000000&\
includePaths=false"

Error Responses

Unknown Token

{
  "error": "unknown token_in 'INVALID-123456'"
}

No Route Found

{
  "error": "routing failed: no path between tokens"
}

Invalid Amount

{
  "error": "invalid amount_in: expected unsigned integer amount"
}

Ambiguous Request

{
  "error": "specify either amount_in or amount_out, not both"
}

Token Identifiers

Token identifiers on MultiversX follow the format TICKER-hexcode:

Token	Identifier
Wrapped EGLD	WEGLD-bd4d79
USDC	USDC-c76f1f
USDT	USDT-f8c08c
UTK	UTK-2f80e9
MEX	MEX-455c57

Use the pair-config endpoint to verify token support and get decimal information.

Using Transaction Data

The txData field contains the raw transaction payload ready to be submitted to the aggregator smart contract. This includes the function name and all encoded arguments:

import { Transaction, TransactionPayload } from '@multiversx/sdk-core';

const quote = await fetchQuote(params);

// txData is the raw payload, e.g.: "swapExactAmountIn@..."
const tx = new Transaction({
  receiver: 'erd1qqqqqqqqqqqqqpgq...', // Aggregator contract
  sender: userAddress,
  value: quote.amountIn, // For EGLD swaps
  data: new TransactionPayload(quote.txData),
  gasLimit: 50000000,
  chainID: '1'
});

Example txData format:

swapExactAmountIn@0000000c555344432d633736663166@0de0b6b3a7640000@...

Rate Limiting

• Maximum 100 requests per second per IP

• Responses are not cached; each request computes fresh routes

• For high-frequency applications, consider WebSocket integration

Related Topics

• Pair Configuration - Verify token support before quoting

• Integration Guide - Complete integration walkthrough

• Relayer WebSocket - Real-time data and transaction tracking

• Troubleshooting - Common API issues