openapi: 3.0.0
info:
  title: Blade Deposit Pool 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: Pool
  description: Pool information and liquidity data endpoints
paths:
  /rfq/v2/pool/{chainId}:
    get:
      tags:
      - Pool
      summary: Get pool information
      description: This endpoint provides comprehensive information about all the pools on the selected chain, including details about its assets, the contract address of its liquidity pool, and other relevant data. This information is crucial for making off-chain calculations and predicting quotes.
      operationId: getPoolInfo
      parameters:
      - name: chainId
        in: path
        description: ID of the blockchain network
        required: true
        schema:
          type: integer
        example: 137
      - name: pool_address
        in: query
        description: The address of the pool. If not provided, all pools on the selected chain will be returned.
        required: false
        schema:
          type: string
        example: '0x655eDCE464CC797526600a462A8154650EEe4B77'
      - name: time_in_seconds
        in: query
        description: 'The time duration for which a quote will be available. This value is used to calculate the fees; as you decrease the time, you will see lower fees. By default, the system sets a predefined value. Note: For on-chain data, this field is not considered.'
        required: false
        schema:
          type: integer
        example: 30
      - name: fieldset
        in: query
        description: Determines whether the API should make calls to the blockchain to return on-chain data. If the parameter is not provided, it will default to handling on-chain data.
        required: false
        schema:
          type: string
          enum:
          - offchain-data
        example: offchain-data
      responses:
        '200':
          description: Pool information retrieved successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OnChainPoolResponse'
                - $ref: '#/components/schemas/OffChainPoolResponse'
              examples:
                offchain-data-polygon:
                  summary: Off-chain data for Polygon chain (chain_id=137)
                  description: Example response when requesting off-chain data using fieldset=offchain-data parameter
                  value:
                    pool_type: offchain
                    pools:
                    - pool:
                        chain_id: 1
                        address: '0x655eDCE464CC797526600a462A8154650EEe4B77'
                        num_assets: 4
                        k: 0.06
                        time_in_seconds: 60
                        default_time_in_seconds: 60
                        swaps_enabled: true
                      assets:
                      - name: ETH
                        address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
                        price_in_usd: 2076.799
                        listing_weight: 79
                      - name: USDC
                        address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                        price_in_usd: 1
                        listing_weight: 188
                      - name: USDT
                        address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
                        price_in_usd: 1
                        listing_weight: 305
                      - name: DAI
                        address: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                        price_in_usd: 1
                        listing_weight: 250
                      pairs:
                      - assets:
                        - ETH
                        - USDC
                        fee_in_basis_points: 9
                      - assets:
                        - ETH
                        - USDT
                        fee_in_basis_points: 9
                      - assets:
                        - ETH
                        - DAI
                        fee_in_basis_points: 8
                      - assets:
                        - USDC
                        - USDT
                        fee_in_basis_points: 5
                      - assets:
                        - USDC
                        - DAI
                        fee_in_basis_points: 5
                      - assets:
                        - USDT
                        - DAI
                        fee_in_basis_points: 5
                onchain-data-mainnet:
                  summary: On-chain data for Ethereum Mainnet (chain_id=1)
                  description: Example response when requesting on-chain data with a specific pool address
                  value:
                    pool_type: onchain
                    pools:
                    - pool:
                        chain_id: 1
                        address: '0x655eDCE464CC797526600a462A8154650EEe4B77'
                        num_assets: 4
                        pool_tokens: 1.3792871898369242e24
                        value_in_usd: 1978682.496424432
                        swaps_enabled: true
                      assets:
                      - name: USDC
                        address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                        balance: '417751254142'
                        price_in_usd: 1
                        value_in_usd: 417751.254142
                        target_value_in_usd: 416727.89356391726
                      - name: USDT
                        address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
                        balance: '259059412007'
                        price_in_usd: 1
                        value_in_usd: 259059.412007
                        target_value_in_usd: 256868.3409508736
                      - name: DAI
                        address: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                        balance: '309714519494182375269440'
                        price_in_usd: 1
                        value_in_usd: 309714.5194941824
                        target_value_in_usd: 313379.3759600658
                      - name: ETH
                        address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
                        balance: '476877882758190421102'
                        price_in_usd: 2080.527
                        value_in_usd: 992157.3107812497
                        target_value_in_usd: 991706.8859495752
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ExternalServiceError'
components:
  schemas:
    OffChainAsset:
      type: object
      properties:
        name:
          type: string
          description: The name of the asset, this value should be used when making a quote
        address:
          type: string
          description: The contract address of the asset
        price_in_usd:
          type: number
          format: float
          description: Current price in dollars for the asset
        listing_weight:
          type: integer
          description: asset weight within the pool
      required:
      - name
      - address
      - price_in_usd
      - listing_weight
    OffChainPoolData:
      type: object
      properties:
        pool:
          $ref: '#/components/schemas/OffChainPool'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/OffChainAsset'
        pairs:
          type: array
          items:
            $ref: '#/components/schemas/Pair'
      required:
      - pool
      - assets
      - pairs
    OffChainPool:
      type: object
      properties:
        chain_id:
          type: integer
          description: ID of the chain
        address:
          type: string
          description: Blade contract address of the pool, is the address used when executing a transaction
        num_assets:
          type: integer
          description: The total of assets available in the chain
        k:
          type: number
          format: float
          description: K factor
        time_in_seconds:
          type: integer
          description: Number of seconds were used to calculate the fees of a swap, this number indicates the number of seconds that quotes are live
        default_time_in_seconds:
          type: integer
          description: Default number of seconds that quotes are live, is value used to calculate fees when don't send the query param time_in_seconds
        swaps_enabled:
          type: boolean
          description: Represents if the swaps are available for the chain
      required:
      - chain_id
      - address
      - num_assets
      - k
      - time_in_seconds
      - default_time_in_seconds
      - swaps_enabled
    OffChainPoolResponse:
      type: object
      properties:
        pool_type:
          type: string
          enum:
          - offchain
          description: Indicates this is off-chain pool data
        pools:
          type: array
          items:
            $ref: '#/components/schemas/OffChainPoolData'
      required:
      - pool_type
      - pools
    OnChainAsset:
      type: object
      properties:
        name:
          type: string
          description: The name of the asset, this value should be used when making a quote
        address:
          type: string
          description: The contract address of the asset
        balance:
          type: string
          description: The balance of the asset in the pool
        price_in_usd:
          type: number
          format: float
          description: Current price in dollars for the asset
        value_in_usd:
          type: number
          format: float
          description: Value of the pool in USD
        target_value_in_usd:
          type: number
          format: float
          description: USD target value for this asset in the pool
      required:
      - name
      - address
      - balance
      - price_in_usd
      - value_in_usd
      - target_value_in_usd
    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
    Pair:
      type: object
      properties:
        assets:
          type: array
          items:
            type: string
          description: 'Pair of assets available to make a swap - e.g: ["ETH", "MATIC"]'
        fee_in_basis_points:
          type: number
          format: float
          description: Fee for make a swap between the pair
      required:
      - assets
      - fee_in_basis_points
    OnChainPoolData:
      type: object
      properties:
        pool:
          $ref: '#/components/schemas/OnChainPool'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/OnChainAsset'
      required:
      - pool
      - assets
    OnChainPoolResponse:
      type: object
      properties:
        pool_type:
          type: string
          enum:
          - onchain
          description: Indicates this is on-chain pool data
        pools:
          type: array
          items:
            $ref: '#/components/schemas/OnChainPoolData'
      required:
      - pool_type
      - pools
    OnChainPool:
      type: object
      properties:
        chain_id:
          type: integer
          description: ID of the chain
        address:
          type: string
          description: Blade contract address of the pool, is the address used when executing a transaction
        num_assets:
          type: integer
          description: The total of assets available in the chain
        pool_tokens:
          type: number
          description: The total number of pool tokens
        value_in_usd:
          type: number
          format: float
          description: Value of the pool in USD
        swaps_enabled:
          type: boolean
          description: Represents if the swaps are available for the chain
      required:
      - chain_id
      - address
      - num_assets
      - pool_tokens
      - value_in_usd
      - swaps_enabled
  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'
    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'
  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.