Naira & Paystack Token Billing

CTS Model Router includes an integrated financial billing engine designed specifically to resolve currency conversion and credit card friction for African engineers and global organizations.

---

1. Unified Ledger Architecture

All balance deductions and additions are managed in Postgres using UUIDv7 immutable transaction records:

• Pre-Debit Hold (/holds/create): When an inference request begins, the gateway calculates an estimated token envelope (e.g. prompt length + requested max_tokens) and places an atomic hold on your balance.
• In-Flight Processing: The inference stream proceeds with guaranteed budget certainty.
• Reconciliation (/holds/reconcile): Upon stream termination, the exact prompt, cached, and completion tokens are recorded, the exact fee is debited, and the remaining hold balance is instantly unlocked.

---

2. Local Funding via Paystack

You can fund your balance in Nigerian Naira (NGN) or US Dollars (USD):

1. Cards: Mastercard, Visa, Verve.
2. Bank Transfers: Instant virtual NGN account numbers.
3. Automated Conversion: FX rates update regularly against monitored currency benchmarks.

---

3. Querying Wallet Balance

Inspect your real-time balance via API:

curl -X GET https://api.creativetechstudios.org/v1/billing/wallet \
  -H "Authorization: Bearer $CTS_API_KEY"

Response:

{
  "wallet_id": "018f234a-9b1c-7f8e-8a2b-1029384756af",
  "currency": "NGN",
  "balance_kobo": 4500000,
  "formatted_balance": "₦45,000.00",
  "active_holds_count": 0
}