Make a Chunked Payment on Interledger

Ben Sharafian
Mar 22, 2018 · 3 min read

One of the important concepts in Interledger is “chunked payments.” The idea is that you can split a payment into many Interledger packets, in the same way that a file is split into many Internet packets.

There are many reasons to split up a payment into chunks. It allows Interledger packets to be more homogenous, which makes routing easier. It lowers the liquidity requirements, because large payments are spread out across time. This makes the network safer and more competitive.

All of these points are pretty abstract, though. To many, chunked payments will sound bizarre. This tutorial aims to make these concepts more concrete.

You’ll send a chunked payment on your own machine to see it work.

Note: some of the modules used in this tutorial are still in flux. If the tools change, a future version of this tutorial may be released.


If you don’t yet have it installed, get the ilp-spsp tool. Make sure you have permissions to install global node modules.

npm install -g ilp-spsp

Creating an Invoice

In order to make a chunked payment, you need some system that tracks the progress of the chunked payment. We use special SPSP endpoints that represent invoices.

We’ve deployed a publicly available server that tracks invoices. Create an invoice by running the command below:

curl -X POST '' \
-H 'Content-Type:application/json' \
-H 'Authorization:Bearer test' \
--data '{"amount":"1000000","reason":"tutorial invoice"}'

You’ll get an SPSP payment pointer as a response. Copy it to your clipboard, because you’ll use it in the next sections.


Query the State of Your Invoice

You can verify the details of this invoice by using the ilp-spsp query command. Use the SPSP payment pointer that you copied in the last section.

ilp-spsp query --receiver '$'

Your response contains the usual information about how to reach the receiver, as well as information about how much of the invoice has been paid:

"destinationAccount": "test.amundsen.bmp.btp18q1...",
"sharedSecret": "QtCs7in15pyHvqzFnQliLiyV...",
"balance": {
"current": "0",
"maximum": "1000000"
"receiverInfo": {
"reason": "tutorial invoice"

The amount is denominated in micro-XRP, because this invoice server is connected to the testnet via XRP. That means you just created an invoice for 1 XRP.

Right now, 0 out of 1000000 µXRP have been paid.

Pay Your Invoice

It’s time to actually send a chunked payment. Use the SPSP payment pointer that you copied in the first section.

DEBUG=ilp* ilp-spsp invoice --receiver '$'

Congratulations! You’ve sent your first chunked payment.

This command produced a lot of output because it split your payment up into chunks and sent them all individually. The debug messages give you an indication of its progress.

You can query the state of your invoice again, to make sure that it was paid.

ilp-spsp query --receiver '$'

Despite the fact that the payment was split into pieces, it ended up with the exact correct amount.

"destinationAccount": "test.amundsen.bmp.btp18q...",
"sharedSecret": "z+8auUK0vzdnGRPM80FRpO...",
"balance": {
"current": "1000000",
"maximum": "1000000"
"receiverInfo": {
"reason": "tutorial invoice"

It shouldn’t be that surprising, if you think about it. The internet can split up an executable file and have it come out intact, so why can’t we do the same for a payment?

  • Try out some different amounts. How big of an invoice can you pay before you exhaust your liquidity?
  • Deploy your own instance of ILP SPSP Invoice Server.
  • Use the webhook functionality in the invoice server to create an ILP checkout.

Make sure to share your experience and ask questions in our Gitter!

Interledger Blog

Articles and tutorials from the Interledger community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store