Skip to content

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 an https://... 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_000 is $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: open is an open budget; closed is 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.