API payment protocol


Our users may not know they are using your service.

Possible protocol

Let’s say we have an ElectrumSV user Alice, and she is using a hosted service which is perhaps providing her with some useful data she is blissfully unaware of. She has a petty cash balance in the wallet, which the wallet can use to operate services like this on her behalf without her permission. There are of course expectations on her part like not wanting to overpay for use of services, but she generally accepts there will be an ongoing cost in the form of micropayments or nanopayments.

Service discovery

The wallet knows that the services it uses have a standard API, and one of these is a service discovery endpoint. From this it identifies that it supports a useful endpoint it needs, it also identifies the pricing policy. For a data search/processing endpoint, this may be dependent on the CPU used and bandwidth consumed. For an endpoint which retains data on the user’s behalf this may indicate how much they need to pay to retain data until a given expiry date based on how much data they have stored. And there may even be one off cost endpoints, like reservation of a Paymail identity.

Unfunded anonymous access

Perhaps the wallet attempts to use an expected endpoint the service just happens to support, and has not engaged in service discovery to either find it and or gauge the cost. It gets back a 402 “payment required” response with attached metadata pointing to the service discovery endpoint.

Establishing funding

The wallet invisibly creates an account with the service in a deterministic way where it can identify if it has an account in future without requiring a password. It gives a prefunding transaction to the service and gets back an API key.

API usage

The wallet now makes requests with the API key. The service returns the charges for each request in the response headers, and the wallet should be able to use these to gauge the balance of the channel.

Channel management

So let’s try to build a picture of how the channel is managed.

Channel operation

So in theory, the channel should be managed as such:

  1. The wallet creates a non-final prefunding transaction.
  2. The service runs a spent balance ideally less than or equal to the current prefunding.
  3. Each request from the wallet is accounted to the spent balance and a receipt returned in the response. If there are insufficient funds to complete the request, it may incur a 402 response or interrupt any streamed data.
  4. When the wallet wishes to finalise the prefunding transaction, it does so through an API on the hosting service.
  5. If the last prefunding transaction is finalised, the wallet needs to create a new one. This will ideally happen before the previous funding is completely spent to avoid 402 or more ambiguous interrupted responses.

More bits and pieces

Multiple balances?

If the Alice has backups on a hosting service and wants to have a minimum period of retention for the amount of data they have stored, she will probably want to have a guarantee of retention. She would likely not want the backup balance to be mixed with the general API usage balance. She needs to see that she has 3 months before she loses her backups, not to see it jump around. And she might want to know she can be away for 2.5 months, before she has to worry about adding more funding for the data retention. This suggests that either she might have to prepay for that data retention.

Service discovery

From ElectrumSV’s perspective we want programmatic API discovery and programmatic pricing discovery. If there are standard endpoints that are expected on a service’s API, of which only some might be supported, then we want to know which are supported. Rather than trying all the endpoints we are interested in, it is better to have a centralised API discovery endpoint.

Final thoughts

The above is solid enough that we can take it and build it. But it is not yet implemented and it is only being thought out to prove ElectrumSV has a model that can work for now. We will likely polish this potential solution and see how well it works when we get our other ducks in a row and are ready to implement it.



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