core-lightning/doc/schemas/lightning-sendinvoice.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "sendinvoice",
  "title": "Command for send an invoice for an offer",
  "warning": "experimental-offers only",
  "description": [
    "The **sendinvoice** RPC command creates and sends an invoice to the issuer of an *invoice_request* for it to pay: lightning-invoicerequest(7).",
    "",
    "If **fetchinvoice-noconnect** is not specified in the configuation, it will connect to the destination in the (currently common!) case where it cannot find a route which supports `option_onion_messages`."
  ],
  "request": {
    "required": [
      "invreq",
      "label"
    ],
    "additionalProperties": false,
    "properties": {
      "invreq": {
        "type": "string",
        "description": [
          "The bolt12 invoice_request string beginning with `lnr1`."
        ]
      },
      "label": {
        "type": "string",
        "description": [
          "The unique label to use for this invoice."
        ]
      },
      "amount_msat": {
        "type": "msat",
        "description": [
          "Required if the *offer* does not specify an amount at all, or specifies it in a different currency. Otherwise you may set it (e.g. to provide a tip)."
        ],
        "default": "the amount contained in the offer (multiplied by *quantity* if any)"
      },
      "timeout": {
        "type": "u32",
        "description": [
          "Seconds to wait for the offering node to pay the invoice or return an error. This will also be the timeout on the invoice that is sent."
        ],
        "default": "90 seconds"
      },
      "quantity": {
        "type": "u64",
        "description": [
          "Quantity is is required if the offer specifies quantity_max, otherwise it is not allowed."
        ]
      }
    }
  },
  "response": {
    "required": [
      "label",
      "description",
      "payment_hash",
      "status",
      "created_index",
      "expires_at"
    ],
    "additionalProperties": false,
    "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": [
          "unpaid",
          "paid",
          "expired"
        ],
        "description": [
          "Whether it's paid, unpaid or unpayable."
        ]
      },
      "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."
        ]
      },
      "bolt12": {
        "type": "string",
        "description": [
          "The BOLT12 string."
        ]
      },
      "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)."
        ]
      },
      "amount_received_msat": {},
      "paid_at": {},
      "pay_index": {},
      "payment_preimage": {}
    },
    "allOf": [
      {
        "if": {
          "additionalProperties": true,
          "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": {},
            "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."
              ]
            },
            "payment_preimage": {
              "type": "secret",
              "description": [
                "Proof of payment."
              ]
            }
          }
        }
      }
    ]
  },
  "errors": [
    "The following error codes may occur:",
    "",
    "- -1: Catchall nonspecific error.",
    "- 1002: Offer has expired.",
    "- 1003: Cannot find a route to the node making the offer.",
    "- 1004: The node making the offer returned an error message.",
    "- 1005: We timed out waiting for the invoice to be paid"
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
  ],
  "see_also": [
    "lightning-fetchinvoice(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:sendinvoice#1",
        "method": "sendinvoice",
        "params": {
          "invreq": "lnr1qqgypua5g7rp293k00s66ayvnv26czst2d5k6urvv5s8getnw3gzqp3zderpzxstt8927ynqg044h0egcd8n5h3n9g0u0v4h8ncc3yg02gps7sjqtqssytfzxcs2xkdy0lml0tzy0jzugmyj8kjn8zfzrgq9fsgurc72x82e7pq947t0ks7a4yejz8w79x4zj25s3pu6zrnw2e0v2ugdescpcqsq307z4p2dlxe92fv7xd43qut0pjkg4y094hupqyhsj8dlhvmmfng6sv",
          "label": "test sendinvoice"
        }
      },
      "response": {
        "label": "test sendinvoice",
        "bolt12": "lni1qqgypua5g7rp293k00s66ayvnv26czst2d5k6urvv5s8getnw3gzqp3zderpzxstt8927ynqg044h0egcd8n5h3n9g0u0v4h8ncc3yg02gps7sjqtqssytfzxcs2xkdy0lml0tzy0jzugmyj8kjn8zfzrgq9fsgurc72x82e5zvqyehytxx360zptatj4pygsv9kpal8gnkeyd0tpvd6jv5rkv2uqdgcq2s27mvxt0arlnulnmce53cuz00vzaqvgvhpphxgavl89r8zrdhaxqgzpvxkkmwsmxnuwflttmnpc8vtzwlgd3cfty3xwlnlc9r2gcjesguqqv4xey4m7l4wxem27vxyxfhwznlc62kffsd5xncx9w49m4g72u2y7lcl6a3x5cpu52j6gm8q5x0q8k7myxdzrsqqqqqqqqqqqqqqq5qqqqqqqqqqqqqayjedltzjqqqqqq9yq3n2s38p5cq442pq5qpm4ht26v8statwxcrl65uy26c9hx4dvy66f9x665eqqy90tpz25qc0gfqtqggzvmj9nrga83q474e2sjygxzmq7ln5fmvjxh4skxafx2pmx9wqx5v0qsqfkcrpht0d3nnt8txkcgf5wr6gzrlacls2gyrvj5hhwuu98shurrn6ayruunju7k9yu9clvaj354tr064ruuht88q5dj73kzru20uzj",
        "payment_hash": "a003badd6ad30f05f56e3607fd538456b05b9aad6135a494dad5320010af5844",
        "amount_msat": 1000000,
        "status": "paid",
        "pay_index": 1,
        "amount_received_msat": 1000000,
        "paid_at": 1722303714,
        "payment_preimage": "6f154ed7d108349cb6385eba5f160294ef83862c2c560ba6446b2a3da5c2b3b3",
        "description": "Simple test",
        "expires_at": 1722303803,
        "created_index": 3,
        "updated_index": 1
      }
    }
  ]
}