Get started¶
This guide walks through the full example of the ritta library: create keys, build a mandate, sign it and verify a payment against it. You need Python 3.12 or newer.
Install¶
pip install ritta
The full example¶
from ritta import Limits, Mandate, Scope, generate_keypair, sign, verify
private_key, public_key = generate_keypair()
mandate = Mandate(
issuer="did:web:farmacia-central.com.ar",
subject="agent:compras-01",
limits=Limits(total=15_000_000, per_operation=5_000_000, currency="ARS"), # cents
scope=Scope(merchants=["MP-123456"], categories=["pharmacy"]),
hitl_threshold=1_000_000, # from $10,000 a human must approve (enforced by the gateway)
state="open",
expires_in_days=30,
)
token = sign(mandate, private_key) # SD-JWT signed with Ed25519
result = verify(
token,
public_key,
amount=120_000, # in cents; comes from the merchant catalog, never from the model
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000, # unspent balance, supplied by the gateway ledger
)
assert result.ok
Now, step by step.
1. Create the keys¶
private_key, public_key = generate_keypair()
generate_keypair() creates an Ed25519 key pair. The private key stays with whoever authorizes the spending (a person or a company) and is used to sign mandates. The public key is shared with whoever has to verify payments.
2. Build the mandate¶
mandate = Mandate(
issuer="did:web:farmacia-central.com.ar",
subject="agent:compras-01",
limits=Limits(total=15_000_000, per_operation=5_000_000, currency="ARS"),
scope=Scope(merchants=["MP-123456"], categories=["pharmacy"]),
hitl_threshold=1_000_000,
state="open",
expires_in_days=30,
)
The mandate is the permission: "this agent may spend up to X, on Y, on behalf of Z".
issuer: who authorizes. A DID (did:...) or anhttps://...URL.subject: the authorized agent.limits: how much it may spend in total and at most per operation, and in which currency. Amounts are always integers in the currency's smallest unit (cents):15_000_000is $150,000.scope: which merchants and categories it may spend on.hitl_threshold: from which amount a person must approve. In this example, from $10,000. The library does not enforce this rule; the gateway does.state:openis an open budget;closedis a mandate tied to a specific checkout.expires_in_days: how many days the mandate is valid.
3. Sign¶
token = sign(mandate, private_key)
sign returns the signed mandate as text: an SD-JWT with an Ed25519 signature. That text is what travels with the agent. If anyone changes a single character, the signature is no longer valid.
4. Verify a payment¶
result = verify(
token,
public_key,
amount=120_000,
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000,
)
assert result.ok
Before every payment, verify checks that the signature is valid, that the mandate has not expired, that the amount is within the per-operation cap and the remaining balance, and that the merchant and category are allowed.
amount: the payment amount, in cents. It must come from the merchant catalog, never from what the language model says.remaining: the unspent balance of the mandate. The gateway ledger supplies it; the library just receives the value.
5. When a payment is not authorized¶
If the payment is not authorized, result.ok is False and result.reason says why. For example, a $60,000 payment exceeds the $50,000 per-operation cap:
result = verify(
token,
public_key,
amount=6_000_000,
merchant="MP-123456",
category="pharmacy",
remaining=15_000_000,
)
assert not result.ok
assert result.reason == "amount_over_per_operation"
The possible reasons are:
| Reason | Meaning |
|---|---|
malformed |
The token is not in the expected format or is missing required data. |
invalid_signature |
The signature does not match the public key, or the token was modified. |
expired |
The mandate has expired. |
amount_over_per_operation |
The amount exceeds the per-operation cap. |
amount_over_remaining |
The amount exceeds the remaining balance. |
merchant_not_allowed |
The merchant is not in the allowed list. |
category_not_allowed |
The category is not in the allowed list. |
If there is more than one problem, the first one in this order is reported. Details are in the specification.
Verification without surprises¶
verify is pure: no network, no state. Same input, same output. To pin the clock (for example, in tests), pass now= with a timezone-aware datetime.
Storing keys¶
Keys are exported and imported as PEM with ritta.mandates.private_key_to_pem, public_key_to_pem, load_private_key_pem and load_public_key_pem.
Protect the private key
Never store a private key in the repository. Whoever holds that key can sign mandates on your behalf.