Machinomy

Machinomy is a Node.js library for micropayments in Ether over HTTP. It allows you to send and receive a minuscule amount of money instantly.

Web site: machinomy.com. Twitter: @machinomy. Support/Discussion: Gitter.

Documentation

The website contains Getting Started guide. It is more illustrative than instructions below.

Machinomy provides a simple JS API.

To run Machinomy against a local Ethereum test network, see the Running with Ganache CLI Guide.

Installation

$ npm install -g machinomy

Assumptions:

geth node runs on http://localhost:8545,
geth runs Ropsten network.

The library supports currently Ropsten network only. It is early days, we would like to avoid losses by mistake on your side. Ether on Ropsten cost nothing. One could get some from ZeroGox Faucet for free.

Set up

To only play with CLI a command below is enough:

$ machinomy setup

If you also intend to sell services via HTTP, set up "receiver" side:

$ machinomy setup --namespace receiver

Environment Variables

Machinomy can be configured on the CLI using a few environment variables. Specifically:

Variables	Use
`MACHINOMY_GETH_ADDR`	Tells the CLI where `geth`'s RPC server is running. Defaults to `http://localhost:8545`.
`MACHINOMY_SENDER_ENGINE`	Tells the CLI which database engine to use. Default to `nedb`, but can also be `mongo` or `postgres`.

Usage

Buy

$ machinomy buy http://playground.machinomy.com/hello

Buys a service provided by a respective endpoint. You could buy the service from JavaScript as well:

'use strict'

const machinomy = require('machinomy')
const uri = 'http://playground.machinomy.com/hello'

const settings = machinomy.configuration.sender()
machinomy.buy(uri, settings.account, settings.password).then(contents => {
  console.log(contents)
}).catch(error => {
  throw error
})

Sell

Machinomy allows you to sell a service over HTTP. The library provides Express middleware to abstract details of payment handling from the business logic.

A code like below runs on http://playground.machinomy.com/hello:

"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.use(bodyParser.json());
app.use(paywall.middleware());

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 ...`);
});

You could test it with machinomy buy command described above.

Contributing

Developers: Machinomy is for you. Feel free to use it, break it, fork it, and make the world better. The code is plain old JavaScript, no special skills required.

If you want to generate html documentation into "documentation" folder:

$ npm install -g typedoc
$ yarn build
$ typedoc --excludeExternals  --out ./documentation --ignoreCompilerErrors index.ts

Non-Developers: You are lovely. As a starter, help us spread the word! Tell a friend right now. If not enough, developers need flesh-world guidance. It starts with proper documentation and a pinch of fantasy. Really anything, whether it is a short post on a use case of IoT micropayments, addition to the documentation (code comments, yay!), or an elaborate analysis of machine economy implications. Do not hesitate to share any idea with us on Gitter.

License

Licensed under Apache License, Version 2.0.

API-market / machinomy