Artifact Content
Not logged in

Artifact d9ba10a644e9e735687360ca549d72642e5e5001:

title: HTTP-ILP

draft: 3


A standard for paid HTTP requests.

Design Goals

Design a protocol to pay for HTTP requests.



1. Setup


Ankita is a server admin who owns a file hosting service at myservice.example and would like to provide an API where her users can upload files without having to register first. In order to enable this in a standards-compliant way, she decides to use HTTP-ILP.

1.1. Server admin installs an ILP payment module

After deciding to use HTTP-ILP, Ankita searches the web on instructions on how to set this up. She finds an open-source HTTP-ILP server module which is compatible with the REST framework (Koa) that she is already using, for instance koa-ilp.

She installs the HTTP-ILP server module. The module provides middleware which she adds to the different API endpoints in order to set prices for each one.

According to the documentation of the HTTP-ILP server module, she learns that she can pass an Interledgerjs plugin to the module, to receive payments.

1.2. Server admin sets up a new receiver

Ankita creates a dedicated subaccount under her account at her Interledger service provider, and takes a note of that subaccount's credentials.

1.3. Server admin enters credentials into the HTTP-ILP server module config

Next, Ankita logs back into her server and edits a config file of the HTTP-ILP server module to enter the plugin type and credentials she obtained:

export PLUGIN_NAME=ilp-plugin-btp-client
export PLUGIN_CONFIG={"server":"btp+wss://"}

Next, she restarts her server to load the new configuration.

1.4. Paid HTTP server fetches receiver information

When the HTTP-ILP server module loads up, it calls plugin#connect so that the plugin gets a subscription to its ledger. Through this subscription, the plugin can listen for incoming payments. The module then uses plugin#getAccount to look up the Interledger address from the plugin and caches it in memory for a certain period.

This completes the setup process. The server is now ready to receive paid API requests.

2. Client interaction


Marat is a graphic designer who would like to upload a mockup image to share with a client. His friend recommended a tool which doesn't require any signup or configuration and uses his existing ILP account to pay for the storage and bandwidth fees.

Sequence Diagram

2.1. Client generates a server-specific token from the hostname and its local secret:

The uploader tool contains an HTTP-ILP client module like superagent-ilp or ilp-curl. This client module may for instance generate and locally save a client_secret using 256 bits of cryptographically secure randomness.

Before making the paid HTTP request, the HTTP-ILP client module generates a token, for instance using such a client_secret and the hostname of the server it is about to make a request to:

2.1. Client attempts to call API using token

The paid HTTP request is fired off:

OPTIONS /upload HTTP/1.1
Host: myservice.example
Pay-Token: 7y0SfeN7lCuq0GFF5UsMYZofIjJ7LrvPvsePVWSv450
Unhash-Content-Length: 123

Note that the client hasn't paid at this point and is only making the request to solicit a response from the server, that's why the OPTIONS verb is used. In this example, Unhash-Content-Length is an application-specific header which describes the request which the client intends to make.

2.2. Server responds with payment details

The server returns an HTTP code of 204 No Content and includes response headers showing the amount, an ILP address and a shared secret. The amount expresses how much the request would have cost, as a decimal string and counted in the base unit of the ledger to which the ILP address belongs.

HTTP/1.1 204 No Content
Pay: interledger-psk2 SkTcFTZCBKgP6A6QOUVcwWCCgYIP4rJPHlIzreavHdU 10
Pay-Balance: 0

The client can now use the shared secret to create a condition to pay this host. The shared secret may for instance be generated by the server as follows:

The shared_secret is now a shared secret between the client and server, but will be unknown to any third-party connectors between them.

2.3. Client initiates a PSK2 payment to refill its balance

In order to refill its balance, the client now creates a PSK2 payment with the following properties:

As the PSK2 payment progresses, the token's balance is increased.

2.6. Sender/client receives the fulfillment.

Once the payment is complete, the client will retry its original request:

POST /upload HTTP/1.1
Host: myservice.example
Pay-Token: 7y0SfeN7lCuq0GFF5UsMYZofIjJ7LrvPvsePVWSv450

The request succeeds:

HTTP/1.1 200 OK
Pay: interledger-psk2 SkTcFTZCBKgP6A6QOUVcwWCCgYIP4rJPHlIzreavHdU 10
Pay-Balance: 90

Notice how the 100 units credit from the payment was added to the balance and the 10 unit cost for the current request was subtracted.