Get Swap Quotes

The Router's /quote endpoint computes optimal swap routes across Ryze pools, returning amounts, fees, price impact, and oracle prices.

Endpoint

POST https://mainnet.router.ryze.pro/quote

Request

{
  "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "tokenOut": "0x4200000000000000000000000000000000000006",
  "amountIn": "100000000",
  "slippageTolerance": 50,
  "maxHops": 3,
  "userAddress": "0xYourWalletAddress"
}

Field	Type	Required	Description
tokenIn	string	Yes	Input token address
tokenOut	string	Yes	Output token address
amountIn	string	Exactly one of amountIn/amountOut	Exact input amount (raw units)
amountOut	string	Exactly one of amountIn/amountOut	Desired output amount (raw units)
slippageTolerance	number	Yes	Slippage in basis points (50 = 0.5%)
maxHops	number	Yes	Maximum hops in the route (1-3)
userAddress	string	No	Wallet address for TSP session lookup
preferredTokens	string[]	No	Preferred intermediate tokens
excludedPools	string[]	No	Pools to exclude from routing

TIP

Always pass userAddress when quoting for a specific user. This enables Trade Slicing Protection (TSP), which adjusts fees based on the user's recent trading session.

Example

# Swap 100 USDC -> WETH
curl -X POST https://mainnet.router.ryze.pro/quote \
  -H "Content-Type: application/json" \
  -d '{
    "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "tokenOut": "0x4200000000000000000000000000000000000006",
    "amountIn": "100000000",
    "slippageTolerance": 50,
    "maxHops": 3,
    "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  }'

Response

{
  "routeId": "a1b2c3d4",
  "type": "single_hop",
  "input": {
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "100000000",
    "decimals": 6
  },
  "output": {
    "token": "0x4200000000000000000000000000000000000006",
    "amount": "62500000000000000",
    "decimals": 18
  },
  "path": [
    "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "0x4200000000000000000000000000000000000006"
  ],
  "steps": [
    {
      "pool": "0x7B41aA91947398CD9244AD4e314C253D9B1B5206",
      "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "100000000",
      "amountOut": "62500000000000000",
      "priceImpact": "100000000000000",
      "fees": {
        "swapFee": "30000",
        "swapFeePct": "300000000000000",
        "takerFee": "10000",
        "takerFeePct": "100000000000000",
        "slippageFee": "5000",
        "slippagePct": "50000000000000",
        "wbfFee": "0",
        "wbfFeePct": "0",
        "wbrReward": "2000",
        "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  ],
  "totalFees": { ... },
  "incentive": {
    "maxBps": 75,
    "displayPct": "0.075%",
    "tokenOut": "0x4200000000000000000000000000000000000006",
    "isImproving": true
  },
  "priceImpact": "100000000000000",
  "spotPrice": "1600000000000000000000",
  "executionPrice": "1599840000000000000000",
  "confidence": 1.0,
  "timestamp": "2026-04-15T12:00:00Z",
  "prices": [
    {
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "pythPrice": "1000000000000000000",
      "cexPrice": "1000000000000000000",
      "blendFactor": "500000000000000000",
      "blendedPrice": "1000000000000000000"
    },
    {
      "token": "0x4200000000000000000000000000000000000006",
      "pythPrice": "1600000000000000000000",
      "cexPrice": "1600500000000000000000",
      "blendFactor": "500000000000000000",
      "blendedPrice": "1600250000000000000000"
    }
  ]
}

Response Fields

Top-Level

Field	Description
routeId	Unique route identifier
type	"single_hop" or "multi_hop"
input / output	Token address, raw amount, and decimals
path	Ordered array of token addresses in the route
steps	Per-hop breakdown (pool, amounts, fees)
priceImpact	Overall price impact in WAD
spotPrice	Oracle spot price (tokenOut per tokenIn) in WAD
executionPrice	Effective execution price in WAD
confidence	Route confidence (0-1)
prices	Oracle price data for each token

Fee Breakdown (per step)

Field	Description
swapFee / swapFeePct	Base swap fee (amount + WAD percentage)
takerFee / takerFeePct	Taker fee
slippageFee / slippagePct	Dynamic slippage fee based on trade size
wbfFee / wbfFeePct	Weight Breaking Fee (penalizes imbalancing trades)
wbrReward	Weight Breaking Reward (incentivizes rebalancing trades)
token	Address of the fee token

Incentive

The incentive object indicates potential Weight Breaking Reward:

Field	Description
maxBps	Maximum incentive in basis points
displayPct	Human-readable percentage string
isImproving	Whether the trade improves pool balance

Prices

Each entry in prices shows how the oracle price is computed:

Field	Description
pythPrice	Pyth oracle price in WAD
cexPrice	CEX reference price in WAD
blendFactor	Blend ratio (0 = pure Pyth, 1e18 = pure CEX)
blendedPrice	Final blended price used for the quote

Response Headers

Header	Description
X-Processing-Time-Us	Total processing time in microseconds
X-Route-Time-Us	Route-finding time in microseconds

Converting Amounts

To convert raw amounts to human-readable values:

// USDC (6 decimals): 100000000 -> 100.0
const usdcAmount = Number(BigInt(raw)) / 10 ** 6;

// WETH (18 decimals): 62500000000000000 -> 0.0625
const wethAmount = Number(BigInt(raw)) / 10 ** 18;

// WAD percentage to percent: 300000000000000 -> 0.03%
const pct = Number(BigInt(wadPct)) / 10 ** 18 * 100;