---

name: credit-metered-ai-endpoints description: Use when monetizing an AI endpoint (image/voice/video/LLM generation, or any paid tool call) with a prepaid credit balance instead of per-call Stripe charges. Teaches the deduct-on-success ordering, the atomic single-UPDATE spend that cannot go negative under concurrency, a consistent error envelope (401/402/429), rate limiting, an append-only ledger, and an owner bypass - the shape a caller can rely on across every metered route.

Credit-Metered AI Endpoints

A prepaid credit balance is the clean way to monetize expensive, variable-cost AI actions: the customer buys credits once, every action spends from one pool, and the same balance works across every endpoint and every product. This skill is the server-side pattern for doing that safely - the ordering, the atomicity, and the response contract that make it robust under real traffic.

It generalizes the deduct-on-success + envelope + rate-limit stack. It is about the pattern, not any one codebase.

When to trigger

• You are turning an AI action (generate image/voice/video, an LLM call, a metered tool) into a paid endpoint and need to charge for it.
• You have a per-call cost model (what an action costs) but no runtime that actually holds, spends, and grants a balance.
• Concurrent requests could drive a balance negative, or a failed generation could still charge the user.
• You want one credit pool shared across many endpoints, with a single error shape every client can handle.

The request lifecycle

Every metered request runs the same gauntlet, in this order:

1. Authenticate -> resolve a caller id from a Bearer API key or a session. No id, return 401.
2. Rate limit -> if the caller is over their window, return 429 with retryAfterSeconds and a Retry-After header. Do this before doing work.
3. Check affordability -> look up the cost from the shared cost model and the caller's balance. If short, return 402 with the current balance.
4. Do the work -> call the model / run the action. This is the step that can fail or cost you money.
5. Deduct on success only -> charge exactly after the work succeeds, never before. Write a ledger entry in the same step. See reference/deduct-on-success.md.
6. Return the result -> plain JSON on success; the shared envelope on error.

The load-bearing rule is step ordering: deduct after the work succeeds. Charge first and every model timeout, safety refusal, or 500 becomes a silent theft you will refund by hand. See reference/deduct-on-success.md.

Core rules

• One cost model, read by both the advertised price and the charge. The price shown to the user and the amount deducted must come from the same source so they cannot drift.
• Deduction is one atomic conditional UPDATE, not read-then-write. Spend only when the row still covers the cost, so concurrent requests cannot overspend. See reference/deduct-on-success.md.
• Append-only ledger. Every balance change (grant, spend, refund) writes an immutable row. The balance is a cache of the ledger; the ledger is the truth.
• Owner / internal accounts bypass charging via an explicit flag, returning success with no balance change and no ledger row.
• One error envelope across every route so any client handles { error, message } once. See reference/envelope-and-limits.md.

Reference files

• reference/deduct-on-success.md - the ordering, the atomic single-UPDATE spend, the ledger, refunds, and the owner bypass.
• reference/envelope-and-limits.md - the 401/402/429/400/500 envelope, rate limiting, and the shared cost model.