Lease API

The Lease API exposes Hydra App's LiquidityService — a service-backed surface for provisioning channel liquidity, releasing channels (withdraw or cooperative close), and extending existing asset leases: what the service offers, the leases it holds for your node, and the requests your node makes of it.

(2026-10-14) A request is submitted, then followed. A Submit* call answers once your node has settled its part of the fee — or failed to — with the request as it then stands; Get Liquidity Request and Subscribe Liquidity Requests follow it until it is final. Name each request with a client_request_id and a call that was cut off can be read back or safely sent again. See Submitting and following a request.

JSON-RPC namespace: liquidity

Endpoints

• Submit Channel Liquidity Request
• Submit Channel Release Request
• Submit Channel Lease Extension Request
• Get Liquidity Request
• Subscribe Liquidity Requests
• Request Channel Liquidity (deprecated)
• Estimate Request Channel Liquidity Fee
• Request Channel Release (deprecated)
• Estimate Request Channel Release Fee
• Request Channel Lease Extension (deprecated)
• Estimate Request Channel Lease Extension Fee

Read-only discovery

• Get Liquidity Service Info
• Get Leaseable Asset Info
• Get Leases
• Get Lease Expiries
• Get Fee Payments

Common types

ChannelLiquidityRequestOperation (one of)

Used by SubmitChannelLiquidityRequest, the deprecated RequestChannelLiquidity, and their estimator. Exactly one variant must be set.

asset_liquidity is map<string, AssetLiquidity> keyed by asset_id.

min_dispute_period_secs (2026-09-25) is the least dispute period the funded channel must carry — see dispute_period on Get Node Policy. An existing channel that falls short on any requested asset is not topped up, and a channel opened to serve the request is opened to carry it. Zero requires nothing; a period past the longest the hub's node accepts on a channel is refused at the quote (INVALID_ARGUMENT). A deposit names its channel, window included, so it carries no requirement.

On an EVM or Tron network your node raises min_dispute_period_secs of open, deposit_any and open_or_deposit to its own proposal (dispute_period.proposed on Get Node Policy) before sending the request, so the provider's liquidity only lands in a channel held to the terms your node opens on today. An older, shorter channel is passed over and a new one opened.

A channel a cooperative close drained is still topped up: on EVM and Tron it only withdrew everything, its asset channels read Closed with force_closed: false yet stay updatable, and a deposit reopens them in place. A channel with nothing left open — every asset channel sealed by a settlement, or closed for good — is never topped up, even for an asset it does not carry yet.

AssetLiquidity:

ChannelReleaseOperation (one of)

Used by SubmitChannelReleaseRequest, the deprecated RequestChannelRelease, and their estimator. Exactly one variant must be set.

withdraw.asset_amounts — per-asset, per-side split

Changed 2026-07-23 — breaking: this replaced the old asset_ids[] list.

asset_amounts is a map of asset_id → AssetWithdrawAmounts:

An absent side withdraws nothing; at least one side must be present. channel_id may be absent on fee estimates only (EstimateRequestChannelReleaseFee) — a swap quotes its exit before the channel exists — and every requested side must then be an exact amount.

⚠️ Absent means absent, not ""

(2026-09-13) channel_id is optional, and an empty string is not the sentinel. The service checks that you own the channel you named, and no empty string satisfies that check — so a quote built with "" comes back priced for somebody else's channel, and the operation silently falls to a rail you did not ask for.

Omit the field. optional is the same bytes on the wire as an unset string, so a client either side of this change reads the other correctly; what changed is that the generated types now carry the case, so it is harder to forget.

Migrating from asset_ids[]: a list entry "0xTOKEN" becomes a map entry "0xTOKEN": { client_amount: { exact: { amount: "..." } } } — you must now say how much and whose balance moves, not just which asset.

A channel the hub opened on demand stays open until keep_open_until

(2026-10-14) The hub sells a channel it opens on demand with a lifetime, and until the lifetime ends it neither takes anything out of one of its asset channels nor closes it. Your node shows that lifetime as AssetChannel.peer_keep_open_until, the hub's node as its own keep_open_until. Counted in blocks, it can only be estimated in time: your node reports it a margin before its last block is expected, so you never count on more than you bought, and the hub holds itself to a margin after, so it never closes early — the hub's time is the later. A withdraw or cooperative_close of such an asset channel before the hub's time is refused with FAILED_PRECONDITION — by the estimate and by the request alike, before any fee is paid — naming the asset, the channel and the time. Close the channel from your own node instead, whenever you choose, or wait until the time the refusal names has passed.

(2026-10-14) The lifetime is a lease. Once the payment the channel was opened for has settled in it, the asset channel carries a lease until the hub's keep_open_until, which its opening fee paid for: AssetChannel.lease_expiry shows it, on a boundary of the provider's lease clock, and moves later with the hub's time. The lease rents what the hub lent into the asset channel — its side of it once that payment had settled, the capital that gives you inbound liquidity. Keep the channel past the lifetime by extending the lease, or with a deposit that carries a lease_duration, as with any lease: the extension rents that capital for the time it adds past lease_expiry, never for time the lifetime already covers.

Fee payment (one of)

All RPCs that take a fee require exactly one fee_payment variant.

(2026-10-14) Which variants a provider accepts, and in which assets, is published in GetLiquidityServiceInfo's fee_payment_assets, with what each one charges. A fee in an asset or on a rail missing there is refused with FAILED_PRECONDITION before it is priced.

OnchainFeePayment (one of):

Fee methods are not interchangeable across the three operations:

