"The **waitanyinvoice** RPC command waits until an invoice is paid, then returns a single entry as per **listinvoices**. It will not return for any invoices paid prior to or including the *lastpay_index*.",
"This is usually called iteratively: once with no arguments, then repeatedly with the returned *pay_index* entry. This ensures that no paid invoice is missed. The *pay_index* is a monotonically-increasing number assigned to an invoice when it gets paid. The first valid *pay_index* is 1."
],
"request":{
"required":[],
"properties":{
"lastpay_index":{
"type":"u64",
"description":[
"Ignores any invoices paid prior to or including this index. 0 is equivalent to not specifying and negative value is invalid."
]
},
"timeout":{
"type":"u64",
"description":[
"If specified, wait at most that number of seconds, which must be an integer. If the specified *timeout* is reached, this command will return with an error. You can specify this to 0 so that **waitanyinvoice** will return immediately with an error if no pending invoice is available yet. If unspecified, this command will wait indefinitely."
]
}
}
},
"response":{
"required":[
"label",
"description",
"payment_hash",
"status",
"created_index",
"expires_at"
],
"properties":{
"label":{
"type":"string",
"description":[
"Unique label supplied at invoice creation."
]
},
"description":{
"type":"string",
"description":[
"Description used in the invoice."
]
},
"payment_hash":{
"type":"hash",
"description":[
"The hash of the *payment_preimage* which will prove payment."
]
},
"status":{
"type":"string",
"enum":[
"paid",
"expired"
],
"description":[
"Whether it's paid or expired."
]
},
"expires_at":{
"type":"u64",
"description":[
"UNIX timestamp of when it will become / became unpayable."
]
},
"amount_msat":{
"type":"msat",
"description":[
"The amount required to pay this invoice."
]
},
"bolt11":{
"type":"string",
"description":[
"The BOLT11 string (always present unless *bolt12* is)."
]
},
"bolt12":{
"type":"string",
"description":[
"The BOLT12 string (always present unless *bolt11* is)."
]
},
"created_index":{
"type":"u64",
"added":"v23.08",
"description":[
"1-based index indicating order this invoice was created in."
]
},
"updated_index":{
"type":"u64",
"added":"v23.08",
"description":[
"1-based index indicating order this invoice was changed (only present if it has changed since creation)."
]
}
},
"allOf":[
{
"if":{
"properties":{
"status":{
"type":"string",
"enum":[
"paid"
]
}
}
},
"then":{
"additionalProperties":false,
"required":[
"pay_index",
"amount_received_msat",
"paid_at",
"payment_preimage"
],
"properties":{
"label":{},
"description":{},
"payment_hash":{},
"status":{},
"msatoshi":{},
"amount_msat":{},
"bolt11":{},
"bolt12":{},
"expires_at":{},
"created_index":{},
"updated_index":{},
"pay_index":{
"type":"u64",
"description":[
"Unique incrementing index for this payment."
]
},
"amount_received_msat":{
"type":"msat",
"description":[
"The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
]
},
"paid_at":{
"type":"u64",
"description":[
"UNIX timestamp of when it was paid."
]
},
"paid_outpoint":{
"type":"object",
"description":[
"Outpoint this invoice was paid with."
],
"added":"v23.11",
"additionalProperties":false,
"required":[
"txid",
"outnum"
],
"properties":{
"txid":{
"added":"v23.11",
"type":"txid",
"description":[
"ID of the transaction that paid the invoice."
]
},
"outnum":{
"added":"v23.11",
"type":"u32",
"description":[
"The 0-based output number of the transaction that paid the invoice."
]
}
}
},
"payment_preimage":{
"type":"secret",
"description":[
"Proof of payment."
]
}
}
},
"else":{
"additionalProperties":false,
"properties":{
"label":{},
"description":{},
"payment_hash":{},
"status":{},
"msatoshi":{},
"amount_msat":{},
"bolt11":{},
"bolt12":{},
"created_index":{},
"updated_index":{},
"expires_at":{}
}
}
}
]
},
"errors":[
"The following error codes may occur:",
"",
"- 904: The *timeout* was reached without an invoice being paid."
