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"