Operation	Accepts
SubmitChannelLiquidityRequest	onchain · offchain · dual_fund · sponsored_deposit
SubmitChannelReleaseRequest	onchain · offchain · sponsored_withdrawal
SubmitChannelLeaseExtensionRequest	onchain · offchain

The deprecated Request* RPC of each operation, and its estimate, accept the same.

SponsoredDepositFeePayment — a deposit for a wallet with no gas

Added 2026-09-11.

The service funds the channel from this wallet's tokens, on its own transaction, and takes its fee out of the deposit. Hydra App signs the token permit that authorises the pull internally — you do not build or sign one yourself.

This exists for the wallet that holds a token and nothing else: no native asset, so no way to pay for a funding transaction of its own. Every other fee method assumes you can broadcast.

The fee is the quote the request references, or the service's price at execution when it references none — see Quotes. Because the fee comes out of the deposit, the channel ends up holding less than client_amount; estimate first so the user sees which figure is which.

The same rail inside a simple swap is DEPOSIT_RAIL_LIQUIDITY_SERVICE, and its post-swap counterpart is EXIT_RAIL_LIQUIDITY_SERVICE.

SponsoredWithdrawalFeePayment — an exit for a wallet with no gas

Added 2026-09-11. Release requests only (SubmitChannelReleaseRequest, the deprecated RequestChannelRelease).

The service broadcasts this wallet's withdrawal on its own transaction and takes its fee out of what is released — credited to the service in the state co-signed alongside it. Hydra App arms the funding allowance that authorises the credit internally; you do not call SetFundingAllowance yourself.

The gap this closes

Release used to offer two ways to pay, and a wallet with a channel balance and no gas could use neither:

• On-chain needs a funded wallet — which is exactly what is missing.
• Off-chain needs a channel balance to pay the invoice from — but withdraw all is about to take that balance away.

So the channel was stranded: funds in it, no way to get them out. This is the only fee method that works from that state, and it is why it exists.

What your node actually does: arm the allowance authorising the credit, then confirm. It never pays a fee of its own, so it takes the funding-allowance confirmation path a dual-funded open takes rather than the settlement path. A request you never confirm takes its allowance back rather than leaving standing consent for the service to draw on.

The fee is the quote the request references, or the service's price at execution when it references none — the same rule as every other method; see Quotes.

Because the fee comes out of the released amount, what lands in your wallet is less than the balance you withdrew. Estimate first so the user sees both figures.

The mechanism underneath is the generic UpdateChannel BalanceCredit — a withdrawal that hands part of itself to the peer. The swap-flow equivalent is EXIT_RAIL_LIQUIDITY_SERVICE; the entry-side counterpart is SponsoredDepositFeePayment.

Quotes: pinning an estimated price

Added 2026-09-11.

Every Estimate*Fee call returns a quote alongside the fee:

Pass quote_id back on the matching request and the service bills at that quote's price for as long as the quote is valid. Omit it and the service prices the request when it executes — which is a different number if the market moved in between.

A quote_id that has expired, or no longer fits the request, causes the request to be refused rather than silently re-priced. That is the point: the user agreed to a figure, and a request that can no longer honour it should come back for a fresh estimate, not quietly cost more.

Estimate*Fee  ──▶  { fee, quote_id, valid_until }
                        │
      show `fee` to the user, they accept
                        │
                        ▼
Submit*       ──▶  same request + quote_id   ──▶  billed at `fee`
                                              └─▶  refused if expired / changed

GetLiquidityServiceInfo.quote_validity_secs is how long every quote the service issues stays valid, so you can size the confirmation window before you ask for one.

A quote does not reserve liquidity. It fixes the price, not the capacity — a lease that no longer fits the provider's available liquidity is refused even inside its validity window.

Submitting and following a request

(2026-10-14) A request to the liquidity service runs in two phases, and the API splits along them.

1. Submit. SubmitChannelLiquidityRequest, SubmitChannelReleaseRequest or SubmitChannelLeaseExtensionRequest has the service commit to the request, settles your node's part of the fee, and answers with the request as it then stands: fee_settled, or fee_settlement_failed with why. That normally takes seconds — on the on-chain rail, settled means your node broadcast the fee transfer, not that it confirmed.
2. Follow. The service carries the request out once it holds the fee: on the on-chain rail once the transfer has the confirmations its network requires, which can take minutes on Ethereum; on every other rail at once. Read the request with GetLiquidityRequest, or watch it on SubscribeLiquidityRequests, until it is final: completed, failed, unresolved or expired.

An error from a Submit* call means the service made no request — the request was invalid, its quote expired or no longer fits, the provider refused it. There is nothing to follow: fix the request and submit it again.

  Submit*  ── error ──▶  no request was made: fix it and submit again
     │
     ▼
  awaiting_fee              the service committed; your node pays its part of the fee
     │
     ├──▶ fee_settled              ┐
     └──▶ fee_settlement_failed    ┘  Submit* answers with one of these
              │
              │  the service carries the request out once it holds the fee:
              │    on-chain rail     — once the transfer has its confirmations
              │    every other rail  — at once
              ▼
  completed · failed · unresolved     final
  expired                             final: fee_deadline passed before the service
                                      received the fee, and nothing was billed

Every request your node makes is recorded, and GetLiquidityRequest and SubscribeLiquidityRequests show it whichever way it was made: through a Submit* RPC, through one of the deprecated Request* RPCs, or by your node's own simple swaps when they provision liquidity.

