> 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`).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://rooster-protocol.gitbook.io/docs/developers/routes-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.