openapi: 3.0.0
info:
  title: Blade Deposit API
  description: Documentation for interacting with the Blade API
  version: 2.0.0
  contact:
    email: aggregators@shipyardsoftware.org
    name: Blade API Support
servers:
- url: https://blade-api.sushi.com
  description: Blade API Production Server
security:
- ApiKeyAuth: []
tags:
- name: Deposit
  description: Liquidity pool deposit operations
paths:
  /rfq/v2/deposit:
    post:
      tags:
      - Deposit
      summary: Deposit assets into liquidity pool
      description: This endpoint allows users to deposit assets into a liquidity pool by submitting the required details, such as the pool contract address and the amount of assets to be deposited. This process is crucial for users who want to increase the liquidity of the pool and potentially earn rewards or fees. Use this endpoint to securely and efficiently add assets to the pool, contributing to the stability and performance of the ecosystem.
      operationId: depositAssets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
            examples:
              multiple-assets-deposit:
                summary: Deposit Multiple Assets
                description: Example of depositing multiple assets into a liquidity pool
                value:
                  deposit:
                    '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1': '2000000000000000000'
                  sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                  days_to_lock: 10
                  chain_id: 10
                  single_asset: false
                  pool_address: '0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40'
              katana-deposit:
                summary: Katana Pool Deposit
                description: Example of depositing into Katana pool (uses lock_time instead of days_to_lock)
                value:
                  deposit:
                    '0x0913DA6Da4b42f538B445599b46Bb4622342Cf52': '2000000000000000000'
                  sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                  lock_time: 720
                  chain_id: 747474
                  single_asset: false
                  pool_address: '0x989E8F547FbCa65f4FB0af41e50e4058e6c68166'
              single-asset-with-pool-tokens:
                summary: Deposit With Specific output pool token
                description: If you want to deposit and specify how many pool tokens receive.
                value:
                  sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                  days_to_lock: 10
                  chain_id: 10
                  single_asset: true
                  output_pool_tokens: 29438108002416884
                  single_token: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1'
                  pool_address: '0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40'
      responses:
        '200':
          description: Deposit processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositResponse'
              examples:
                multiple-assets-response:
                  summary: Multiple Assets Deposit Response
                  description: Response for depositing multiple assets into a liquidity pool
                  value:
                    sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                    n_days: 10
                    pool_tokens: '29438108002416884'
                    good_until: 1729657240
                    signature:
                      v: 28
                      r: '0x7c37b52021ea25ed38cbaf4def111eb9b5e6f0c1dc6c34ded53b9824c40febbf'
                      s: '0x66ce09126a23cadf277877e556f2d6c5bc3ad1e7080368a13bb0349208d30396'
                    clipper_exchange_address: '0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40'
                    deposit_amounts:
                    - '0'
                    - '0'
                    - '0'
                    - '0'
                    - '2000000000000000000'
                    - '0'
                    - '0'
                katana-response:
                  summary: Katana Pool Deposit Response
                  description: Response for depositing into Katana pool with extra_data and lock_time
                  value:
                    sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                    pool_tokens: '1911697202535426211354545867456512'
                    good_until: 1754952442
                    signature:
                      v: 27
                      r: '0xa4be6ab4120b2d55e383f9489e317c05911097cf38b92f8dffe393fed23c07ec'
                      s: '0x66d48deb50124d9e4d20c5f6ce570fd930f6bb8a1cd67bae68daef5fbf89112c'
                    clipper_exchange_address: '0x989E8F547FbCa65f4FB0af41e50e4058e6c68166'
                    extra_data: '0x000000000000000000000000000000000000000098b593221fc2d138f0a669c5000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000e475704f93603000000000000000000000000000000000000000000000000019257a485f5ec7000000'
                    deposit_amounts:
                    - '0'
                    - '2000000000000000000'
                    lock_time: 720
                single-asset-response:
                  summary: Deposit With Specific output pool token Response
                  description: Response for deposit with specific pool tokens specified
                  value:
                    sender: '0x54298A80a06068587E13b9dC1AC090259A98D5cD'
                    n_days: 10
                    pool_tokens: '29438108002416884'
                    good_until: 1729657750
                    signature:
                      v: 28
                      r: '0x8abcd885e7c151158e21288124b6cac461088ecd9ac07938752667277de2f581'
                      s: '0x4716077b4ee2eaf0668d0c219c507581efa61c287e1bdfe32597fb5d19609641'
                    clipper_exchange_address: '0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40'
                    amount: '1998512049104122112'
                    token: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/InvalidInputData'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ExternalServiceError'