fee_settled is not done. On the on-chain rail the Submit* call answers as soon as the fee transfer is broadcast, and the service acts only once that transfer has the confirmations its network requires. Wait for completed before you rely on the channel, and read what the service did from its result.

client_request_id — naming a request

client_request_id is your own name for a request: a string of 1 to 64 characters, unique per node and network. It is optional, the Submit* RPCs take it, and it survives restarts of your node.

• A request refused before the service committed to it — an error from Submit* — leaves the id free, so the corrected request can go out under the same id.
• Read a request back by its id with GetLiquidityRequest.
• An id outside 1 to 64 characters is refused with INVALID_ARGUMENT: client_request_id must be 1 to 64 characters, got N.
• The Estimate*Fee RPCs ignore it. The deprecated Request* RPCs refuse a request that carries it, with INVALID_ARGUMENT.

Give every request an id, and recover by it. A Submit* call that was cut off — DEADLINE_EXCEEDED, a dropped connection — may already have made the request: the submission runs on in your node whether or not its caller is still there. Submit again under the same id. That answers with the request the first call made, waiting for the first call if it is still running, and makes the request only if none was made. GetLiquidityRequest by the id reads it without submitting, but a NOT_FOUND right after a cut-off call does not prove that nothing was made: the first call may not have reached the service yet. Without an id, nothing names the request but the payment_uuid in the answer you lost.

Resend the request exactly as you first sent it — the same quote_id too. A retry that re-estimates first carries a new quote_id, which makes it a different request, and the id refuses it with client_request_id_taken.

LiquidityRequest

A request your node submitted to the liquidity service, and where it stands: what every Submit* call, GetLiquidityRequest and SubscribeLiquidityRequests return.

Request states

Exactly one state is set. completed, failed, unresolved and expired are final.

completed.result is one of, in the shape of the request's operation:

LiquidityFeeRefund

What the service gave back of a fee, and how it reached your node. A refund goes back the way the fee came: a fee paid on chain by a transaction to the payment's refund address, a fee paid off chain by a payment back over your node's channel. Fees on DUAL_FUND, SPONSORED_DEPOSIT and SPONSORED_WITHDRAWAL never leave a wallet and are never refunded.

LiquidityFeeTransfer

How a fee, or its refund, moved between your node and the service. Exactly one variant is set:

A final request changes only to take what it lacks: a completion's missing result, or the refund given after a failure.

completed without a result, failed or unresolved without a reason

These come from a reconnect. When your node reconnects to the liquidity service, it reads the service's fee-payment history for the requests still in progress and moves each to where the service has it. A request that completed while your node was not following the service takes the result its fee payment recorded (FeePayment.results), and is completed without one only when the service recorded none. A request that failed, or stopped at an operation whose outcome is unknown, meanwhile has no reason: the service's words never reached your node. Read the channel (watchOnlyNode.GetChannel) for what changed.

fee_settlement_failed is not final. The fee may still reach the service, and the request is then carried out as usual. Follow it to a final state before you submit the same request again — submitted twice, it can be carried out twice.

unresolved means unknown, not failed. Its operation may still land on chain, and the request will never say whether it did. Read the channel before you submit the same operation again: a second deposit or withdrawal on top of one that landed is a second operation.

Submit Channel Liquidity Request

(2026-10-14) Ask the liquidity service to provision channel liquidity on your node's behalf. Answers once your node has settled its part of the fee, or failed to; the service then carries the request out on its own, and you follow it.

Method: SubmitChannelLiquidityRequest

Parameters: the RequestChannelLiquidityRequest that Request Channel Liquidity documents — every field, rule and refusal there applies here, What this RPC cannot provision included — plus:

Response: SubmitLiquidityRequestResponse

An error means the service made no request: every refusal Request Channel Liquidity documents, a quote_id that expired or no longer fits, the provider's refusal. There is nothing to follow. Fix the request and submit it again — under the same client_request_id if you like, since a refused request leaves it free.

What fee settled means on each rail

Deadline

A Submit* call runs under the 30 s request deadline — it is not exempt, as the deprecated Request* RPCs are — and normally answers in seconds. The submission runs on a task of its own in your node, so a caller that disconnects or is cut off does not stop it. A call cut off with DEADLINE_EXCEEDED (JSON-RPC -32002) may therefore have made the request: submit again under the same client_request_id, or read the request back by it with GetLiquidityRequest — see client_request_id. Without an id, look for the request on SubscribeLiquidityRequests or in GetFeePayments before you submit it again.

Example Request (open channel, offchain fee):

// `request` is the RequestChannelLiquidityRequest of the Request Channel Liquidity example.
request.setClientRequestId('lease-btc-0001')   // your name for it: 1 to 64 characters

// An error here means the service made no request.
const submitted = (await client.submitChannelLiquidityRequest(request, {})).getRequest()!
if (submitted.hasFeeSettlementFailed()) {
  // Not final: the fee may still reach the service. Follow the request.
  console.warn('Fee not settled:', submitted.getFeeSettlementFailed()!.getReason())
}
console.log('Request:', submitted.getPaymentUuid(), 'fee:', submitted.getFee()?.getValue())

To wait for the request to finish, open Subscribe Liquidity Requests before you submit; Common Workflows puts the whole flow together.

Example Response:

