[Feature Request] Add spending limits and policy controls for agent payments

[mkmkkkkk]

Problem

MCPay handles the payment lifecycle elegantly — 402 negotiation, on-chain settlement, transparent retries. But once an agent has wallet access, there's no enforcement layer between "agent wants to pay" and "payment goes on-chain."

Today, maxPaymentValue in withX402Client is the only guardrail, and it's a static per-transaction cap set at init time. There's no way to enforce:

• Cumulative budgets — hourly/daily/monthly spend limits
• Rate limiting — max N transactions per time window
• Recipient allowlists/blocklists — restrict which addresses an agent can pay
• Per-tool policies — different limits for different tool calls (e.g. a $0.001 weather lookup vs. a $5 data export)
• Human-in-the-loop approval — flag transactions above a threshold for manual review

As agents gain more financial autonomy, the gap between "can pay" and "should pay" becomes a real risk surface.

Proposal

Add a policy engine that evaluates every payment against configurable rules before it hits the chain. Conceptually, this sits between the x402 negotiation and the actual signing step.

Possible interface

const paymentClient = withX402Client(client, {
  wallet: { evm: evmSigner },
  policy: {
    maxPerTransaction: 0.10,       // USDC
    maxPerHour: 1.00,
    maxPerDay: 10.00,
    allowedRecipients: ["0x..."],  // optional allowlist
    requireApproval: {
      above: 5.00,                 // flag for human review
      callback: async (tx) => { /* webhook / UI prompt */ }
    }
  }
})

Where it fits in the flow

In the existing sequence diagram, the policy check would happen at steps (5a)/(6b) — after the 402 metadata is received but before signing/broadcasting the transaction:

402 received → policy.evaluate(amount, recipient, tool, context) → allow/deny/escalate → sign → broadcast

This keeps it non-breaking — the policy engine is opt-in and the default behavior (no policy = allow all) stays the same.

Existing work

PaySentry is an open-source SDK that implements this pattern for x402 payments — per-transaction limits, rolling budgets, recipient controls, and observability hooks. Its @paysentry/control package specifically handles the policy evaluation step.

Could be worth looking at as a reference implementation or potential integration path. The core idea (evaluate-before-sign) is what matters, regardless of which library implements it.

Why this matters for MCPay

MCPay is positioned as the payment infra for MCP. Adding governance/controls would:

1. Unlock enterprise adoption — no finance team will approve agent wallets without spending controls
2. Differentiate from raw x402 — x402 handles the protocol, MCPay + policy handles the trust layer
3. Reduce liability — if an agent misbehaves, the policy engine is the circuit breaker

Happy to discuss implementation approaches or contribute if there's interest.