Credits & Budget Management

AEO Optima uses a three-layer credit system to manage API costs transparently. Credits flow from the platform through organizations to individual projects.

Credit Architecture

How Credits Flow

1. Platform Owner loads credits via OpenRouter (the LLM API gateway)
2. Platform Owner allocates a portion to each customer organization
3. Organization Admin distributes their org pool across projects as budgets
4. Snapshot captures deduct credits atomically as they consume API tokens
5. Budget advisor monitors actual usage and recommends rebalancing

Budget Advisor

The budget advisor analyzes actual 7-day rolling daily cost (not estimates) and classifies each project:

• Critical — Less than 7 days of runway remaining
• Warning — Less than 14 days remaining
• Healthy — Sufficient budget for current usage patterns
• Idle — Budget allocated but no recent captures

Based on these classifications, the advisor generates smart recommendations:

• Transfer — Move budget from idle projects to starving ones
• Increase — Use unallocated org pool for underfunded projects
• Request Credits — Org pool exhausted, request more from platform owner

Onboarding Bonus

New organizations that complete their setup receive a one-time $1 onboarding credit and an auto-provisioned OpenRouter API key. Eligibility requires:

• A proper organization name (not auto-generated)
• At least 1 project created
• At least 5 prompts configured

Credit Requests

Organization admins can request additional credits:

1. Navigate to Settings → Organization → Credits
2. Enter the amount needed and a brief reason
3. The Platform Owner reviews the request in the Platform Cockpit
4. On approval, credits are added automatically and the org's OpenRouter key limit is synced

Where to Check Credits

• Header widget — Balance and runway shown next to the notifications bell
• Dashboard — Credit health alert appears when runway drops below 14 days
• Settings → Organization — Full breakdown with per-project budgets, usage history, and the budget advisor

Budget Alerts

The system runs proactive budget checks every 6 hours:

• Org pool low — Less than 20% of allocated credits remaining
• Project exhausted — Project budget fully consumed
• Project running low — Less than 14 days remaining at current burn rate
• Platform insufficient — Estimated monthly cost exceeds platform balance

Cost Estimation

Each project's estimated monthly cost is calculated from:

prompts × frequency_multiplier × active_models × avg_cost_per_snapshot

The average cost per snapshot is computed from actual 7-day data for the project, falling back to platform-wide averages when project data is insufficient.

API Key Management

Each organization can have an auto-provisioned OpenRouter sub-key with a credit limit matching their allocation. The key lifecycle:

1. Created when platform owner provisions the organization
2. Limit synced whenever credits are added or budgets change
3. Disabled if the organization is paused
4. Deleted if the organization is removed

Organizations can also bring their own API keys (BYOK) which bypass the credit system entirely.