{
  "request": {
    "paymentUuid": "5b0d3c1e-8f7a-4c52-9e1b-2a6f0d4c7e91",
    "clientRequestId": "lease-btc-0001",
    "network": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
    "operation": {
      "provision": {
        "operation": {
          "open": {
            "assetLiquidity": {
              "0x0000000000000000000000000000000000000000000000000000000000000000": {
                "serverAmount": { "value": "0.1" },
                "clientAmount": { "value": "0" }
              }
            }
          }
        },
        "leaseDurationSeconds": "2592000"
      }
    },
    "rail": "FEE_PAYMENT_RAIL_OFFCHAIN",
    "paymentNetwork": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
    "paymentAssetId": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "fee": { "value": "0.0001" },
    "feeDeadline": "2026-10-04T10:20:00Z",
    "feeSettlement": { "offchain": { "paymentId": "9c1f0e7d..." } },
    "createdAt": "2026-10-04T10:05:00Z",
    "updatedAt": "2026-10-04T10:05:02Z",
    "feeSettled": {}
  }
}

Over JSON-RPC — submit under a clientRequestId, then read the request back by it. Keys are camelCase, uint64 values are strings, and each oneof is the key of its set arm, per the wire encoding:

curl -s -X POST http://127.0.0.1:5003 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "liquidity_submitChannelLiquidityRequest",
    "params": [{
      "network": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
      "operation": {
        "open": {
          "assetLiquidity": {
            "0x0000000000000000000000000000000000000000000000000000000000000000": {
              "serverAmount": { "value": "0.1" },
              "clientAmount": { "value": "0" }
            }
          }
        }
      },
      "leaseDurationSeconds": "2592000",
      "paymentNetwork": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
      "paymentAssetId": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "offchainFeePayment": {},
      "clientRequestId": "lease-btc-0001"
    }]
  }'
# → {"jsonrpc":"2.0","id":1,"result":{"request":{"paymentUuid":"5b0d3c1e-...","clientRequestId":"lease-btc-0001",...,"feeSettled":{}}}}

curl -s -X POST http://127.0.0.1:5003 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "liquidity_getLiquidityRequest",
    "params": [{
      "network": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
      "clientRequestId": "lease-btc-0001"
    }]
  }'
# → {"jsonrpc":"2.0","id":2,"result":{"request":{...,"completed":{"channelLiquidity":{"channelId":"...","txid":"..."}}}}}

A call cut off by the deadline answers {"code":-32002,…} in an ordinary HTTP 200 response. Send the first call again unchanged: under the same clientRequestId it answers with the request already made.

Submit Channel Release Request

(2026-10-14) Ask the liquidity service to withdraw from a channel or cooperatively close it on your node's behalf. Answers as Submit Channel Liquidity Request does: the same response, the same client_request_id rules, the same deadline, and an error the same way means no request was made.

Method: SubmitChannelReleaseRequest

Parameters: the RequestChannelReleaseRequest that Request Channel Release documents, plus client_request_id (string, optional).

Response: SubmitLiquidityRequestResponse — request, a LiquidityRequest. Completed, its result is channel_release { channel_id, txid }. On sponsored_withdrawal_fee_payment, fee_settled means your node confirmed the funding allowance, and the fee comes out of what is released.

A release submitted and followed to its end is in Common Workflows.

Submit Channel Lease Extension Request

(2026-10-14) Extend the lease of one asset on a channel. Answers as Submit Channel Liquidity Request does.

Method: SubmitChannelLeaseExtensionRequest

Parameters: the RequestChannelLeaseExtensionRequest that Request Channel Lease Extension documents — read what an extension rents there — plus client_request_id (string, optional).

Response: SubmitLiquidityRequestResponse — request, a LiquidityRequest. Completed, its result is channel_lease_extension { channel_id, asset_id, lease_expiry }: when the extended lease ends.

Get Liquidity Request

(2026-10-14) One request your node submitted, as it stands now, by the service's id or by your client_request_id. Read-only and local: your node answers from its own record, with no round trip to the liquidity service.

Method: GetLiquidityRequest

Parameters:

Response:

NOT_FOUND (JSON-RPC -32004, no such liquidity request) when your node holds no such request on that network. Right after a Submit* call was cut off, that can mean the submission has not reached the service yet — see client_request_id.

Example Request:

import { GetLiquidityRequestRequest } from './proto/liquidity_pb'

const get = new GetLiquidityRequestRequest()
get.setNetwork({ protocol: 1, id: '0a03cf40' })
get.setClientRequestId('lease-btc-0001')   // or setPaymentUuid(...)

const request = (await client.getLiquidityRequest(get, {})).getRequest()!
if (request.hasCompleted()) {
  const result = request.getCompleted()!.getChannelLiquidity()   // absent if the report was missed
  console.log('Channel:', result?.getChannelId(), 'TX:', result?.getTxid())
}

Example Response:

{
  "request": {
    "paymentUuid": "5b0d3c1e-8f7a-4c52-9e1b-2a6f0d4c7e91",
    "clientRequestId": "lease-btc-0001",
    "network": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
    "operation": {
      "provision": {
        "operation": {
          "open": {
            "assetLiquidity": {
              "0x0000000000000000000000000000000000000000000000000000000000000000": {
                "serverAmount": { "value": "0.1" },
                "clientAmount": { "value": "0" }
              }
            }
          }
        },
        "leaseDurationSeconds": "2592000"
      }
    },
    "rail": "FEE_PAYMENT_RAIL_OFFCHAIN",
    "paymentNetwork": { "protocol": "PROTOCOL_BITCOIN", "id": "0a03cf40" },
    "paymentAssetId": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "fee": { "value": "0.0001" },
    "feeDeadline": "2026-10-04T10:20:00Z",
    "feeSettlement": { "offchain": { "paymentId": "9c1f0e7d..." } },
    "createdAt": "2026-10-04T10:05:00Z",
    "updatedAt": "2026-10-04T10:05:41Z",
    "completed": {
      "channelLiquidity": { "channelId": "ch_def456", "txid": "abc123..." }
    }
  }
}

