Pathfinder API - the Route Request Response

Sample Response

{
    "token_in":"0xacc15dc74880c9944775448304b263d191c6077f",
    "token_out":"0x818ec0a7fe18ff94269904fced6ae3dae6d6dc0b",
    "amount_in":"0x579a814e10a740000",
    "amount_out":"0x203c06b",
    "swap_paths":"0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000053392e0a296bb0000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000001000000000000000000000000b929914b89584b4081c7966ac6287636f7efd0530000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000818ec0a7fe18ff94269904fced6ae3dae6d6dc0b00000000000000000000000000000000000000000000000000000000000f36880000000000000000000000000000000000000000000000004615343e73b90000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000fc422eb0a2c7a99bad330377497fd9798c9b10010000000000000000000000008273de7090c7067f3ae1b6602eedbd2dbc02c48f0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a649325aa7c5093d12d6f98eb4378deae68ce23f00000000000000000000000000000000000000000000000000000000000f3688000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000000000000000000000000000000818ec0a7fe18ff94269904fced6ae3dae6d6dc0b0000000000000000000000000000000000000000000000000000000000000000",
    "swap_viz_data":[
        {
            "route_tokens":["0xacc15dc74880c9944775448304b263d191c6077f","0x818ec0a7fe18ff94269904fced6ae3dae6d6dc0b"],
            "route_protocols":["Beamswap"],
            "route_percent":95
        },
        {
            "route_tokens":["0xacc15dc74880c9944775448304b263d191c6077f","0xa649325aa7c5093d12d6f98eb4378deae68ce23f","0x818ec0a7fe18ff94269904fced6ae3dae6d6dc0b"],
            "route_protocols":["Beamswap","Beamswap"],
            "route_percent":5
        }
    ],
    "price_impact":0.0004684849937906582
}

The Route Response object contains the following fields:

A route request JSON object contains the following fields:

• token_out: Hex-string formatted swap output token address

• token_in: Hex-string formatted swap input token address

• amount_in: Hex-string formatted swap amount in

• amount_out: Hex-string formatted swap amount out (quote)

• swap_paths: Bytecode package for on-chain token swap call

• swap_viz_data: Data for graphical representation of the swap paths

• price impact: Estimated price impact for the swap.*

Confirming the quote on-chain

The quoted price can be confirmed via an on-chain call to the BrainDex Router contract by passing the route route request response swap_paths to getMultiSwapAmountOut() on the BrainDex Router contract.

Quote Confirmation function definition

interface IBrainDexRouter {
    function getMultiSwapAmountOut(bytes calldata data) external view returns(uint256);
}

Sample quote confirmation call using wagmi.sh

const swapAmountOutRead = useContractRead({
    addressOrName: routerContractAddress,
    contractInterface: BrainDexRouterAbi,
    functionName: "getMultiSwapAmountOut",
    args: [
        swap_paths
    ],
    cacheOnBlock: true,
    watch: true,
});

Route Response Parameters In-Depth

Contract call parameters

The following parameters are necessary inputs for the onchain call to perform the swap.

token_in

Hex-string formatted ethereum-style address. Should echo the token_in from the route request object.

token_out

Hex-string formatted ethereum-style address. Should echo the token_out from the route request object.

amount_in

Hex-string formatted integer value. Should echo the amount_in from the route request object.

amount_out

Hex-string formatted integer value, the swap output quote.

swap_paths

Hex-string formatted bytes package representing the routing data for the above parameters. Can be passed to the view function getMultiSwapAmountOut on the BrainDex Router to confirm quote result on chain.

Route visualization parameters

The following parameter is for route visualization via frontend interface.

price_impact

A decimal-formatted percentage value indicating the estimated price impact of the swap. Price impact is calculated as the weighted average of the sum of the price impacts for each hop in a route.

swap_viz_data

Array of path objects. Each element of the array represents one, the net of which represents the total route.

route_tokens

Array of token addresses, each representing one hop in the swap path. The first element should always be token_in, and the last element should always be token_out of above route response object. Intermediary addresses represent tokens used as intermediaries in a cross-trade route.

route_protocols

Array of protocol IDs, each representing the protocol through which the above swap was processed. This array should always be one element shorter than route_tokens, as the protocols represent the pool through which the tokens were swapped.

route_percent

Number value representing what percentage of the total swap volume was used for the given route. A value of 95 signifies that 95% of the total swap amount_in was routed through this route, whereas a value of 5 signifies that 5% of the total swap volume was routed through this route. For a given route response, all route_percents should sum to 100.

Price Impact Note

Due to the nature of cross-route swaps, sometimes price impact may be higher than 100%. This may change in the future.