CIcash

A budget you lend to an AI agent — not money you give it.

Bounded · expiring · revocable · auditable · worthless once stolen.

The unit of account is the CIcash. It is deliberately boring: if the unit appreciates, agents hoard it and the payment layer dies — that is Gresham's law, and it is how Bitcoin stopped being cash and became a thing people keep.

Two independent implementations, held to one published conformance suite. Python (stdlib only; cryptography optional for Ed25519) and JavaScript (node:crypto only, zero dependencies). They share no code.

pip install cicash          # Python
npm install cicash          # JavaScript

python3 demo.py                                  # the whole story in 10 scenes
python3 -m unittest discover -s tests -t .       # 56 tests
cd js && node --test test/*.test.mjs             # 24 tests
python3 tools/interop_check.py                   # python mints it, javascript spends it
bash examples/quickstart.sh                      # a real wallet in 4 commands
python3 examples/llm_budget.py                   # a real paid API, capped

What it's actually for today. There is no network of merchants accepting CIcash, so the use case that works right now is internal budget control — wrapping an API your agent already pays for. examples/llm_budget.py does exactly that with the Claude API: count_tokens and max_tokens give the worst-case cost before the call, response.usage gives the truth after it, and that gap is precisely what a hold is for. Reserve the ceiling, settle the actual, release the difference. An agent cannot overspend even on a call whose price isn't known yet.

🧭 docs/PROJECT_STATE.md — start here if you are picking this up: current state, which decisions are settled, and where the trapdoors are. 📄 OVERVIEW.md — the design note: the problem, what Bitcoin got right and wrong, the mechanism, the evidence, and what this is not. 🇹🇭 OVERVIEW.th.md — ฉบับภาษาไทย เข้าใจง่าย อ่านรวดเดียวจบ

The thesis

Bitcoin's key model is unlimited, eternal, irrevocable bearer authority in a single secret. That is safe for a careful sovereign and catastrophic in the hands of something that leaks its own context, retries in loops, and can be talked into things by a web page.

So this keeps Bitcoin's L0 philosophy — commitments that cannot be loosened, receipts anyone can verify, cost as the anti-spam mechanism — and inverts its key model completely.

Bitcoin failed as money not for technical reasons but because it optimised the wrong function: it maximised "nobody can stop or change this" and got a speculative asset. Optimise the same axis for agents and you get the same result. The function that matters here is bounded, revocable, auditable spending, which is nearly the opposite axis.

Related MCP server: lightning-mcp

Six invariants, each with a test that proves it

1. Delegation is a ratchet. Macaroon-style chain: sigₙ = HMAC(sigₙ₋₁, caveatₙ). The current signature is the key for the next link, so any holder can append a constraint offline — and nobody can remove one without the root key. No syntax in this system widens a budget. → test_removing_a_caveat_breaks_signature, test_widening_would_be_inert_even_if_forced

2. Attenuation is economic, not just syntactic. A payment debits every ancestor. An agent capped at 50 CIcash cannot mint ten 50-CIcash children. Rate limits attenuate the same way. → test_cannot_escape_parent_cap_by_forking_children, test_deep_chain_still_bound

3. A leaked token is worthless. Assume the agent leaks everything — logs, tracebacks, screenshots, the next model's training data. Spending needs a proof bound to this exact request, so a captured token cannot be replayed and a captured proof cannot be re-aimed. → test_leaked_token_without_secret_is_worthless, test_wrong_key_cannot_spend_a_valid_token

4. The agent never writes the amount or the payee. Both come from a quote the merchant signed and the ledger re-verifies. Prompt injection has nowhere to put the number. → test_payee_allowlist_blocks_injected_recipient, test_forged_quote_rejected

5. Retries are free — including across a crash. Agents retry. That is not a bug to be trained out of them. → test_same_idem_key_charges_once, test_idempotency_survives_restart

6. The cap does not tear under concurrency. 16 threads × 10 payments against one parent cap: exactly the cap is spent, never a micro-unit more. A cap that silently stops being a cap is worse than an outage. → test_parent_cap_holds_under_16_threads

The part that is genuinely AI-native

A human who gets declined asks a person. An agent that gets declined has three moves, and if the error does not say which one, it loops until the budget is gone:

except Denied as e:
    e.as_dict()
    # {'denied': 'RATE_LIMITED', 'action': 'RETRY_AFTER', 'retry_after': 12.4,
    #  'hint': 'you are looping faster than the grant allows; wait, or stop
    #           and re-read why you are repeating'}

RETRY_AFTER · REPLAN · ESCALATE. And balance() / can_afford() exist so the agent plans before acting rather than discovering its limits by hitting them.

Wallet has no set_budget, no raise_limit, no transfer_to. The API surface an agent can reach is deliberately unable to express "give me more."

Use it

Python

from cicash import Ledger, ci

led   = Ledger.sqlite("ac.db")
acme  = led.register_principal("acme-corp")
api   = led.register_merchant("api.search")

agent = acme.grant(
    budget   = ci(50),
    per_tx   = ci(5),
    rate     = {"max_count": 20, "max_amount": ci(10), "window_s": 60},
    ttl_s    = 24 * 3600,
    payees   = ["api.search"],
    purposes = ["research"],
)

receipt = agent.pay(api.quote(ci(2), "research"), idem_key="run1/step3")
sub     = agent.delegate(budget=ci(5), note="sub: summarise")   # offline, tighter only
acme.revoke(agent)                                               # kills sub too
led.audit_verify()

Any MCP agent

The model gets tools; the key stays in the server process. A credential that never enters a context window cannot leak out of one.

{"mcpServers": {"cicash": {
  "command": "python3", "args": ["-m", "cicash.mcp_server"],
  "env": {"CICASH_DB": "/abs/ac.db", "CICASH_WALLET": "/abs/wallet.json"}}}}

Tools: budget_check · budget_quote · budget_pay · budget_delegate · budget_receipts. There is deliberately no tool that widens a budget.

Any language, over HTTP

python3 -m cicash.cli --db ac.db serve      # 127.0.0.1:8402

402 budget · 401 proof · 403 revoked · 429 rate (with Retry-After). HTTP has had a code meaning "you must pay to proceed" for thirty years and it went unused because humans were never the ones being metered. Agents are.

Operator CLI

cicash --db ac.db grant --budget 50 --per-tx 5 --payees api.search --out wallet.json
cicash --db ac.db balance --wallet wallet.json
cicash --db ac.db revoke  --wallet wallet.json
cicash --db ac.db audit

Interoperability

Neither package is the standard — spec/SPEC.md is, and spec/vectors.json pins caveat serialisation, both signature chains, lineage derivation, the request string, quote signing, and the receipt chain. Reproduce the vectors in any language and you interoperate.

tools/interop_check.py proves the stronger claim: Python mints a wallet, JavaScript verifies it, signs a payment against it, and delegates a tighter child wallet entirely offline — then Python settles both and confirms the ancestor debit crossed the language boundary. CI runs it on every push, alongside a guard that fails the build if the vectors drift from their generator.

Writing the second implementation is also what hardened the format. It found two bugs that fail silently — a token that simply stops verifying on the other side of the wire, with nothing to point at:

• Python renders an integral float as 1800000000.0; JavaScript renders 1800000000. No float may appear in a signed structure, and encoders now reject one rather than guess (SPEC §2.1).

• Python escapes non-ASCII by default, JavaScript does not. A budget note in Thai would have broken cross-language verification. Raw UTF-8 is normative (SPEC §2.2), and the vectors carry a non-ASCII case.

That is the argument for a second implementation in general: the first one cannot tell you which of its choices were decisions and which were defaults.

What this is still not

Stated plainly, because a payment library that oversells itself is worse than none:

• No L0. Nothing settles to a real asset. Receipts are the netting input; the settlement leg is not written.

• No privacy layer. The ledger sees every payment. Auditable to the principal, private to the world needs blinding this does not have.

• No dispute layer. The design calls for finality to the seller with recourse handled off the payment path. Not built.

• Trusts its clock. Expiry and rate windows are only as good as time.time().

• Not audited. The cryptographic construction is standard (HMAC chain, Ed25519, SHA-256), but no third party has reviewed this. Treat v0.2 as a working reference implementation of a design, not as something to put real money behind today.

Next

1. Netting + settlement to a stable unit

2. Blinded receipts

3. Dispute layer off the payment path — finality for the seller, recourse for the principal, which is the trade Bitcoin never made and cards made backwards

4. A Go implementation against the same vectors — the JavaScript one took an afternoon and paid for itself twice over

Releasing

pip install cicash · npm install cicash · both reached through OIDC trusted publishing, so no PYPI_TOKEN and no NPM_TOKEN secret exists anywhere. Cutting a release is a tag push; see PUBLISH.md.

That is the same argument this library makes. Releasing it on a permanent bearer token pasted into a config would have been a poor look.

Apache-2.0. See CHANGELOG.md for what changed in 0.3, including two breaking wire-format fixes.