Add prepaid_credit as first-class settlement pattern

[fxops-ai]

Issue: Add Prepaid Credit Wallet as First-Class Settlement Pattern

Summary

The current ATS settlement_methods field is a flat array of method name strings. This is insufficient for autonomous agent settlement decisions because it provides no semantic information about which methods are appropriate for which pricing models, what the minimum purchase requirements are, or how top-up billing is handled.

This issue proposes adding prepaid_credit as a first-class settlement pattern in the ATS schema, with structured metadata that enables agents to make intelligent, autonomous settlement decisions — and that aligns with enterprise procurement workflows.

---

Background and Motivation

The current ATS schema expresses settlement methods as:

"settlement_methods": ["x402", "stripe", "invoice_net30"]

This creates two problems:

1. Stripe is structurally mismatched to per-query micropayments.

Stripe assumes a human cardholder, a checkout session, and per-transaction fees of 2.9% + $0.30. For per-query pricing at $0.02–$0.05 per call, the fee structure makes the economics unworkable — the processing fee exceeds the transaction value. An agent selecting Stripe for per-query settlement would either fail or produce economically irrational transactions.

2. Agents cannot distinguish which settlement method is appropriate for which pricing model.

A flat list of method names provides no guidance on whether stripe is intended for subscriptions, prepaid credit top-ups, or per-query billing. An agent has no basis for intelligent selection.

---

Proposed Solution: Prepaid Credit Wallet Pattern

The prepaid credit wallet model decouples two concerns that should not be coupled in autonomous agent workflows:

Human-to-platform billing — happens once, at human pace, via standard payment methods (Stripe, invoice, bank transfer). The organization's finance team approves a budget allocation. Normal procurement, normal reconciliation. One line item.

Agent-to-provider settlement — happens autonomously, at agent pace, drawing down against the pre-purchased balance. No per-transaction payment friction. No human approval required per access. No crypto rails required.

This is a proven pattern in adjacent domains. Print-on-demand platforms (e.g., printful, Printify) use exactly this model: the account holder purchases a minimum credit balance via standard billing; individual print jobs (ranging from cents to several dollars) draw down against that balance autonomously; low-balance alerts trigger human top-up actions. The per-job transactions never touch the payment processor directly.

This model is particularly well-suited to enterprise ACP adoption because:

• It works within existing procurement and finance workflows
• Finance teams see clean purchase orders, not thousands of micropayment line items
• Consumption reports against the wallet provide clear ROI evidence
• Low-balance alerts create a natural renewal and expansion motion for providers
• ATR records provide per-transaction audit detail without per-transaction billing complexity

---

Proposed Schema Changes

ATS Schema — settlement_methods field

Change from flat string array to structured object array:

"settlement_methods": {
  "type": "array",
  "items": {
    "type": "object",
    "required": ["method"],
    "properties": {
      "method": {
        "type": "string",
        "enum": [
          "prepaid_credit",
          "x402",
          "ap2",
          "stripe",
          "paypal",
          "usdc",
          "invoice_net30",
          "invoice_net60"
        ]
      },
      "use_case": {
        "type": "string",
        "enum": [
          "per_query",
          "per_record",
          "per_workflow",
          "subscription",
          "prepaid_credit_topup",
          "any"
        ],
        "description": "Which pricing model this settlement method is appropriate for"
      },
      "min_transaction_usd": {
        "type": "number",
        "description": "Minimum viable transaction amount (relevant for x402/crypto rails)"
      },
      "min_purchase_usd": {
        "type": "number",
        "description": "Minimum credit purchase amount (relevant for prepaid_credit)"
      },
      "low_balance_alert_usd": {
        "type": "number",
        "description": "Balance threshold at which provider sends low-balance notification"
      },
      "topup_via": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Payment methods accepted for credit wallet top-up (prepaid_credit only)"
      },
      "auto_topup_supported": {
        "type": "boolean",
        "description": "Whether provider supports automatic top-up when balance falls below threshold"
      }
    }
  }
}

Example ATS settlement block

"settlement_methods": [
  {
    "method": "prepaid_credit",
    "use_case": "per_query",
    "min_purchase_usd": 5.00,
    "low_balance_alert_usd": 1.00,
    "topup_via": ["stripe", "invoice_net30"],
    "auto_topup_supported": true
  },
  {
    "method": "x402",
    "use_case": "per_query",
    "min_transaction_usd": 0.001
  },
  {
    "method": "stripe",
    "use_case": "subscription",
    "min_transaction_usd": 1.00
  },
  {
    "method": "invoice_net30",
    "use_case": "prepaid_credit_topup"
  }
]