Subscribe Liquidity Requests

(2026-10-14) The requests your node submits on a network. Server-streaming. The stream opens with every request still in progress — not final — as it stands now, then sends each request again whenever it changes, in the order the changes happened. Each item is the whole LiquidityRequest, not a delta.

Method: SubscribeLiquidityRequests — over JSON-RPC, the WebSocket subscription liquidity_subscribeLiquidityRequests (unsubscribe: liquidity_unsubscribeLiquidityRequests), whose items are LiquidityRequest.

Parameters:

Stream item: LiquidityRequest

Waiting for one request

The race-free way to wait for a request you submit:

1. Open the subscription first, and wait until it is in place: the stream's response headers over gRPC, the subscription id over JSON-RPC.
2. Submit the request.
3. Wait on the stream for the submitted payment_uuid to reach a final state. Keep the events that arrive before the Submit* call answers: the request's awaiting_fee and fee_settled usually do.

When the Submit* answer is already final — it answered an earlier submission under the same client_request_id — there is nothing to wait for.

Subscribed after submitting? Read the request once more. The opening snapshot holds only the requests still in progress, so a request that became final before your subscription was in place is not in it, and no later change brings it. Call GetLiquidityRequest once after the subscription is in place: that read and the stream together miss nothing. The same holds when the stream drops — reopen it, then read each request you are still waiting for once.

Example (helpers the Common Workflows use):

import {
  LiquidityRequest,
  SubscribeLiquidityRequestsRequest,
} from './proto/liquidity_pb'

/** completed, failed, unresolved and expired are final. */
function isFinal(r: LiquidityRequest): boolean {
  return r.hasCompleted() || r.hasFailed() || r.hasUnresolved() || r.hasExpired()
}

/**
 * Opens SubscribeLiquidityRequests and resolves once the node has it in place
 * (the response headers). It keeps the latest state of every request it sees,
 * so the events that arrive before a Submit call answers are not lost.
 */
async function openRequests(
  client: LiquidityServiceClient,
  network: { protocol: number; id: string },
) {
  const subscribe = new SubscribeLiquidityRequestsRequest()
  subscribe.setNetwork(network)
  const stream = client.subscribeLiquidityRequests(subscribe, {})

  const latest = new Map<string, LiquidityRequest>()   // payment_uuid → latest state
  let failure: unknown
  let wake: () => void = () => {}
  stream.on('data', (r: LiquidityRequest) => { latest.set(r.getPaymentUuid(), r); wake() })
  stream.on('error', (e: unknown) => { failure = e; wake() })
  stream.on('end', () => { if (!failure) failure = new Error('stream ended'); wake() })
  await new Promise<void>(resolve => {
    wake = () => resolve()
    stream.on('metadata', () => resolve())
  })
  if (failure) throw failure

  return {
    /** Resolves with the submitted request once it is final. */
    async waitFinal(submitted: LiquidityRequest): Promise<LiquidityRequest> {
      if (isFinal(submitted)) return submitted       // answered an earlier submission
      for (;;) {
        const r = latest.get(submitted.getPaymentUuid())
        if (r && isFinal(r)) return r
        if (failure) throw failure                   // reopen, then GetLiquidityRequest once
        await new Promise<void>(resolve => { wake = () => resolve() })
      }
    },
    close: () => stream.cancel(),
  }
}

Keep one stream per network open for the life of your client rather than one per request, as with every other stream: the helpers above open one per call only to stay self-contained.

Request Channel Liquidity

Ask the liquidity service to provision channel liquidity on the client's behalf. Hydra App completes fee settlement and the required local confirmations before returning.

Method: RequestChannelLiquidity

Parameters:

Response:

What this RPC cannot provision

Two rules, and together they close one case off entirely.

A round the client funds alone is served only by the rails the service broadcasts — DualFundFeePayment and SponsoredDepositFeePayment. On OnchainFeePayment and OffchainFeePayment the service funds its own side and broadcasts nothing of the client's, so a request whose every server_amount is zero is refused:

A round funded by the client alone is served by the DualFund and SponsoredDeposit rails only

The native asset cannot be deposited on the client's behalf at all. A native contribution can only ride the transaction's own value, and on both broadcasting rails that transaction is the service's — so a leg asking the client to fund native is refused there too:

the native asset … cannot be deposited on the client's behalf: a native deposit is
settled from the broadcaster's own transaction value, and the hub broadcasts a
sponsored round

Example Request (open channel, offchain fee):

import { LiquidityServiceClient } from './proto/LiquidityServiceClientPb'
import {
  RequestChannelLiquidityRequest,
  ChannelLiquidityRequestOperation,
  AssetLiquidity,
  OffchainFeePayment
} from './proto/liquidity_pb'

const client = new LiquidityServiceClient('http://localhost:5003')

const request = new RequestChannelLiquidityRequest()
request.setNetwork({ protocol: 1, id: '0a03cf40' }) // Bitcoin Signet

// Open new channel with 0.1 BTC on the server side
const open = new ChannelLiquidityRequestOperation.Open()
const liq = new AssetLiquidity()
liq.setServerAmount({ value: '0.1' })
liq.setClientAmount({ value: '0' })
open.getAssetLiquidityMap().set('0x0000000000000000000000000000000000000000000000000000000000000000', liq)

const op = new ChannelLiquidityRequestOperation()
op.setOpen(open)
request.setOperation(op)

