amashukov/lnd-client-php

Typed LND (Lightning Network Daemon) REST client in pure PHP — invoices, payments, channel management and backups over any PSR-18 client, with millisatoshi amounts kept exact as bcmath numeric-strings.

An LND client in pure PHP speaking the node's REST gateway, built on any PSR-18 HTTP client. It covers the surface a custodial service actually needs: mint an invoice, watch it settle, pay a BOLT11, track that payment to a verdict, read channel and wallet balances, and drive channel lifecycle (open, close, fee policy, static backup) from an operator panel rather than lncli over ssh.

Features

• Millisatoshi arithmetic that cannot silently lose money — Msat is a bcmath numeric-string value object. No floats anywhere; 2100000000000000000 msat survives a round trip that IEEE-754 would mangle. Sub-satoshi remainders are rejected loudly instead of being rounded away.
• A timeout is not a failure — sendPayment() raises LndUnavailableException when the node is unreachable or the call times out, and LnPaymentState treats every unrecognised or unknown state as unresolved. Only SUCCEEDED and FAILED are terminal, so a caller can never mistake "I don't know yet" for "it failed" and pay twice.
• Transport-agnostic — bring your own PSR-18 client and PSR-17 factories. The macaroon header, TLS pinning, retries and timeouts are middleware concerns of the host application, deliberately not baked in.
• Typed value objects — LnInvoice, LnPayment, LnChannel, LnChannelBalance, LnWalletBalance, LnNodeInfo, LnChannelPoint, LnChannelBackup. They are total functions over wire data: a missing invoice becomes an absent instance, never an exception and never null.
• Wire quirks handled — LND returns payment hashes and funding txids base64-encoded in some responses and hex in others; the VOs normalise both to lowercase hex. The v2/router streaming endpoints wrap their payload in a result envelope, which is unwrapped transparently.
• Zero framework coupling — no Symfony, no Laravel, no App\ namespace. PHPStan level 8 across src and tests.

Installation

composer require amashukov/lnd-client-php

Requires PHP >= 8.3 and ext-bcmath.

Usage

use Amashukov\Lnd\LndClient;
use Amashukov\Lnd\Msat;
use Nyholm\Psr7\Factory\Psr17Factory;

$psr17 = new Psr17Factory();

// The macaroon header and TLS options belong in your PSR-18 pipeline, not here.
$client = new LndClient($http, $psr17, $psr17, 'https://lnd:8080');

$invoice = $client->addInvoice(Msat::fromBtc('0.0005'), 'order-7f3a91c2', 3600);
echo $invoice->bolt11;       // lnbc500u1p...
echo $invoice->paymentHash;  // lowercase hex, ready to persist

// later, from a poller
if ($client->lookupInvoice($invoice->paymentHash)->isSettled()) {
    // credit the order
}

Paying an invoice, with a hard cap on routing fees:

$payment = $client->sendPayment($bolt11, feeLimit: Msat::fromString('150000'), timeoutSeconds: 60);

if ($payment->isFailed()) {
    // terminal: no funds left the node
}

Settling a payment safely

sendPayment() returning is not the end of the story, and neither is it throwing. The only authority on whether money moved is trackPayment():

$state = $client->trackPayment($paymentHash);

match (true) {
    $state->isSucceeded() => $order->finalize(),
    $state->isFailed()    => $order->markFailed(),
    default               => null, // still unresolved — poll again, do NOT re-send
};

If sendPayment() throws LndUnavailableException, the HTLC may still be in flight. Treat that as unresolved and let the next poll decide. Mapping it to failure and re-sending is how a custodial service double-pays.

Channel operations

$client->connectPeer($pubkey, 'node.example:9735');
$point = $client->openChannel($pubkey, localFundingSat: '10000000', satPerVbyte: 8);

foreach ($client->listChannels() as $channel) {
    // basis points, for liquidity alerting
    $channel->localShareBps();
    $channel->inboundShareBps();
}

$client->closeChannel($point, force: false, satPerVbyte: 8);

Backups

exportChannelBackup() returns the multi-channel static backup blob. It is the only artefact that can recover funds from a lost node — and it is worthless if the recovered node is later started from stale channel state. Store it off-box, encrypted and versioned; never run two daemons against one state directory.

Value objects

Exceptions

LndUnavailableException extends LndException, so one catch (LndException) covers both — but the distinction matters: LndUnavailableException means transient, retry (transport failure or HTTP 5xx), while a plain LndException carries an error the node itself reported, with getLndCode().

Testing

composer test
composer stan
composer cs

Contract tests read recorded LND responses from tests/fixtures/*.json and assert the value objects decode them exactly, so a change in the node's wire format fails a test rather than surfacing as a wrong balance in production.