components:
  responses:
    ExternalServiceError:
      description: External Service Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidInputData:
      description: Invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errorMessage: Invalid input data
            errorType: BadData
            errorCode: 422
            data:
            - type: missing
              loc:
              - chain_id
              msg: Field required
              input:
                input_amount: '18000'
                input_asset_symbol: ETH
                output_asset_symbol: WBTC
                time_in_seconds: 60
              url: https://errors.pydantic.dev/2.1/v/missing
    Unauthorized:
      description: Unauthorized - Missing or invalid API key. Ensure you include a valid `x-api-key` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errorMessage: 'Auth: Access is forbidden'
            errorType: Forbidden
    BadRequest:
      description: Bad Request - Invalid data in the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden Error - Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DepositResponse:
      type: object
      properties:
        sender:
          type: string
          description: The address of the user who initiated the deposit transaction.
        n_days:
          type: integer
          description: The number of days the assets will be locked in the pool, matching the `days_to_lock` from the request. Supported for all pools except Katana. For katana, returns `lock_time`.
        lock_time:
          type: integer
          description: The number of minutes the assets will be locked in the pool, matching the `lock_time` from the request. Only supported by the Katana pool. For other pools, returns `n_days`.
        good_until:
          type: integer
          description: The timestamp indicating how long the deposit details, including the signature, are valid.
        pool_tokens:
          type: string
          description: The total number of pool tokens that will be given to the user as a result of the deposit.
        signature:
          $ref: '#/components/schemas/EIP2098Signature'
        clipper_exchange_address:
          type: string
          description: The address of the Blade exchange contract where the deposit is being made.
        deposit_amounts:
          type: array
          items:
            type: string
          description: A list of the amounts to be deposited for each asset. If an asset was not provided in the request, the amount returned will be 0. For example, if 3 assets were provided in a 4-asset pool, the response will include an amount of 0 for the missing asset. For single asset deposit this field is not present
        amount:
          type: string
          description: (Single-asset deposits only) The total amount of the single asset that is being deposited into the pool.
        token:
          type: string
          description: (Single-asset deposits only) The address of the token that is being deposited into the pool.
        extra_data:
          type: string
          description: Encode LP token price and prices list into ABI-compatible bytes. Only supported by the Katana pool.
      required:
      - sender
      - good_until
      - pool_tokens
      - signature
      - clipper_exchange_address
    EIP2098Signature:
      type: object
      description: A EIP 2098 'short signature' representation for the signature from the Blade Exchange server
      properties:
        v:
          type: integer
          description: Recovery identifier
        r:
          type: string
          description: ECDSA signature r
        s:
          type: string
          description: ECDSA signature s
      required:
      - v
      - r
      - s
    ErrorResponse:
      type: object
      properties:
        errorMessage:
          type: string
          description: Description of the error
        errorType:
          type: string
          description: Type of the error
        errorCode:
          type: integer
          description: Error code (returned only when we have a blade code for the error)
        data:
          type: array
          items:
            type: object
          description: Additional error data (returned only when the input data is invalid)
      required:
      - errorMessage
      - errorType
    DepositRequest:
      type: object
      properties:
        sender:
          type: string
          description: The address of the user initiating the deposit transaction.
          example: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
        pool_address:
          type: string
          description: The address of the pool
          example: '0x989E8F547FbCa65f4FB0af41e50e4058e6c68166'
        days_to_lock:
          type: integer
          description: Number of days to lock the deposit in the liquidity pool. Required for all pools except Katana, which uses `lock_time` instead.
          example: 5
        lock_time:
          type: integer
          description: Number of minutes to lock the deposit in the liquidity pool. Only supported by the Katana pool. For other pools, use `days_to_lock`.
          example: 5
        deposit:
          type: object
          additionalProperties:
            type: string
          description: An object containing the asset address and the amount to deposit as a string. The amount should be in its machine-readable form. This parameter is required only if `single_asset` is false.
          example:
            '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599': '400000000'
            '0x6B175474E89094C44Da98b954EedeAC495271d0F': '2000000000000000000'
            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2': '1000000000000000000'
            '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': '2000000'
        chain_id:
          type: integer
          description: The unique identifier of the blockchain network where the deposit will be made.
          example: 1
        output_pool_tokens:
          type: integer
          description: The total number of pool tokens the user wants to receive. It is only valid for single-asset deposits.
          example: 10000
        single_asset:
          type: boolean
          description: A boolean that indicates whether only one asset is being deposited.
          default: false
          example: true
        single_token:
          type: string
          description: Required only when `single_asset` is true. This represents the address of the single asset being deposited.
          example: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599'
      required:
      - sender
      - pool_address
      - chain_id
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key required for all endpoints. In order to prevent abuse on the API we implement rate limits on the requests, to overcome these limits as an aggregator get in contact with the [support team](mailto:aggregators@shipyardsoftware.org) to get API credentials.