openapi.yml

openapi: '3.0.2'
info:
  title: NLoop Server OpenAPI definition
  version: '2.1.1'
  description:
    Lightning Channel Manager. It will maintain the channel balance by performing
    submarine swap against Boltz server.
  contact:
    email: joemphilips@gmail.com
    name: Joe Miyamoto
    url: https://twitter.com/joemphilips
servers:
  - url: https://api.server.test/v1
paths:
  /v1/version:
    get:
      tags:
        - general
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string

  /v1/info:
    get:
      tags:
        - general
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInfoResponse'

  /v1/swaps/{id}:
    get:
      tags:
        - swap
      description:
        Get the list of ongoing swaps.
      parameters:
        - $ref: '#/components/schemas/swapId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSwapResponse'

  /v1/swaps/history:
    get:
      description:
        Get the full history of swaps. This might take long if you have a lots of entries in a database.
      tags:
        - swap
      parameters:
        - in: query
          name: since
          schema:
            type: string
            format: date
          example: "2021-01-30"
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSwapHistoryResponse"
  /v1/swaps/ongoing:
    get:
      description:
        Get the list of ongoing swaps.
      tags:
        - swap
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetOngoingSwapResponse"

  /v1/cost/summary:
    get:
      description: 
        Get the summary of the cost we paid for swaps.
      tags:
        - cost
      parameters:
        - in: query
          name: since
          schema:
            type: string
            format: date
          example: "2021-01-30"
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetCostSummaryResponse"

  /v1/loop/out:
    post:
      tags:
        - loop
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoopOutRequest'
      security:
        - Cookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoopOutResponse'
        '400':
          description: invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: error message
                    minItems: 1
                    items:
                      type: string

  /v1/loop/in:
    post:
      tags:
        - loop
      requestBody:
        content:
          application/json:
            schema:
              $ref:  "#/components/schemas/LoopInRequest"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoopInResponse'
        '400':
          description: invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: error message
                    minItems: 1
                    items:
                      type: string

  /v1/auto/suggest/{offchainAsset}:
    get:
      description:
        Get suggestion for the swaps.
      parameters:
        - in: path
          name: offchainAsset
          schema:
            $ref:  "#/components/schemas/cryptoCode"
          required: false
          description: off-chain asset which autoloop manager will take care. default is BTC.
      tags:
        - loop
        - autoloop
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestSwapsResponse'

  /v1/liquidity/params/{offchainAsset}:
    get:
      description:
        Get the parameters that the daemon's liquidity manager is currently configured with.
        This may be nil if nothing is configured.
      tags:
        - autoloop
      parameters:
        - in: path
          name: offchainAsset
          schema:
            $ref:  "#/components/schemas/cryptoCode"
          required: false
          description: off-chain asset which autoloop manager will take care. default is BTC.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiquidityParameters'

    post:
      description:
        Overwrites the current set of parameters for the daemon's liquidity manager.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLiquidityParametersRequest'
      responses:
        '200':
          description: OK
        '400':
          description: invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: error message
                    minItems: 1
                    items:
                      type: string

