Toll

Server

Two servers speak the same /v1 API. Node is the published package @lessspam/server at version 0.1.0. PHP is the Toll\Protocol library shipped inside the WordPress plugin (GPL-2.0-or-later), under lib/server-php. That library is not a separate package on a public PHP registry.

Reads stay free. A write with no pass gets 403 and toll_required. The pass cookie is toll_pass. The header is Authorization: Toll.

No real money moves on the self-hosted server's stub backend.

The hosted demo at lessspam.dev charges real money: a write is 10,000 msat, paid with Cashu through the Minibits mint or with a BOLT11 mint quote (L402_ENABLED is 1). Search, account, and admin on that worker are 2,000, 25,000, and 100,000 msat. That site also serves POST /v1/demo/agent. An unpaid post gets the payment offer. A paid post gets a pass. /.well-known/toll.json names that URL as pay. A plain post to the demo form still gets the work check.

Node

npm install @lessspam/server@0.1.0 express

secret in the config is at least 16 characters. Put it in the environment. Do not commit it.

site_id: site_abc123
secret: env:TOLL_SECRET
issuer_public_url: http://127.0.0.1:8787
routes:
  - { prefix: "/", class: read }
  - { prefix: "/contact", class: write }

The / route keeps every page view free. A route's class applies to writes under that prefix.

import express from "express";
import { Toll, loadConfig } from "@lessspam/server";

const toll = Toll.create(loadConfig("toll.yaml"));
const app = express();
app.use(Toll.router(toll));
app.post("/contact", Toll.middleware(toll, { action: "write" }), (req, res) => {
  res.status(200).json({ ok: true });
});
app.listen(8787);

Toll.router() serves /v1 and the widget files. Toll.middleware() checks the pass before your handler runs.

Behind a reverse proxy, list it in the TOLL_TRUSTED_PROXIES environment variable (comma-separated addresses and ranges). Toll does not read the framework's proxy setting.

PHP

From a checkout, run composer install in packages/server-php, then load vendor/autoload.php. Inside the plugin zip the same library is lib/server-php.

<?php
require __DIR__ . '/vendor/autoload.php';

use Toll\Protocol;

$claims = Protocol::verifyPass($secret, $pass, time(), $siteId, 'write');

A bad pass throws Toll\TollError. The WordPress plugin is the PHP issuer: the same routes live under /wp-json/toll/v1/. On a theme form, call toll_gate_verify_request('write') before handling the post. The WordPress page covers that.

/v1 API

GET /.well-known/toll.json and GET /.well-known/agents.json are free. They describe the write check. They do not identify the caller.