request.setLeaseDurationSeconds(2592000) // 30 days
request.setPaymentNetwork({ protocol: 1, id: '0a03cf40' })
request.setPaymentAssetId('0x0000000000000000000000000000000000000000000000000000000000000000')
request.setOffchainFeePayment(new OffchainFeePayment())

const response = await client.requestChannelLiquidity(request, {})
console.log('Channel:', response.getChannelId(), 'TX:', response.getTxid())

Example Response:

{
  "txid": "abc123...",
  "channel_id": "ch_def456"
}

Estimate Request Channel Liquidity Fee

Estimate the service fee for a channel liquidity request before executing it. Takes the same RequestChannelLiquidityRequest and returns just the fee.

Topping up a leased channel renews what is already in it. A lease covers the provider's whole side of an asset channel, so a deposit into a channel the provider already leases also leases the capital already there for the new window, for every hour past where its current lease ends. The fee includes that rent, which is why the same window can cost more on one channel than on another. Ask for an open to lease only the new amount, in a channel of its own.

Method: EstimateRequestChannelLiquidityFee

Parameters: Same as Request Channel Liquidity.

Response:

Example Request:

// Build the same RequestChannelLiquidityRequest as you would for the actual call
const response = await client.estimateRequestChannelLiquidityFee(request, {})
console.log('Estimated fee:', response.getFee()?.getValue())

Example Response:

{
  "fee": { "value": "0.0001" },
  "quoteId": "q_8f3c1a...",
  "validUntil": "2026-09-10T03:52:25+00:00"
}

Request Channel Release

Ask the liquidity service to withdraw assets from a channel or cooperatively close it. The service charges a fee and Hydra App settles it before observing the release update.

Method: RequestChannelRelease

Parameters:

Response:

Example Request (cooperative close, offchain fee):

import {
  RequestChannelReleaseRequest,
  ChannelReleaseOperation,
  OffchainFeePayment
} from './proto/liquidity_pb'

const request = new RequestChannelReleaseRequest()
request.setNetwork({ protocol: 1, id: '0a03cf40' })

const close = new ChannelReleaseOperation.CooperativeClose()
close.setChannelId('ch_def456')
const op = new ChannelReleaseOperation()
op.setCooperativeClose(close)
request.setOperation(op)

request.setPaymentNetwork({ protocol: 1, id: '0a03cf40' })
request.setPaymentAssetId('0x0000000000000000000000000000000000000000000000000000000000000000')
request.setOffchainFeePayment(new OffchainFeePayment())

const response = await client.requestChannelRelease(request, {})
console.log('Release TX:', response.getTxid())

Example Response:

{ "txid": "rel_abc789..." }

Estimate Request Channel Release Fee

Estimate the service fee for a channel release before executing it.

Method: EstimateRequestChannelReleaseFee

Parameters: Same as Request Channel Release.

Response:

Example:

const response = await client.estimateRequestChannelReleaseFee(request, {})
console.log('Estimated fee:', response.getFee()?.getValue())

Example Response:

{ "fee": "0.00005" }

Request Channel Lease Extension

Extend the duration of an existing lease on a specific channel asset — including one the hub opened on demand, whose lifetime is its lease. lease_extension_seconds is an extension delta, not a replacement absolute expiry. It is added to the expiry of the lease you paid for — AssetChannel.lease_expiry — and sold in whole slots of the provider's lease clock (lease_slot_secs in Get Liquidity Service Info, one hour): extending by an hour moves lease_expiry by exactly an hour, and half an hour is sold, priced and delivered as a whole one. A lease that has already ended is extended from the next slot boundary. The estimate returns the rounded extension and the expiry it delivers.

Check both expiries before paying to extend. AssetChannel.lease_expiry is the lease you paid for. AssetChannel.liquidity_expiry is until when the provider's liquidity actually stays in the channel: the later of that lease and what the channel's usage, or how little of the provider's capital it holds, buys it. Every payment through the channel buys it time, in proportion to the payment's size against the provider's capital in the channel; that time adds up, but never reaches more than the provider's usage window (ten days on mainnet) past the latest payment. So an actively-traded channel's liquidity_expiry keeps running ahead of its lease, while one that no payment has crossed for that window keeps the provider's liquidity only until its lease ends — then the provider withdraws it, leaving the channel open with no inbound liquidity from the provider until you lease again. Provider liquidity in a channel that carries no lease follows the same rule. Both ride along on every watchOnlyNode.GetChannels / GetChannel read, and liquidity.GetLeaseExpiries returns them for all channels at once. Extend when liquidity_expiry is actually running down, or when you need the time guaranteed: only the lease is.

An extension rents exactly the time it adds. It counts from lease_expiry, or from the next slot boundary once the lease has ended, and rents that time — the estimate's lease_extension.rented_seconds. Time usage holds the liquidity in place past the lease is not paid time and is not counted: a lease paid to 15:00 on a channel whose liquidity_expiry is 18:00 extends by one hour to 16:00, for one hour of rent, and liquidity_expiry then shows the later of 16:00 and what usage still buys.

Method: RequestChannelLeaseExtension

Parameters:

Response:

Example Request:

import {
  RequestChannelLeaseExtensionRequest,
  OffchainFeePayment
} from './proto/liquidity_pb'

