Scheme: exact on Bitcoin Lightning (lnbtc)
Summary
This document specifies the x402 exact payment scheme for Bitcoin Lightning
networks using the lnbtc namespace defined here, in CAIP-2 format. The client
pays a fresh BOLT11 invoice from the resource server and returns its 32-byte
payment preimage. The facilitator verifies SHA-256(preimage) == payment_hash
and requires the invoice signing key to match payTo. This check does not require
access to the receiver’s Lightning node. A client MUST NOT select this scheme
unless its payer Lightning node returns the preimage after payment.
The scheme supports only the bolt11 asset transfer method and the upfront
payment flow. The resource server processes the request only after the facilitator
validates the proof and records the payment hash.
This scheme targets x402 protocol version 2 and uses the core
PaymentRequirements, PaymentPayload, and SettlementResponse types from
x402-specification-v2.md.
Scheme and Networks
The lnbtc namespace identifies Bitcoin Lightning networks. Its reference MUST
be the first 32 characters of the underlying Bitcoin network’s genesis block
hash in lowercase hexadecimal, following the
BIP-122 CAIP-2 reference convention.
The supported networks are listed below.
schemeMUST be"exact".assetMUST be"BTC".- Mainnet MUST use
lnbtc:000000000019d6689c085ae165831e93and BOLT11 currencybc. - Bitcoin testnet MUST use
lnbtc:000000000933ea01ad0ee984209779baand BOLT11 currencytb. - Messages on the wire MUST use one of these concrete network identifiers.
Asset Transfer Method and Payment Flow
"bolt11" is the only supported asset transfer method.
extra.assetTransferMethod MAY be omitted, in which case it defaults to
"bolt11". Any explicit value MUST be "bolt11".
"upfront" is the only supported payment flow because a Lightning payment settles
before its preimage is available. The resource server MUST set
extra.paymentFlow to "upfront" in every payment requirement. Clients and
resource servers MUST reject any other value.
The request hash is the SHA-256 digest of a JSON object encoded with the JSON
Canonicalization Scheme (JCS, RFC 8785). It covers a versioned transport profile
and that profile’s request inputs. The server sends it as extra.requestHash and
puts it in the invoice’s signed BOLT11 description hash. See
Request Binding for the encoding.
The protocol sequence is:
- The resource server computes the request hash and returns a fresh BOLT11 invoice that commits to it in a payment requirement.
- The client validates and pays the invoice, then constructs a payment payload containing the preimage.
- The resource server sends the payload to the facilitator’s
/settleendpoint. It MUST NOT call/verifyfor this flow. - The facilitator validates the proof and atomically records the payment hash as used.
- The resource server processes the protected request only after
/settlesucceeds.
Terminology and Adapter Requirements
- Receiver: The seller-side Lightning node that creates invoices.
- Payer: The client-side Lightning node that pays an invoice.
- Payment hash: The 32-byte value committed to by the BOLT11 invoice.
- Preimage: The 32-byte secret whose SHA-256 digest is the payment hash.
- Replay store: Storage that atomically records settled network and payment-hash pairs and persists across facilitator restarts.
A payer adapter MUST return the payment preimage when it reports a payment as paid. A client MUST NOT use an adapter that cannot return the preimage.
A receiver adapter MUST be able to create a fresh invoice for an exact
millisatoshi amount with a caller-supplied BOLT11 description hash. The resource
server MUST have exclusive invoice-issuance authority for the receiver key in
payTo; an untrusted party MUST NOT be able to create invoices signed by that key.
Amounts
amount MUST be a decimal string that encodes a positive integer number of
millisatoshis. It MUST NOT contain a sign, decimal point, exponent, separator, or
unit suffix. The BOLT11 invoice MUST specify an integral millisatoshi amount.
Examples:
| Meaning | Wire amount |
|---|---|
| 1 millisatoshi | "1" |
| 1 satoshi | "1000" |
| 21 satoshis | "21000" |
| 1 bitcoin | "100000000000" |
User-facing SDKs MUST use explicit atomic AssetAmount pricing by default, for
example { "asset": "BTC", "amount": "21000" } for 21 satoshis. They MAY also
accept qualified forms such as "21 sat" or "21 sats". Parsers MUST use exact
decimal arithmetic and reject negative values and sub-millisatoshi precision.
Bare numeric prices such as "21" or 21 MUST NOT default to satoshis. These and
other forms, such as $1, 1 USD, or 0.0001 BTC, MUST be rejected unless the
application has registered a conversion parser. The error SHOULD direct the
caller to use an explicit atomic AssetAmount.
For this method, the x402 settled amount is the invoice amount, which MUST equal
PaymentRequirements.amount. The preimage does not reveal the amount actually
received. Lightning can settle a payment above the invoice amount, as described
in BOLT11.
The facilitator MUST accept an otherwise valid proof at the invoice amount even
if Lightning overpayment occurred. Overpayment grants no additional resource or
credit. This scheme provides no refund path; any refund is a separate arrangement
with the receiver. Clients MUST NOT assume a refund is available.
Clients MUST instruct their payer adapter to pay the invoice amount. Routing fees are paid by the payer in addition to that amount and do not count toward it. The receiver MUST reject payments whose aggregate amount is below the invoice amount without releasing the preimage. An incomplete or failed payment MUST NOT authorize the resource. Its HTLCs follow Lightning failure or timeout handling; there is no x402 refund transaction.
PaymentRequirements
The resource server MUST generate a fresh BOLT11 invoice for each payment
challenge and place it in extra.invoice. A fresh invoice MUST use a new 32-byte
preimage generated with cryptographically secure randomness and a previously
unused payment hash, including across networks. The signed payment hash
identifies the invoice.
The server MUST set extra.requestBindingProfile and
extra.requestBindingParams from its transport and resource configuration, and
extra.requestHash to the digest of the actual request, as specified below.
The following deterministic example is a test vector, not a reusable challenge.
Its validation time is Unix timestamp 1700000000, equal to the invoice creation
time.
{
"scheme": "exact",
"network": "lnbtc:000000000019d6689c085ae165831e93",
"amount": "25000",
"asset": "BTC",
"payTo": "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
"maxTimeoutSeconds": 300,
"extra": {
"assetTransferMethod": "bolt11",
"paymentFlow": "upfront",
"requestHash": "0d6623f775e025501fa7f0a30b54da25aad62b6ccfe35c85da38016711e6c018",
"requestBindingProfile": "http:1",
"requestBindingParams": { "headers": [] },
"invoice": "lnbc250n1pj48ugqpp54y3u9s8ylemsv8l3ewyzzu0klhujvuvmkl6llchq23vy8rzjsf0qsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygshp5p4nz8am4uqj4q8a87z3sk4x6yk4dv2mvel34epw68qqkwy0xcqvqxqzfvcqpjr4rx6ls6j5rpwknuea64evlk7yfx56wmqcer5eerekdsn9tlv6v4ex9mlz5dtm9qapl3svwlqcf7837dmjkru9z9w4h2rvm0md52w2sqxrwu5f"
}
}
The extra fields are:
| Field | Required | Meaning |
|---|---|---|
extra.assetTransferMethod |
No | If present, MUST be "bolt11"; defaults to "bolt11". |
extra.paymentFlow |
Yes | MUST be "upfront". |
extra.invoice |
Yes | Fresh, signed BOLT11 invoice for amount on network that passes the checks below. |
extra.requestHash |
Yes | Expected request hash, encoded as 64 lowercase hexadecimal characters. |
extra.requestBindingProfile |
Yes | Versioned request binding profile: "http:1" or "mcp:1". |
extra.requestBindingParams |
Yes | Object containing exactly the parameters required by the selected profile. |
maxTimeoutSeconds MUST be a positive integer. The BOLT11 invoice expiry MUST
equal maxTimeoutSeconds exactly.
payTo MUST be the receiver node’s valid compressed secp256k1 public key: exactly
33 bytes encoded as 66 lowercase hexadecimal characters without a prefix. The
invoice signing key MUST equal payTo. If the invoice contains an n field, that
field MUST equal payTo. Otherwise, the implementation MUST recover the key from
the invoice signature and require it to equal payTo.
Before returning the challenge, the server MUST strictly decode the invoice and verify all of the following:
- The BOLT11 amount equals
PaymentRequirements.amountexactly. - The BOLT11 currency matches the concrete network (
bcfor mainnet,tbfor testnet). - The invoice’s description hash equals the request hash.
- The invoice signing key equals
payTo. - The BOLT11 expiry equals
maxTimeoutSecondsexactly. - The BOLT11 creation time is not later than the server’s validation time plus its configured non-negative clock-skew allowance, whose default MUST be 60 seconds. Equality at this boundary is valid.
- The invoice has not expired at the server’s validation time.
The server MUST NOT reuse an invoice across clients or challenges.
extra.invoice is dynamic. Scheme implementations MUST declare invoice as a
dynamic extra field. requestHash, requestBindingProfile, and
requestBindingParams MUST NOT be dynamic. The server MUST derive them from the
actual request and its configuration before matching requirements. Every core
field and every server-declared extra field
except invoice MUST match the accepted requirements. This permits a paid retry
to use its original invoice for the same request.
Request Binding
The BOLT11 description hash MUST equal the request hash defined below. Clients, servers, and facilitators MUST reject invoices without this binding. The invoice signature covers both the description hash and the unique payment hash. Identical requests can have the same request hash while their invoices have distinct payment hashes.
The payment hash identifies the invoice, not a particular request attempt. An unused proof MUST be accepted for another challenge with the same request binding and payment terms if all validation rules pass. Servers need not track issued payment hashes per challenge.
The server MUST select the profile for the operation being purchased. MCP tool
calls MUST use mcp:1, including when MCP uses an HTTP transport. Other HTTP
requests use http:1. Clients, servers, and facilitators MUST reject missing,
unknown, or unsupported profiles and malformed profile parameters; they MUST NOT
fall back to another profile. Other transports require a separately defined
profile before they can use this method.
The domain tag MUST be "x402:exact:lnbtc:bolt11:" concatenated with
extra.requestBindingProfile. Clients and servers MUST construct the profile’s
binding object from the actual request. The server MUST reject requests whose
purchased operation, content interpretation, or account selection depends on
context not represented by that object. It MUST apply its normal authentication
and authorization checks on every attempt.
Description Hash Encoding
The description bytes MUST be the UTF-8 output of JCS (RFC 8785) applied to the profile’s binding object:
descriptionBytes = UTF8(JCS(binding))
requestHash = SHA-256(descriptionBytes)
Implementations MUST use JCS member sorting, string escaping, and number
serialization, and reject inputs outside its data model, including duplicate
object member names and invalid Unicode. No byte-order mark or trailing newline
is part of the hash input. The binding object is constructed locally; it is not
an additional field in PaymentRequirements or PaymentPayload.
The BOLT11 description hash MUST contain the raw 32-byte requestHash digest.
extra.requestHash MUST contain that same digest as 64 lowercase hexadecimal
characters. The client reconstructs the description bytes from its request and
the validated profile parameters without another server lookup.
The invoice signature also commits to its amount, currency, expiry, and payment
hash; the signer identifies the receiver. The domain tag fixes the x402 version-2
exact/bolt11/upfront interpretation. The existing payment-term checks remain
mandatory. Neither the invoice nor extra.requestHash is part of the hash input.
On a paid retry, the server MUST recompute the digest from the request that will
execute, using its configured profile and parameters. It MUST NOT take the
expected digest or profile parameters from accepted.extra,
PaymentPayload.resource, or the accepted invoice. It sends the computed digest
in requirements.extra.requestHash to /settle. The facilitator MUST compare
the accepted invoice’s signed description hash against that expected digest.
Missing binding fields MUST fail rather than disable the check. A previous
successful claim remains duplicate_settlement.
HTTP Profile (http:1)
extra.requestBindingParams MUST contain exactly one member, headers, whose
value is the configured array of bound header names. The client and server
compute the binding from the HTTP request itself.
methodandurlMUST use the@methodand@target-uricomponent rules in RFC 9421, section 2.2. The URL MUST be an absolutehttporhttpsURL in ASCII URI syntax, including the query string, without a fragment or user information. Implementations MUST preserve method case, percent escapes, and query parameter order. The server MUST validate the public origin against its configuration and reconstruct it only from trusted proxy information when behind a proxy.bodyHashMUST be SHA-256 of the content bytes after transfer decoding and before content decoding or application parsing. An absent body uses SHA-256 of empty bytes. JSON bodies MUST NOT be parsed and serialized before hashing. The paid retry MUST preserve the content bytes.- Bound headers MUST be selected by the server’s configuration for the resource,
never from the client echo.
extra.requestBindingParams.headersMUST contain every header that can affect the purchased operation, content interpretation, or account selection, even when absent. Examples includecontent-type,content-encoding,accept,range,authorization, andcookiewhen used for these purposes. Names MUST be lowercase HTTP field-name tokens in ascending ASCII byte order, with no duplicates. An empty array is valid only when no header affects these decisions.payment-signatureMUST NOT be included.
For each present bound header, valueHash MUST be SHA-256 of
0x01 || ASCII(value), where value uses the default field-component rules in
RFC 9421, section 2.1,
without component parameters. For an absent header it MUST be SHA-256 of the
single byte 0x00. This distinguishes absent and empty values. Unsupported field
values MUST cause rejection.
An account selected only through a TLS client certificate is an example of
unrepresented context and MUST cause rejection. Clients and servers MUST require
PaymentRequired.resource.url to equal url.
The client and server MUST construct a JSON object, binding, with exactly these
members:
| Member | Value |
|---|---|
domain |
The string "x402:exact:lnbtc:bolt11:http:1". |
method |
The HTTP method defined above. |
url |
The HTTP target URL defined above. |
bodyHash |
The body digest defined above, encoded as 64 lowercase hexadecimal characters. |
headers |
An array with one object per name in extra.requestBindingParams.headers, in the same order. Each object has exactly name and valueHash members. name is the header name; valueHash is its digest defined above, encoded as 64 lowercase hexadecimal characters. |
All members are required, including headers when empty. This object contains
only strings, arrays, and objects. JCS applies to this object; the HTTP body is
hashed as bytes as specified above.
MCP Profile (mcp:1)
This profile covers tools/call in the MCP transport.
Other MCP operations MUST NOT use this profile. extra.requestBindingParams
MUST contain exactly server and metadata:
serverMUST be an absolute URI in ASCII syntax, without user information or a fragment, identifying the MCP server. For HTTP connections it MUST be the public MCP endpoint URI; for other connections it MUST be a URI agreed through client and server configuration. Both sides MUST use the exact configured spelling. The client MUST check this value against its intended server’s connection or trusted configuration, not learn its identity from the payment challenge. The server MUST use its own configuration, not the client echo.metadataMUST be an array of non-emptyparams._metamember names, sorted according to JCS property ordering, without duplicates. Names are case sensitive. The server MUST include every metadata member that affects the purchased operation or account selection, even when absent. It MUST NOT includex402/paymentorprogressToken. An empty array is valid when no metadata affects those decisions.
The binding object MUST contain exactly these members:
| Member | Value |
|---|---|
domain |
The string "x402:exact:lnbtc:bolt11:mcp:1". |
server |
The independently validated extra.requestBindingParams.server. |
method |
The string "tools/call". |
name |
The actual params.name, a non-empty string, without normalization. |
arguments |
The actual params.arguments object, before defaults or application transformations; {} if omitted. Null and non-object values MUST be rejected. |
metadata |
An array with one object per configured metadata name, in the same order. Each object has exactly name and valueHash members as defined below. |
For each present bound metadata member, valueHash MUST be SHA-256 of
0x01 || UTF8(JCS(value)). For an absent member it MUST be SHA-256 of the single
byte 0x00. Each digest MUST be encoded as 64 lowercase hexadecimal characters.
An absent _meta is treated as an empty object; a present non-object _meta
MUST be rejected. Null values remain distinct from absent values.
The JSON-RPC id, payment metadata, progress token, and transport framing are
not binding inputs. A paid retry MAY change them without changing the purchased
operation. The tool MUST treat omitted arguments and {} identically. Servers
MUST reject operations that depend on any excluded input or unrepresented
context, including an account selected only by transport authentication or
session state. A bound account argument or metadata value MUST still be checked
against the authenticated caller’s permissions.
The server MUST associate PaymentRequired.resource.url with the actual tool
in its own configuration. Clients MUST derive the binding from the intended
server and tool call, never from the echoed resource URL. The server identity,
tool name, arguments, and relevant metadata together identify what is purchased.
PaymentPayload
After paying the invoice, the client sends the preimage in the scheme-specific
payload object. The invoice remains in accepted.extra.invoice:
{
"x402Version": 2,
"accepted": {
"scheme": "exact",
"network": "lnbtc:000000000019d6689c085ae165831e93",
"amount": "25000",
"asset": "BTC",
"payTo": "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
"maxTimeoutSeconds": 300,
"extra": {
"assetTransferMethod": "bolt11",
"paymentFlow": "upfront",
"requestHash": "0d6623f775e025501fa7f0a30b54da25aad62b6ccfe35c85da38016711e6c018",
"requestBindingProfile": "http:1",
"requestBindingParams": { "headers": [] },
"invoice": "lnbc250n1pj48ugqpp54y3u9s8ylemsv8l3ewyzzu0klhujvuvmkl6llchq23vy8rzjsf0qsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygshp5p4nz8am4uqj4q8a87z3sk4x6yk4dv2mvel34epw68qqkwy0xcqvqxqzfvcqpjr4rx6ls6j5rpwknuea64evlk7yfx56wmqcer5eerekdsn9tlv6v4ex9mlz5dtm9qapl3svwlqcf7837dmjkru9z9w4h2rvm0md52w2sqxrwu5f"
}
},
"payload": {
"preimage": "0001020304050607080900010203040506070809000102030405060708090102"
}
}
payload.preimage is required:
| Field | Type | Requirements |
|---|---|---|
preimage |
string | MUST be exactly 64 lowercase hexadecimal characters encoding 32 bytes. |
accepted.extra.invoice MUST be byte-identical to the invoice that the client
paid. It MAY differ from a newly generated requirements.extra.invoice on the
retry. Its signing key, request binding, and payment terms MUST pass the checks
below. No additional challenge identifier or request copy is required.
Request Binding Test Vectors
HTTP
The examples above describe GET https://api.example.com/article/A with an empty
body and no bound headers. They use the test-only secp256k1 private key
0000000000000000000000000000000000000000000000000000000000000001.
The canonical description is the following single line, encoded as UTF-8 without
its trailing newline:
{
"bodyHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"domain": "x402:exact:lnbtc:bolt11:http:1",
"headers": [],
"method": "GET",
"url": "https://api.example.com/article/A"
}
Its SHA-256 digest, which MUST equal extra.requestHash and the signed BOLT11
description hash, is:
0d6623f775e025501fa7f0a30b54da25aad62b6ccfe35c85da38016711e6c018
Changing only the URL to https://api.example.com/article/B produces this digest:
4a99860f75eed1ea8178a5db488e044173bc570c8a6210f2c8590cdf8622d509
Each case below starts independently at validation time 1700000000 with an
empty replay store. Mutations leave the accepted invoice and preimage unchanged
unless stated otherwise. The server computes requirements.extra.requestHash
from the actual request before calling /settle.
| Case | Expected result |
|---|---|
| Unchanged examples, including different JSON member order or whitespace. | Settlement succeeds. |
Replace only requirements.extra.invoice with a fresh valid invoice for the same request and terms. |
Settlement succeeds using the original accepted invoice. |
| Issue two concurrent challenges for the same request and terms. Pay only the first invoice, then present its proof against the second challenge. | Settlement succeeds using the first invoice; no record linking it to the second challenge is needed. |
| Present the same paid proof concurrently against both challenges for the same request and terms. | Exactly one settlement succeeds; the other returns duplicate_settlement. |
| Pay both invoices for concurrent challenges with the same request and terms, then present each invoice’s own proof. | Both settlements succeed; each payment has a distinct consumption key. |
| Present article A’s proof with an actual request for article B at the same price. | invalid_exact_lnbtc_request_mismatch. |
Also change the accepted requestHash to article B’s digest. |
invalid_exact_lnbtc_invoice_request_mismatch; the invoice still commits to article A. |
Change the actual method to POST, or body to the single byte 78 (hexadecimal), and echo the new digest. |
invalid_exact_lnbtc_invoice_request_mismatch. |
Remove requestHash, requestBindingProfile, or requestBindingParams from either side. |
invalid_exact_lnbtc_request_binding. |
| Use an unknown profile, omit its required parameters, or add an unknown parameter. | invalid_exact_lnbtc_request_binding. |
| Change only the accepted header list. | invalid_exact_lnbtc_request_mismatch. |
| Replace the accepted invoice with a valid signed invoice containing an inline description instead of a description hash. | invalid_exact_lnbtc_invoice_description. |
MCP
For tools/call with params.name equal to "get_article",
params.arguments equal to { "article": "A" }, and no bound metadata, use:
{
"requestBindingProfile": "mcp:1",
"requestBindingParams": {
"server": "https://api.example.com/mcp",
"metadata": []
},
"requestHash": "03941bfedc6af8a09b2f459fe83470284a76a8c75801caa9e1487a9276a693f4"
}
The canonical description is this single line, without its trailing newline:
{
"arguments": { "article": "A" },
"domain": "x402:exact:lnbtc:bolt11:mcp:1",
"metadata": [],
"method": "tools/call",
"name": "get_article",
"server": "https://api.example.com/mcp"
}
Its SHA-256 digest is the requestHash above. The following independent changes
produce these digests:
| Change | Request hash |
|---|---|
Change arguments.article to "B". |
b3e425970d64cd4f08fc4d57a11b76da59ce6a5760d92687398c91f063120678 |
Change name to "delete_article". |
3a52bbf19dda8b5765a27246b12e805770298273b48526956c421f02fe043455 |
Change server to "https://other.example.com/mcp". |
96903c29186c6aabc95e48abafd8ce3ad32b4060f5d5bf22cf75f3fbfe816e45 |
For a bound metadata name, an absent value hashes to
6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d;
a present null hashes to
c58dcb77cee9027d1f4b3207bd876d232e61f79ee9f9dbd4e6d834778da78b16.
For the settlement cases below, issue and pay an otherwise valid invoice whose description hash is the MCP article A digest. Each case starts independently with an empty replay store while the invoice is valid. Recompute requirements from the actual call, leaving the accepted invoice unchanged unless stated.
| Case | Expected result |
|---|---|
Retry the same tool call with a new JSON-RPC id, a changed progressToken, and the payment in _meta["x402/payment"]. |
The request hash is unchanged; settlement succeeds. |
| Change only JSON whitespace or member order in the tool arguments. | The request hash is unchanged; settlement succeeds. |
| Change the actual tool name or arguments while keeping the original accepted binding. | invalid_exact_lnbtc_request_mismatch. |
| Also echo the new request hash after changing the tool name or arguments. | invalid_exact_lnbtc_invoice_request_mismatch. |
| Change the configured server identity and echo the new parameters and request hash. | invalid_exact_lnbtc_invoice_request_mismatch. |
| Use the HTTP article A invoice and preimage with accepted binding fields copied from valid MCP requirements. | invalid_exact_lnbtc_invoice_request_mismatch; the HTTP and MCP domains differ. |
Change only the accepted profile and its parameters to a valid http:1 binding. |
invalid_exact_lnbtc_request_mismatch. |
Advertise http:1 for an MCP tool call, even over HTTP. |
The client rejects the challenge before payment. |
Omit a profile or required parameter, use an unknown profile, or include x402/payment or progressToken in the metadata list. |
invalid_exact_lnbtc_request_binding. |
| With a separately issued invoice binding a metadata value, change that value (including absent to null) and echo the new digest. | invalid_exact_lnbtc_invoice_request_mismatch. |
Client Payment Construction
Before paying, a client MUST:
- Require
scheme == "exact", a supported concrete network,asset == "BTC", a positive integralamount, a positive integralmaxTimeoutSeconds, and a valid compressed secp256k1payToencoded as 66 lowercase hexadecimal characters. - Require
extra.paymentFlow == "upfront"and a non-emptyextra.invoice. Treat a missingextra.assetTransferMethodas"bolt11"and reject any other value. - Strictly decode and verify the BOLT11 invoice and its signature.
- Validate
extra.requestHash,extra.requestBindingProfile, andextra.requestBindingParams. Require the profile to match the actual operation’s transport and compute the digest from the intended request using that profile’s rules, including its resource and server identity checks. Require exactly one description hash and no inline description. Both the description hash andextra.requestHashMUST equal the computed digest. - Require the invoice signing key to equal
payTo. - Require the invoice currency to match the selected network.
- Require the invoice to specify an integral millisatoshi amount equal to
PaymentRequirements.amount. - Require the invoice expiry to equal
maxTimeoutSecondsand its creation time to be no later than the client’s validation time plus its configured non-negative clock-skew allowance, whose default MUST be 60 seconds. - Require the invoice to be unexpired at the client’s validation time.
- Ask its payer adapter to pay the invoice on the selected network.
The payer result MUST report paid and identify the same invoice, payment hash,
and invoice amount. Any separately reported routing fee MUST NOT be included in
the amount comparison. The client SHOULD report in_flight as a distinct result
so the caller can retry without starting a second payment. For a paid result,
the client MUST validate the preimage format and SHA-256 digest. It MUST NOT
construct a PaymentPayload if a check fails.
Facilitator Validation
The upfront flow does not invoke facilitator /verify. The facilitator’s
/settle endpoint MUST treat the payload and echoed requirements as untrusted and
perform the following checks in order before it records the payment hash:
- Require
accepted.scheme,network,amount,asset,payTo, andmaxTimeoutSecondsto equal the corresponding requirement fields. - Require
scheme == "exact", a supported network,asset == "BTC", positive integralamountandmaxTimeoutSecondsvalues, and a valid compressed secp256k1payToencoded as 66 lowercase hexadecimal characters. - Resolve a missing
extra.assetTransferMethodtobolt11on both sides and requirebolt11. Requireextra.paymentFlow == "upfront"on both sides. Require both request hashes to be 64 lowercase hexadecimal characters. Require supported profiles and validate the syntax of both parameter objects using the Request Binding rules. Require the hashes, profiles, and parameters to match; parameter equality uses JCS serialization. Every other server-declaredextrafield exceptinvoiceMUST have the same value inaccepted; additive client fields MAY remain. - Require non-empty invoices in
requirements.extra.invoiceandaccepted.extra.invoice. The facilitator MUST use the accepted invoice for settlement and MUST NOT require the two invoices to be equal. - Strictly decode and verify the accepted invoice and its signature. Require
exactly one description hash and no inline description.
Require the signed description hash to equal the 32-byte digest decoded from
requirements.extra.requestHash. This check is mandatory; missing binding fields MUST fail. The facilitator checks the server-supplied expected digest; it does not need the original request. Require its signing key to equalrequirements.payTo, its BOLT11 currency to match the network, and its integral millisatoshi amount to equalrequirements.amount. Require its expiry to equalrequirements.maxTimeoutSeconds, and require its creation time not to exceed the facilitator’s settlement time plus the configured clock-skew allowance. - Require the preimage to contain exactly 64 lowercase hexadecimal characters.
Decode it as exactly 32 bytes and require
SHA-256(preimage_bytes) == payment_hash_bytes. - Apply the expiry policy below.
The facilitator MUST verify the preimage locally and MUST NOT require receiver access.
Paid-but-expired Policy
Let:
invoice_end = invoice_creation_time + invoice_expiry_secondssettlement_time =the facilitator’s validation time during/settleskew =the facilitator’s configured non-negative clock-skew allowance, whose default MUST be 60 seconds
The invoice passes the expiry check while
settlement_time <= invoice_end + skew, including after the BOLT11 expiry time. It
MUST fail the check after this boundary. Equality at the boundary is valid.
This grace period permits a retry when payment completed shortly before expiry.
Settlement and Replay Protection
Settlement does not move funds. The Lightning payment completed before the client received the preimage. Cryptographic proof verification is stateless, but enforcing single-use settlement requires a replay store. The canonical consumption key MUST be the ASCII string:
network + ":" + payment_hash
network is the validated concrete CAIP-2 network identifier. payment_hash is
the accepted invoice’s payment hash, encoded as 64 lowercase hexadecimal
characters without a prefix. The separator is one colon, with no whitespace.
After validation, the facilitator MUST atomically insert this key into a
restart-durable replay store. The insert MUST fail if the key already exists. In
that case, the facilitator MUST return duplicate_settlement. The resource server
MUST NOT process the protected request until the insert succeeds. The same hash
on different networks produces different keys.
The replay entry MUST remain until at least one hour after
invoice_end + skew. It MUST NOT be removed while the invoice can still pass
validation.
On success, SettlementResponse.transaction MUST be the lowercase invoice payment
hash and network MUST be the concrete lnbtc network. payer MUST be omitted
because Lightning does not reveal a stable payer address.
{
"success": true,
"transaction": "a923c2c0e4fe77061ff1cb882171f6fdf926719bb7f5ffe2e05458438c52825e",
"network": "lnbtc:000000000019d6689c085ae165831e93"
}
Error Vocabulary
Facilitators MUST use the following stable strings in errorReason. Settlement
MUST preserve the validation reason when validation fails.
| Reason | Meaning |
|---|---|
unsupported_scheme |
Either side is not exact. |
network_mismatch |
accepted.network differs from the requirement. |
unsupported_network |
The concrete lnbtc network is unsupported. |
invalid_exact_lnbtc_asset |
Either side does not specify BTC. |
invalid_exact_lnbtc_amount |
Either amount is not a positive integer. |
invalid_exact_lnbtc_amount_mismatch |
accepted.amount differs from the requirement. |
invalid_exact_lnbtc_pay_to_mismatch |
accepted.payTo differs from the requirement. |
invalid_exact_lnbtc_pay_to_malformed |
payTo is not a lowercase compressed secp256k1 public key. |
invalid_exact_lnbtc_max_timeout_mismatch |
accepted.maxTimeoutSeconds differs from the requirement. |
invalid_exact_lnbtc_extra_mismatch |
A server-declared extra field other than invoice, requestHash, requestBindingProfile, or requestBindingParams differs. |
invalid_exact_lnbtc_request_binding |
A request hash, profile, or parameter object is missing or malformed, or a profile is unsupported. |
invalid_exact_lnbtc_request_mismatch |
The accepted request hash, profile, or parameters differ from the requirement. |
invalid_exact_lnbtc_asset_transfer_method |
Either explicit asset transfer method is not bolt11. |
invalid_exact_lnbtc_payment_flow |
Either payment flow is missing or not upfront. |
invalid_exact_lnbtc_invoice_missing |
Either required invoice field is absent. |
invalid_exact_lnbtc_invoice_decode_failed |
Strict BOLT11 decoding, signature validation, or integral-msat validation failed. |
invalid_exact_lnbtc_invoice_description |
The invoice does not contain exactly one description hash or contains an inline description. |
invalid_exact_lnbtc_invoice_request_mismatch |
The signed description hash differs from the expected request hash. |
invalid_exact_lnbtc_invoice_payee_mismatch |
The invoice signing key differs from payTo. |
invalid_exact_lnbtc_invoice_currency_mismatch |
BOLT11 currency does not match the network. |
invalid_exact_lnbtc_invoice_amount_mismatch |
BOLT11 amount differs from the required millisatoshis. |
invalid_exact_lnbtc_max_timeout |
maxTimeoutSeconds is not a positive integer. |
invalid_exact_lnbtc_invoice_expiry_mismatch |
BOLT11 expiry does not equal maxTimeoutSeconds. |
invalid_exact_lnbtc_invoice_created_in_future |
BOLT11 creation time exceeds validation time plus the clock-skew allowance. |
duplicate_settlement |
The network and payment-hash pair is already used or lost an atomic settlement race. |
invalid_exact_lnbtc_preimage_missing |
payload.preimage is absent. |
invalid_exact_lnbtc_preimage_malformed |
Preimage contains non-lowercase-hex characters. |
invalid_exact_lnbtc_preimage_length |
Decoded preimage is not exactly 32 bytes. |
invalid_exact_lnbtc_preimage_hash_mismatch |
SHA-256 of the preimage does not equal the payment hash. |
invalid_exact_lnbtc_invoice_expired |
The paid-but-expired settlement-time window was exceeded. |
Client and server implementations SHOULD use these stable local failure reasons. They are not facilitator response reasons unless a transport explicitly maps a local failure into one:
| Reason | Meaning |
|---|---|
exact_lnbtc_invoice_issuance_denied |
The server’s issuance limiter denied a new invoice. |
invalid_exact_lnbtc_payer_invoice_mismatch |
The payer adapter returned a different invoice. |
invalid_exact_lnbtc_payer_payment_hash_mismatch |
The payer adapter returned a different payment hash. |
invalid_exact_lnbtc_payer_amount_mismatch |
The payer adapter returned a different amount. |
exact_lnbtc_payment_in_flight |
Payment is still in flight and may be retried. |
exact_lnbtc_payment_not_paid |
The payer did not report a paid status. |
invalid_exact_lnbtc_payer_preimage_required |
A paid result omitted the mandatory preimage. |
invalid_exact_lnbtc_payer_preimage_malformed |
A payer preimage is not 64 lowercase hex characters. |
invalid_exact_lnbtc_payer_preimage_hash_mismatch |
A payer preimage does not hash to the invoice payment hash. |
Security Considerations
Mandatory Cryptographic Proof
The preimage is bearer proof of payment. Implementations MUST avoid logging or otherwise disclosing it. A client MUST send it only to the resource server for the invoice it paid. The facilitator can verify the invoice and preimage without receiver credentials.
Invoice Substitution
On a paid retry, the accepted invoice can differ from the new challenge invoice.
The server MUST compute the expected request hash from the incoming request
before matching requirements. A matching client echo alone is insufficient. The
client and facilitator MUST check the signed description hash against the
expected digest and require the signing key to equal payTo and the
payment terms to match. A proof for another request fails even if its price and
receiver are the same. A self-issued invoice fails unless the attacker controls
the receiver node key.
Request binding does not identify the payer. A disclosed preimage and invoice remain bearer proof for the bound request; replay protection permits at most one successful claim. No server challenge store or receiver lookup is required.
Receiver Key Isolation
payTo binds the invoice to the receiver node. A shared custodial node is not
compatible if an untrusted tenant can create invoices under the same node key. The
tenant could pay its own invoice and use the preimage against another tenant’s
payment requirement. A compliant deployment MUST give the resource server
exclusive invoice-issuance authority for the receiver key.
Invoice Issuance Denial of Service
Fresh invoices consume receiver node resources. Servers SHOULD limit or authorize invoice issuance before calling the receiver. They MUST NOT reuse an invoice across clients or challenges. If the transport provides a payment payload before challenge generation, the server SHOULD validate it before it creates a replacement invoice.
Network and Currency Confusion
Servers, clients, and facilitators MUST map the concrete lnbtc network to the
expected BOLT11 currency and reject mismatches. In particular, a tb testnet
invoice MUST NOT appear under the mainnet identifier.
Durable Replay Protection
An in-memory replay store is not compliant because a restart loses consumed keys. All facilitator instances that settle for the same receiver MUST share a restart-durable replay store with an atomic insert. A resource server MUST NOT send invoices for one receiver to independent replay stores. A database can enforce this rule with a unique canonical consumption key. Persistent state is required because Lightning has no public spent marker for the bearer proof.
Payer Anonymity
Lightning routing does not give a facilitator a stable payer identity. Facilitators
MUST omit SettlementResponse.payer and MUST NOT infer payer identity from payTo
or the invoice payee.