Watch-Only Node API

The Watch-Only Node API exposes Hydra App's WatchOnlyNodeService — read-only queries over node identity, channels and payment history on every protocol the node runs, not just Lightning. Nothing here signs or moves funds, so it is the surface to point monitoring and display at.

JSON-RPC namespace: watchOnlyNode

Endpoints

• Get Node ID
• Get Channels
• Get Channels With Counterparty
• Get Channel
• Get Payments
• Get Pending Payments
• Get Payments By Hash
• Get Payment

Get Node ID

Get the node ID for a specific network.

Service: WatchOnlyNodeServiceMethod: GetNodeId

Parameters:

Response:

Example Request:

const nodeId = await hydraGrpcClient.getNodeId({
  network: { protocol: 1, id: '0a03cf40' }   // Bitcoin Signet
})

let request = tonic::Request::new(GetNodeIdRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
});

let response = client.get_node_id(request).await?;
let node_id = response.into_inner().node_id;

Get Channels

Get all channels for a network.

Service: WatchOnlyNodeServiceMethod: GetChannels

Parameters:

Response:

Channel Object:

A channel holds several assets at once; status is the channel-wide summary, and the real per-asset state lives in asset_channels. AssetChannelStatus is a oneof with fourteen arms — cooperatively_opening, opening, cooperatively_updating, updating, cooperatively_closing, closing ({ closed_at_block }), force_closing ({ force_closed_at_block?, disputer, dispute_deadline? }), closed_redeemable, closed ({ force_closed }), inactive, active_sending, active_receiving, active, recovering — so match on it rather than comparing to a single "active" value.

closed.force_closed tells you whether the slot is reusable. false is a cooperative close: on Lithium the channel slot stays reusable for further deposits, while Lightning destroys the channel on any close. true is a unilateral / disputed close, and the slot is permanently dead under every protocol — the only way forward is a new channel.

AssetChannel Object:

One entry per asset held in the channel. This is where per-asset balance, usability, and lease state live.

Use can_send / can_receive for routing decisions rather than inferring usability from status plus balances — they account for the states a raw status check misses.

funding_credited is not is_updatable. A zero-conf open has its funding credited (so it can carry payments) while still admitting no further on-chain update.

lease_expiry is the cheap way to monitor a lease — it rides along on every channel read, so you don't need a separate liquidity.GetLeaseExpiries poll. Leases extend automatically with channel usage, so an actively-used channel's expiry moves forward on its own; see Lease API → Request Channel Lease Extension.

Example Request:

const channels = await hydraGrpcClient.getChannels({
  protocol: Protocol.BITCOIN,
  id: '0a03cf40'
})

channels.forEach(ch => {
  console.log(`Channel ${ch.id} with ${ch.counterparty}`)
})

let request = tonic::Request::new(GetChannelsRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
});

let response = client.get_channels(request).await?;
let channels = response.into_inner().channels;

for channel in channels {
    println!("Channel {} with {}", channel.id, channel.counterparty);
}

Get Channels With Counterparty

Get all channels with a specific counterparty node.

Service: WatchOnlyNodeServiceMethod: GetChannelsWithCounterparty

Parameters:

Response:

Example Request:

const channels = await hydraGrpcClient.getChannelsWithCounterparty({
  network: { protocol: 1, id: '0a03cf40' },
  counterpartyPubkey: '02abc123...'
})

let request = tonic::Request::new(GetChannelsWithCounterpartyRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
    counterparty_pubkey: "02abc123...".to_string(),
});

let response = client.get_channels_with_counterparty(request).await?;
let channels = response.into_inner().channels;

Get Channel

Get detailed information about a specific channel.

Service: WatchOnlyNodeServiceMethod: GetChannel

Parameters:

Response:

Example Request:

const channel = await hydraGrpcClient.getChannel({
  network: {
    protocol: Protocol.BITCOIN,
    id: '0a03cf40'
  },
  channelId: 'ch_abc123'
})

console.log(`Channel status: ${channel.status}`)
console.log(`Counterparty: ${channel.counterparty}`)

let request = tonic::Request::new(GetChannelRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
    channel_id: "ch_abc123".to_string(),
});

let response = client.get_channel(request).await?;
let channel = response.into_inner().channel;

Get Payments

Get payment history for a network.

Service: WatchOnlyNodeServiceMethod: GetPayments