const request = new RequestChannelLeaseExtensionRequest()
request.setNetwork({ protocol: 1, id: '0a03cf40' })
request.setChannelId('ch_def456')
request.setAssetId('0x0000000000000000000000000000000000000000000000000000000000000000')
request.setLeaseExtensionSeconds(2592000) // +30 days
request.setPaymentNetwork({ protocol: 1, id: '0a03cf40' })
request.setPaymentAssetId('0x0000000000000000000000000000000000000000000000000000000000000000')
request.setOffchainFeePayment(new OffchainFeePayment())

const response = await client.requestChannelLeaseExtension(request, {})
console.log('New expiry:', response.getExpiryTimestampSeconds())

Example Response:

{
  "channelId": "ch_def456",
  "assetId": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "expiryTimestampSeconds": "1735689600"
}

Estimate Request Channel Lease Extension Fee

Estimate the service fee for a lease extension before executing it.

The fee is the whole fee the extension is billed: the setup fee, plus the rental of the capital the provider lent into the asset channel — never funds you put in yourself — for lease_extension.rented_seconds, the time the extension adds. Pass its quote_id back on the request and you are billed no more than that figure, even if the channel grows in between — less when another paid operation carries the lease part of the way meanwhile — and the lease runs to the expiry the estimate showed: later when the lease ends while the fee is being paid, since it then counts from a later slot boundary, earlier only when lease time the estimate counted from is taken back because its own fee was never collected. See Quotes.

The estimate refuses an extension the request would refuse: an asset channel that is closed, has an on-chain update in flight, holds no capacity, or holds none of the provider's funds.

Method: EstimateRequestChannelLeaseExtensionFee

Parameters: Same as Request Channel Lease Extension.

Response:

LeaseExtensionTerms — every instant is a slot boundary, and every duration a whole number of slots:

Example:

const response = await client.estimateRequestChannelLeaseExtensionFee(request, {})
console.log('Estimated fee:', response.getFee()?.getValue())

Example Response:

{
  "fee": "0.00008",
  "quoteId": "3f0f6f52-5a3b-4b1e-9b1f-6a0e2c1d9e44",
  "validUntil": "2026-09-25T09:57:00+00:00",
  "leaseExtension": {
    "extensionSeconds": "3600",
    "startsAt": "2026-09-25T18:00:00+00:00",
    "expiry": "2026-09-25T19:00:00+00:00",
    "rentedSeconds": "3600"
  }
}

Get Liquidity Service Info

Server-wide bounds, durations, per-asset fee configuration, the assets a fee may be paid in with what each rail charges, and the provider's node public key on each network. Read-only, no side effects. (2026-10-14) Your node keeps the answer until the provider announces a change of its terms, and then reads it again: call it whenever you show fee options, rather than once at start.

Method: GetLiquidityServiceInfo — Parameters: None.

Response:

LiquidityAssetConfig:

node_pubkeys is where a bot gets the peer id to connect to before requesting liquidity — it is the same value the peer tables publish, read from the live service.

LiquidityFeePaymentAsset (2026-10-14):

LiquidityFeeRails — one field per fee_payment variant, each a LiquidityFeeRailTerms, absent when the service refuses that rail for the asset: onchain, offchain, dual_fund, sponsored_deposit, sponsored_withdrawal. Bitcoin carries only onchain and offchain, and a sponsored deposit is never offered in a network's native asset.

LiquidityFeeRailTerms — what a fee paid on that rail is made of, beyond the hourly rent of the leased assets (fee_ratio_per_hour above):

The terms say how a fee is built, not what it comes to. Estimate the request (Estimate*Fee) for the figure: on-chain costs move with the chain's fee rate, and the rent with the amount and duration.

Get Leaseable Asset Info

Liquidity bounds and fee ratio for one (network, asset) pair on the provider. This is the call that answers "can I lease this, and how much".

Method: GetLeaseableAssetInfo

Parameters:

Response: info (LeaseableAssetInfo):

Sizing a lease against available_liquidity is what avoids the lease_too_big estimate variant — that variant reports the same three numbers after the fact.

Get Leases

The caller's active leases on a network.

Method: GetLeases

Parameters:

Response: leases (AssetChannelLease[]):

Get Lease Expiries

Every lease expiry the node holds for a network, in one call, keyed by channel then asset.

Method: GetLeaseExpiries

Parameters:

Response:

This one reads the local cache — no round-trip to the provider

That makes it cheap enough to poll on a UI timer, and it is the right call for "which of my leases are running down". GetLeases asks the provider and is the authority when the two disagree.

Usage keeps the provider's liquidity in place past the lease on its own, so an actively-traded channel's liquidity expiry moves forward without you paying anything. Watch it rather than counting down from the duration you bought.

Get Fee Payments

(2026-09-15) What this node has been billed on a network, newest first — one record per payment the service committed to, whatever became of it.

Method: GetFeePayments

Parameters:

Response:

FeePaymentCursor

Treat it as opaque — pass back the next you were given, unchanged. The two fields are documented so you can persist and reconstruct one across a restart, not so you can synthesise a position.

The instant is microseconds rather than seconds on purpose: payments committed inside the same second still have to page deterministically, and the id is the tie-breaker when even that collides.

FeePayment

FeePaymentOperation

The same operation shapes a request carries, read back. Exactly one variant is set:

The duration sits inside provision rather than beside the variants because only a provisioning operation has one: a release buys no lease time, and an extension states its own delta.

Page by cursor, never by offset

Pass the response's next back as before, and stop when it comes back absent. New payments arrive at the newest end of this ordering, which is exactly where an offset would shift a page under you — the same row returned twice, or skipped.

The cursor is a position, not an index: a creation instant in microseconds plus the payment id that breaks ties with anything committed in the same instant. Treat it as opaque and hand it back unchanged.

