{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "rpc": "waitanyinvoice",
  "title": "Command for waiting for payments",
  "description": [
    "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."
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
  ],
  "see_also": [
    "lightning-waitinvoice(7)",
    "lightning-listinvoices(7)",
    "lightning-delinvoice(7)",
    "lightning-invoice(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:waitanyinvoice#1",
        "method": "waitanyinvoice",
        "params": {}
      },
      "response": {
        "label": "inv1",
        "bolt11": "lnbcrt10n1pjmxtsxsp56sn02x8lccjfsvunnhz5858zuyxztug9luy226w4qsmfm4r8pkcspp5gw5r0dw99yf3zqxrg24l8g9m9hun9cu06ldg4rga8s9t9kv8z45sdq8d9h8vvgxqyjw5qcqp99qxpqysgqv537uh2sx8ch640mf4t43t8qjtpg3z7gukgm07tlyq986m7nvsnxkapg37z4vsxtl4thfqzc64anqr83geygkc2xaftxgr97dltqfjqpe3mhja",
        "payment_hash": "43a837b5c529131100c342abf3a0bb2df932e38fd7da8a8d1d3c0ab2d9871569",
        "amount_msat": 1000,
        "status": "paid",
        "pay_index": 1,
        "amount_received_msat": 1000,
        "paid_at": 1706241546,
        "payment_preimage": "a0c668998de14b975f33e1060b3efd7efc0bde784ac266ab667a1b2fddab3cd1",
        "description": [
          "Inv1."
        ],
        "expires_at": 1706846342,
        "created_index": 1,
        "updated_index": 1
      }
    },
    {
      "request": {
        "id": "example:waitanyinvoice#2",
        "method": "waitanyinvoice",
        "params": {
          "lastpay_index": 3,
          "timeout": 0
        }
      },
      "response": {
        "label": "inv4",
        "bolt11": "lnbcrt10n1pja0tkmsp57j4z9zwvdsyh57unh3da7aac5z20clfnrwy5nqm6wujaelduw23qpp580mdrwakz9xewc2vhvpucset9gjkgdvyhw7h9frcy2d6p2lwdw2qdq8d9h8vdqxqyjw5qcqp99qxpqysgqtgyzhtxs3p2dyk8wk9q028033303702d2hml4frmu38qe79mrkgzgxvyjmq2q4nhjgcuz3uhmlda3jnhf9w6mj8mj97pkgnda9l5kdcqsdgewf",
        "payment_hash": "3bf6d1bbb6114d97614cbb03cc432b2a25643584bbbd72a478229ba0abee6b94",
        "amount_msat": 1000,
        "status": "paid",
        "pay_index": 4,
        "amount_received_msat": 1000,
        "paid_at": 1708633825,
        "payment_preimage": "77336a342dde76050c7ee7fc18599e407dfc1edad3c784ba68e9603004365b94",
        "description": "inv4",
        "expires_at": 1709238619,
        "created_index": 4,
        "updated_index": 4
      }
    }
  ]
}