Skip to content

Chain · checked 9 November 2026

Agent payment safety checks for Bitcoin Lightning Network

Lightning settles Bitcoin payments off-chain through invoices, where the preimage is the receipt and expiry, routing and liquidity are the failure points.

What your agent needs to know about Bitcoin Lightning Network

Finality
A Lightning payment is complete for the payer when the preimage matching the invoice payment hash comes back. Lightning Labs says the preimage can act as proof of payment. There is no confirmation count. The agent should treat a payment as settled only when it holds the preimage, and SHA-256 of it must equal the invoice payment hash. A payment that returns an error is not proof it failed until the HTLC has resolved. The docs cited here do not give HTLC resolution timings, so none are stated.[1],[2]
Fees
The official pages cited here give no fee numbers. They say routing nodes set their own fees and need both inbound and outbound capacity. Do not assert a fee figure for this page; the agent should ask for a route and fee estimate before paying.[3]
Stablecoins
Circle's list of native USDC networks does not include Lightning. Tether announced USDT on Bitcoin and Lightning via Taproot Assets, developed by Lightning Labs, in January 2025, but Lightning is not on Tether's supported-protocols list as of 9 November 2026. Treat any USDT received over Lightning as unconfirmed with the issuer until Tether lists it.[4],[5],[8],[9]

How agent payments go wrong on Bitcoin Lightning Network

  1. 1. Invoice expired

    BOLT 11 sets a default expiry of 3600 seconds when the x field is absent. After timestamp plus expiry the payer should not pay and the payee should not accept. An agent that queues a payment must check expiry at send time, not when it read the invoice.[1]

  2. 2. Paying without a usable receipt

    The payment hash is SHA-256 of the preimage, and the preimage is the proof of payment. An agent that records only 'sent' has no proof. Store the invoice, payment hash and returned preimage, and verify the hash match.[1],[2]

  3. 3. No route or insufficient liquidity

    BOLT 4 defines failures such as temporary_channel_failure, which means the channel could not take the HTLC now but may later, and unknown_next_peer. Liquidity depends on the balance in each channel along the path. Retry with a different route or smaller multi-part shards, but only for failures marked temporary, and stop retrying after a bounded number.[6],[3]

  4. 4. Final-hop rejection

    incorrect_or_unknown_payment_details is returned when the hash is unknown, the secret does not match, the amount is too low, the expiry is too close, or required metadata is missing. It is permanent, so retrying the same invoice will not help. Fetch a fresh invoice instead.[6]

  5. 5. Unverified invoice contents

    The invoice carries an amount, a description or description hash, a payment secret and a signature that the payer must verify. An agent that pays any invoice a remote server hands it can be given a different amount or payee than it intended. Check the decoded amount, the payee pubkey, and the description hash against the request.[1]

Pre-flight checklist for a Bitcoin Lightning Network agent

  • Decode the invoice and compare amount and payee node to what the task authorized.
  • Reject invoices past timestamp plus expiry, with a margin for retry time.
  • Verify SHA-256(preimage) equals the payment hash before marking paid.
  • Persist payment hash, preimage and invoice for every payment.
  • Cap retries and total routing fee per payment.
  • For L402 endpoints, pay once per 402 challenge and keep the token with its preimage.

Run the checks now, free

The free tools run in your browser: nothing you type leaves your browser, and wallet reads go only to a public RPC.

  • The Wrong-Money Test

    Write down what happens when your agent pays the wrong amount, the wrong address or the wrong token on Bitcoin Lightning Network, and see whether the answer holds up.

  • Agent Spend-Cap Stress Test

    Work out how much your agents can really move in one window once retries, parallel runs and per-key limits stack up.

Want a second pair of eyes on how your agent pays on Bitcoin Lightning Network? Book the free 48-hour integration review (opens Cal.com in a new tab).

Explorers to confirm a payment

Sources

  1. [1] BOLT 11: Invoice Protocol for Lightning Payments, Lightning BOLTs
  2. [2] Understanding Lightning Invoices, Lightning Labs docs
  3. [3] Understanding Liquidity, Lightning Labs docs
  4. [4] Multi-chain USDC, Circle
  5. [5] Supported Protocols, Tether
  6. [6] BOLT 4: Onion Routing Protocol, Lightning BOLTs
  7. [7] L402, Lightning Labs docs
  8. [8] Tether brings USDT to Bitcoin and the Lightning Network, Tether
  9. [9] Tether on Lightning, Lightning Labs

Checked against these sources on 9 November 2026. Networks change: confirm against the live docs before you rely on a number. This page is a checklist from public documentation. It is not a security audit, legal, compliance or investment advice.