metered-billing.spec.md

Principles

• Prepaid credits. Agents top up a balance; metered interactions debit it.
• Agent-native payments. Insufficient balance returns HTTP 402 with machine-readable top-up instructions — an agent can self-remediate.
• Cloud costs are never ours. Provider spend bills to the customer's own cloud account (ADR-002 §3). Fees below are platform fees only.
• Failed deployments are free (ADR-002 §4).
• Auditable and idempotent. Every credit/debit is a ledger event with an idempotency key; retries never double-charge.
• Config-driven pricing. The price schedule is configuration, not code.

Price schedule (MVP defaults)

Rationale: top-of-funnel free (discoverability), micro-fees on metered reads, meaningful but small fee on the high-value action. Schedule lives in config (e.g. billing.prices.json / env) and can change without deploys.

Flows

Top-up — Stripe (human pays)

1. POST /api/v1/billing/topup/stripe { amountUsd, successUrl?, cancelUrl? } → returns Stripe Checkout URL + topupId.
2. Human completes checkout. Stripe webhook (POST /api/v1/billing/webhooks/stripe) verifies signature and credits the account.
3. Ledger event: credit(stripe, amount, topupId) — idempotent on Stripe session ID.

Top-up — XRP (agent pays)

1. POST /api/v1/billing/topup/xrp { amountUsd } → returns deposit address (account wallet), memo/destination tag, and topupId.
2. Existing CryptoPaymentsService monitors the wallet; on confirmation, credits the account at the XRP/USD rate at confirmation time.
3. Ledger event: credit(xrp, amount, txHash) — idempotent on tx hash.

Metered call

1. Request arrives with bearer token → resolve account.
2. Look up price for the route (price schedule; sandbox mode = 0).
3. Balance check: insufficient → 402 Payment Required with body: { error: "insufficient_credits", balanceUsd, requiredUsd, topup: { stripe: "POST /api/v1/billing/topup/stripe", xrp: "POST /api/v1/billing/topup/xrp" } }.
4. Sufficient → process request → debit(route, price, requestId) — idempotent on request ID.

Deployment payment gate (replaces unverified paymentRef)

1. POST /api/v1/deployments { quoteId, ... } — no paymentRef needed; the account balance IS the payment.
2. Place a hold of the deployment fee on the account (hold(deployFee, deploymentId)).
3. Deployment reaches active (verification passed) → capture the hold.
4. Deployment reaches failed → release the hold (free, ADR-002 §4).
5. Destroy before capture → release.

API surface (new/changed)

MCP: add get_balance and top_up tools so agents can self-fund without leaving the MCP session.

Data model (minimum)

• accounts: id, token(s), createdAt
• ledger: id, accountId, type (credit|debit|hold|capture|release|refund), amountUsd, reference (topupId / requestId / deploymentId), idempotencyKey, createdAt
• Balances are derived from the ledger (single source of truth).

Security & correctness

• Stripe webhook signature verification mandatory.
• XRP credit only after N ledger confirmations (existing service config).
• Idempotency keys on every ledger mutation; unique constraint enforced.
• Debits and holds must be atomic with the balance check (transaction).
• Never log full card/wallet secrets; reference IDs only.

Out of scope (MVP)

• Subscriptions, invoicing, fiat payouts, multi-currency balances.
• Negative balances / postpaid.
• Provider cost pass-through (customer pays their own cloud bill).