HTTP-ILP allows you to pay for an HTTP call directly, without any registration or API keys. It lets you make paid APIs that anyone can use, and for which you receive your payment instantly. In this tutorial, you will:

Prerequisites

This tutorial assumes that you’re running Moneyd on your computer, and that it’s connected to the Interleger testnet.

If you’re not yet set up, it should only take a minute. You don’t need to register any accounts or use any cryptocurrency to use the Interledger testnet.

Use a Paid API

In order to interact with these paid APIs, you can use ILP Curl, a command-line HTTP client with support for Interledger payments.

Make sure that you have permissions to install node modules globally.

npm install -g ilp-curl
ilp-curl -X POST https://unhash.ilp-test.com --data "Hello World"

If it works, you’ll receive a response that looks like:

{
  "url":"https://unhash.ilp-test.com/a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e",
  "digest":"a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e"
}

You just used “Unhash,” which is an extremely simple paid API for hosting files. Unhash works similar to something like IPFS, where you can upload files and address them by their hash. With Unhash you upload files directly to the people hosting them, and you pay with Interledger instead of with a special token.

To see that your file was uploaded, you can run the curl command below, and see that the data you uploaded (Hello World) are still there.

curl "https://unhash.ilp-test.com/a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e"

Write a Paid API

There’s nothing special about Unhash. The module we used wasn’t specially purposed for it: it was just a generic HTTP client that comes with Interledger support.

There is a freely available node module that allow you to easily make your own paid API too. It’s called koa-ilp, and allows you to add payments as a middleware to any Koa application.

First, let’s set up the project for our paid API:

mkdir my-paid-api
cd my-paid-api
npm init
npm install --save koa koa-router koa-ilp ilp-plugin
vim index.js

Now in index.js, add the following code:

const Koa = require('koa')
const router = require('koa-router')()
const app = new Koa()

const KoaIlp = require('koa-ilp')
const plugin = require('ilp-plugin')()
const ilp = new KoaIlp({ plugin })

router.get('/', ilp.paid({ price: 100 }), async ctx => {
  ctx.body = 'Hello World!'
})

app
  .use(router.routes())
  .use(router.allowedMethods())
  .listen(8080)

We used ilp-plugin to get a connection to our local moneyd instance. Then we gave it to koa-ilp. The important part is this call:

ilp.paid({ price: 100 })

This call creates a Koa middleware that charges for this endpoint. The user must pay 100 base units of your moneyd’s currency, and then the route’s code will be run.

Start your application with:

DEBUG=ilp* node index.js

In a separate terminal, you can call into the paid API using ilp-curl again.

ilp-curl -X GET http://localhost:8080/

You’ll see that the server gets an ILP payment, and the client gets the response of “Hello World!” Congratulations: you’ve technically made a paid API.

Of course, the number of things you can payment-enable with this tecnique is unlimited. You can wrap any existing API and add a flat price, or you can make the price a function for more complex use cases. If you make anything, be sure to let us know in Gitter!