Prepaid credits

Design only. Qty does not store a balance, a wallet ledger, or a credit key.

# Prepaid credits

Qty paid routes settle each call with x402 exact USDC. This note is the design for a prepaid balance. It is not implemented.

## Status

Qty does not store balances. There is no Redis key, no database table, and no change to settlement. A caller cannot buy credits or spend them. `GET /v1/feed` and the convert rate limit keep using Redis for other jobs, and neither of those stores a wallet balance.

## Purchase

1. `POST /v1/credits/purchase` would take an amount in USD, with a floor of $1 and a ceiling of $50.
2. The route would return HTTP 402 for that amount, on the same Base and Solana accepts as the other paid routes.
3. After the facilitator reports a successful settlement and the handler returns 2xx, Qty would credit the payer address from that settlement.
4. The credit would be USDC atomic units on that network. Qty would not invent a second currency.

## Spend

1. A paid route would accept either a fresh x402 payment or a payer that already has a balance covering the posted price.
2. The balance check would happen before the handler. If the balance covers the route price, Qty would append a spend entry and skip a second facilitator settlement for that call.
3. If the balance is short, the route stays on the normal 402 path. Qty would not debit part of the price.
4. Prices stay the prices published on each route. Credits would not discount them.
5. An `Idempotency-Key` on a spend would be stored with the journal id so a replay does not debit twice.

## Ledger

- One balance per payer address and network. The balance is the sum of the journal, not a mutable counter on its own.
- Journal kinds: purchase, spend, expire, refund.
- Credits would expire 12 months after purchase. Expiry is a journal entry, not a silent deletion.
- A refund would be a journal entry back to the payer. Qty would not reverse a chain transaction from this document's design.
- Stored fields: payer address, network, amount, route, journal id, idempotency key, timestamp. No request body, no IP, no API key.

## What this version does

Agents pay per call. This page is the design so a later change can add balances without changing the prices or the 402 shape. Until that change ships, Qty stores no credit balance.