nano-empire-tollbooth 0.3.0

Monetize any Python function with one decorator. Unlimited paper-mode metering, a one-time upgrade prompt around call 100, local ledger, signed receipts; Pro adds CSV/JSON export, higher caps, and CLI tools.

nano-empire-tollbooth

Monetize and meter any Python function with one decorator.

from nano_empire_tollbooth import monetize

@monetize(price_usd=0.01)
def summarize(text: str) -> str:
    return my_llm(text)

Every call is metered and logged to a local JSONL ledger. Paper-mode metering is unlimited and free — a one-time upgrade prompt prints around call 100, and the function keeps working (it nags, it does not block).

Install

pip install nano-empire-tollbooth

Python 3.9+, one dependency (pydantic).

Command line

The package ships a tollbooth command that works over your local ledger:

tollbooth status                 # show tier (free/pro) and a ledger summary
tollbooth report                 # aggregate: calls, spend, by status
tollbooth report --json          # same, machine readable
tollbooth verify                 # integrity check of the ledger file
tollbooth export --format csv    # export the ledger (Pro)
tollbooth settle                 # batch-net released tolls into one charge-sized settlement (paper mode; --live fails closed until you wire your own rail)

Free vs Pro

What Pro actually unlocks today. No overstated claims.

	Free	Pro ($19/mo)
Metered calls	Unlimited (paper mode)	Unlimited (paper mode)
Local JSONL ledger	Yes	Yes
report and verify	Yes	Yes
Upgrade prompt	Shown after 100 calls	Suppressed
tollbooth export (CSV/JSON)	No	Yes
Default daily cap	$10 / agent	$1000 / agent

Pro is in private setup and not yet purchasable. The licensing pipeline (Ed25519-signed keys + checkout issuance) is built and tested but not wired live yet — so there's no buy link here on purpose. Watch the repo for availability.

When you have a key, activate it with:

export TOLLBOOTH_LICENSE_KEY=your-key

License validation is a real offline check: each key carries an Ed25519 signature from the issuer plus an expiry, verified locally with the published public key — no secret, no phone-home. A random, tampered, or expired key does not unlock Pro. Online revocation before expiry is on the roadmap.

Live settlement (experimental)

The tollbooth includes an x402 hook so you can wire your own live settlement verifier:

from nano_empire_tollbooth import Tollbooth, TollboothConfig

booth = Tollbooth(TollboothConfig(paper_mode=False))

async def my_verifier(wallet, tx_signature, amount_usd):
    # verify a real on-chain or off-chain payment, return True/False
    return await check_payment(wallet, tx_signature, amount_usd)

booth.set_x402_verifier(my_verifier)

This ships the escrow lifecycle (lock, release, refund) and the verifier hook. It does NOT include a hosted settlement backend. Connecting real funds is your responsibility and is on the project roadmap. This is informational and not financial advice.

How metering works

1. Decorate any sync or async function with @monetize(price_usd=...).
2. Each call writes a record to logs/toll_ledger.jsonl with a settlement hash.
3. In paper mode (default) nothing is charged. Set paper_mode=False plus your own verifier to move real funds.

License

MIT