components:
  securitySchemes:
    Cookie:
      type: apiKey
      name: Cookie
      in: cookie
  schemas:
    cryptoCode:
      type: string
      enum:
        - BTC
        - LTC
    pairId:
      type: string
      example:
        "BTC/LTC"
    # ----- Primitive objects
    PubKey:
      type: string
      maxLength: 33
      minLength: 33
      example:
        03afbba930dc74d6412b71c31f72bfb8d4615121174dd4290cbbf83960961ba9ab
    P2PKH:
      type: string
      pattern: ^[1][a-km-zA-HJ-NP-Z1-9]{25,34}$
      example:
        1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
    BitcoinAddressNonMalleable:
      oneOf:
        - $ref: '#/components/schemas/P2WSH'
        - $ref: '#/components/schemas/P2WPKH'
    P2SH:
      type: string
      pattern: ^[3][a-km-zA-HJ-NP-Z1-9]{25,34}$
      example:
        3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy
    P2WPKH:
      type: string
      pattern: ^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25}$
      example:
        bc1qcw9l54jre2wc4uju222wz8su6am2fs3vufsc8c
    P2WSH:
      type: string
      pattern: ^(bc1|[13])[a-zA-HJ-NP-Z0-9]{39}$
      example:
        bc1q2y7lfmmm7xhv2dpf0n0mx6w26zspmvszm3hvkc4yn785xp8dvs5shejlc5
    ShortChannelId:
      oneOf:
        - type: string
          pattern: (\d{3})x(\d{3})x(\d{2})
          description:
            pointer to the funding outpoint.
            i.e. triplet of 1. block height, 2. tx index number in the block. 3. tx out index
            Of the funding tx of the channel.
          example: 140x10x1
        - type: integer
          format: uint64
          description: uint64 representation used in LND.
        - type: string
          pattern: (\d{3})x(\d{3})x(\d{2}):(\d+)
          description: both bolt-style triplet and lnd-compatible style concatenated.
    swapId:
      type: string

    # -----
    # ----- requests
    LoopOutRequest:
      type: object
      properties:
        channel_ids:
          type: array
          items:
            $ref: '#/components/schemas/ShortChannelId'
          description:
            ShortChannelId for the one you want to get inbound liquidity for.
            default is the one it has least.
          nullable: true
        pair_id:
          oneOf:
            - $ref: '#/components/schemas/pairId'
          description:
            currency pair to perform the swap.
            Default is BTC/BTC. In case of loopout, Base/Quote is OnChain/OffChain
            So say if you want to use LTC as an on-chain asset, you must specify LTC/BTC
          nullable: true
        address:
          oneOf:
            - $ref: '#/components/schemas/BitcoinAddressNonMalleable'
          nullable: true
          description:
            An external address that to which the counterparty will pay.
            i.e. final destination of our on-chain funds.
            default is a wallet of the lnd (in case of BTC), or blockchain daemon's wallet
            (e.g. in case of LTC, litecoind's wallet-controlled address.)
        amount:
          type: integer
          format: int64
          description:
            amount you wish to swap out (in satoshi).
        swap_tx_conf_requirement:
          type: integer
          description:
            The number of confirmation of the swaptx (htlc tx) before we make an off-chain offer.
            a.k.a. `htlc_confirmations` on the lightning loop.
            Default number depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
            Set this to 0 for zero-conf swap.
          nullable: true
        label:
          type: string
          description:
            Additional label for this request.
          nullable: true
        max_swap_routing_fee:
          type: integer
          format: int64
          description:
            Maximum off-chain fee in sats that may be paied for swap payment to the
            server. This limit is applied during path finding.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        max_prepay_routing_fee:
          type: integer
          format: int64
          description:
            Maximum off-chain fee in sat that may be paid for the prepay to the server.
            This limit is applied during path finding.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        max_swap_fee:
          type: integer
          format: int64
          description:
            Maximum we are willing to pay the server for the swap (by diff of on/off-chain payment).
            If the server asks for a higher fee, we do not perform the swap.
            For multi-asset swap, the unit of this value is off-chain currency.
            We use a rate information from external exchanges to calculate the value.
            Default value depends on the asset type, and a channel size.
            (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        max_prepay_amount:
          type: integer
          format: int64
          description:
            The server might request a pre-payment for the sake of DoS-prevention,
            this is a maximum amount (in sats) of the off-chain prepayment.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        max_miner_fee:
          type: integer
          format: int64
          description:
            Maximum on-chain fees that we are willing to spend. If we want to sweep the on-chain
            htlc and the fee estimate turns out higher than this value, we cancel the swap.
            If the fee estimate is lower, we publish the sweep tx.
            If the sweep tx is not confirmed, we are forced to ratchet up fees until it is swept.
            Possibly even exceeding max_miner_fee if we get close to the HTLC timeout.
            Because the initial publication revealed the preimage, we have no other choice.
            The server may already have pulled the off-chain HTLC. Only when the fee becomes higher than
            the swap amount, we can wait for fees to come down and hope -- if we are past the timeout -- that
            the server is not publishing the revocation.
            So think this value as a \"soft-limit\" for preventing to start the swap when the fee market
            is too expensive, rather than the hard-limit.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        sweep_conf_target:
          type: integer
          format: int32
          description:
            Confimation target (block num) for estimating the fee for the
            sweeping tx (a.k.a. sweep tx, claim tx.) from the HTLC tx (a.k.a. swaptx, lockuptx)
            Default depends on the asset type, but usually it is not that short.
            If you want to finish swap asap and get your on-chain funds quickly,
            You probably want to set a short time.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
      required:
        - amount
    LoopInRequest:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          description:
            amount you wish to swap in to the channel (in satoshi).
        last_hop:
          oneOf:
            - $ref: '#/components/schemas/PubKey'
          description:
            node_id (pubkey) to perform the swap against.
            If you specify both last_hop and channel_id, channel_id is be prioritized.
          nullable: true
        channel_id:
          oneOf:
            - $ref: '#/components/schemas/ShortChannelId'
          description:
            channel_id (ShortChannelId) to perform the swap for.
            If you specify both last_hop and channel_id, channel_id is be prioritized.
          nullable: true
        pair_id:
          oneOf:
            - $ref: '#/components/schemas/pairId'
          description:
            currency pair to perform the swap.
            Default is BTC/BTC. In case of loopin, Base/Quote is OffChain/OnChain
            So say if you want to use LTC as an on-chain asset, you must specify BTC/LTC
          nullable: true
        label:
          type: string
          description:
            Additional label for this request.
          nullable: true
        max_miner_fee:
          type: integer
          format: int64
          description:
            Maximum on-chain fees that we are willing to spend. If we want to
            publish the on-chain htlc and the fee estimate turns out higher than this value, we cancel the swap.
            Default value depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        max_swap_fee:
          type: integer
          format: int64
          description:
            Maximum we are willing to pay the server for the swap (by diff of on/off-chain payment).
            If the server asks for a higher fee, we do not perform the swap.
            For multi-asset swap, the unit of this value is off-chain currency.
            We use a rate information from external exchanges to calculate the value.
            Default number depends on the asset type, and a channel size.
            (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
        htlc_conf_target:
          type: integer
          format: int32
          description:
            Confimation target for estimating the fee for HTLC tx (a.k.a. swaptx, lockuptx)
            If the server is not willing to accept zero-conf swap, Making this value smaller might
            make a swap fast.
            Default number depends on the asset type, (see NLoop.Server/Options/CryptoCodeParams.fs)
          nullable: true
      required:
        - amount

    # -----

    # ----- responses
    GetInfoResponse:
      type: object
      properties:
        version:
          type: string
        supported_coins:
          type: object
          properties:
            on_chain:
              type: array
              items:
                $ref: '#/components/schemas/cryptoCode'
            off_chain:
              type: array
              items:
                $ref: '#/components/schemas/cryptoCode'
      required:
        - version
        - supported_coins

    GetSwapResponse:
      type: object

    ShortSwapSummary:
      type: object
      properties:
        "type":
          type: string
          enum:
            - SuccessfullyFinished
            - FinishedByError
            - FinishedByRefund
            - OnGoing
        error_msg:
          type: string
          nullable: true
        refund_txid:
          type: string
          nullable: true
        swap_txid:
          type: string
          nullable: true
        swap_address:
          type: string
          nullable: true
        cost:
          $ref: "#/components/schemas/Cost"
      required:
        - "type"

    GetSwapHistoryResponse:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/ShortSwapSummary"

    Cost:
      type: object
      properties:
        onchain_payment:
          type: integer
          format: int64
          description:
            An on-chain amount we gained/lost through swap.
            This might be positive value iff in the case of loop out.
        offchain_payment:
          type: integer
          format: int64
          description:
            An off-chain amount we gained/lost through swap.
            This might be positive value iff in the case of loop in.
        onchain_fee:
          type: integer
          format: int64
          description:
            An on-chain miner fee we lost through swap.
            This value is always negative.
            The absolute value tends to get higher in case of loop-in, since
            we must create two txs in case of refund. And its swap tx is usually larger than
            the tx we create in case of loop-out.
        offchain_fee:
          type: integer
          format: int64
          description:
            An off-chain routing fee we lost through swap.
            This value is always negative, and it is only for loop-out.
        offchain_prepayment:
          type: integer
          format: int64
          description:
            An off-chain prepayment value for the swap.
            This value is always negative, and it is only for loop-out.
        offchain_prepayment_fee:
          type: integer
          format: int64
          description:
            An off-chain prepayment routing fee for the swap.
            This value is always negative, and it is only for loop-out.

    GetOngoingSwapResponse:
      type: array
      description: list of swap
      items:
        type: object
    
    GetCostSummaryResponse:
      type: array
      description: list of possible swap server's and assets we have gained/lost so far.
      items:
        type: object
        properties:
          server_endpoint:
            type: string
            description: The endpoint of the server
          costs:
            type: array
            description: Summary of the income/outcome with the swap.
            items:
              type: object
              description:
                Units for each values are sats. negative value represents an amount we have lost.
                Positive means we have gained.
                You can just summerize everything to get the net income of the asset.
              properties:
                crypto_code:
                  oneOf:
                    - $ref: "#/components/schemas/cryptoCode"
                cost:
                  oneOf:
                    - $ref: "#/components/schemas/Cost"

    LoopOutResponse:
      type: object
      properties:
        id:
          description:
            Swap identifier to track status.
          nullable: false
          example: "tY8iDo"
        address:
          oneOf:
            - $ref:  "#/components/schemas/BitcoinAddressNonMalleable"
          description:
            An address to which counterparty has paid.
            Must be the same one with the one in the request if there is any.
            Otherwise, it is the address controlled by lnd or blockchain daemon (e.g. litecoind.)
          nullable: false
        claim_tx_id:
          description:
            An txid by which they have paid to us. It is populated only when its 0-conf.
          nullable: true
    LoopInResponse:
      type: object
      properties:
        id:
          description:
            Swap identifier to track status.
          nullable: false
          example: "tY8iDo"
        address:
          oneOf:
            - $ref:  "#/components/schemas/P2WSH"
          description:
            The address of the on-chain HTLC

    LiquidityRuleType:
      enum:
        - UNKNOWN
        - THRESHOLD

    LiquidityRule:
      type: object
      properties:
        incoming_threshold_percent:
          type: integer
          format: int16
          description:
            if the incoming liquidity (i.e. other party's share of the channel cap) has become
            less than this, we will dispatch the loop-out swap
        outgoing_threshold_percent:
          type: integer
          format: int16
          description:
            if the outgoing liquidity (i. our share in the channel cap) has become
            less than this, we will dispatch the loop-in swap
        pubkey:
          oneOf:
            - $ref: '#/components/schemas/PubKey'
          description:
            Peer id to apply the rule against.
            pubkey and channel_id fields are mutually exclusive.
          nullable: true
        channel_id:
          oneOf:
            - $ref: "#/components/schemas/ShortChannelId"
          description:
            channel id to apply the rule.
            pubkey and channel_id fields are mutually exclusive.
          nullable: true
        type:
          $ref:  "#/components/schemas/LiquidityRuleType"
          description:
            The type of the liquidity rule we apply.
            Currently, we only have Threshold

    LiquidityParameters:
      type: object
      properties:
        rules:
          type: array
          items:
            $ref: '#/components/schemas/LiquidityRule'
        fee_ppm:
          type: integer
          description:
            The parts per million of swap amount that is allowed to be allocated to swap fees.
            This valie is applied across swap categories and may not be set in conjunction with sweep fee rate,
            swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.
          nullable: true
        sweep_fee_rate_sat_per_kvbyte:
          type: integer
          description:
            The limit we place on our estimated sweep cost for a swap in sat/kilo-vByte. If the estimated fee for our
            sweep tx within the specified confirmation target is above this value, we will not suggest any swaps.
          nullable: true
        max_swap_fee_ppm:
          type: integer
          description:
            The maximum fee paid to the server for facilitating the swap, expressed as parts-per-million of the swap amount.
          nullable: true
        max_routing_fee_ppm:
          type: integer
          nullable: true
        max_prepay_routing_fee_ppm:
          type: integer
          nullable: true
        max_prepay_sat:
          type: integer
          format: int64
          nullable: true
        max_miner_fee_sat:
          type: integer
          format: int64
          nullable: true
        sweep_conf_target:
          type: integer
          description: The number of blocks from the on-chain HTLC7s confirmation height that it shuold be swept within.
        failure_backoff_sec:
          type: integer
          description:
            The amount of time we require to pass since a channel was part of a failed swap due to off chain payment
            failure until it will be considered for swap suggestions again, expressed in seconds.
        autoloop:
          type: boolean
          description:
            Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters,
        auto_max_in_flight:
          type: integer
          description: The maximum number of of automatically dispatched swaps that we allow to be in flight at any point in time.
        min_swap_amount_loopout:
          type: integer
          format: int64
          description:
            The minimum off-chain amount for loop out, expressed in satoshis, that the autoloop client will dispatch a swap for.
          nullable: true
        max_swap_amount_loopout:
          type: integer
          format: int64
          description: The maximum off-chain amount for loop out, expressed in satoshis.
          nullable: true
        min_swap_amount_loopin:
          type: integer
          format: int64
          description:
            The minimum off-chain amount for loop in, expressed in satoshis, that the autoloop client will dispatch a swap for.
          nullable: true
        max_swap_amount_loopin:
          type: integer
          format: int64
          description: The maximum off-chain amount for loop in, expressed in satoshis.
          nullable: true
        onchain_asset:
          $ref: "#/components/schemas/cryptoCode"
          description: on-chain asset for the swap. default is BTC.
          nullable: true
        
        htlc_conf_target:
          type: integer
          format: int32
          description: The conf target we use to estimate the fee for swaptx in loop-in.
          nullable: true
      required:
        - "rules"
        - "sweep_conf_target"
        - "failure_backoff_sec"
        - "autoloop"
        - "auto_max_in_flight"

    SetLiquidityParametersRequest:
      type: object
      properties:
        parameters:
          $ref: "#/components/schemas/LiquidityParameters"

    Disqualified:
      type: object
      properties:
        channel_id:
          $ref: '#/components/schemas/ShortChannelId'
          nullable: true
        pubkey:
          $ref: "#/components/schemas/PubKey"
          nullable: true
        reason:
          type: string

    SuggestSwapsResponse:
      type: object
      properties:
        loop_out:
          type: array
          items:
            $ref: "#/components/schemas/LoopOutRequest"
        loop_in:
          type: array
          items:
            $ref: "#/components/schemas/LoopInRequest"
        disqualified:
          type: array
          items:
            $ref:  "#/components/schemas/Disqualified"