Credit and wallet economics

Unit and starter grant

• One point has a face value of USD 0.001. Stripe sells 1,000 points for USD 1.
• New accounts receive 1,000 bonus points. Bonus points expire after 90 days and are spent before paid points, earliest expiry first.
• The grant has USD 1.00 face value and approximately USD 0.50 platform COGS at the normal 2x agent markup. It buys roughly 333 fast-tier messages, 20 best-tier messages, or 25 image generations at the current seed prices.
• A reconciliation worker runs immediately at process startup and hourly. It idempotently grants active users who have no starter_grant ledger entry, covering OAuth, magic-link races, and transient post-commit failures.

Creator-revenue funding policy

Creator purchases remain bonus-first so promotional credit is useful, but only the paid-funded portion of a buyer debit participates in the 70% creator share. The creator earning is credited as paid, withdrawable points and records the buyer debit transaction plus paid/bonus provenance. Bonus-funded spend creates no creator payout lot. Purchases of one’s own listing or content are blocked; owner expert and Painter runs remain non-revenue operations.

This closes the previous conversion loop. Under the old behavior, a new user could spend a 150-point grant on a 100-point listing and create 70 withdrawable creator points. Raising the grant to 1,000 points would have enlarged that hole by about 6.7x.

Existing accounts and rollout

Historical balances are preserved. In particular, legacy 20,000-point paid, non-expiring grants and audited admin adjustments are not rewritten or clawed back. The new amount and pool rules apply prospectively; the reconciliation worker only acts when no starter-grant ledger entry exists.

The AUTOPILOT_STARTER_GRANT_POINTS runtime override is changed through the admin runtime-settings API only after the code containing the paid-funded share policy and reconciliation worker is deployed. Operators must first exercise the full-domain GET/ETag/PUT flow in staging, then repeat it in production with all five autopilot keys, If-Match, confirmEnvironment: "production", and an auditable reason. Environment variables are retired for this setting.

Web search

Platform web search costs about USD 0.008 per Tavily call. The default user charge is therefore 10 points (USD 0.010), and the usage event is linked to the platform turn’s wallet reserve so normal cost settlement and the reserve cap include search cost. Existing deployments with a managed platform_agent runtime-settings domain retain their persisted snapshot; operators apply the 10-point value through the guarded full-domain API after this code is deployed.

Ledger boundaries and legacy compatibility

Compatibility wallet views are read-only. The registered wallet_drop_legacy_compat_triggers migration removes their old write triggers because those triggers collapsed all incoming value into paid points and could bypass pool provenance. Admin adjustments use the audited API-credit path: credits require an explicit paid or bonus pool, and debits require an explicit paid-only, bonus-only, or normal-order policy. The ledger rejects bonus credits to the withdrawable creator wallet even if a future caller attempts one.

Core financial ledger columns plus pool, refund, and Stripe provenance are append-only at the database boundary. Lifecycle annotations remain mutable and a bonus lot’s remaining_points may only decrease; GDPR tombstoning uses an explicit, transaction-local maintenance mode. Positive creator-wallet admin reversals must point to, and cannot exceed, an existing debit for the same user.

The wallet_balance_reconciliation worker runs immediately and hourly under a fleet-wide advisory lease. It persists a bounded round-robin comparison of the materialized paid/bonus balances against ledger provenance in wallet_balance_reconciliations, logs every mismatch, and never repairs money automatically. Operators investigate repeated mismatches before making an audited adjustment. Legacy balance and transaction views expose BIGINT values so a large accumulated balance cannot overflow their compatibility API.

Stripe checkout metadata freezes points, minor-unit price, and currency at session creation. Webhooks credit that immutable snapshot even if the product catalog changes while payment is in flight. The user-scoped checkout-status endpoint reports success only after it finds the resulting point_purchase ledger row.

Admin wallet-adjustment SOP

Before submitting an adjustment, record the user’s current paid and bonus balances, use a unique request ID, and state the operational reason precisely. For a positive adjustment, select paid or bonus explicitly. Bonus credits default to the standard 90-day expiry; set another future expiry only when the promotion or support decision requires it. For a negative adjustment, select paid_only, bonus_only, or default explicitly. Reserve default for a normal user-equivalent deduction, which consumes expiring bonus lots first.

If a credit was issued into the wrong bucket, do not use the reversal endpoint. Submit an equal negative adjustment with the matching bucket-only policy (paid_only for a paid credit or bonus_only for a bonus credit), then verify the returned pool split and paid/bonus balances. If the credit is still owed, issue a separate positive adjustment with a new request ID into the correct bucket and verify its expiry. The reversal endpoint remains debit-only and is not a mechanism for undoing credits.