Getting Started

An idea behind Machinomy project is to allow any device to pay another device a minuscule amount of money over the internet. In short: to provide a viable means of exchange for machine economy. Current implementation is a Node.js package. It represents a somewhat constrained vision: allows a device to instantly pay a fraction of Ether over HTTP, no trust established. Actually, the device is a networked computer able to run geth and Node.js. A server or your laptop qualify, as well as Raspberry Pi board.

Paying over HTTP for service implies there is a buyer and a seller. As a simplification for future developments, buyer is called sender, and seller is named receiver in code.


$ npm install -g machinomy

Then set it all up using your ethereum account. By default, machinomy uses a current test network Ropsten to prevent erroneous expenditures. Console commands also assume you act on behalf of sender side.

For a receiver side provide an option -n receiver or --namespace receiver.

You could override any password provided here using environment variable, as will be shown below.


Now, after you set it up, start local geth instance on http://localhost:8545. For now, machinomy is not itself an Ethereum node. Then, issue machinomy buy command:

This goes to the server, gets the price and sends the money required. By the way it finds out there is no payment channel available, so it also opens a channel to send the money. For now, it suffices to say a payment channel is a way to securely transfer money off-chain. Details on that matter will be published later.

To override a password set in configuration file pass it in environment variable MACHINOMY_SENDER_PASSWORD. Optionally, you could enable verbose or debug logging:

LOG_LEVEL=verbose \
machinomy buy

A developer is free to use the underlying API. The console command serves illustrative purpose only. Below is a javascript file, that does the same as the command above:

"use strict";

const machinomy = require("machinomy");
const uri = "";

const settings = machinomy.configuration.sender();, settings.account, settings.password, function (err, contents) {
    if (err) throw err;


Machinomy integrates with Express providing a middleware to sell a service over HTTP. One needs to add few lines of code to a conventional Express application to accept payments.

"use strict";

const express    = require("express"),
      bodyParser = require("body-parser"),
      machinomy  = require("machinomy");

const BASE = "http://localhost:3000";

const settings = machinomy.configuration.receiver();
let paywall = new machinomy.Paywall(settings.account, BASE);

let app = express();

app.get("/hello", paywall.guard(1000, function (req, res) {
    res.write("Have just received 1000 wei.\n");
    res.end("Hello, meat world!");

app.listen(8080, function(_) {
    console.log(`Waiting at ${BASE}/hello ...`);

The middleware intercepts Payment header, and checks its contents (=token) against open channels. If the token is invalid or absent, the client is redirected to a payment gateway page and asked a specific amount to pay. Then the client sends the payment to the gateway, and gets back to the original URL, now with the token. The content is returned, as there is no middleware.

The middleware depends on geth instance running on http://localhost:8545. Also you need to provide details on account to accept payments to. To do that, run setup command for receiver side:

$ machinomy setup --namespace receiver

Otherwise the code runs on any machine just like any other NodeJS code, and is invisible to your application.

$ node server.js

Instead of putting a password in a configuration file in clear text, one could set it via environment variable MACHINOMY_RECEIVER_PASSWORD. Log level is adjusted via environment variable too.

LOG_LEVEL=verbose \
node server.js

You could test the server code above on your local machine by buying a service.


Payment channel transfers money off chain. At the end of the day a seller of the service would like to get the money, that is to move the money on chain or settle the channel. Seller of the service, that is receiver of the money, could settle the channel right away. There is a caveat. While settling the receiver sends a transaction to Ethereum network, and it costs some gas/ether. Currently, the cost of the settling transaction is under 0.002 Ether (65510 gas). Make sure you have at least 0.002 Ether on the receiver’s account.

Sender initiates channel setting. This signals the seller to settle the channel. The sender can not settle the channel right away. It would allow her to cheat by settling on a value less than sent one. The sender initiates channel settling by the same machinomy close command. The get the funds a receiver is expected to finish settle on her side.

Next Steps

Now play and build something. What you can do with micropayments is the most interesting thing now. Few ideas to foster your imagination:

Feel free to share your thoughts and questions on Gitter Chat, and follow on Twitter for updates.