Create a mandate

Establish the standing authorization behind a recurring, agent-initiated debit relationship.

POST /v1/mandates

cURL

curl https://api.openfi.co/v1/mandates \
  -H "Authorization: Bearer $OPENFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_account_id": "acc_123",
    "max_amount": 50,
    "currency": "USD",
    "interval": "daily",
    "purpose": "AI agent operational expenses"
  }'

200

{
  "id": "man_01HZY...",
  "status": "active",
  "max_amount": 50,
  "currency": "USD",
  "interval": "daily",
  "created_at": "2026-08-27T14:05:00Z"
}

A mandate is the top of the three-call agentic flow (mandate → session key → debit pull). It defines who can eventually be pulled from, the ceiling amount, cadence, and purpose, but does not itself move money or authorize any single agent to act.

CAD payer accounts cannot use this endpoint today. The underlying CAD rail only supports one-time payments. Use /v1/payments for CAD instead. See Supported Rails.

Body Parameters

payer_account_id · string · required

The linked bank account or wallet the mandate authorizes pulls from.

max_amount · number · required

Ceiling amount per interval, in the mandate’s currency.

currency · string · required

USD or GBP. (CAD not currently supported, see warning above.)

interval · string · required

One of daily, weekly, monthly.

purpose · string

Free-text description, surfaced in audit logs (e.g. "AI agent operational expenses").

requires_identity_credential · boolean · default: "false"

If true, session keys issued under this mandate can only be granted to subjects holding a valid Verifiable Credential.

Response

id · string

Mandate ID, prefixed man_.

status · string

active, paused, or revoked.

cURL

curl https://api.openfi.co/v1/mandates \
  -H "Authorization: Bearer $OPENFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_account_id": "acc_123",
    "max_amount": 50,
    "currency": "USD",
    "interval": "daily",
    "purpose": "AI agent operational expenses"
  }'

200

{
  "id": "man_01HZY...",
  "status": "active",
  "max_amount": 50,
  "currency": "USD",
  "interval": "daily",
  "created_at": "2026-08-27T14:05:00Z"
}