Metadata-Version: 2.4
Name: mandata
Version: 0.3.0
Summary: The mandate toolkit for agent-initiated payments
Author-email: Shedrack Chiedozie Aji <shedrack.aji@doztra.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/ashedrack/mandata
Project-URL: Documentation, https://github.com/ashedrack/mandata/tree/main/docs
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynacl>=1.5
Dynamic: license-file

# Mandata

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ashedrack/mandata/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ashedrack/mandata)

**The mandate toolkit for agent-initiated payments.**

When AI agents hold spending authority, someone must answer: *what exactly are they allowed to do — and can you prove it afterward?* Mandata is a reference implementation of the bounded-autonomy mandate chain:

**principal → agent → credential → transaction → evidence**

## The problem

Agentic payment protocols (AP2, x402, card-network agent programs) let AI agents initiate real financial transactions. But production systems lack a standard way to:

- **Express mandates** — bounded permissions: amounts, payees, time windows, velocity limits
- **Bind credentials** — cryptographic proof a transaction was made within mandate
- **Enforce at the gate** — deterministic checks *before* settlement, not logs after
- **Produce evidence** — an auditable chain showing every agent action against its mandate

Mandata formalizes all four as a small, dependency-light library.

## Quickstart

```bash
pip install mandata
```

```python
from mandata import Mandate, Bounds, enforce

# A principal grants a bounded mandate to an agent
mandate = Mandate(
    principal="user:alice",
    agent="agent:shopping-bot",
    bounds=Bounds(
        max_amount=500.00,          # per transaction
        currency="GBP",
        allowed_payees=["store.example"],
        expires_in_days=30,
        velocity_limit=3,           # max transactions per day
    ),
)

# At transaction time: deterministic enforcement BEFORE settlement
decision = enforce(mandate, payee="store.example", amount=49.99)
assert decision.allowed          # → True
print(decision.check)            # → "WITHIN" (normative MMF check ID)
print(decision.evidence)         # → hash-chained evidence record of the check
```

## Architecture

```
principal issues mandate ──► credential binds mandate to agent
        │                           │
        ▼                           ▼
  agent proposes transaction ──► mandate gate (enforce())
        │                           │
        ▼                           ▼
   allowed? ──► yes: execute    no: reject
        │                           │
        └───────► evidence record appended (hash-chained audit log)
```

See [`docs/architecture.md`](docs/architecture.md) for the full model, [`docs/mandate-model.md`](docs/mandate-model.md) for the schema, and [`docs/diagrams.md`](docs/diagrams.md) for the system design diagrams.

## Roadmap

- [x] **v0.1** — Mandate model, bounds enforcement, evidence chain (Python)
- [x] Credential signing (Ed25519) + verification API
- [x] Revocation registry (mandate kill-switch at transaction speed)
- [x] AP2 / x402 / LangChain adapter layer
- [x] Multi-hop delegation (agent → sub-agent mandate weakening)
- [x] **v0.3** — [MMF-v0.2](spec/mmf-v0.2.md): credential-bound gate, chain-wide delegation enforcement, fail-closed registry, canonical evidence hashing, 43 conformance vectors
- [ ] TypeScript implementation (core gate scaffold only — not yet MMF-v0.2 conformant)

## Research

This project is the open-source implementation arm of the survey:

> *Agentic AI in Payments and Financial Transactions: A Survey of Architectures, Safeguards and Open Problems* — S.C. Aji, 2026. [doi:10.13140/RG.2.2.13674.89288](https://doi.org/10.13140/RG.2.2.13674.89288)

## Contributing

We welcome contributors — see [CONTRIBUTING.md](CONTRIBUTING.md). Good entry points are labelled [`good first issue`](https://github.com/ashedrack/mandata/labels/good%20first%20issue).

## License

Apache-2.0 — see [LICENSE](LICENSE).

## Demo app

`examples/demo_app.py` runs a full simulated deployment over real HTTP — a
revocation-registry service, a mock payment rail, and an agent whose every
proposed payment goes through the gate: signed credentials, sub-agent
delegation, x402 intake, compromise attempts, remote revocation, then a full
evidence-chain audit. `python examples/demo_app.py` — stdlib only.

For a shorter single-process walkthrough see `examples/end_to_end.py`.