Parameters:

Response:

This call is paginated. Without a pagination block you get the newest 100 payments, not the whole history. Page by feeding next_cursor back as the next request's pagination.cursor until has_more is false. GetPendingPayments is not paginated — in-flight payments are a bounded set.

Payment Object:

There is no direction field, and no amount field. Direction is implied by which operations arm is set, and by whether the amount lands in spent or received. Older revisions of this page listed a PaymentDirection enum that has never been on the wire.

PaymentStatus — exactly one arm is set:

PaymentOperation — also a oneof, one entry per leg:

recipient_amount is what the recipient is meant to end up with; the shards are how it was actually split across channels, and their amounts include the routing fee. A multi-path payment has one operation with several shards, not several operations.

Example Request:

const { payments, pagination } = await hydraGrpcClient.getPayments({
  network: { protocol: 1, id: '0a03cf40' },
  pagination: { limit: 100 }
})

for (const payment of payments) {
  const [kind] = Object.keys(payment.status)      // pending | completed | failed | …
  console.log(`${payment.id}: ${kind}`)
}
// pagination.hasMore ⇒ call again with pagination.cursor = pagination.nextCursor

let request = tonic::Request::new(GetPaymentsRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
    pagination: Some(PaginationRequest { limit: 100, cursor: None }),
});

let response = client.get_payments(request).await?.into_inner();

for payment in response.payments {
    println!("{}: {:?}", payment.id, payment.status);
}
// response.pagination.has_more ⇒ call again with the returned next_cursor

Get Pending Payments

Returns all pending (in-flight) off-chain payments on the specified network.

Method: GetPendingPayments

Parameters:

Response:

Example Request:

import { GetPendingPaymentsRequest } from './proto/watch_only_node_pb'

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

const response = await client.getPendingPayments(request, {})
const pending = response.getPaymentsList()
console.log(`${pending.length} pending payments`)

Get Payments By Hash

Returns all payments matching a specific payment hash. Useful for resolving the state of a known invoice or hashlock.

Method: GetPaymentsByHash

Parameters:

Response:

Example Request:

import { GetPaymentsByHashRequest } from './proto/watch_only_node_pb'

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

const response = await client.getPaymentsByHash(request, {})
console.log(`Found ${response.getPaymentsList().length} payments`)

Get Payment

Returns the details of a specific payment by its unique ID.

Method: GetPayment

Parameters:

Response:

Example Request:

import { GetPaymentRequest } from './proto/watch_only_node_pb'

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

const response = await client.getPayment(request, {})
console.log('Payment:', response.getPayment()?.toObject())

Common Patterns

Monitor channel status

async fn get_active_channels(
    client: &mut WatchOnlyNodeServiceClient<Channel>,
    network: Network,
) -> Result<Vec<Channel>, Box<dyn std::error::Error>> {
    let channels = client
        .get_channels(GetChannelsRequest {
            network: Some(network),
        })
        .await?
        .into_inner()
        .channels;

    Ok(channels
        .into_iter()
        .filter(|ch| ch.status == ChannelStatus::Active as i32)
        .collect())
}

Find channel with peer

async fn find_channel_with_peer(
    client: &mut WatchOnlyNodeServiceClient<Channel>,
    network: Network,
    peer_id: String,
) -> Result<Option<Channel>, Box<dyn std::error::Error>> {
    let channels = client
        .get_channels_with_counterparty(GetChannelsWithCounterpartyRequest {
            network: Some(network),
            counterparty_node_id: peer_id,
        })
        .await?
        .into_inner()
        .channels;

    Ok(channels.into_iter().next())
}

Error Handling

Best Practices

1. Use this surface for monitoring. Nothing here can move funds, so it is safe to expose to a dashboard that the trading path is not.
2. Prefer the event stream to polling. SubscribeNodeEvents pushes channel and payment changes; these calls are for the initial snapshot and for reconciliation.
3. Judge a channel by can_send / can_receive / is_updatable, not by the high-level status. A channel can be on-chain confirmed and still unusable for the thing you want to do — see the AssetChannel notes.
4. Page GetPayments. The default page is 100 rows, newest first, not the whole history.
5. Resolve an invoice through GetPaymentsByHash, not by scanning GetPayments — a hash can have several attempts behind it, and this returns all of them.

← Back to API Reference | Next: Events & Subscriptions →