# Paygente

> The financial control plane for AI agents. An agent requests a purchase, a
> deterministic policy engine decides whether it is permitted, a person approves
> it when the policy says a person must, and an execution rail carries it out
> exactly once.
>
> Shadow Mode records what the policy would have decided without deciding it:
> no payment, no approval request, no budget consumed, and no path from a
> shadow decision to an executed payment.

Tagline: The financial control plane for AI agents.
Product: Agents request. Paygente decides. Payment rails execute.

## Status: sandbox

This release is a software-only sandbox. It:

- holds no customer funds and custodies no private keys;
- contacts no blockchain, no payment provider and no card issuer;
- issues no cards and executes no regulated transfers;
- performs no KYC, KYB or final sanctions screening;
- is not licensed, regulated or approved, and claims none of those things.

Every payment is executed by a deterministic mock rail. Every mandate and
payment attempt is returned with `"simulated": true`. Do not present a
Paygente result as evidence that money moved.

Production execution is intended to be delegated to licensed CASP, EMI,
card-issuing or payment partners through adapters. Those adapters are
documented but not built.

## How to integrate

Two equivalent interfaces, validated by the same schemas and decided by the
same engine:

- REST API: https://api.paygente.com/api/v1 — contract at https://app.paygente.com/openapi.json
- MCP server: six tools, described at https://app.paygente.com/mcp

## Core concepts

- **Mandate** — the primary object. A bounded permission to pay: one agent, one
  recipient, one amount, one asset, one stated purpose, one expiry. Not a
  wallet and not a card.
- **Spend request** — a purchase an agent asks about. Paygente records what the
  policy would have decided and everything it was decided against. Nothing is
  paid, ordered or reserved, no approver is asked, and no budget is consumed.
  A spend request never becomes a mandate; there is no field or column that
  could link one to the other.
- **Agent** — a named principal that may propose payments. Registering an agent
  grants no authority and returns no credential.
- **Recipient** — a destination a payment may reach, carrying a verification
  status and a risk classification that the policy engine reads.
- **Policy** — a closed set of rules that bound an agent: maximum per payment,
  daily and monthly totals, allowed assets, approved recipients, the human
  approval threshold, the maximum mandate duration, and whether first-time
  recipients and recurring payments are permitted. A policy is data. There is
  no expression language and no way for a policy to execute.
- **Approval** — a person's decision on a mandate that the policy escalated.
  One decision per mandate, and the proposer cannot be the approver.
- **PaymentAttempt** — one execution of a mandate against a rail, recording
  what the rail actually did and whether it matched what was authorised.

## Mandate lifecycle

DRAFT → PROPOSED → EVALUATING → { BLOCKED | PENDING_APPROVAL | APPROVED }
PENDING_APPROVAL → { APPROVED | REJECTED | REVOKED | EXPIRED }
APPROVED → { EXECUTING | REVOKED | EXPIRED }
EXECUTING → { COMPLETED | FAILED }
FAILED → { EXECUTING | REVOKED | EXPIRED }

Terminal: BLOCKED, REJECTED, COMPLETED, REVOKED, EXPIRED.

Invariants enforced in the domain layer, not only in the interface:

- A blocked mandate cannot execute.
- A rejected mandate cannot be approved later.
- An expired mandate cannot execute, even if it was approved.
- A completed mandate cannot be revoked.
- A revoked mandate cannot execute.
- Nothing executes while the organization kill switch is active.
- A mandate cannot execute twice.
- An approval cannot be submitted by an unauthorized role.

## What an agent may and may not do

An agent may: list agents, list approved recipients, read a mandate, list
pending approvals, and propose a payment.

An agent may never: approve, reject, revoke or execute a mandate; change a
policy; or touch the kill switch. This is not a matter of which tools are
offered — the agent permission set does not contain those permissions, and
every operation checks it. Persuading an agent cannot grant it authority,
because persuasion is not how authority is granted here.

## Money

Amounts are integer minor units. They are never JSON numbers. Every amount is
returned three ways:

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

Parse `amountMinor` as a big integer. Requests send `amount` as an exact
decimal string: "40" or "40.50", with no separators, symbols or exponents.

## Error codes

validation_failed (400), unauthenticated (401), forbidden (403),
not_found (404), conflict (409), invalid_state_transition (409),
idempotency_key_reused (409), execution_disabled (409), policy_denied (422),
rate_limited (429), rail_failure (502), internal_error (500).

Errors are structured: `{ "error": { code, message, details[], correlationId } }`.
A resource belonging to another organization returns 404, identically to one
that does not exist.

## Idempotency

Every mutating request accepts an `Idempotency-Key` header. The same key with
the same body replays the original result. The same key with a different body
is a 409. Retrying an execute call cannot produce a second payment.

## Links

- Documentation: https://app.paygente.com/docs
- OpenAPI: https://app.paygente.com/openapi.json
- MCP tools: https://app.paygente.com/mcp
- Security and threat model: https://app.paygente.com/security
- Sandbox application: https://app.paygente.com/app