Duration Reference

lease_duration_seconds and lease_extension_seconds are expressed in seconds. Every lease ends on a boundary of the service's lease clock (lease_slot_secs): a lease window runs from when the service funds it to the next boundary, and an extension is rounded up to whole slots — its estimate says what it became.

const days = 30
const leaseSeconds = days * 24 * 60 * 60 // 2,592,000

Choosing a fee payment method

Common Workflows

(2026-10-14) Both workflows submit under a client_request_id and follow the request to its end with the helpers from Subscribe Liquidity Requests: the stream is open before the request is submitted, so no change of it is missed.

Open a channel with server-provided liquidity (offchain fee)

async function openChannelWithLiquidity(
  client: LiquidityServiceClient,
  network: { protocol: number; id: string },
  assetId: string,
  serverAmount: string,
  leaseDays: number,
  clientRequestId: string   // your name for this request: persist it, and reuse it on a retry
) {
  const request = new RequestChannelLiquidityRequest()
  request.setNetwork(network)

  const open = new ChannelLiquidityRequestOperation.Open()
  const liq = new AssetLiquidity()
  liq.setServerAmount({ value: serverAmount })
  liq.setClientAmount({ value: '0' })
  open.getAssetLiquidityMap().set(assetId, liq)

  const op = new ChannelLiquidityRequestOperation()
  op.setOpen(open)
  request.setOperation(op)

  request.setLeaseDurationSeconds(leaseDays * 24 * 60 * 60)
  request.setPaymentNetwork(network)
  request.setPaymentAssetId(assetId)
  request.setOffchainFeePayment(new OffchainFeePayment())
  request.setClientRequestId(clientRequestId)

  // 1. Estimate first
  const estimate = await client.estimateRequestChannelLiquidityFee(request, {})
  console.log('Estimated fee:', estimate.getFee()?.getValue())

  // 2. Subscribe, then submit, then follow the request until it is final
  const requests = await openRequests(client, network)
  try {
    const submitted = (await client.submitChannelLiquidityRequest(request, {})).getRequest()!
    const final = await requests.waitFinal(submitted)
    if (!final.hasCompleted()) {
      throw new Error(`request ${final.getPaymentUuid()} ended without completing`)
    }
    // Absent when the node missed the service's report: read the channel then.
    const result = final.getCompleted()!.getChannelLiquidity()
    return {
      channelId: result?.getChannelId(),
      txid: result?.getTxid()
    }
  } finally {
    requests.close()
  }
}

Cooperatively close a channel through the service

async function cooperativeClose(
  client: LiquidityServiceClient,
  network: { protocol: number; id: string },
  channelId: string,
  paymentAssetId: string,
  clientRequestId: string   // your name for this request: persist it, and reuse it on a retry
) {
  const request = new RequestChannelReleaseRequest()
  request.setNetwork(network)

  const close = new ChannelReleaseOperation.CooperativeClose()
  close.setChannelId(channelId)
  const op = new ChannelReleaseOperation()
  op.setCooperativeClose(close)
  request.setOperation(op)

  request.setPaymentNetwork(network)
  request.setPaymentAssetId(paymentAssetId)
  request.setOffchainFeePayment(new OffchainFeePayment())
  request.setClientRequestId(clientRequestId)

  // Subscribe, then submit, then follow the request until it is final
  const requests = await openRequests(client, network)
  try {
    const submitted = (await client.submitChannelReleaseRequest(request, {})).getRequest()!
    const final = await requests.waitFinal(submitted)
    if (!final.hasCompleted()) {
      throw new Error(`release ${final.getPaymentUuid()} ended without completing`)
    }
    // Absent when the node missed the service's report: read the channel then.
    return final.getCompleted()!.getChannelRelease()?.getTxid()
  } finally {
    requests.close()
  }
}

Error Handling

Best Practices

1. Submit with a client_request_id, and follow the request. (2026-10-14) Use the Submit* RPCs, not the deprecated Request* ones. Name every request, open SubscribeLiquidityRequests before you submit, and act on the request's final state — not on the Submit* answer, which on the on-chain rail comes before the fee transfer has confirmed. After a call that was cut off, submit again under the same id.
2. Always estimate first. Call the matching Estimate* RPC before the operation.
3. Provide lease_duration_seconds only when needed. Required if any asset has server_amount > 0; otherwise omit.
4. Pick the right fee payment. Offchain is cheapest; dual-fund and sponsored-deposit are only valid on a channel liquidity request.
   • Pass the quote_id from your estimate. Without it the service prices the request at execution, and the user is billed a figure they never saw.
5. Reuse channels when possible. deposit / deposit_any / open_or_deposit avoid the cost of opening a new channel.
6. Treat lease_extension_seconds as a delta, not a target expiry. It counts from lease_expiry and is sold in whole slots; offer durations in multiples of lease_slot_secs.
7. Watch AssetChannel.liquidity_expiry to know when the provider takes its liquidity back. lease_expiry is the lease you paid for and moves only when a lease is paid for; usage keeps the liquidity in place past it for as long as payments keep buying time, and liquidity_expiry shows until when. Read both on channel reads (or liquidity.GetLeaseExpiries) and extend only when liquidity_expiry is genuinely running down. Once it has passed, the provider takes its liquidity back as soon as your node is online — it does not wait for you to be online at a particular time.
8. On withdraw, name the side. asset_amounts needs server_amount and/or client_amount per asset — at least one — since 2026-07-23.

← Back to API Reference | Next: Watch-Only Node API →