Simulate Route Swap

curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/route-swap/simulate \
  --header 'Content-Type: application/json' \
  --data '{
  "amountIn": "100000000",
  "hops": [
    {
      "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
      "assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
    },
    {
      "assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
      "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
    }
  ],
  "maxRouteSlippageBps": "100"
}'

{
  "executionPrice": "0.94",
  "hopBreakdown": [
    {
      "amountIn": "100000000",
      "amountOut": "4850000",
      "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778",
      "priceImpactPct": "3.00%"
    },
    {
      "amountIn": "4850000",
      "amountOut": "94000000",
      "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011",
      "priceImpactPct": "3.50%"
    }
  ],
  "outputAmount": "94000000",
  "totalHostFees": "1500000",
  "totalLpFees": "3000000",
  "totalPriceImpactPct": "6.50%",
  "warningMessage": "High total price impact"
}

Swaps

Simulate Route Swap

This endpoint allows users to preview the results of a multi-hop swap through a sequence of liquidity pools without executing the transaction. It calculates expected outputs, fees, and price impacts across the entire route.

Simulation Process

Load all pools in the route into memory
Validate asset pairs match between consecutive hops
Simulate each swap sequentially using current reserves
Calculate cumulative fees and price impacts
Apply slippage protection to determine viability
Return detailed breakdown without modifying state

Multi-Hop Calculation

The simulation executes virtually through each pool:

Each hop’s output becomes the next hop’s input
Fees are deducted at each step, compounding through route
Price impact accumulates across all hops
Final output reflects all fees and slippage

Route Validation

Before simulation, the system validates:

Minimum 2 hops required (use regular swap for single hop)
Maximum 4 hops allowed (to prevent excessive complexity)
All pools exist and have sufficient liquidity
Asset pairs are correctly chained (hop[n].output = hop[n+1].input)
Maximum slippage tolerance is reasonable (0-100%)

Price Impact Analysis

The simulation provides detailed impact metrics:

Per-hop impact: Price movement in each individual pool
Cumulative impact: Total price degradation across route
Warning threshold: Alerts when impact exceeds 5%
Impact increases with trade size relative to pool liquidity

Fee Breakdown

Simulation calculates all fees separately:

LP fees: Fees paid to liquidity providers at each pool
Host fees: Platform fees for each pool’s host
Total fees: Sum of all fees across the route
Fees compound (each reduces next hop’s input amount)

Execution Price

The execution price represents:

Effective exchange rate: output_amount / input_amount
Includes all fees and price impacts
Comparable to direct pair pricing for arbitrage detection

Use Cases

Route simulation is useful for:

Finding optimal paths between assets without direct pairs
Comparing routes for best execution
Estimating costs before committing funds
Detecting arbitrage opportunities
Understanding fee impact on large trades

No Authentication Required

Simulations are read-only operations that don’t modify pool state or require authentication. Anyone can simulate routes.

Arguments

hops - Ordered sequence of pools and assets defining the route
amount_in - Initial amount to swap through the route
max_route_slippage_bps - Maximum acceptable slippage in basis points

Returns

200 OK with detailed simulation results and per-hop breakdown
400 Bad Request if route validation fails or pools don’t exist
500 Internal Server Error if simulation calculation fails

POST

route-swap

simulate

Simulate Route Swap

curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/route-swap/simulate \
  --header 'Content-Type: application/json' \
  --data '{
  "amountIn": "100000000",
  "hops": [
    {
      "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
      "assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
    },
    {
      "assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
      "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
    }
  ],
  "maxRouteSlippageBps": "100"
}'

{
  "executionPrice": "0.94",
  "hopBreakdown": [
    {
      "amountIn": "100000000",
      "amountOut": "4850000",
      "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778",
      "priceImpactPct": "3.00%"
    },
    {
      "amountIn": "4850000",
      "amountOut": "94000000",
      "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011",
      "priceImpactPct": "3.50%"
    }
  ],
  "outputAmount": "94000000",
  "totalHostFees": "1500000",
  "totalLpFees": "3000000",
  "totalPriceImpactPct": "6.50%",
  "warningMessage": "High total price impact"
}

Body

application/json

Route simulation details including hop sequence and input amount

Defines the request for simulating a swap across a defined route of liquidity pools.

hops

object[]

required

An ordered sequence of pools and assets that defines the swap route. Must contain at least 2 hops and no more than 4 hops.

Show child attributes

Example:

[
  {
    "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
    "assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
    "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
  },
  {
    "assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
    "assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
    "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
  }
]

amountIn

integer

required

The total amount of the input asset to be swapped, in its smallest unit.

Required range: x >= 0

Example:

100000000

maxRouteSlippageBps

integer

required

The maximum acceptable slippage for the entire route, in basis points (0-10000).

Required range: x >= 0

Example:

100

Response

Route simulation successful

Represents the complete simulation result for the requested route swap.

outputAmount

integer

required

The estimated final amount of the output asset to be received, in its smallest unit.

Required range: x >= 0

executionPrice

string

required

The estimated effective price of the swap, calculated as output_amount / input_amount.

totalLpFees

integer

required

The total estimated fees paid to liquidity providers across all hops.

Required range: x >= 0

totalHostFees

integer

required

The total estimated fees paid to pool hosts across all hops.

Required range: x >= 0

totalPriceImpactPct

string

required

The total estimated price impact for the entire route as a percentage string.

hopBreakdown

object[]

required

A detailed breakdown of the simulation results for each hop in the route.

Show child attributes

warningMessage

string | null

An optional warning message, e.g., if the calculated slippage exceeds the user's maximum setting.

Execute Route Swap

Execute Swap

Auth

Clawback

Hosts

Integrators

Liquidity

Status

Pools

Swaps

Simulate Route Swap

Simulation Process

Multi-Hop Calculation

Route Validation

Price Impact Analysis

Fee Breakdown

Execution Price

Use Cases

No Authentication Required

Arguments

Returns

Body

Response