> ## Documentation Index > Fetch the complete documentation index at: https://docs.swap.coffee/llms.txt > Use this file to discover all available pages before exploring further. # Returns the best route for the given trade pair ## OpenAPI ````yaml https://backend.swap.coffee/openapi post /v1/route openapi: 3.0.3 info: title: Swap Coffee API version: 1.0.0 servers: - url: https://backend.swap.coffee/ - url: http://localhost:8080/ security: - {} - ApiKey: [] tags: - name: Entity description: Tokens, pools, DEXes, etc. - name: Routing description: >- Core functionality of the aggregation service. Build routes, get transactions, etc. - name: Strategies description: Limit orders, DCA, VCA, etc. - name: Yield description: >- Yield aggregator functionality. Provides and handles routes to pools with the best yield. - name: Referral description: Everything related to the referral program of swap.coffee. - name: Cashback description: Cashback programs conducted on swap.coffee. - name: Claim description: Claiming various rewards available on swap.coffee. - name: Contests description: Timed contests based on trading volumes for certain token-pairs. - name: Staking description: Responsible of managing staked funds, corresponding rewards, etc. - name: DEX description: Core functionality of the Coffee DEX service. - name: LiquidityProvisioning description: Everything related to liquidity provisioning in DEXes. - name: Boosts description: >- Functionality to support incentives and rewards for liquidity providers among all DEXes. - name: Profile description: Retrieve information about user profiles. - name: Partnership description: Various functionality for our partners. - name: Statistics description: Retrieve information about dex aggregation stats. - name: Ton description: Retrieve information about TON entities. - name: Auth description: Auth operations. For internal usage only. paths: /v1/route: post: tags: - Routing summary: Returns the best route for the given trade pair operationId: buildRoute requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApiRouteRequest' responses: '200': description: resulting route content: application/json: schema: $ref: '#/components/schemas/ApiRoute' default: $ref: '#/components/responses/ApiError' components: schemas: ApiRouteRequest: type: object required: - input_token - output_token properties: input_token: $ref: '#/components/schemas/ApiTokenAddress' output_token: $ref: '#/components/schemas/ApiTokenAddress' input_amount: type: number format: double description: Input amount in tokens (not nano!) to be swapped minimum: 0 exclusiveMinimum: true output_amount: type: number description: >- If specified, the route will be built to get the specified output amount. If not specified, the route will be built to get the maximum output amount for the given input amount. format: double minimum: 0 exclusiveMinimum: true max_splits: type: integer format: int32 description: >- Defines the maximum number of independent paths (i.e., transactions) the route can split into. For v4 wallets, you can omit this or set it to 4; for v5 wallets, you can set it to 20 (this is our internal upper limit, and we may reduce it later to something like 10). minimum: 1 maximum: 20 default: 4 max_length: type: integer format: int32 description: >- Defines the maximum length of each path in tokens. It accepts values from [2; 5]. If it's 2, only direct swaps A -> B without multihops are possible. If it's 3, there can be a maximum of 1 intermediate token, i.e., A -> X -> B. If it's 4/5, there can be 2/3 intermediate tokens. A value of 2 deprives you of more profitable exchanges by finding market inefficiencies and does not allow you to exchange tokens without a direct pair (since there can be no intermediate tokens). The higher the value, the more profitable routes can be built, but the higher the likelihood that the user ends up with an intermediate token (since our blockchain is asynchronous, and some swap in the middle of the route may fail due to slippage). minimum: 2 maximum: 5 default: 3 pool_selector: $ref: '#/components/schemas/ApiPoolSelector' mev_protection: type: boolean description: Whether a MEV protection should be enabled example: true additional_data: $ref: '#/components/schemas/ApiRouteRequestAdditionalData' ApiRoute: type: object required: - input_token - output_token - input_amount - output_amount - input_usd - output_usd - recommended_gas - price_impact - paths properties: input_token: $ref: '#/components/schemas/ApiToken' output_token: $ref: '#/components/schemas/ApiToken' input_amount: type: number format: double output_amount: type: number format: double input_usd: type: number format: double output_usd: type: number format: double savings: type: number format: double left_amount: type: number format: double recommended_gas: type: number format: double price_impact: type: number format: double estimated_cashback_usd: type: number format: double partner_commission_ton: type: number format: double mev_protection_fee: type: number description: Fees for the usage of MEV protection. format: double paths: type: array items: $ref: '#/components/schemas/ApiRoutingStep' ApiTokenAddress: type: object required: - blockchain - address properties: blockchain: type: string example: ton address: type: string example: native ApiPoolSelector: type: object description: >- Configures the DEX pools that can appear in the generated route. By setting blockchains = ["ton"] inside it, you can remove the dexes field; max_volatility allows you to exclude pools whose volatility has been above a certain percentage in the last 15 minutes. This makes sense when you allow 2-3 intermediate tokens or a large number of splits to smooth out potential issues. properties: blockchains: description: >- If specified, only pools from given blockchains will be used for routing type: array minItems: 1 items: type: string example: ton dexes: description: If specified, only pools from given dexes will be used for routing type: array minItems: 1 items: type: string example: dedust max_volatility: description: >- If specified, only pools with volatility lower than given value will be used for routing type: number format: double minimum: 0 ApiRouteRequestAdditionalData: type: object properties: sender_address: type: string example: UQCNTO0Nh0Z7QNyRW1BLWfk08f2dAOw4izrx9sO6OUPg4DoV referral_name: type: string example: tonkeeper ApiToken: type: object required: - address - metadata properties: address: $ref: '#/components/schemas/ApiTokenAddress' metadata: $ref: '#/components/schemas/ApiTokenMetadata' ApiRoutingStep: type: object required: - blockchain - dex - pool_address - input_token - output_token - swap - recommended_gas - average_gas properties: blockchain: type: string example: ton dex: type: string example: stonfi pool_address: type: string input_token: $ref: '#/components/schemas/ApiToken' output_token: $ref: '#/components/schemas/ApiToken' swap: $ref: '#/components/schemas/ApiSwap' recommended_gas: type: number format: double average_gas: type: number format: double next: type: array items: $ref: '#/components/schemas/ApiRoutingStep' ApiTokenMetadata: type: object required: - name - symbol - decimals - listed - verification properties: name: type: string example: ARBUZ symbol: type: string example: ARBUZ decimals: type: integer format: int32 image_url: type: string listed: type: boolean verification: $ref: '#/components/schemas/ApiTokenVerification' ApiSwap: type: object required: - result - input_amount - output_amount - before_reserves - after_reserves properties: result: $ref: '#/components/schemas/ApiSwapResult' input_amount: type: number format: double output_amount: type: number format: double before_reserves: $ref: '#/components/schemas/ApiPoolReserves' after_reserves: $ref: '#/components/schemas/ApiPoolReserves' reason: type: string left_amount: type: number format: double ApiTokenVerification: type: string enum: - whitelisted - blacklisted - community - unknown ApiSwapResult: type: string description: Result of the swap enum: - fully_fulfilled - partially_fulfilled - unavailable ApiPoolReserves: type: array items: type: number format: double responses: ApiError: description: Some error during request processing content: application/json: schema: type: object required: - error properties: error: type: string securitySchemes: ApiKey: type: apiKey name: X-Api-Key in: header ````