Syntax

exchange.IO("simulate", ...)

Builds a swap transaction with the order logic (route selection, quoting, price protection) and only simulates it on chain (eth_call): nothing is signed, broadcast or paid.


    
    
    
exchange.IO(k, symbol, side, qty)


    
    
    
exchange.IO(k, symbol, side, qty, price)


    
    
    
exchange.IO(k, symbol, side, qty, price, stateOverride)


    
    
    
exchange.IO(k, symbol, side, qty, price, stateOverride, route)

Examples

Gives the wallet a temporary balance of 100 ETH and simulates selling 1 ETH.


    javascript
    
    
function main() {
    var ov = {}
    ov[exchange.IO("address")] = { balance: "0x56bc75e2d63100000" }
    var r = exchange.IO("simulate", "ETH_USDC", "sell", 1, null, ov)
    Log("Route:", r.route, "quoted:", r.quoted, "simulated:", r.executed)
}

Returns

Type	Description
object / null value	Returns `{route, exactIn, amountIn, amountOut, quoted, executed, value, calls}`. The key fields are the quote at order time, `quoted`, and the amount from the simulated execution, `executed`. See the remarks for what each field means. If the order cannot be filled, the function returns null and reports an error.

Arguments

Name	Type	Required	Description
k	string	Yes	Always `simulate`. It selects a simulated order.
symbol	string	Yes	The trading pair, for example `ETH_USDC`.
side	string	Yes	The trade direction: `buy` or `sell`.
qty	number	Yes	The order quantity. It has the same meaning as in `exchange.CreateOrder()`. For a market buy, it is the amount of quote currency to spend.
price	number	No	The limit price. If you omit it or pass `null`, the order is a market order.
stateOverride	object	No	The state override parameter for the node's `eth_call` (the geth state override set). Use it to give the wallet temporary balance or allowance during the simulation, for example `{"0xWalletAddress": {"balance": "0x56bc75e2d63100000"}}`. It applies to this simulation only.
route	string	No	Limits the route type: `v2`, `v3`, `v4`, `hop` (two hops) or `direct` (direct pool). On PancakeSwap, `v4` means the Infinity CL pools. On Aerodrome and Velodrome, `v2` means the basic pools and `v3` means the Slipstream pools (`v4` is not supported). If omitted, the best route among all routes is used.

Remarks

The simulation uses the latest block state. The only difference from a real order is that the price may change before the transaction is actually included on-chain.

For a swap paid with a token (such as buying with USDC), a short wallet allowance is supplied through a state override before simulating (approve defaults to exact, which approves only right before a real order), and allowanceOverride in the result lists what was supplied; a stateOverride you pass is merged with it, without overwriting slots you set. Balances are not supplied: when paying with the native coin, give the wallet a balance in stateOverride; when paying with a token, override the token contract's balance slot yourself.

Fields of the returned object: quoted is the quote at order time. executed is the actual amount from the simulated execution: the amount received for an exact-input swap, or the amount spent for an exact-output swap. Both are decimal strings in the token's smallest unit. Uniswap V4 routes and PancakeSwap Infinity routes run through the Universal
Router, which does not return the filled amount, so executed is null. In that case, a simulation that does not fail means the order can be filled with these parameters, including the minimum amount received or maximum amount spent. If the limit price is not met, or the balance or allowance is too low (and not overridden), the function returns null and reports an error.

On the KyberSwap and 1inch exchange objects (aggregators) the transaction built by the aggregator is simulated, and route looks like kyberswap:ETH-USDC via flux-prop, listing the liquidity sources after via; the seventh argument route does not apply and fails with route is not applicable to the KyberSwap aggregator (likewise for 1inch).