Kyber Network Service API

openapi: 3.0.0
info:
  title: KyberSwap Aggregator General Service API
  version: 2.12.1
servers:
- url: https://aggregator-api.kyberswap.com
tags:
- name: Service
paths:
  /api/v1/in/route:
    get:
      tags:
      - Service
      summary: Get the best zap-in route.
      operationId: Service_GetInRoute
      parameters:
      - name: dex
        in: query
        description: Refer to https://docs.kyberswap.com/kyberswap-solutions/kyberswap-zap-as-a-service/zaps-supported-chains-dexes for list of supported dexes for each chain
        required: true
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DEX_UNISWAPV3
      - name: pool.id
        in: query
        description: id of the pool to zap into.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: position.id
        in: query
        description: id of the position to add liquidity to; omit to create a new uniswapV3 position. for uniswapV2 this is user address
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: position.tickLower
        in: query
        description: min tick of the position, required if creating a new uniswapV3 position.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: position.tickUpper
        in: query
        description: max tick of the position, required if creating a new uniswapV3 position.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: tokensIn
        in: query
        description: which token(s) to use as zap source. also accepts comma separated addresses
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: amountsIn
        in: query
        description: amount(s) to zap including fee, corresponding to tokenIn. also accepts comma separated amounts.
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: tokenIn
        in: query
        description: 'which token(s) to use as zap source. also accepts comma separated addresses.

          deprecated: use tokens_in. if both fields are specified, they are combined'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: amountIn
        in: query
        description: 'amount(s) to zap including fee, corresponding to tokenIn. also accepts comma separated amounts.

          deprecated: use amounts_in. if both fields are specified, they are combined'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: aggregatorOptions.disable
        in: query
        description: whether to disable swapping with the aggregator
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: aggregatorOptions.includedSources
        in: query
        description: comma-separated list of sources to use for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedSources
        in: query
        description: comma-separated list of sources to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedPools
        in: query
        description: comma-separated list of pools to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feeAddress
        in: query
        description: the address of the fee recipient.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feePcm
        in: query
        description: 'fee percentage in per cent mille (0.001% or 1 in 100,000). Ignored if feeAddress is empty.

          From 0 to 100,000 inclusively. Example: 1 for 0.001%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: slippage
        in: query
        description: 'maximum slippage tolerance in basis points (0.01%), used for aggregator (exceeding which the transaction will

          revert) and pool swap during zap (for additional zapping and for refund).

          From 0 to 10,000 inclusively. Example: 1 for 0.01%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: X-Client-Id
        in: header
        description: Client Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: Request Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1GetInRouteResponse'
        '400':
          description: Invalid Argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
  /api/v1/migrate/route:
    get:
      tags:
      - Service
      summary: Get the best zap-migrate route.
      operationId: Service_GetMigrateRoute
      parameters:
      - name: dexFrom
        in: query
        description: Refer to https://docs.kyberswap.com/kyberswap-solutions/kyberswap-zap-as-a-service/zaps-supported-chains-dexes for list of supported dexes for each chain
        required: true
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DEX_UNISWAPV3
      - name: dexTo
        in: query
        description: Refer to https://docs.kyberswap.com/kyberswap-solutions/kyberswap-zap-as-a-service/zaps-supported-chains-dexes for list of supported dexes for each chain
        required: true
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DEX_UNISWAPV3
      - name: poolFrom.id
        in: query
        description: id of the pool to zap into.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: poolTo.id
        in: query
        description: id of the pool to zap into.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: positionFrom.id
        in: query
        description: id of the position to withdraw from
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: positionTo.id
        in: query
        description: id of the position to add liquidity to; omit to create a new uniswapV3 position. for uniswapV2 this is user address
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: positionTo.tickLower
        in: query
        description: min tick of the position, required if creating a new uniswapV3 position.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: positionTo.tickUpper
        in: query
        description: max tick of the position, required if creating a new uniswapV3 position.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: liquidityOut
        in: query
        description: liquidity amount to withdraw, or empty or 0 to withdraw all
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.disable
        in: query
        description: whether to disable swapping with the aggregator
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: aggregatorOptions.includedSources
        in: query
        description: comma-separated list of sources to use for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedSources
        in: query
        description: comma-separated list of sources to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedPools
        in: query
        description: comma-separated list of pools to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feeAddress
        in: query
        description: 'options for getting aggregator routes

          the address of the fee recipient.'
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feePcm
        in: query
        description: 'fee percentage in per cent mille (0.001% or 1 in 100,000). Ignored if feeAddress is empty.

          From 0 to 100,000 inclusively. Example: 1 for 0.001%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: slippage
        in: query
        description: 'maximum slippage tolerance in basis points (0.01%), used for aggregator (exceeding which the transaction will

          revert) and pool swap during zap (for additional zapping and for refund).

          From 0 to 10,000 inclusively. Example: 1 for 0.01%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: X-Client-Id
        in: header
        description: Client Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: Request Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1GetMigrateRouteResponse'
        '400':
          description: Invalid Argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
  /api/v1/out/route:
    get:
      tags:
      - Service
      summary: Get the best zap-out route.
      operationId: Service_GetOutRoute
      parameters:
      - name: dexFrom
        in: query
        description: Refer to https://docs.kyberswap.com/kyberswap-solutions/kyberswap-zap-as-a-service/zaps-supported-chains-dexes for list of supported dexes for each chain
        required: true
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DEX_UNISWAPV3
      - name: poolFrom.id
        in: query
        description: id of the pool to withdraw from.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: positionFrom.id
        in: query
        description: id of the position to withdraw from
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: liquidityOut
        in: query
        description: liquidity amount to withdraw, or empty or 0 to withdraw all
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: tokenOut
        in: query
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.disable
        in: query
        description: whether to disable swapping with the aggregator
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: aggregatorOptions.includedSources
        in: query
        description: comma-separated list of sources to use for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedSources
        in: query
        description: comma-separated list of sources to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: aggregatorOptions.excludedPools
        in: query
        description: comma-separated list of pools to exclude for aggregator
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feeAddress
        in: query
        description: fee recipient
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: feePcm
        in: query
        description: 'fee percentage in per cent mille (0.001% or 1 in 100,000). Ignored if feeAddress is empty.

          From 0 to 100,000 inclusively. Example: 1 for 0.001%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: slippage
        in: query
        description: 'maximum slippage tolerance in basis points (0.01%), used for aggregator (exceeding which the transaction will

          revert) and pool swap during zap (for additional zapping and for refund).

          From 0 to 10,000 inclusively. Example: 1 for 0.01%.'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: X-Client-Id
        in: header
        description: Client Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: Request Id
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1GetOutRouteResponse'
        '400':
          description: Invalid Argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
