Everything an agent needs to spend safely.

Quickstart

Propose a payment. The response tells you the outcome and every reason behind it, in the same request — an agent should never have to poll to find out whether it is allowed to act.

curl -sX POST "$PAYGENTE_API/api/v1/mandates" \
  -H "content-type: application/json" \
  -H "idempotency-key: run-2026-04-01-0031" \
  -H "x-paygente-user: elena" \
  -d '{
    "agentId": "agt_01JQ…",
    "recipientId": "rcp_01JQ…",
    "asset": "EURC",
    "amount": "75.00",
    "purpose": "Extended dataset licence"
  }'

{
  "mandate": {
    "id": "mnd_01JQ…",
    "status": "PENDING_APPROVAL",
    "statusLabel": "Waiting for approval",
    "requiresApproval": true,
    "simulated": true
  },
  "decision": {
    "outcome": "REQUIRE_APPROVAL",
    "engineVersion": "policy-engine@1.0.0",
    "reasons": [{
      "code": "AMOUNT_REQUIRES_APPROVAL",
      "message": "€75.00 EURC is at or above the €40.00 EURC threshold, so a person has to approve it."
    }]
  },
  "url": "https://paygente.com/app/mandates/mnd_01JQ…"
}

The full machine-readable contract is at /openapi.json. The identity header is a sandbox development shim, not a credential — see the boundary.

Concepts

Five objects. The mandate is the one that matters; the rest exist to bound it.

Mandate lifecycle

Transitions are enforced in the domain layer. An interface cannot talk a mandate into a state the state machine refuses, because every interface calls the same function.

DRAFT             → PROPOSED, REVOKED, EXPIRED
PROPOSED          → EVALUATING, REVOKED, EXPIRED
EVALUATING        → BLOCKED, PENDING_APPROVAL, APPROVED, EXPIRED
PENDING_APPROVAL  → APPROVED, REJECTED, REVOKED, EXPIRED
APPROVED          → EXECUTING, REVOKED, EXPIRED
EXECUTING         → COMPLETED, FAILED
FAILED            → EXECUTING, REVOKED, EXPIRED

BLOCKED · REJECTED · COMPLETED · REVOKED · EXPIRED   terminal

Guarantees

• A blocked mandate cannot execute. A policy denial is permanent for that mandate.
• A rejected mandate can never be approved later.
• An expired mandate cannot execute, even if it was approved before it expired.
• A completed mandate cannot be revoked.
• A revoked mandate cannot execute.
• Nothing executes while the organization kill switch is active.
• A mandate executes at most once. The state machine, a row lock, a database partial unique index and the rail’s own idempotency each refuse a second payment independently.
• An approval cannot be submitted by a role that does not hold the permission.

Budget is reserved at approval

An approved mandate consumes its amount against the daily and monthly limits immediately, before it executes. If only completed payments counted, ten mandates could each individually pass the same daily limit and then all execute — the limit would be checked ten times and honoured zero. Budget is released when a mandate fails, expires or is revoked.

Policy engine

A pure TypeScript function. No I/O, no randomness, no clock of its own, and no language model. The same inputs always produce the same decision, and the inputs are snapshotted with the result — so a decision made in April can still be re-explained in October, even if the policy has changed since.

type PolicyDecision = {
  outcome: "ALLOW" | "REQUIRE_APPROVAL" | "DENY";
  reasons: Array<{ code: string; message: string }>;
  appliedPolicyId: string | null;
  engineVersion: string;
};

NO_POLICY_ASSIGNED            AMOUNT_NOT_POSITIVE
EXECUTION_DISABLED            AMOUNT_EXCEEDS_MAX_TRANSACTION
AGENT_NOT_ACTIVE              AMOUNT_REQUIRES_APPROVAL
ASSET_NOT_ALLOWED             DAILY_LIMIT_EXCEEDED
ASSET_NOT_SUPPORTED_BY_…      MONTHLY_LIMIT_EXCEEDED
RECIPIENT_NOT_VERIFIED        EXPIRY_IN_PAST
RECIPIENT_NOT_APPROVED        MANDATE_DURATION_TOO_LONG
RECIPIENT_INACTIVE            RECURRING_NOT_ALLOWED
RECIPIENT_RISK_TOO_HIGH       RECIPIENT_FIRST_TIME_NOT_ALLOWED
WITHIN_POLICY

Every rule runs on every evaluation. The engine does not stop at the first problem, because a requester deserves the full list rather than discovering it one round trip at a time. The outcome is the most restrictive severity among the reasons produced, so adding a rule can never accidentally loosen a decision.

Policy limits are compared against the mandate amount without currency conversion. Paygente holds no exchange rate and implies none: a policy permitting more than one asset applies the same numeric limit to each.

Money

There is no code path in Paygente where an amount becomes a floating-point number. Amounts are integer minor units — for EURC and USDC that is 1e-6 of one token, matching the on-chain contracts.

"money": {
  "asset": "EURC",
  "amountMinor": "75000000",
  "amount": "75.000000",
  "amountDisplay": "€75.00 EURC"
}

{ "asset": "EURC", "amount": "75.00" }

// Accepted:  "40"  "40.5"  "0.000001"
// Rejected:  "1,000.00"   thousands separator
//            "1e3"        exponent notation
//            "€40"        currency symbol
//            "1.0000001"  more precision than the asset has

Parse amountMinor as a big integer — it is the authoritative value. Display values truncate rather than round, so a rendered amount can never read as more than what was actually authorised.

Idempotency

Send an Idempotency-Key header on every mutating request. A timeout is indistinguishable from a failure, so clients retry; without a key, a retried execute would be a second payment.

• Same key, same body → the original result is replayed.
• Same key, different body → 409 idempotency_key_reused. Silently accepting it would lose one of the two requests without anyone noticing.
• Uniqueness is a database constraint, not a read-then-write, so two concurrent retries cannot both pass the check.

Error codes

Every error has the same shape. No stack trace, no SQL and no driver message ever crosses the boundary; the correlation id locates the server log entry and the audit records that share it.

{
  "error": {
    "code": "invalid_state_transition",
    "message": "This payment was blocked by the spending policy and cannot be approved or executed.",
    "details": [],
    "correlationId": "cor_01JQ8F7Z9K3M4N5P6Q7R8S9T0V"
  }
}

Regulatory boundary

Paygente Phase 1 is software only. Being precise about this is not a disclaimer; it is a description of what the code does.

This release contacts no blockchain and no payment provider. Every transaction is executed by a deterministic mock rail and every mandate and payment attempt is returned with "simulated": true. Paygente is not licensed, regulated or approved, and makes no claim to be. Future production execution is intended to be delegated to licensed CASP, EMI, card-issuing or payment partners through adapters that sit behind the same interface the mock implements today.

Glossary

Mandate

A bounded permission to make one payment. The primary product object.

Principal

The organization on whose behalf an agent acts.

Policy

The closed rule set that bounds an agent’s authority.

Rail

The system that actually moves value. Paygente authorises; a rail executes.

Kill switch

An organization-wide stop on all new executions.

Correlation id

One identifier following a request from the HTTP boundary through the domain into every audit event it produced.

Reconciliation

Comparing what a rail actually did against what the mandate authorised.

Minor units

The smallest indivisible unit of an asset. 1e-6 of one token for EURC and USDC.

CASP

Crypto-Asset Service Provider — a licence category under the EU MiCA regulation.

EMI

Electronic Money Institution — a licence category for issuing e-money and holding client funds.

MCP tools and authorization boundaries →