> For the complete documentation index, see [llms.txt](https://rooster-protocol.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rooster-protocol.gitbook.io/docs/developers/routes-api.md).

# Routes API

## Calculate Optimal Swap Paths

> Accepts an input token, output token, and the amount to swap.\
> Queries available liquidity pools, calculates potential 1-hop, 2-hop, and 3-hop paths,\
> checks for sufficient liquidity for the given amount, scores the paths based on liquidity,\
> volume, and fees, and returns the top 5 ranked paths.

```json
{"openapi":"3.0.0","info":{"title":"Swap Path Finder API","version":"1.0.0"},"servers":[{"url":"https://api.rooster-protocol.xyz"}],"paths":{"/api/swap":{"post":{"summary":"Calculate Optimal Swap Paths","description":"Accepts an input token, output token, and the amount to swap.\nQueries available liquidity pools, calculates potential 1-hop, 2-hop, and 3-hop paths,\nchecks for sufficient liquidity for the given amount, scores the paths based on liquidity,\nvolume, and fees, and returns the top 5 ranked paths.","operationId":"calculateSwapPaths","tags":["Swap Routing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapRequest"}}}},"responses":{"200":{"description":"Successfully calculated and returned the top swap paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapPathsResponse"}}}},"400":{"description":"Bad Request - Missing or invalid required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Failed to calculate swap routes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"SwapRequest":{"type":"object","required":["amount","inputTokenAddress","outputTokenAddress"],"properties":{"amount":{"type":"string","format":"decimal","description":"The amount of the input token to swap, represented as a string to preserve precision."},"inputTokenAddress":{"type":"string","format":"address","description":"The contract address of the token being swapped FROM.","pattern":"^0x[a-fA-F0-9]{40}$"},"outputTokenAddress":{"type":"string","format":"address","description":"The contract address of the token being swapped TO.","pattern":"^0x[a-fA-F0-9]{40}$"}}},"SwapPathsResponse":{"type":"object","properties":{"paths":{"type":"array","description":"An array containing the top 5 ranked swap paths. Each path itself is an array.","items":{"type":"array","description":"Represents a single swap path consisting of one or more hops.\nThe array alternates between a pool address (string) and a boolean flag.\nThe boolean flag indicates if the input for that specific pool hop is Token A (`true`) or Token B (`false`) of the pool.\nExample 1-hop: [pool_address, is_token_A_input]\nExample 2-hop: [pool1_address, is_token_A_input1, pool2_address, is_token_A_input2]","items":{"oneOf":[{"type":"string","description":"The contract address of the liquidity pool for this hop.","pattern":"^0x[a-fA-F0-9]{40}$"},{"type":"boolean","description":"Indicates the direction of the swap within the *preceding* pool address.\n`true`: The token entering the preceding pool is Token A.\n`false`: The token entering the preceding pool is Token B."}]}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"A message describing the error that occurred."}}}}}}
```

## The SwapRequest object

```json
{"openapi":"3.0.0","info":{"title":"Swap Path Finder API","version":"1.0.0"},"components":{"schemas":{"SwapRequest":{"type":"object","required":["amount","inputTokenAddress","outputTokenAddress"],"properties":{"amount":{"type":"string","format":"decimal","description":"The amount of the input token to swap, represented as a string to preserve precision."},"inputTokenAddress":{"type":"string","format":"address","description":"The contract address of the token being swapped FROM.","pattern":"^0x[a-fA-F0-9]{40}$"},"outputTokenAddress":{"type":"string","format":"address","description":"The contract address of the token being swapped TO.","pattern":"^0x[a-fA-F0-9]{40}$"}}}}}}
```

## The SwapPathsResponse object

```json
{"openapi":"3.0.0","info":{"title":"Swap Path Finder API","version":"1.0.0"},"components":{"schemas":{"SwapPathsResponse":{"type":"object","properties":{"paths":{"type":"array","description":"An array containing the top 5 ranked swap paths. Each path itself is an array.","items":{"type":"array","description":"Represents a single swap path consisting of one or more hops.\nThe array alternates between a pool address (string) and a boolean flag.\nThe boolean flag indicates if the input for that specific pool hop is Token A (`true`) or Token B (`false`) of the pool.\nExample 1-hop: [pool_address, is_token_A_input]\nExample 2-hop: [pool1_address, is_token_A_input1, pool2_address, is_token_A_input2]","items":{"oneOf":[{"type":"string","description":"The contract address of the liquidity pool for this hop.","pattern":"^0x[a-fA-F0-9]{40}$"},{"type":"boolean","description":"Indicates the direction of the swap within the *preceding* pool address.\n`true`: The token entering the preceding pool is Token A.\n`false`: The token entering the preceding pool is Token B."}]}}}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.0.0","info":{"title":"Swap Path Finder API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"A message describing the error that occurred."}}}}}}
```

***

### RPC Calls to Quoter

With the paths, a user can use RPC calls to the [MaverickV2Quoter](https://phoenix-explorer.plumenetwork.xyz/address/0xf245948e9cf892C351361d298cc7c5b217C36D82?tab=write_contract) contract and `calculateMultiHopSwap` function to get the prices. 

**calculateMultiHopSwap**

Calculates a multihop swap and returns the resulting amount and estimated gas. The gas estimate is only a rough estimate and may not match a swap's gas.

Copy

```
function calculateMultiHopSwap(bytes memory path, uint256 amount, bool exactOutput)
    external
    returns (uint256 returnAmount, uint256 gasEstimate);
```

**Parameters**

`path`

`bytes`

The path of pools to swap through. Path is given by an packed array of `(pool, tokenAIn)` tuples. So each step in the path is 160 + 8 = 168 bits of data. e.g. `path = abi.encodePacked(pool1, true, pool2, false);`

`amount`

`uint256`

The raw input amount.  (e.g. 1.0 in an 18-decimal token will be 1e18)

`exactOutput`

`bool`

A boolean indicating whether `amount` is the desired *input* amount (`false`) or the desired *output* amount (`true`).

<br>