{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "getroute",
  "title": "Command for routing a payment (low-level)",
  "description": [
    "The **getroute** RPC command attempts to find the best route for the payment of *amount_msat* to lightning node *id*, such that the payment will arrive at *id* with *cltv*.",
    "",
    "There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck in a delayed output if a node goes down during the process. ."
  ],
  "categories": [
    "readonly"
  ],
  "request": {
    "required": [
      "id",
      "amount_msat",
      "riskfactor"
    ],
    "additionalProperties": false,
    "properties": {
      "id": {
        "type": "pubkey",
        "description": [
          "Node pubkey to find the best route for the payment."
        ]
      },
      "amount_msat": {
        "type": "msat",
        "description": [
          "Amount to send. It can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*. The 0 value is special: it ignores any *htlc_minimum_msat* setting on channels, and simply returns a possible route (if any) which is useful for simple probing."
        ]
      },
      "riskfactor": {
        "type": "u64",
        "description": [
          "A non-negative floating-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage). For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, *riskfactor* would be 20. If you didn't care about risk, *riskfactor* would be zero."
        ]
      },
      "cltv": {
        "type": "u32",
        "description": [
          "Cltv-blocks to spare."
        ],
        "default": "9"
      },
      "fromid": {
        "type": "pubkey",
        "description": [
          "The node to start the route from."
        ],
        "default": "this node"
      },
      "fuzzpercent": {
        "type": "u32",
        "description": [
          "Used to distort fees to provide some randomization to the route generated, but it was not properly implemented and is ignored."
        ]
      },
      "exclude": {
        "type": "array",
        "description": [
          "A JSON array of short-channel-id/direction (e.g. ['564334x877x1/0', '564195x1292x0/1' ]) or node-id which should be excluded from consideration for routing. Note if the source or destination is excluded, the command result is undefined."
        ],
        "default": "not to exclude any channels or nodes",
        "items": {
          "type": "string"
        }
      },
      "maxhops": {
        "type": "u32",
        "description": [
          "The maximum number of channels to return."
        ],
        "default": "20"
      }
    }
  },
  "response": {
    "required": [
      "route"
    ],
    "additionalProperties": false,
    "properties": {
      "route": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "direction",
            "channel",
            "amount_msat",
            "delay",
            "style"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "pubkey",
              "description": [
                "The node at the end of this hop."
              ]
            },
            "channel": {
              "type": "short_channel_id",
              "description": [
                "The channel joining these nodes."
              ]
            },
            "direction": {
              "type": "u32",
              "description": [
                "0 if this channel is traversed from lesser to greater **id**, otherwise 1."
              ]
            },
            "amount_msat": {
              "type": "msat",
              "description": [
                "The amount expected by the node at the end of this hop."
              ]
            },
            "delay": {
              "type": "u32",
              "description": [
                "The total CLTV expected by the node at the end of this hop."
              ]
            },
            "style": {
              "type": "string",
              "description": [
                "The features understood by the destination node."
              ],
              "enum": [
                "tlv"
              ]
            }
          }
        }
      }
    },
    "post_return_value_notes": [
      "The final *id* will be the destination *id* given in the input. The difference between the first *amount_msat* minus the *amount_msat* given in the input is the fee (assuming the first hop is free). The first *delay* is the very worst case timeout for the payment failure, in blocks."
    ]
  },
  "riskfactor_effect_on_routing": [
    "The risk factor is treated as if it were an additional fee on the route, for the purposes of comparing routes.",
    "",
    "The formula used is the following approximation:",
    "",
    "    risk-fee = amount x blocks-timeout x per-block-cost",
    "",
    "We are given a *riskfactor* expressed as a percentage. There are 52596 blocks per year, thus *per-block-cost* is *riskfactor* divided by 5,259,600.",
    "",
    "The final result is:",
    "",
    "    risk-fee = amount x blocks-timeout x riskfactor / 5259600",
    "",
    "Here are the risk fees in millisatoshis, using various parameters. I assume a channel charges the default of 1000 millisatoshis plus 1 part-per-million. Common to_self_delay values on the network at 14 and 144 blocks.",
    "",
    "| Amount (msat)          | Riskfactor         | Delay         | Risk Fee         | Route fee         |",
    "|------------------------|--------------------|---------------|------------------|-------------------|",
    "| 10,000                 | 1                  | 14            | 0                | 1001              |",
    "| 10,000                 | 10                 | 14            | 0                | 1001              |",
    "| 10,000                 | 100                | 14            | 2                | 1001              |",
    "| 10,000                 | 1000               | 14            | 26               | 1001              |",
    "| 1,000,000              | 1                  | 14            | 2                | 1001              |",
    "| 1,000,000              | 10                 | 14            | 26               | 1001              |",
    "| 1,000,000              | 100                | 14            | 266              | 1001              |",
    "| 1,000,000              | 1000               | 14            | 2661             | 1001              |",
    "| 100,000,000            | 1                  | 14            | 266              | 1100              |",
    "| 100,000,000            | 10                 | 14            | 2661             | 1100              |",
    "| 100,000,000            | 100                | 14            | 26617            | 1100              |",
    "| 100,000,000            | 1000               | 14            | 266179           | 1100              |",
    "| 10,000                 | 1                  | 144           | 0                | 1001              |",
    "| 10,000                 | 10                 | 144           | 2                | 1001              |",
    "| 10,000                 | 100                | 144           | 27               | 1001              |",
    "| 10,000                 | 1000               | 144           | 273              | 1001              |",
    "| 1,000,000              | 1                  | 144           | 27               | 1001              |",
    "| 1,000,000              | 10                 | 144           | 273              | 1001              |",
    "| 1,000,000              | 100                | 144           | 2737             | 1001              |",
    "| 1,000,000              | 1000               | 144           | 27378            | 1001              |",
    "| 100,000,000            | 1                  | 144           | 2737             | 1100              |",
    "| 100,000,000            | 10                 | 144           | 27378            | 1100              |",
    "| 100,000,000            | 100                | 144           | 273785           | 1100              |",
    "| 100,000,000            | 1000               | 144           | 2737850          | 1100              |",
    ""
  ],
  "recommended_riskfactor_values": [
    "The default *fuzz* factor is 5%, so as you can see from the table above, that tends to overwhelm the effect of *riskfactor* less than about 5.",
    "",
    "1 is a conservative value for a stable lightning network with very few failures.",
    "",
    "1000 is an aggressive value for trying to minimize timeouts at all costs.",
    "",
    "The default for lightning-pay(7) is 10, which starts to become a major factor for larger amounts, and is basically ignored for tiny ones."
  ],
  "author": [
    "Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
  ],
  "see_also": [
    "lightning-pay(7)",
    "lightning-sendpay(7)"
  ],
  "resources": [
    "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
  ],
  "examples": [
    {
      "request": {
        "id": "example:getroute#1",
        "method": "getroute",
        "params": {
          "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
          "amount_msat": 10000,
          "riskfactor": 1
        }
      },
      "response": {
        "route": [
          {
            "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
            "channel": "109x1x1",
            "direction": 1,
            "amount_msat": 10001,
            "delay": 15,
            "style": "tlv"
          },
          {
            "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
            "channel": "111x1x1",
            "direction": 0,
            "amount_msat": 10000,
            "delay": 9,
            "style": "tlv"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:getroute#2",
        "method": "getroute",
        "params": {
          "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
          "amount_msat": 500000,
          "riskfactor": 10,
          "cltv": 9
        }
      },
      "response": {
        "route": [
          {
            "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
            "channel": "111x1x1",
            "direction": 0,
            "amount_msat": 500006,
            "delay": 15,
            "style": "tlv"
          },
          {
            "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
            "channel": "125x1x1",
            "direction": 0,
            "amount_msat": 500000,
            "delay": 9,
            "style": "tlv"
          }
        ]
      }
    }
  ]
}