AAP Schema — settlement preference field

The AAP preferred_settlement_methods field should be updated to reference method names in the same structured format, allowing agents to express preference ordering per use case:

"preferred_settlement_methods": [
  { "method": "prepaid_credit", "use_case": "per_query" },
  { "method": "x402", "use_case": "per_query" },
  { "method": "stripe", "use_case": "subscription" }
]

---

Evaluator Changes Required

ACPEvaluator._select_settlement_method() currently matches on string values. It needs to be updated to:

1. Filter available settlement methods by use_case compatibility with the selected pricing model
2. Match against AAP preferred methods using both method and use_case
3. Prefer prepaid_credit over x402 when the agent's AAP indicates an enterprise deployment context (no crypto rails preference)
4. Fall back to best available match if no exact use_case match exists

---

ATR Changes Required

The ATR transaction.settlement_method field should be extended to include:

"transaction": {
  "settlement_method": "prepaid_credit",
  "settlement_use_case": "per_query",
  "amount_paid": 0.02,
  "wallet_balance_before": 4.82,
  "wallet_balance_after": 4.80,
  "settlement_reference": "wallet_draw_abc123",
  "topup_required": false
}

The wallet balance fields enable the agent to self-monitor balance levels and trigger escalation when approaching zero — a new escalation rule type wallet_balance_low should be added to the AAP escalation_rules schema.

---

Backwards Compatibility

The flat string array format should remain supported in ATS parsing for v0.1.x compatibility. The evaluator should treat a string entry as equivalent to { "method": "<string>", "use_case": "any" }.

Full migration to structured format in v0.2.0. Deprecation of flat string format in v0.3.0.

---

Additional Context

This pattern also has significant GTM implications for data providers:

• Consumption-based expansion signal: top-up frequency and wallet burn rate are leading indicators of agent workflow adoption depth — a CRM-visible metric that doesn't exist in subscription models
• Finance-friendly procurement: one purchase order per period rather than thousands of micropayment line items
• Natural renewal motion: low-balance alerts are a provider touch point with demonstrated value already consumed

Related discussion: [ACP @SaaSCRO article](https://x.com/SaaSCRO/status/2027087308097302568)

---

Proposed Milestone

v0.2.0

Labels

enhancement schema settlement gtm breaking-change-v0.3

[fxops-ai]

Two signals from the past 72 hours that are directly relevant to this issue.
Stripe token billing — private preview
Stripe has a private preview running for usage-based, metered, per-token billing. The architecture: route LLM calls through a Stripe proxy, Stripe syncs model prices across providers, configures usage-based billing for your margin, records metered usage per call automatically.
This is currently designed for AI app builders billing their human subscribers — one layer above what ACP is solving. But it signals that Stripe is actively building the metered micropayment infrastructure that would make stripe viable for per-query agent settlement at sub-cent transaction sizes. The issue's current framing — that Stripe is structurally mismatched to per-query micropayments — is correct for today's Stripe. It may have a shorter shelf life than the schema design assumes.
Recommended: add a note to the schema proposal acknowledging that stripe use_case mapping may expand as Stripe's metered billing matures. The structured format proposed here (method + use_case object) already accommodates this cleanly — no schema change required, just updated guidance on use_case values for stripe as the product evolves.
Market conversation: the liability and architecture debate
There is an active thread on X.com (@aakashgupta, @Brian_Armstrong, @sigilrisk, @ruidasilva) mapping the agent payments landscape. Two points from that conversation are directly relevant here:

Rui da silva's framing of HTTP 402 as a self-settling primitive — where each request settles itself and replay protection comes from single-use settlement primitives rather than billing databases — is architecturally complementary to the prepaid_credit pattern proposed in this issue. Prepaid_credit handles the human-to-platform procurement layer; x402/HTTP 402 handles the agent-to-provider settlement layer. They are not competing patterns. The schema should reflect this explicitly in documentation.
The liability framing from the Aakash thread (Visa's Ramachandran: agents are now a fifth party in the dispute chain) strengthens the case for prepaid_credit as the enterprise-preferred pattern. Finance teams can reconcile one PO. They cannot reconcile a dispute chain that includes an autonomous agent as a named party. This is a GTM argument for the prepaid_credit pattern that belongs in the issue's "additional context" section.

Thread reference: https://x.com/aakashgupta [(https://x.com/aakashgupta/status/2031234270317129746?s=20)]
Stripe token billing: https://docs.stripe.com/billing/token-billing