Intents

Ein Intent ist eine Deklaration was ein Agent zahlen will, wie viel und an wen. Policy-Engine und Risk-Engine bewerten jeden Intent bevor er settlen kann. requireIntent ist eine der Sacred Invariants — niemals stillschweigend abgeworfen, niemals umgangen.

Das Intent-Modell

Feld	Beschreibung
`id`	`int_*`
`agentId`	Owning Agent
`cardId` / `cardName`	Welche Karte zu belasten — genau eines davon
`purpose`	Freitext — sichtbar in Audit und Dashboard
`expectedAmountEuros`	Optional aber stark empfohlen
`expectedMerchant`	Optional aber stark empfohlen
`recurring`	Optional — `cadence` (`daily`/`weekly`/`monthly`/`yearly`) + Toleranz-Windows
`clientIntentId`	Optionaler client-seitiger Dedupe-Key
`ttlMinutes`	Default 24h, max 30 Tage (`43200`)
`status`	FSM (siehe unten)

Lebenszyklus (FSM)

pending_approval → approved | denied | expired | cancelled
approved         → completed | failed | expired | cancelled
denied | completed | failed | expired | cancelled = terminal

Status	Bedeutung
`pending_approval`	Policy oder Risk verlangt einen Menschen
`approved`	Auto-approved oder human-approved; bereit zum Zahlen
`completed`	Erfolgreich settled
`denied`	Abgelehnt von Policy oder Risk
`failed`	Settlement downstream fehlgeschlagen
`expired`	TTL abgelaufen
`cancelled`	Owner cancelled vor Settlement

Intent erstellen

curl -X POST https://api.getovra.com/intents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "agentId": "ag_...",
    "cardName": "subscriptions",
    "purpose": "Hetzner monatlich verlängern",
    "expectedAmountEuros": 4.51,
    "expectedMerchant": "hetzner.com",
    "ttlMinutes": 60
  }'

Response:

{
  "id": "int_...",
  "status": "approved",
  "expiresAt": "2026-04-20T11:00:00Z",
  "agentId": "ag_...",
  "cardId": "ca_...",
  "expectedAmountEuros": 4.51,
  "expectedMerchant": "hetzner.com"
}

Wenn Status pending_approval ist, vom Dashboard oder API genehmigen.

Genehmigen / ablehnen

# Genehmigen
curl -X POST https://api.getovra.com/intents/int_.../approve \
  -H "Authorization: Bearer $OVRA_API_KEY"

# Ablehnen
curl -X POST https://api.getovra.com/intents/int_.../deny \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Quartalsbudget aufgebraucht" }'

Recurring Intents

Ein einzelner Intent kann eine Serie von Belastungen autorisieren mit Toleranz-Windows auf Amount und Zeit:

{
  "agentId": "ag_...",
  "cardName": "subscriptions",
  "purpose": "Hetzner — monatlicher Server",
  "expectedAmountEuros": 4.51,
  "expectedMerchant": "hetzner.com",
  "recurring": {
    "cadence": "monthly",
    "windowStartDaysBefore": 3,
    "windowEndDaysAfter": 2,
    "amountTolerancePercent": 10,
    "merchantMatch": true
  }
}

Verifikation (Post-Settlement)

Nach abgeschlossener Belastung kannst du Actual-Amount und Merchant für Reconciliation aufzeichnen:

curl -X POST https://api.getovra.com/intents/int_.../verify \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{
    "actualAmountEuros": 4.51,
    "actualMerchant": "hetzner.com"
  }'

Wenn actualAmountEuros von expectedAmountEuros über die amountTolerancePercent der Policy hinaus abweicht, wird der Intent geflaggt.

Webhooks

Event	Wann
`intent.created`	Intent-Insert
`intent.approved`	Status-Flip auf `approved`
`intent.denied`	Policy oder Risk hat abgelehnt
`intent.expired`	TTL erreicht
`intent.cancelled`	Owner hat cancelled

Surfaces

Surface	Capability
REST	`/intents`, `/intents/:id/{approve,deny,verify,cancel}`
SDK	`ovra.intents.*`
MCP	`ovra_intent` (action: `declare` · `get` · `cancel` · `verify`)
Dashboard	`/dashboard/intents` (Liste, Drawer, inline Approve/Deny)

Weiter

Policies

Die Regeln die approved vs pending_approval vs denied treiben.

Bezahlung

Was nach approved passiert.

Transaktionen

Der Record den ein settled Intent produziert.

Webhooks

In Echtzeit auf FSM-Transitions reagieren.

Erste Schritte

Die sechs Säulen

Kern-Primitive

Zahlungsmodi

Plattform

Das Intent-Modell

Lebenszyklus (FSM)

Intent erstellen

Genehmigen / ablehnen

Recurring Intents

Verifikation (Post-Settlement)

Webhooks

Surfaces

Weiter

Policies

Bezahlung

Transaktionen

Webhooks

​Das Intent-Modell

​Lebenszyklus (FSM)

​Intent erstellen

​Genehmigen / ablehnen

​Recurring Intents

​Verifikation (Post-Settlement)

​Webhooks

​Surfaces

​Weiter

Policies

Bezahlung

Transaktionen

Webhooks

Das Intent-Modell

Lebenszyklus (FSM)

Intent erstellen

Genehmigen / ablehnen

Recurring Intents

Verifikation (Post-Settlement)

Webhooks

Surfaces

Weiter