# Allowance

> Consumer trust layer for AI agent payments. Allowance lets humans give AI assistants safe, limited, revocable spending power — without sharing their real card.

Allowance is pre-launch. The API is not yet active. All API endpoints return 501 Not Implemented. Discovery endpoints (listed below) are live and static.

## How it works

1. **Agent proposes a mandate.** The agent calls `POST /v1/mandates` with a suggested amount, merchant, and cadence. The mandate starts in `status: pending_approval`.
2. **Human approves the mandate.** The owner receives a notification and approves it out-of-band. The mandate becomes `active`. The agent polls `GET /v1/mandates/{id}` and waits — it never triggers this step.
3. **Agent requests a virtual card.** At purchase time, the agent calls `POST /v1/mandates/{id}/credential-requests`. The system automatically validates the request against the mandate rules (amount, merchant, MCC, time period). No human involvement at this step. If valid, a single-use virtual card (PAN, expiry, CVV) is returned. The agent uses these details at merchant checkout like a normal card number. Safety comes from the card being single-use, amount-capped, merchant-locked, and short-lived (~15 min) — not from hiding credentials.
4. **Mandate lifecycle.** For `cadence: "once"` (immediate) mandates, the mandate auto-moves to `exhausted` after the first credential is issued. For recurring mandates, the mandate stays active and the agent can request credentials on each cycle within the defined rules.

## Core concepts

- **Mandate** (`mnd_*`): A permission object. Defines budget (cadence, per-transaction cap, total cap), merchant/MCC restrictions, expiry. Created by the agent, approved by the human.
- **Mandate status**: `pending_approval → active → exhausted | expired | revoked`
- **Credential request** (`cr_*`): Agent's request for a virtual card at time of purchase. Auto-validated by the system against mandate rules.
- **Virtual card**: Single-use card (PAN, expiry, CVV) issued on approval. Used at merchant checkout like a normal card. Safety comes from single-use, amount cap, merchant lock, and ~15 min expiry.
- **Cadence**: `once | daily | weekly | monthly | annually | never`. `once` = single-use. `never` = lifetime cap that never resets.
- **Amounts**: Always integers in minor currency units (cents for USD). `47231` = $472.31. Never floats.

## API surface (pre-launch stubs)

All endpoints are under `https://api.useallowance.com/v1`. Auth: `X-Allowance-Key: alw_*` header.

- `POST /v1/mandates` — propose a spending mandate (starts pending_approval)
- `GET  /v1/mandates/{id}` — retrieve mandate; poll for status=active
- `POST /v1/mandates/{id}/credential-requests` — request virtual card (auto-validated, no human step)
- `GET  /v1/mandates/{id}/credential-requests/{cr_id}` — retrieve a credential request
- `POST /v1/mandates/{id}/revoke` — revoke a mandate immediately
- `GET  /v1/pricing` — pricing info
- `GET  /v1/status` — health check

Rate limits: 100 req/min standard, 10 req/min for `POST /v1/mandates/{id}/credential-requests`. Always set `Idempotency-Key` on credential requests.

## AP2 compatibility

Allowance is designed as a natural precursor to the [AP2 Agent Payments Protocol](https://ap2-protocol.org) (Google's open standard for agentic payments). The Allowance mandate maps directly to AP2's Intent Mandate (human-not-present scenario). In a future AP2-compatible version, the mandate will be a cryptographically signed Verifiable Digital Credential (VDC) and human approval will produce a non-repudiable cryptographic attestation. The same concepts and fields carry forward — no rearchitecture needed.

## Machine-readable endpoints (live now)

- MCP server manifest: https://useallowance.com/.well-known/mcp.json
- OpenAI plugin manifest: https://useallowance.com/.well-known/ai-plugin.json
- Capabilities registry: https://useallowance.com/.well-known/ai-capabilities.json
- OpenAPI 3.1 spec: https://useallowance.com/openapi.json
- System status: https://useallowance.com/status.json
- Pricing: https://useallowance.com/pricing.json

## Worked examples

Full mandate + credential request + virtual card for three scenarios:

- https://useallowance.com/examples/flight-booking.json — once mandate, immediate use, exhausts after first credential
- https://useallowance.com/examples/recurring-household-item.json — monthly recurring, single merchant, auto-validated
- https://useallowance.com/examples/subscription-renewals.json — monthly recurring, open merchant, MCC-locked

## Human-readable docs

- https://useallowance.com/agents — overview for developers and agents

## Contact

- Email: hello@useallowance.com
- Website: https://useallowance.com
- Stage: pre-launch, no live API