components:
  schemas:
    ZapDetailsAction:
      title: one of the zap actions, specified by the type field
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ZapDetailsActionType'
        protocolFee:
          $ref: '#/components/schemas/ZapDetailsFeeAction'
        partnerFee:
          $ref: '#/components/schemas/ZapDetailsFeeAction'
        aggregatorSwap:
          $ref: '#/components/schemas/ZapDetailsSwapAction'
        poolSwap:
          $ref: '#/components/schemas/ZapDetailsSwapAction'
        addLiquidity:
          $ref: '#/components/schemas/ZapDetailsLiquidityAction'
        removeLiquidity:
          $ref: '#/components/schemas/ZapDetailsLiquidityAction'
        refund:
          $ref: '#/components/schemas/ZapDetailsRefundAction'
    ZapDetailsSwapAction:
      title: token swap, either with aggregator or with pool
      type: object
      properties:
        swaps:
          type: array
          items:
            $ref: '#/components/schemas/SwapActionSwap'
    v1PoolDetails:
      title: details of the pool
      type: object
      properties:
        category:
          type: string
        uniswapV3:
          $ref: '#/components/schemas/PoolDetailsUniswapV3'
        uniswapV2:
          $ref: '#/components/schemas/PoolDetailsUniswapV2'
        algebraV1:
          $ref: '#/components/schemas/PoolDetailsAlgebraV1'
    v1GetInRouteResponseData:
      type: object
      properties:
        poolDetails:
          $ref: '#/components/schemas/v1PoolDetails'
        positionDetails:
          $ref: '#/components/schemas/v1PositionDetails'
        zapDetails:
          $ref: '#/components/schemas/v1ZapDetails'
        route:
          title: the zap route to pass to build API to get call-data
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        routerAddress:
          title: the router address to check approval amount
          type: string
        gas:
          title: rough estimate of gas required for the transaction
          type: string
        gasUsd:
          title: USD value of estimated gas required
          type: string
      description: Encompasses returned data.
    v1PositionDetails:
      title: details of the new position state
      type: object
      properties:
        removedLiquidity:
          title: how much position liquidity to be removed
          pattern: \d+
          type: string
        removedAmountUsd:
          title: total USD value of the position to be removed
          type: string
        addedLiquidity:
          title: how much position liquidity to be added
          pattern: \d+
          type: string
        addedAmountUsd:
          title: total USD value of the position to be added
          type: string
    v1GetMigrateRouteResponse:
      type: object
      properties:
        code:
          title: grpc error code
          type: integer
          format: int32
        message:
          title: grpc error message
          type: string
        data:
          $ref: '#/components/schemas/v1GetMigrateRouteResponseData'
        requestId:
          title: request trace id
          type: string
      description: Returns the best route to zap-migrate from an existing position to the specified pool position.
    ZapDetailsActionType:
      title: type of the zap action
      type: string
      description: "- ACTION_TYPE_UNSPECIFIED: Unspecified action\n - ACTION_TYPE_PROTOCOL_FEE: protocol fee\n - ACTION_TYPE_PARTNER_FEE: partner fee\n - ACTION_TYPE_AGGREGATOR_SWAP: aggregator swap\n - ACTION_TYPE_POOL_SWAP: pool swap\n - ACTION_TYPE_ADD_LIQUIDITY: add liquidity\n - ACTION_TYPE_REMOVE_LIQUIDITY: remove liquidity\n - ACTION_TYPE_REFUND: refund"
      default: ACTION_TYPE_UNSPECIFIED
      enum:
      - ACTION_TYPE_UNSPECIFIED
      - ACTION_TYPE_PROTOCOL_FEE
      - ACTION_TYPE_PARTNER_FEE
      - ACTION_TYPE_AGGREGATOR_SWAP
      - ACTION_TYPE_POOL_SWAP
      - ACTION_TYPE_ADD_LIQUIDITY
      - ACTION_TYPE_REMOVE_LIQUIDITY
      - ACTION_TYPE_REFUND
    v1GetOutRouteResponseData:
      type: object
      properties:
        zapDetails:
          $ref: '#/components/schemas/v1ZapDetails'
        route:
          title: the zap route to pass to build API to get call-data
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        routerAddress:
          title: the router address to check approval amount
          type: string
        gas:
          title: rough estimate of gas required for the transaction
          type: string
        gasUsd:
          title: USD value of estimated gas required
          type: string
      description: Encompasses returned data.
    PoolDetailsUniswapV2:
      title: details of the uniswapV2 pool
      type: object
      properties:
        reserve0:
          title: reserve0 before zap
          type: string
        newReserve0:
          title: reserve0 after zap
          type: string
        reserve1:
          title: reserve1 before zap
          type: string
        newReserve1:
          title: reserve1 after zap
          type: string
    PoolDetailsAlgebraV1:
      title: details of the algebraV1 pool
      type: object
      properties:
        tick:
          title: pool tick before zap
          type: integer
          format: int32
        newTick:
          title: pool tick after zap
          type: integer
          format: int32
        sqrtP:
          title: pool sqrt price (times 2^96) before zap
          type: string
        newSqrtP:
          title: pool sqrt price (times 2^96) after zap
          type: string
    ZapDetailsRefundAction:
      title: refund left-over tokens to user
      type: object
      properties:
        tokens:
          title: refunded token amounts
          type: array
          items:
            $ref: '#/components/schemas/ZapDetailsTokenAmount'
    v1ZapDetails:
      title: details of the zap
      type: object
      properties:
        initialAmountUsd:
          title: USD value of the source zap token amount
          type: string
        actions:
          title: list of zap actions
          type: array
          items:
            $ref: '#/components/schemas/ZapDetailsAction'
        finalAmountUsd:
          title: USD value of the final amount including the added position and the left-over amount
          type: string
        priceImpact:
          title: price impact after zapping of final amount against initial amount
          type: number
          format: float
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v1GetInRouteResponse:
      type: object
      properties:
        code:
          title: grpc error code
          type: integer
          format: int32
        message:
          title: grpc error message
          type: string
        data:
          $ref: '#/components/schemas/v1GetInRouteResponseData'
        requestId:
          title: request trace id
          type: string
      description: Returns the best route to zap-in to the specified pool position.
    SwapActionSwap:
      title: a single swap
      type: object
      properties:
        tokenIn:
          $ref: '#/components/schemas/ZapDetailsTokenAmount'
        tokenOut:
          $ref: '#/components/schemas/ZapDetailsTokenAmount'
    ZapDetailsLiquidityAction:
      title: added or removed liquidity
      type: object
      properties:
        tokens:
          title: added or removed token amounts
          type: array
          items:
            $ref: '#/components/schemas/ZapDetailsTokenAmount'
        fees:
          title: collected fees
          type: array
          items:
            $ref: '#/components/schemas/ZapDetailsTokenAmount'
        token0:
          $ref: '#/components/schemas/ZapDetailsTokenAmount'
        token1:
          $ref: '#/components/schemas/ZapDetailsTokenAmount'
    ZapDetailsTokenAmount:
      title: token address and amount in wei and in usd
      type: object
      properties:
        address:
          title: token address
          pattern: ^0x[0-9A-Za-z]{40}$
          type: string
        amount:
          title: wei amount of the token
          type: string
        amountUsd:
          title: USD value of the token
          type: string
    PoolDetailsUniswapV3:
      title: details of the uniswapV3 pool
      type: object
      properties:
        tick:
          title: pool tick before zap
          type: integer
          format: int32
        newTick:
          title: pool tick after zap
          type: integer
          format: int32
        sqrtP:
          title: pool sqrt price (times 2^96) before zap
          type: string
        newSqrtP:
          title: pool sqrt price (times 2^96) after zap
          type: string
    v1GetMigrateRouteResponseData:
      type: object
      properties:
        poolDetails:
          $ref: '#/components/schemas/v1PoolDetails'
        positionDetails:
          $ref: '#/components/schemas/v1PositionDetails'
        zapDetails:
          $ref: '#/components/schemas/v1ZapDetails'
        route:
          title: the zap route to pass to build API to get call-data
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        routerAddress:
          title: the router address to check approval amount
          type: string
        gas:
          title: rough estimate of gas required for the transaction
          type: string
        gasUsd:
          title: USD value of estimated gas required
          type: string
      description: Encompasses returned data.
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties:
        type: object
    ZapDetailsFeeAction:
      title: fee collection
      type: object
      properties:
        pcm:
          title: fee per cent mille (0.001%) of the source zap amount
          type: integer
          format: int64
        tokens:
          title: token amounts
          type: array
          items:
            $ref: '#/components/schemas/ZapDetailsTokenAmount'
    v1GetOutRouteResponse:
      type: object
      properties:
        code:
          title: grpc error code
          type: integer
          format: int32
        message:
          title: grpc error message
          type: string
        data:
          $ref: '#/components/schemas/v1GetOutRouteResponseData'
        requestId:
          title: request trace id
          type: string
      description: Returns the best route to zap-out from an existing position to the specified pool position.