> For the complete documentation index, see [llms.txt](https://swapnet-1.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://swapnet-1.gitbook.io/docs/reference/api/swapnet-aggregator-api.md).
# SwapNet Aggregator API
## Get swap routing plan
> Returns a graph-based routing plan for swap request. The plan includes detailed routes \
> through various liquidity sources and can optionally include encoded calldata for immediate execution.
```json
{"openapi":"3.0.3","info":{"title":"SwapNet Aggregator API","version":"1.0.0"},"servers":[{"url":"https://app.swap-net.xyz/api/v1.0","description":"Production server"}],"paths":{"/swap":{"get":{"summary":"Get swap routing plan","description":"Returns a graph-based routing plan for swap request. The plan includes detailed routes \nthrough various liquidity sources and can optionally include encoded calldata for immediate execution.\n","operationId":"getSwapRoute","parameters":[{"name":"chainId","in":"query","required":true,"description":"Integer ID of the blockchain","schema":{"type":"integer"}},{"name":"sellToken","in":"query","required":true,"description":"Address of sell token. For native tokens, use either \n`0x0000000000000000000000000000000000000000` or `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`\n","schema":{"type":"string"}},{"name":"buyToken","in":"query","required":true,"description":"Address of buy token. For native tokens, use either \n`0x0000000000000000000000000000000000000000` or `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`\n","schema":{"type":"string"}},{"name":"sellAmount","in":"query","required":false,"description":"Amount of sellToken to sell (in base units). \nExactly one of sellAmount or buyAmount must be provided.\n","schema":{"type":"string"}},{"name":"buyAmount","in":"query","required":false,"description":"Amount of buyToken to buy (in base units). \nExactly one of sellAmount or buyAmount must be provided.\n","schema":{"type":"string"}},{"name":"useRfq","in":"query","required":false,"description":"Whether to use market maker RFQ liquidity","schema":{"type":"boolean","default":false}},{"name":"router","in":"query","required":false,"description":"Router contract unique name","schema":{"type":"string","enum":["swapnet-router","universal-router","default-router"],"default":"default-router"}},{"name":"includeCalldata","in":"query","required":false,"description":"Whether to include calldata in the response","schema":{"type":"boolean","default":false}},{"name":"userAddress","in":"query","required":false,"description":"User's wallet address. Required when includeCalldata=true\n","schema":{"type":"string"}},{"name":"slippageTolerance","in":"query","required":false,"description":"Slippage tolerance (0.01 = 1%). Required when includeCalldata=true\n","schema":{"type":"number","minimum":0,"maximum":1,"multipleOf":0.0001}},{"name":"apiKey","in":"query","required":true,"description":"Your API key","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful swap routing response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapResponse"}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SwapResponse":{"type":"object","required":["aggregator","router","sell","buy","nativeTokenUsdPrice","tokens","routes"],"properties":{"aggregator":{"type":"string","description":"Name of the aggregator service"},"router":{"type":"string","description":"Router contract unique name used"},"sell":{"$ref":"#/components/schemas/TradeToken"},"buy":{"$ref":"#/components/schemas/TradeToken"},"nativeTokenUsdPrice":{"type":"number","description":"Current price of the native token on this chain"},"tokens":{"type":"array","description":"Metadata of tokens involved in the routing result","items":{"$ref":"#/components/schemas/Token"}},"routes":{"type":"array","description":"Collection of swaps forming a directed acyclic graph","items":{"$ref":"#/components/schemas/Route"}},"routerAddress":{"type":"string","description":"Address of router contract (only when includeCalldata=true)"},"calldata":{"type":"string","description":"Calldata to settle the trade (only when includeCalldata=true)"},"gasLimit":{"type":"string","description":"Estimated upper bound of gas consumption (only when includeCalldata=true)"}}},"TradeToken":{"type":"object","required":["referenceId","amount"],"properties":{"referenceId":{"type":"integer","description":"Reference ID of the token in the tokens array"},"amount":{"type":"string","description":"Amount of the token in base units"},"wrapFromNative":{"type":"boolean","description":"Whether the sell token is native token that needs wrapping"},"unwrapToNative":{"type":"boolean","description":"Whether the buy token is native token that needs unwrapping"}}},"Token":{"type":"object","required":["referenceId","address","name","symbol","decimals","usdPrice"],"properties":{"referenceId":{"type":"integer","description":"Unique reference ID for this token"},"address":{"type":"string","description":"Token contract address"},"name":{"type":"string","description":"Token name"},"symbol":{"type":"string","description":"Token symbol"},"decimals":{"type":"integer","description":"Number of decimal places for the token","minimum":0,"maximum":18},"usdPrice":{"type":"number","description":"Current USD price of the token"}}},"Route":{"type":"object","required":["address","name","fromTokens","toTokens"],"properties":{"address":{"type":"string","description":"Address of the liquidity pool"},"name":{"type":"string","description":"Name of the liquidity source"},"details":{"type":"object","description":"Additional information about this route used during encoding","additionalProperties":true},"fromTokens":{"type":"array","description":"Tokens to swap from","items":{"$ref":"#/components/schemas/RouteToken"}},"toTokens":{"type":"array","description":"Tokens to swap to","items":{"$ref":"#/components/schemas/RouteToken"}}}},"RouteToken":{"type":"object","required":["referenceId","amount"],"properties":{"referenceId":{"type":"integer","description":"Reference ID of the token in the tokens array"},"amount":{"type":"string","description":"Amount of the token in base units"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","description":"Additional error details","additionalProperties":true}}}}}}
```
## Get example tokens
> Returns a list of example tokens for trading on the specified chain. Notice that this is not \
> a full list of tradable tokens.
```json
{"openapi":"3.0.3","info":{"title":"SwapNet Aggregator API","version":"1.0.0"},"servers":[{"url":"https://app.swap-net.xyz/api/v1.0","description":"Production server"}],"paths":{"/tokens":{"get":{"summary":"Get example tokens","description":"Returns a list of example tokens for trading on the specified chain. Notice that this is not \na full list of tradable tokens.\n","operationId":"getTokens","parameters":[{"name":"chainId","in":"query","required":true,"description":"Integer ID of the blockchain","schema":{"type":"integer"}},{"name":"apiKey","in":"query","required":true,"description":"Your API key","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful tokens response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TokenInfo"}}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"TokenInfo":{"type":"object","required":["address","name","symbol","decimals","metadata"],"properties":{"address":{"type":"string","description":"Token contract address"},"name":{"type":"string","description":"Token name"},"symbol":{"type":"string","description":"Token symbol"},"decimals":{"type":"integer","description":"Number of decimal places for the token","minimum":0,"maximum":18},"metadata":{"type":"object","required":["logoURI"],"properties":{"logoURI":{"type":"string","description":"URL to the token's logo image"}}}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","description":"Additional error details","additionalProperties":true}}}}}}
```
## Get available chains
> Returns a list of blockchain networks supported by the SwapNet aggregator.
```json
{"openapi":"3.0.3","info":{"title":"SwapNet Aggregator API","version":"1.0.0"},"servers":[{"url":"https://app.swap-net.xyz/api/v1.0","description":"Production server"}],"paths":{"/chains":{"get":{"summary":"Get available chains","description":"Returns a list of blockchain networks supported by the SwapNet aggregator.\n","operationId":"getChains","parameters":[{"name":"apiKey","in":"query","required":true,"description":"Your API key","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful chains response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Chain":{"type":"object","required":["chainId","name"],"properties":{"chainId":{"type":"integer","description":"Unique identifier for the blockchain network"},"name":{"type":"string","description":"Human-readable name of the blockchain network"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","description":"Additional error details","additionalProperties":true}}}}}}
```
## Get detailed chain information
> Returns detailed information about a specific blockchain network, including\
> supported routers, liquidity sources, and key token addresses.
```json
{"openapi":"3.0.3","info":{"title":"SwapNet Aggregator API","version":"1.0.0"},"servers":[{"url":"https://app.swap-net.xyz/api/v1.0","description":"Production server"}],"paths":{"/chainInfo":{"get":{"summary":"Get detailed chain information","description":"Returns detailed information about a specific blockchain network, including\nsupported routers, liquidity sources, and key token addresses.\n","operationId":"getChainInfo","parameters":[{"name":"chainId","in":"query","required":true,"description":"Integer ID of the blockchain","schema":{"type":"integer"}},{"name":"apiKey","in":"query","required":true,"description":"Your API key","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful chain info response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainInfo"}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ChainInfo":{"type":"object","required":["chainId","name","usdTokenAddress","wrappedNativeTokenAddress","routers"],"properties":{"chainId":{"type":"integer","description":"Unique identifier for the blockchain network"},"name":{"type":"string","description":"Human-readable name of the blockchain network"},"usdTokenAddress":{"type":"string","description":"Address of the primary USD-pegged token on this chain"},"wrappedNativeTokenAddress":{"type":"string","description":"Address of the wrapped native token (e.g., WETH, WMATIC)"},"routers":{"type":"array","description":"Available router contracts and their configurations","items":{"$ref":"#/components/schemas/RouterInfo"}}}},"RouterInfo":{"type":"object","required":["name","liquiditySources","deployedAddress","hasEncoder"],"properties":{"name":{"type":"string","description":"Router contract unique name","enum":["swapnet-router","universal-router","default-router"]},"liquiditySources":{"type":"array","description":"Supported liquidity sources for this router","items":{"type":"string"}},"deployedAddress":{"type":"string","description":"Deployed address of the router contract"},"tokenProxyAddress":{"type":"string","description":"Address of the token proxy contract (if applicable)"},"hasEncoder":{"type":"boolean","description":"Whether the router has an available encoder for calldata generation"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","description":"Additional error details","additionalProperties":true}}}}}}
```