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. Hydra App completes fee settlement and any required local confirmations internally before returning the final operation result.

JSON-RPC namespace: liquidity

Endpoints

• Request Channel Liquidity
• Estimate Request Channel Liquidity Fee
• Request Channel Release
• Estimate Request Channel Release Fee
• Request Channel Lease Extension
• 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 RequestChannelLiquidity and its 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 RequestChannelRelease and its 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.

Fee payment (one of)

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

OnchainFeePayment (one of):

Fee methods are not interchangeable across the three operations:

Operation	Accepts
RequestChannelLiquidity	onchain · offchain · dual_fund · sponsored_deposit
RequestChannelRelease	onchain · offchain · sponsored_withdrawal
RequestChannelLeaseExtension	onchain · offchain

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. RequestChannelRelease only.

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_timestamp_seconds }
                        │
      show `fee` to the user, they accept
                        │
                        ▼
Request*      ──▶  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.

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...",
  "validUntilTimestampSeconds": "1789012345"
}

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. 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. Usage keeps a channel's liquidity in place on its own, so an actively-traded channel's liquidity_expiry runs ahead of its lease — a market maker routing volume through a channel typically pays only the initial lease. 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",
  "validUntilTimestampSeconds": "1790330220",
  "leaseExtension": {
    "extensionSeconds": "3600",
    "fromTimestampSeconds": "1790359200",
    "expiryTimestampSeconds": "1790362800",
    "rentedSeconds": "3600"
  }
}

Get Liquidity Service Info

Server-wide bounds, durations, per-asset fee configuration, and the provider's node public key on each network. Read-only, no side effects — call it once at start and cache it.

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.

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

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
) {
  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())

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

  // 2. Execute
  const result = await client.requestChannelLiquidity(request, {})
  return {
    channelId: result.getChannelId(),
    txid: result.getTxid()
  }
}

Cooperatively close a channel through the service

async function cooperativeClose(
  client: LiquidityServiceClient,
  network: { protocol: number; id: string },
  channelId: string,
  paymentAssetId: string
) {
  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())

  const result = await client.requestChannelRelease(request, {})
  return result.getTxid()
}

Error Handling

Best Practices

1. Always estimate first. Call the matching Estimate* RPC before the operation.
2. Provide lease_duration_seconds only when needed. Required if any asset has server_amount > 0; otherwise omit.
3. Pick the right fee payment. Offchain is cheapest; dual-fund and sponsored-deposit are only valid on RequestChannelLiquidity.
   • 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.
4. Reuse channels when possible. deposit / deposit_any / open_or_deposit avoid the cost of opening a new channel.
5. 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.
6. 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, and liquidity_expiry shows until when. Read both on channel reads (or liquidity.GetLeaseExpiries) and extend only when liquidity_expiry is genuinely running down.
7. 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 →