How AutopayOS works

AutopayOS enables AI agents to make autonomous purchases within constraints defined by human principals. This guide explains the core concepts and how they work together.

The agent payment problem

AI agents need to make purchases on behalf of users, but traditional payment systems weren't designed for this:

Architecture overview

AutopayOS consists of three core platform components connected to external actors:

Platform Components:

• Policy Engine — Evaluates requests against spending rules
• Evidence Store — Cryptographic audit trail with hash chaining
• Payment Rails — Integrations with Stripe, Visa IC

External Actors:

• Agents — AI shopping assistants making purchases
• Merchants — Online stores providing cart data
• Dashboard — Human principals managing policies

Core components

1. Policies

Policies define what agents are allowed to do. They're configured by human principals and enforced automatically.

{
  "spend": {
    "amount_cap": 100.00,
    "currency": "USD",
    "categories": ["groceries", "household"]
  },
  "merchant": {
    "allow_list": ["amazon.com", "walmart.com"]
  },
  "risk": {
    "velocity_limit": {
      "max_transactions": 10,
      "time_window": "24h"
    }
  }
}

Learn more: Policy configuration

2. Mandates

Mandates are signed permissions that flow through the system:

Each mandate is a Verifiable Credential (VC) signed with Ed25519.

3. Evidence Chain

Every action creates a cryptographic record in the Evidence Chain. Events are linked via SHA-256 hashes:

This hash chaining ensures tamper detection — modifying any event breaks the chain.

Learn more: Evidence and audit trails

4. Payment Rails

Payment Rails connect to actual payment processors:

Learn more: Payment execution

The payment flow

Step 1: Intent Mandate

The agent requests permission to shop:

const permission = await client.requestPermission({
  agentDid: 'did:key:z6Mk...',      // Who is the agent?
  principalDid: 'did:key:z6Mp...',  // Who authorized it?
  amount: 50.00,                     // How much?
  currency: 'USD',
  merchantDomain: 'amazon.com',      // Where?
});

Policy engine checks:

• Amount within cap
• Merchant on allowlist
• Within velocity limits
• Time window valid
• MCC category allowed

Output: Signed IntentMandate VC

Step 2: Cart Mandate

The agent builds a cart and submits it for verification:

const verification = await client.verifyCart({
  intentVc: permission.intentVc,
  cartVc: merchantCartVc,
});

Verification checks:

• Cart total ≤ intent amount
• Merchant matches intent
• Cart signature valid
• Items match allowed categories
• No duplicate submission

Output: approvalToken + railDecision

Step 3: Payment Mandate

With approval, the agent executes the payment:

const payment = await client.executePayment({
  approvalToken: verification.approvalToken,
});

Execution:

1. Verify approval token (not expired, not used)
2. Issue PaymentMandate VC
3. Route to selected payment rail
4. Process payment with Stripe/Visa
5. Log to evidence chain

Output: Signed PaymentMandate VC

Step 4: Settlement

The payment rail handles actual money movement:

AutopayOS Gateway → Stripe → Merchant Bank

Sequence of operations

Key concepts

Verifiable Credentials (VCs)

All mandates are Verifiable Credentials — standardized, cryptographically signed JSON documents:

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "IntentMandate"],
  "issuer": "did:key:z6Mk...",
  "issuanceDate": "2025-12-17T10:00:00Z",
  "credentialSubject": {
    "mandateId": "intent_abc123",
    "maxAmount": 100.00
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "jws": "eyJhbGciOiJFZERTQSJ9..."
  }
}

Decentralized Identifiers (DIDs)

Every participant has a DID — a globally unique identifier:

DIDs enable:

• Cryptographic identity
• Self-sovereign control
• Cross-platform interoperability

Policy Attestation

When an intent is approved, AutopayOS issues a Policy Attestation — a signed record of which policy was in effect:

{
  "policyId": "pol_abc123",
  "policyHash": "sha256:def456...",
  "evaluatedAt": "2025-12-17T10:00:00Z"
}

This prevents policy bypass by proving the rules at the time of approval.

Security model

Defense in depth

Human Presence

For high-value or risky transactions, AutopayOS requires Human Presence (HP) verification via WebAuthn:

Amount > $500 → HP Required → WebAuthn Challenge → Proceed

Learn more: Human Presence guide

Next steps

• Intent Mandates — Deep dive into permission requests
• Cart verification — How carts are validated
• Payment execution — Completing the transaction
• Policy configuration — Define spending rules